chore: resync the production spec and document the two generators

.changeset/production-spec-pagination-secrets.md

@@ -0,0 +1,9 @@
+---
+'@runpod/typescript-api-sdk': minor
+---
+
+Resync the vendored production spec and regenerate the types. Adds cursor
+pagination on the list endpoints (`cursor` and `limit` query parameters, and a
+`pagination` block carrying `nextCursor` and `hasNextPage` on the response) and
+the account-secrets paths. Both are additive upstream, so existing calls keep
+their current types.

.github/workflows/spec-drift.yml

@@ -43,6 +43,25 @@ jobs:
       - run: pnpm test
       - run: pnpm test:package
       - run: pnpm test:examples
+      # The update PR carries its own version bump and changelog, so merging it
+      # releases. Main's pending changesets are consumed into the same version.
+      - name: Version the spec update
+        env:
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          if git diff --quiet -- spec/openapi.yaml src/generated/schema.ts; then
+            echo 'No spec change; nothing to version.'
+            exit 0
+          fi
+          cat > .changeset/production-spec-update.md <<EOF
+          ---
+          '@runpod/typescript-api-sdk': minor
+          ---
+
+          Refresh the vendored production spec as of $(date -u +%Y-%m-%d) and
+          regenerate the types. Validation run: $RUN_URL
+          EOF
+          pnpm changeset:version
       # Run even with no diff so the action can close a superseded update PR.
       - name: Create or update the spec review PR
         id: update-pr
@@ -53,6 +72,10 @@ jobs:
           add-paths: |
             spec/openapi.yaml
             src/generated/schema.ts
+            .changeset
+            package.json
+            CHANGELOG.md
+            pnpm-lock.yaml
           commit-message: 'chore(spec): refresh production API contract'
           title: 'chore(spec): review production API contract update'
           body: |
@@ -67,11 +90,12 @@ jobs:
             Check those results before merging.
 
             Review removed or changed operations, request/response types, and compatibility.
-            Classify the eventual version bump explicitly; a spec diff is not necessarily a patch.
+            This PR bumps the version as a minor release and writes the changelog.
+            **Merging it publishes that version to npm** and creates the tag and GitHub release.
             This branch is regenerated from the default branch: put durable fixes there,
             rather than editing the bot branch.
 
-            No automatic merge, version bump, tag, GitHub release, or npm publication.
+            No automatic merge.
       - name: Run the full runtime matrix on the generated branch
         if: steps.update-pr.outputs.pull-request-number != '' && steps.update-pr.outputs.pull-request-operation != 'closed'
         env:

.github/workflows/version.yml

@@ -54,9 +54,11 @@ jobs:
           branch=$(gh pr view "$VERSION_PR" --json headRefName --jq .headRefName)
           gh workflow run ci.yml --ref "$branch"
 
+  # Evaluated on every push: release.mjs only approves the merge commit of a
+  # release-branch PR, and a spec PR merge can publish while changesets from
+  # other PRs are still pending.
   eligibility:
     needs: version
-    if: needs.version.outputs.has_changesets == 'false'
     runs-on: ubuntu-latest
     outputs:
       eligible: ${{ steps.plan.outputs.eligible }}

docs/development.md

@@ -48,10 +48,15 @@ fail the run before updating the PR.
 
 The workflow explicitly dispatches `SDK checks` on the update branch for Node
 20/22/24, rather than relying on bot-generated PR events. Review that matrix
-before merging. Neither workflow merges, bumps versions, tags, or publishes.
-Review the compatibility impact of spec changes before choosing a version bump.
-Bot-branch edits can be overwritten on the next refresh; land durable fixes on
-the default branch instead.
+before merging. When the spec changed, the update PR also carries a minor
+version bump and changelog entry, consuming any changesets pending on the
+default branch. Merging it publishes that version (see
+[releases](releases.md)). Nothing merges automatically, so review the
+compatibility impact before merging. If the change needs a bigger bump than
+minor, land a changeset with that bump on the default branch and dispatch the
+workflow again; Changesets takes the highest pending bump. Bot-branch edits can
+be overwritten on the next refresh; land durable fixes on the default branch
+instead.
 
 To enable automated update PRs, allow GitHub Actions to create pull requests.
 The update job needs `contents: write`, `pull-requests: write`, and `actions: write`.
@@ -69,6 +74,41 @@ encodings that need a different runtime serializer.
 CI verifies generated freshness, Python and TypeScript tests, and installed
 ESM/CJS consumers on Node 20, 22, and 24. The separate SDK release workflow validates the same matrix before publishing.
 
