Release SDK

Tag-driven TypeScript SDK release: regenerate types from openapi/v1.yaml, build, tag sdk-v* → GitHub Actions runs npm publish. The SDK is a thin wrapper over openapi-fetch (~5KB runtime dep) — most of the value is the typed API surface generated from the spec.

Default stance

The OpenAPI spec is the source of truth. Never edit sdks/typescript/src/types.ts manually. It's regenerated from openapi/v1.yaml and overwritten by the build. Hand-edits get clobbered and the SDK drifts from the API.

Run preflight before tagging. ./scripts/release-sdk.sh --check runs steps 1-4 (regen, build, typecheck, npm auth) without tagging or publishing. Use it after every spec change to verify everything is wired before committing to a release.

Releases happen from main. Same rule as CLI — main is the releasable branch.

Use this skill when

Publishing the SDK, bumping the version, after OpenAPI spec changes that need a new SDK, debugging a failed npm publish, or setting up SDK distribution for a new fork.

Quick release

./scripts/release-sdk.sh 0.2.0

This:

1. Regenerates types from openapi/v1.yaml.
2. Builds the SDK (ESM + CJS + DTS via tsup).
3. Typechecks.
4. Validates npm auth (NPM_TOKEN).
5. Creates and pushes the sdk-v0.2.0 git tag.
6. Monitors the GitHub Actions release workflow.
7. Verifies the package appears on npm.

Preflight only

./scripts/release-sdk.sh --check

Steps 1-4 without tagging or publishing. The right move after every OpenAPI change.

Dry run

./scripts/release-sdk.sh 0.2.0 --dry-run

Builds, sets version, runs npm pack --dry-run. Shows what would publish.

After OpenAPI changes

bun run generate:sdk           # regenerate sdks/typescript/src/types.ts
cd sdks/typescript && bun install && bun run build
git add sdks/typescript/src/types.ts
git commit -m "chore: regen SDK types"
./scripts/release-sdk.sh 0.x.y  # ship

What the pipeline does

git tag sdk-v0.2.0 → push → GitHub Actions:
  1. bun install + generate types
  2. Verify types match spec (git diff --exit-code)
  3. Build SDK (tsup → ESM + CJS + DTS)
  4. Set version from tag
  5. npm publish --access public

The "verify types match spec" gate fails the build if types.ts drifts from the spec — this is what catches the "I forgot to regen" mistake.

Hard rules

• Don't edit sdks/typescript/src/types.ts. Generated. Overwritten. Lost.
• Don't tag without running preflight first. A broken build wastes the tag.
• Don't reuse versions. npm rejects duplicate versions; you'll have to bump anyway.
• Don't release from a branch other than main.
• Don't break public exports without a major version bump. The SDK is consumed by external integrations.

Package details

Field	Value
Package	@unionstreetai/seed-sdk (rename per fork)
Registry	npm public
Formats	ESM + CJS + DTS
Runtime dep	openapi-fetch (~5KB)
Tag pattern	sdk-v{MAJOR}.{MINOR}.{PATCH}
CI secret	NPM_TOKEN (GitHub org secret)

Initial release for a new fork

1. Update sdks/typescript/package.json — change name to @yourorg/your-sdk.
2. Update sdks/typescript/src/index.ts — change default baseUrl.
3. bun run generate:sdk.
4. Verify NPM_TOKEN available.
5. Preflight: ./scripts/release-sdk.sh --check.
6. First release: ./scripts/release-sdk.sh 0.1.0.

Version conventions

• 0.x.y — pre-1.0, breaking changes allowed between minor versions.
• MAJOR.MINOR.PATCH (no v prefix in the version; the tag adds sdk-v).
• SDK version is independent of CLI version (v* tags). They can ship at different cadences.

Troubleshooting

Symptom	Fix
"Types are stale" in CI	Spec changed but types.ts wasn't regenerated. Run bun run generate:sdk, commit.
npm publish 403	NPM_TOKEN expired or missing. gh secret list --org UnionStreetAI | grep NPM.
Package name conflict	Rename in sdks/typescript/package.json. Use scoped (@org/name).
Verify-types gate fails	Local bun run generate:sdk produces a diff. Commit it.

Where things live

File	Purpose
openapi/v1.yaml	Spec — source of truth
sdks/typescript/src/types.ts	Generated — never edit
sdks/typescript/src/index.ts	Public exports + default baseUrl
sdks/typescript/package.json	Package metadata (name, version)
sdks/typescript/AGENTS.md	SDK architecture
scripts/release-sdk.sh	Release entrypoint
.github/workflows/release-sdk.yml	GitHub Actions workflow
SECRETS.md	Credential management

Auxiliary content

• references/original-guide.md — full canonical guide with pipeline details, troubleshooting, fork checklist
• references/graph.md — handoff to add-api-endpoint, run-quality-gates, promote-deployment
• scripts/release-sdk-check.sh — preflight runner; same as release-sdk.sh --check
• assets/sdk-release-checklist.md — pre-release checklist (regen, diff review, version bump, npm verify)
• assets/evals/basic.json — eval cases for skill regression