From 3d7cd2d49dc5bc758b7cd8a171430ef6fa560ed8 Mon Sep 17 00:00:00 2001 From: nishantms Date: Mon, 10 Aug 2026 16:38:53 -0400 Subject: [PATCH 1/3] docs: document the package version status endpoint --- api/base.yaml | 6 + api/merge-config.yaml | 1 + .../package-version-status.yaml | 142 ++++++++++++++++++ 3 files changed, 149 insertions(+) create mode 100644 api/registry.npmjs.com/package-version-status.yaml diff --git a/api/base.yaml b/api/base.yaml index 065ef94..74192fe 100644 --- a/api/base.yaml +++ b/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 diff --git a/api/merge-config.yaml b/api/merge-config.yaml index 1c66271..ea762e3 100644 --- a/api/merge-config.yaml +++ b/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 diff --git a/api/registry.npmjs.com/package-version-status.yaml b/api/registry.npmjs.com/package-version-status.yaml new file mode 100644 index 0000000..da7639f --- /dev/null +++ b/api/registry.npmjs.com/package-version-status.yaml @@ -0,0 +1,142 @@ +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 + "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: + 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. + content: + application/json: + schema: + type: object + properties: + error: + type: string + PackageVersionStatusNotFound: + description: The package version does not exist or the authenticated user does not have access to it. + 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 From 84c243bad624a7d8a3dbed80deab3dc2747e58ba Mon Sep 17 00:00:00 2001 From: nishantms Date: Mon, 10 Aug 2026 18:48:03 -0400 Subject: [PATCH 2/3] docs: document the 400 response for invalid package name or version --- api/registry.npmjs.com/package-version-status.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/api/registry.npmjs.com/package-version-status.yaml b/api/registry.npmjs.com/package-version-status.yaml index da7639f..cf3856b 100644 --- a/api/registry.npmjs.com/package-version-status.yaml +++ b/api/registry.npmjs.com/package-version-status.yaml @@ -46,6 +46,8 @@ paths: packageName: "@npmcli/example-package" version: "1.2.3" status: validating + "400": + $ref: "#/components/responses/PackageVersionStatusBadRequest" "401": $ref: "#/components/responses/PackageVersionStatusUnauthorized" "403": @@ -86,6 +88,16 @@ components: - 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: From 6df07dd9a05dc08be5931b4051ba79268311ae26 Mon Sep 17 00:00:00 2001 From: nishantms Date: Mon, 10 Aug 2026 19:07:16 -0400 Subject: [PATCH 3/3] docs: clarify that 403 is the rollout gate and 404 hides package access --- api/registry.npmjs.com/package-version-status.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/registry.npmjs.com/package-version-status.yaml b/api/registry.npmjs.com/package-version-status.yaml index cf3856b..07a50cd 100644 --- a/api/registry.npmjs.com/package-version-status.yaml +++ b/api/registry.npmjs.com/package-version-status.yaml @@ -108,7 +108,8 @@ components: error: type: string PackageVersionStatusForbidden: - description: Package version status is not enabled for this package. + 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: @@ -117,7 +118,8 @@ components: error: type: string PackageVersionStatusNotFound: - description: The package version does not exist or the authenticated user does not have access to it. + 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: