docs: document the package version status endpoint

api/base.yaml

@@ -108,6 +108,11 @@ tags:
     description: |
       Trust-related endpoints for managing package trust and security settings.
 
+  - name: Packages
+    x-displayName: Packages
+    description: |
+      Package metadata and lifecycle endpoints.
+
 x-tagGroups:
   - name: Introduction
     tags:
@@ -121,6 +126,7 @@ x-tagGroups:
       - Audit
       - OIDC
       - Org
+      - Packages
       - Publish
       - Search
       - Stage

api/merge-config.yaml

@@ -4,6 +4,7 @@ inputs:
   - inputFile: registry.npmjs.com/audit.yaml
   - inputFile: registry.npmjs.com/oidc.yaml
   - inputFile: registry.npmjs.com/org.yaml
+  - inputFile: registry.npmjs.com/package-version-status.yaml
   - inputFile: registry.npmjs.com/publish.yaml
   - inputFile: registry.npmjs.com/search.yaml
   - inputFile: registry.npmjs.com/stage.yaml

api/registry.npmjs.com/package-version-status.yaml

@@ -0,0 +1,156 @@
+paths:
+  /-/package/{package-name}/version/{version}/status:
+    get:
+      tags:
+        - Packages
+      summary: Get the lifecycle status of an exact package version.
+      description: |
+        Returns the current lifecycle status of an exact package version. The response may represent validation progress, manual approval, or publication without exposing validation-system details.
+
+        The authenticated user must have publish access to the package. A package authorization failure is returned as not found.
+      operationId: getPackageVersionStatus
+      parameters:
+        - name: package-name
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The exact package name. Scoped names must be URL-encoded with the slash escaped.
+        - name: version
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The exact semantic version.
+        - name: Authorization
+          in: header
+          required: true
+          schema:
+            type: string
+            pattern: "^Bearer .+"
+          description: An npm access token or granular access token for a package maintainer.
+      security:
+        - npmAccessToken: []
+        - granularAccessToken: []
+      responses:
+        "200":
+          description: The current lifecycle status of the package version.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PackageVersionStatus"
+              examples:
+                validationInProgress:
+                  summary: The version is still being processed
+                  value:
+                    packageName: "@npmcli/example-package"
+                    version: "1.2.3"
+                    status: validating
+        "400":
+          $ref: "#/components/responses/PackageVersionStatusBadRequest"
+        "401":
+          $ref: "#/components/responses/PackageVersionStatusUnauthorized"
+        "403":
+          $ref: "#/components/responses/PackageVersionStatusForbidden"
+        "404":
+          $ref: "#/components/responses/PackageVersionStatusNotFound"
+        "429":
+          $ref: "#/components/responses/PackageVersionStatusTooManyRequests"
+        "500":
+          $ref: "#/components/responses/PackageVersionStatusInternalServerError"
+        "503":
+          $ref: "#/components/responses/PackageVersionStatusUnavailable"
+components:
+  schemas:
+    PackageVersionStatus:
+      type: object
+      required:
+        - packageName
+        - version
+        - status
+      properties:
+        packageName:
+          type: string
+          description: The exact package name.
+        version:
+          type: string
+          description: The exact package version.
+        status:
+          type: string
+          description: |
+            Where the version currently stands.
+
+            `published` means it is live and installable. `validating` means it is still on its way and the caller should check again shortly. `staged` means it is waiting for a maintainer to approve it. `blocked` means it did not pass automated validation and cannot be installed. `deleted` means it was published and has since been removed.
+          enum:
+            - published
+            - validating
+            - staged
+            - blocked
+            - deleted
+  responses:
+    PackageVersionStatusBadRequest:
+      description: |
+        The package name or the version is not valid. The version must be an exact semver version, so a range such as `^1.0.0` is rejected. This is checked before authentication, so it is returned even when no credential is supplied.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+    PackageVersionStatusUnauthorized:
+      description: Authentication is missing or invalid.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+    PackageVersionStatusForbidden:
+      description: |
+        Package version status is not enabled for this package. This is the rollout gate only. Not having access to a package is reported as `404`, not here.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+    PackageVersionStatusNotFound:
+      description: |
+        The package version does not exist, or the authenticated user cannot read it. These are deliberately indistinguishable so the response does not reveal whether a package the caller cannot see exists.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+    PackageVersionStatusTooManyRequests:
+      description: The request was rate limited.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+    PackageVersionStatusInternalServerError:
+      description: An internal error occurred.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+    PackageVersionStatusUnavailable:
+      description: The package-version status service is temporarily unavailable.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string