Document SDK and API contract versioning (#585)

* Document SDK contract versioning and require SDK-breaking majors

* Publish dependency guidance in both SDK names

Author: kvz

.ai/skills/release/SKILL.md

@@ -17,12 +17,18 @@ description: Checklist for releasing packages from this monorepo (code PR -> Ver
       2. Run `corepack yarn verify:full` locally once before pushing.
          - This catches wrapper sync drift early and still runs the deeper repo checks.
       3. If `verify` / `verify:full` fails with transloadit wrapper drift, run `node scripts/prepare-transloadit.ts`, commit the tracked `packages/transloadit` updates, and re-run `corepack yarn verify:full`.
-   4. If you add a changeset for `@transloadit/node`, also add a similar changeset for `@transloadit/mcp-server` if it could affect its workings. The chances are, they are, since the latter is mostly a thin wrapper around the former.
+   4. Classify changes using [the versioning policy](../../../CONTRIBUTING.md#versioning-policy).
+      - API2 contract type/schema changes ship in minors, with a `Contract:` summary and a
+        `Type-breaking:` line per type break. Description-only syncs are patches; pre-1.0 package
+        exceptions follow the policy.
+      - Every major changeset must contain a nonempty `SDK-breaking:` line naming the SDK surface
+        it breaks. `yarn lint:changesets` enforces this for each file.
+   5. If you add a changeset for `@transloadit/node`, also add a similar changeset for `@transloadit/mcp-server` if it could affect its workings. The chances are, they are, since the latter is mostly a thin wrapper around the former.
       - This repo enforces a one-way coupling: node releases should also publish a new mcp-server version (but mcp-server releases do not require node releases).
       - `yarn check`/`yarn verify` will fail fast if you forget.
-   5. Commit + push branch
-   6. Open PR, wait for CI green
-   7. Squash-merge the PR
+   6. Commit + push branch
+   7. Open PR, wait for CI green
+   8. Squash-merge the PR
 
    Notes:
    1. When creating PRs with `gh pr create` from a shell, avoid unescaped backticks in the `--body` string.

.changeset/contract-versioning.md

@@ -0,0 +1,10 @@
+---
+'@transloadit/node': patch
+'transloadit': patch
+'@transloadit/types': patch
+'@transloadit/zod': patch
+'@transloadit/mcp-server': patch
+---
+
+Document how SDK exports follow strict SemVer while API contract types and schemas follow API2
+in minor releases, with guidance on dependency ranges and narrowing parsed output.

CONTRIBUTING.md

@@ -110,6 +110,106 @@ The `packages/transloadit` folder is a generated legacy wrapper. Tracked files u
 yarn pack
 ```
 
+## Versioning policy
+
+These packages mirror a live API. When API2 changes a Robot parameter, every customer gets that
+change at once, whatever SDK version they installed. A major for each such change would give us
+dozens of majors a year and teach users to ignore them. So we version two surfaces differently:
+the **SDK surface** follows strict SemVer, and the **API contract** follows the API.
+
+### SDK surface: strict SemVer
+
+A breaking change to any of these requires a major:
+
+- Package names, `exports` entry points and subpaths, module format and the supported Node.js
+  range. We support TypeScript releases from the last two years, like DefinitelyTyped; dropping an
+  older one is not breaking.
+- Names of exported symbols, generated ones included. When API2 renames something, add the new
+  name, keep the old one as a `@deprecated` alias, and remove it in the next major.
+- The `Transloadit` client: constructor options, method names and parameters, return wrappers,
+  error classes and their documented fields, and retry, polling and upload behavior.
+- Hand-written helpers and types, such as `prepareInputFiles`, the signing helpers and
+  `StoredImageReceipt`, and everything in `@transloadit/utils`.
+- CLI command names, hand-written flags, exit codes, credential resolution order and `--json`
+  output.
+- The helper functions and supported Zod versions of `@transloadit/zod`.
+- What the SDK, CLI and MCP server send, accept or reject at runtime for unchanged caller code,
+  apart from explicit API-contract schema parsing and lint validation described below.
+
+### API contract: follows API2
+
+Types and schemas synced from alphalib describe what the Transloadit API accepts and returns today:
+Robot parameters (names, optionality, nullability, defaults, enums, limits and refinements),
+Assembly Instructions, Assembly status and other response types, error-code lists, Robot
+metadata, model lists, descriptions and examples, lint rules that mirror API validation, and CLI
+intent flags generated from Robot parameters. Their shapes, and Zod internals such as wrapper
+classes, `.shape` and parse-time defaults, follow the API rather than SemVer.
+
+### Bump rules
+
+| Change | Bump |
+| --- | --- |
+| SDK bug fix, documentation, or a contract sync that only changes descriptions or examples | patch |
+| New SDK feature or export, or an additive contract sync: new Robot, optional parameter, enum value or response field | minor |
+| Type-breaking contract sync: an input type accepts less, or an output type returns more (`null`, `undefined`, a wider union, a removed parse-time default) | minor, with a `Type-breaking:` line |
+| Breaking change to the SDK surface | major |
+| Contract sync that changes SDK runtime behavior for unchanged code, for example the CLI rejecting instructions the API still accepts | major, or a warning in a minor first |
+
+- Stable-package patch releases never contain contract type or validation changes, or type-breaking
+  changes, so a `~` range only brings fixes. We do not backport fixes to older minors.
+- A contract sync may still justify a major if it also breaks the SDK surface and the README quick
+  start or `examples/` need edits to compile. Name that SDK break in the changeset; a contract-only
+  type break still ships in a minor.
+- SDK majors are batched: deprecate in a minor, collect removals in one tracking issue, and remove
+  them together in the next major.
+- Pre-1.0 packages (`@transloadit/mcp-server`, `@transloadit/notify-url-relay` and the alpha
+  `@transloadit/viewer`) use a minor for breaking changes and a patch for everything else. Contract
+  syncs are patches there unless their tools, CLI or exports change.
+
+### Writing contract changesets
+
+- Bump `@transloadit/node`, `transloadit`, `@transloadit/types` and `@transloadit/zod` by `minor`,
+  or by `patch` for description-only syncs. Add `@transloadit/mcp-server` as described under
+  Releasing.
+- Start the summary with `Contract:` and link the API2 pull requests being synced.
+- Add one `Type-breaking:` bullet per type-breaking change: what changed, who is affected (authors
+  of Assembly Instructions, or readers of parsed output and API responses) and how to adapt.
+- A contract-only sync is never `major`. Every `major` changeset contains an `SDK-breaking:` line
+  that names the SDK surface it breaks.
+
+```md
+---
+'@transloadit/node': minor
+'transloadit': minor
+'@transloadit/types': minor
+'@transloadit/zod': minor
+'@transloadit/mcp-server': patch
+---
+
+Contract: sync Robot schemas from API2 (transloadit/api2#9897, transloadit/api2#9938).
+
+- Type-breaking: `/video/subtitle` no longer fills in `font`, `font_size` and `bold` while
+  parsing. Parsed values (`RobotVideoSubtitleInstructions`, `AssemblyInstructions`,
+  `schema.parse()`) can be `undefined`; the API still applies Arial, 16 and `false`, or the
+  `social` style’s defaults. Instruction input types are unchanged.
+- Type-breaking: `/video/thumbs` accepts `null` for `offsets`, `width` and `height`, so parsed
+  values can be `null`. Treat `null` like an omitted value.
+```
+
+### What we tell consumers
+
+Repeat this in the package READMEs:
+
+- Commit your lockfile and type-check dependency update PRs. Type-breaking contract changes show
+  up there, not in production.
+- For the stable SDK packages, use `~` ranges for stable types: patch releases never change contract
+  types. Use `^` to follow the API as it evolves. Pre-1.0 packages follow the exceptions above.
+- Type the instructions you write with the input types, for example
+  `const params = { steps } satisfies CreateAssemblyParams`. API changes usually widen these.
+- Narrow fields from responses and parsed output before using them (`null`, `undefined`, unknown
+  strings).
+- Do not depend on Zod internals such as wrapper classes, `.shape` or parse-time defaults.
+
 ## Releasing
 
 Only maintainers can make releases. Releases to [npm](https://www.npmjs.com) are automated using GitHub Actions and Changesets (including the legacy `transloadit` package).

docs/fingerprint/transloadit-baseline.json

@@ -1,13 +1,13 @@
 {
   "packageDir": "packages/transloadit",
   "tarball": {
-    "filename": "transloadit-6.1.1.tgz",
-    "sizeBytes": 1406530,
-    "sha256": "ef663482bdedeec0d556dcd485ac547d0725e929139288a4f32d89964d5bab4b"
+    "filename": "transloadit-6.1.2.tgz",
+    "sizeBytes": 1406977,
+    "sha256": "f45d608797e6963f62066cc1a4e16babb1e04305674b3136f7b6dde2caf25313"
   },
   "packageJson": {
     "name": "transloadit",
-    "version": "6.1.1",
+    "version": "6.1.2",
     "main": "./dist/Transloadit.js",
     "exports": {
       ".": "./dist/Transloadit.js",
@@ -1034,7 +1034,7 @@
     {
       "path": "package.json",
       "sizeBytes": 2770,
-      "sha256": "465e0c3528f85fe43ef3eb993679477d7196e25f441e5f5ceb2415bcab891d6e"
+      "sha256": "1b7049ee8de43da6af0fcfe735a162dec54f907f995b703efb2680fe8145259c"
     },
     {
       "path": "dist/alphalib/types/robots/_ai-models.d.ts.map",
@@ -3053,8 +3053,8 @@
     },
     {
       "path": "README.md",
-      "sizeBytes": 112372,
-      "sha256": "aff8599d46547bdbfbcbe3f84233776f2f74522a14128a75b6bce742b2a7cf79"
+      "sizeBytes": 113193,
+      "sha256": "beef7dc51ec496758f54f740a88deb4a1b0260ac16a227c4283018ff79cf620e"
     },
     {
       "path": "dist/alphalib/types/robots/_ai-models.d.ts",

docs/fingerprint/transloadit-baseline.package.json

@@ -1,6 +1,6 @@
 {
   "name": "transloadit",
-  "version": "6.1.1",
+  "version": "6.1.2",
   "description": "Node.js SDK for Transloadit",
   "homepage": "https://github.com/transloadit/node-sdk/tree/main/packages/node",
   "bugs": {

package.json

@@ -30,7 +30,7 @@
     "test:img:fixture": "node scripts/test-img-next-fixture.ts",
     "test:init:fixture": "node scripts/test-init-example.ts",
     "test:sdk:edge": "node scripts/test-sdk-edge.ts",
-    "test:unit": "vitest run ./scripts/fingerprint-pack.test.ts ./scripts/withProcess.test.ts ./scripts/img-next-fixture.test.ts ./scripts/knip.test.ts ./scripts/publish-release.test.ts ./scripts/release-run.test.ts ./scripts/sdk-edge.test.ts ./scripts/sync-robot-index.test.ts && yarn workspace @transloadit/utils test:unit && yarn workspace @transloadit/viewer test:unit && yarn workspace @transloadit/node test:unit && yarn workspace @transloadit/mcp-server test:unit && yarn workspace @transloadit/types test:unit && yarn workspace @transloadit/zod test:unit && yarn workspace @transloadit/notify-url-relay test:unit",
+    "test:unit": "vitest run ./scripts/fingerprint-pack.test.ts ./scripts/guard-changesets.test.ts ./scripts/withProcess.test.ts ./scripts/img-next-fixture.test.ts ./scripts/knip.test.ts ./scripts/publish-release.test.ts ./scripts/release-run.test.ts ./scripts/sdk-edge.test.ts ./scripts/sync-robot-index.test.ts && yarn workspace @transloadit/utils test:unit && yarn workspace @transloadit/viewer test:unit && yarn workspace @transloadit/node test:unit && yarn workspace @transloadit/mcp-server test:unit && yarn workspace @transloadit/types test:unit && yarn workspace @transloadit/zod test:unit && yarn workspace @transloadit/notify-url-relay test:unit",
     "test:types": "yarn workspace @transloadit/zod test:types",
     "test:widget-visual": "node scripts/test-mcp-widget-visual.ts",
     "test:widget-visual:update": "node scripts/test-mcp-widget-visual.ts --update --states-dir /tmp/widget-states",
@@ -45,6 +45,7 @@
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
     "@changesets/cli": "^2.31.0",
+    "@changesets/parse": "^0.4.3",
     "@types/node": "^25.8.0",
     "@vitest/coverage-v8": "^4.1.6",
     "execa": "^9.6.1",

packages/node/README.md

@@ -45,6 +45,20 @@ npm install --save @transloadit/node
 The legacy npm package name `transloadit` is kept as an alias for backward compatibility, but
 `@transloadit/node` is the canonical package name.
 
+## Versioning and dependency updates
+
+The SDK surface follows strict SemVer. API contract types and schemas follow API2 and can change
+in minor releases, including type-breaking updates. See the
+[versioning policy](https://github.com/transloadit/node-sdk/blob/main/CONTRIBUTING.md#versioning-policy).
+
+- Commit your lockfile and type-check dependency update PRs.
+- Use `~` ranges for stable contract types within a minor; patch releases do not change contract
+  types. Use `^` to follow the API as it evolves.
+- Use input types for instructions you write, for example
+  `const params = { steps } satisfies CreateAssemblyParams`.
+- Narrow fields from responses and parsed output before use (`null`, `undefined`, unknown strings).
+- Do not depend on Zod internals such as wrapper classes, `.shape` or parse-time defaults.
+
 ## Command Line Interface (CLI)
 
 This package includes a full-featured CLI for interacting with Transloadit from your terminal.

packages/transloadit/README.md

@@ -45,6 +45,20 @@ npm install --save @transloadit/node
 The legacy npm package name `transloadit` is kept as an alias for backward compatibility, but
 `@transloadit/node` is the canonical package name.
 
+## Versioning and dependency updates
+
+The SDK surface follows strict SemVer. API contract types and schemas follow API2 and can change
+in minor releases, including type-breaking updates. See the
+[versioning policy](https://github.com/transloadit/node-sdk/blob/main/CONTRIBUTING.md#versioning-policy).
+
+- Commit your lockfile and type-check dependency update PRs.
+- Use `~` ranges for stable contract types within a minor; patch releases do not change contract
+  types. Use `^` to follow the API as it evolves.
+- Use input types for instructions you write, for example
+  `const params = { steps } satisfies CreateAssemblyParams`.
+- Narrow fields from responses and parsed output before use (`null`, `undefined`, unknown strings).
+- Do not depend on Zod internals such as wrapper classes, `.shape` or parse-time defaults.
+
 ## Command Line Interface (CLI)
 
 This package includes a full-featured CLI for interacting with Transloadit from your terminal.

packages/types/README.md

@@ -1,7 +1,15 @@
 # @transloadit/types
 
-**Stability:** This package is still relatively new and may evolve quickly.
+**Stability:** Exported names follow strict SemVer. API contract types and schemas
+follow API2 and can change in minor releases, including type-breaking updates. See the
+[versioning policy](https://github.com/transloadit/node-sdk/blob/main/CONTRIBUTING.md#versioning-policy).
+
+- Commit your lockfile and type-check dependency update PRs.
+- Use `~` ranges for stable contract types within a minor; patch releases do not change contract
+  types. Use `^` to follow the API as it evolves.
+- Use input types for instructions you write, such as `AssemblyInstructionsInput`; narrow fields
+  from responses and parsed output before use (`null`, `undefined`, unknown strings).
 
 This package provides type-only exports generated from Transloadit schemas.
 
-For the stable SDK, use the unscoped `transloadit` package.
+For the SDK client, use `@transloadit/node` or the unscoped `transloadit` package.

packages/zod/README.md

@@ -1,10 +1,20 @@
 # @transloadit/zod
 
-**Stability:** This package is still relatively new and may evolve quickly.
+**Stability:** Exported names, helper functions and supported Zod versions follow strict SemVer.
+API contract types and schemas follow API2 and can change in minor releases, including
+type-breaking updates. See the
+[versioning policy](https://github.com/transloadit/node-sdk/blob/main/CONTRIBUTING.md#versioning-policy).
+
+- Commit your lockfile and type-check dependency update PRs.
+- Use `~` ranges for stable contract types within a minor; patch releases do not change contract
+  types. Use `^` to follow the API as it evolves.
+- Use input types for instructions you write, such as `AssemblyInstructionsInput`; narrow fields
+  from responses and parsed output before use (`null`, `undefined`, unknown strings).
+- Do not depend on Zod internals such as wrapper classes, `.shape` or parse-time defaults.
 
 Exports Zod schemas derived from Transloadit types.
 
-For the stable SDK, use the unscoped `transloadit` package.
+For the SDK client, use `@transloadit/node` or the unscoped `transloadit` package.
 
 ## Migrating schema consumers