U
Union Street AI Docs
Home
HomeAdd Api EndpointDb HealthPromote DeploymentRelease CliRelease SdkRun Quality GatesSetup Product

Release SDK

Quick Release

./scripts/release-sdk.sh 0.2.0

This script:

  1. Regenerates types from openapi/v1.yaml
  2. Builds the SDK (ESM + CJS + DTS)
  3. Typechecks
  4. Validates npm auth
  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

Runs steps 1-4 without tagging or publishing. Use after spec changes to verify everything is wired correctly.

Dry Run

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

Builds, sets version, and runs npm pack --dry-run to show what would be published. Does not tag or push.

After Updating the OpenAPI Spec

When endpoints are added or changed in openapi/v1.yaml:

  1. Regenerate types: bun run generate:sdk
  2. Build: cd sdks/typescript && bun install && bun run build
  3. Commit the updated sdks/typescript/src/types.ts
  4. Release: ./scripts/release-sdk.sh 0.x.y

Do NOT edit sdks/typescript/src/types.ts manually. It's overwritten by the generator.

What the Pipeline Does

git tag sdk-v0.2.0 → push → GitHub Actions triggers:
  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

Package Details

FieldValue
Package@unionstreetai/seed-sdk (change per fork)
Registrynpm public
FormatsESM + CJS
Runtime depopenapi-fetch (~5KB)
Tag patternsdk-v{MAJOR}.{MINOR}.{PATCH}
CI secretNPM_TOKEN (GitHub org secret)

Initial Release for a New Fork

When setting up a new product forked from seed:

  1. Update sdks/typescript/package.json — change name to @yourorg/your-sdk
  2. Update sdks/typescript/src/index.ts — change default baseUrl
  3. Regenerate types: bun run generate:sdk
  4. Ensure NPM_TOKEN is available (inherited from org secret, or set per-repo)
  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
  • Semantic versioning: MAJOR.MINOR.PATCH (no v prefix in the version number; the tag adds sdk-v)
  • The SDK version is independent of the CLI version (v* tags)

Troubleshooting

"Types are stale" error in CI

The spec was updated but types.ts wasn't regenerated. Run bun run generate:sdk and commit.

npm publish 403

The NPM_TOKEN secret may be expired or missing. Check: gh secret list --org UnionStreetAI | grep NPM

Package name conflict

If the npm package name is taken, change it in sdks/typescript/package.json. Scoped packages (@org/name) are recommended.

If You're Lost