+## The other generator: runpod-mcp
+
+Two repositories generate from the same `https://api.runpod.io/v2/openapi.json`,
+and they produce different things for different consumers. Knowing which is
+which saves an afternoon when an API change looks half-applied.
+
+This repository generates **types**. `spec/openapi.yaml` becomes
+`src/generated/schema.ts`, a file of TypeScript declarations with no runtime
+code. It is what lets `sdk.GET("/v2/pods")` know that the path exists, which
+query parameters it accepts, and what shape comes back. Everything around it
+(retries, deadlines, rate-limit metadata, the SSE iterator) is written by hand.
+
+The [MCP server](https://github.com/runpod/runpod-mcp) generates **tool
+definitions**. Its own vendored copy of the spec becomes
+`src/specgen/generated/tools.gen.ts`, an array of plain objects: tool name,
+description written for a language model, JSON Schema for the arguments, and
+the method and path to call. That array is data read at runtime to answer
+`tools/list` and to route a call, not types erased at compile time.
+
+The two are stacked rather than parallel: the MCP server's generated tools
+describe what to call, and the call itself goes through this SDK, which it
+pins as a devDependency and bundles into its build. So an upstream API change
+usually has to be taken up **twice, in order**:
+
+1. Here: pull the spec, regenerate, bump the version, and publish. The daily
+   automation's spec PR carries the version bump, so merging it publishes.
+2. In runpod-mcp: pull the spec and regenerate its tools, and bump the pinned
+   SDK version when its hand-written tools need the new types.
+
+Step 2's generated half picks up new paths and parameters on its own. Its
+hand-written tools do not, and they are the ones that call this SDK, so they
+stay on the old contract until a published version carries the new types. A
+resync that stops after step 1, or after step 2's regeneration alone, leaves
+part of the surface stale while looking complete.
+
 ## Release preparation
 
 Use [Changesets](releases.md) to record release notes and compatibility changes.

docs/releases.md

@@ -48,7 +48,11 @@ PR, then explicitly dispatches SDK CI on that PR. Review the Node 20/22/24 check
 and manually squash-merge the release PR when ready to release.
 
 Publication requires the workflow commit to be the merge commit of a release PR
-from `changeset-release/main` in the same repository. Ordinary commits, the
+from `changeset-release/main` or `automation/production-spec` in the same
+repository. The daily spec update PR carries its own minor bump and changelog,
+so merging it releases without a separate version PR, even if changesets from
+other PRs landed on `main` after the bot last refreshed the branch. Those go
+into the next version PR. Ordinary commits, the
 initial repository import, and open release PRs do not publish. The workflow
 revalidates Node 20/22/24, checks the packed package, publishes to npm, and creates
 a `v<version>` tag and GitHub release. A failure stops the remaining steps.

scripts/release.mjs

@@ -2,10 +2,14 @@ import { execFileSync } from 'node:child_process';
 import { appendFileSync, readFileSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 
+// Branches whose PRs carry a version bump: the Changesets release PR and the
+// daily spec update PR.
+const releaseBranches = ['changeset-release/main', 'automation/production-spec'];
+
 export function approvedRelease(pr, repository, sha) {
   return Boolean(pr.merged_at && pr.merge_commit_sha === sha &&
     pr.base?.ref === 'main' && pr.base?.repo?.full_name === repository &&
-    pr.head?.ref === 'changeset-release/main' && pr.head?.repo?.full_name === repository);
+    releaseBranches.includes(pr.head?.ref) && pr.head?.repo?.full_name === repository);
 }
 
 export function releaseVersion(pkg, changelog) {

scripts/test_release.mjs

@@ -10,10 +10,12 @@ const pr = { merged_at: '2026-01-01', merge_commit_sha: sha,
 
 test('only the merged release PR commit is approved, including manual retries', () => {
   assert.equal(approvedRelease(pr, repository, sha), true);
+  assert.equal(approvedRelease({ ...pr, head: { ...pr.head, ref: 'automation/production-spec' } }, repository, sha), true);
   for (const rejected of [
     { ...pr, merged_at: null }, { ...pr, merge_commit_sha: 'b'.repeat(40) },
     { ...pr, head: { ...pr.head, ref: 'feature' } },
     { ...pr, head: { ...pr.head, repo: { full_name: 'fork/sdk' } } },
+    { ...pr, head: { ref: 'automation/production-spec', repo: { full_name: 'fork/sdk' } } },
     { ...pr, base: { ...pr.base, ref: 'development' } },
   ]) assert.equal(approvedRelease(rejected, repository, sha), false);
 });