From 240e88ada3d0518d6e02421e2a45373dc754f5fb Mon Sep 17 00:00:00 2001 From: shmam Date: Tue, 22 Sep 2026 16:17:03 -0700 Subject: [PATCH 1/2] docs: clarify staged publishing can create new packages Clarify that the stage-package endpoint supports creating a brand-new package (not just staging new versions of existing packages). Staging the first version of a package that does not yet exist creates it on approval, provided the publisher is permitted to create the name. Also note this in the approve endpoint description. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- api/registry.npmjs.com/stage.yaml | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/api/registry.npmjs.com/stage.yaml b/api/registry.npmjs.com/stage.yaml index fd5a3f0..4c55ca6 100644 --- a/api/registry.npmjs.com/stage.yaml +++ b/api/registry.npmjs.com/stage.yaml @@ -97,16 +97,23 @@ paths: post: tags: - Stage - summary: Publishes a package version to staging to be reviewed by maintainers. + summary: Stage a package version for maintainer review, creating the package if it does not yet exist. description: | Submit a package version to staging for maintainer review. + This endpoint supports both staging a new version of an existing package and + creating a brand-new package. When the package does not yet exist in the + registry, staging its first version creates the package on approval — you do + not need to publish the package directly beforehand. The authenticated + publisher must be allowed to create the package name (for example, hold the + relevant scope or organization permissions). + The request body must contain a publish-style packument payload, including version metadata and package attachments. The staged item can then be reviewed, inspected, approved, or deleted by authorized maintainers. ## Requirements - - Package MUST exist or be creatable by the authenticated publisher + - Package MUST already exist, or the authenticated publisher MUST be permitted to create it (staging the first version creates a new package on approval) - User MUST be authenticated with a valid npm token - Request body MUST include required fields in `StagedPackumentRequest` operationId: stagePackageVersion @@ -323,7 +330,8 @@ paths: This endpoint moves a version from staged review state to a published package version. On success, the staged record will be processed and the package version will become - installable. + installable. If the staged version is the first version of a package that does not + yet exist, approving it creates the new package in the registry. ## Requirements - `stage-id` MUST reference an existing staged package version From 879a0376788df5ecd1c77d37d1ee0987c4712574 Mon Sep 17 00:00:00 2001 From: sam crochet Date: Tue, 22 Sep 2026 17:10:42 -0700 Subject: [PATCH 2/2] Revise staging endpoint summary and description Updated the summary and description for the staging package version endpoint in the API documentation. --- api/registry.npmjs.com/stage.yaml | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/api/registry.npmjs.com/stage.yaml b/api/registry.npmjs.com/stage.yaml index 4c55ca6..a92706a 100644 --- a/api/registry.npmjs.com/stage.yaml +++ b/api/registry.npmjs.com/stage.yaml @@ -97,15 +97,14 @@ paths: post: tags: - Stage - summary: Stage a package version for maintainer review, creating the package if it does not yet exist. + summary: Publishes a package version to staging to be reviewed by maintainers. description: | Submit a package version to staging for maintainer review. This endpoint supports both staging a new version of an existing package and creating a brand-new package. When the package does not yet exist in the - registry, staging its first version creates the package on approval — you do - not need to publish the package directly beforehand. The authenticated - publisher must be allowed to create the package name (for example, hold the + registry, staging its first version creates the package with a standardized placeholder version. + The authenticated publisher must be allowed to create the package name (for example, hold the relevant scope or organization permissions). The request body must contain a publish-style packument payload, including version @@ -113,7 +112,6 @@ paths: approved, or deleted by authorized maintainers. ## Requirements - - Package MUST already exist, or the authenticated publisher MUST be permitted to create it (staging the first version creates a new package on approval) - User MUST be authenticated with a valid npm token - Request body MUST include required fields in `StagedPackumentRequest` operationId: stagePackageVersion @@ -330,8 +328,7 @@ paths: This endpoint moves a version from staged review state to a published package version. On success, the staged record will be processed and the package version will become - installable. If the staged version is the first version of a package that does not - yet exist, approving it creates the new package in the registry. + installable. ## Requirements - `stage-id` MUST reference an existing staged package version @@ -807,4 +804,4 @@ components: internal_error: summary: "Internal Server Error" value: - message: "An error occurred while processing your request." \ No newline at end of file + message: "An error occurred while processing your request."