Skip to content

Sync Robot schemas from API2 and keep CLI signing payloads stable - #666

Open
kvz wants to merge 12 commits into
mainfrom
alphalib-261119
Open

kvz wants to merge 12 commits into
mainfrom
alphalib-261119

Conversation

@kvz

@kvz kvz commented Nov 19, 2026

Copy link
Copy Markdown
Member

Type-breaking contract sync (proposed: minor for @transloadit/node, transloadit, @transloadit/types, @transloadit/zod; patch for @transloadit/mcp-server). Parsed /file/serve, /image/generate and /transloadit/import Instructions gain required download, inpainting and return_file_stubs; parsed /video/merge framerate can be undefined; /document/split pages can contain numbers; provider adds elevenlabs; Robot unions and name enums add /document/watermark; imageGenerateModelIdentifiers adds two models; Robot metadata replaces applyCommunityPlanMediaTrim; runtimeStackVersions.imagemagick literal types change. Draft: the release decision is the maintainers'.

Why

The Robot schemas in this repository describe what the Transloadit API accepts and returns. They had fallen behind the API: a new Robot (/document/watermark), the ElevenLabs provider, image inpainting controls, per-speaker subtitle colors, Storage asset search and upgraded ImageMagick stacks were missing, so the SDK's types, linter and CLI rejected or mistyped Instructions the API accepts.

What

  • Contract sync (first commit): packages/node/src/alphalib updated from API2. 41 files, +914 / −77.
  • auth signature and templates sync keep emitting what the previous release emitted for input it accepted. These two commands serialize default-filled Steps, so new contract defaults would otherwise have changed signed params and synced Template files, for example writing inpainting: "best_effort" over a stored Template's "strict". One documented map next to the serializer (previousStepDefaults, to be removed in the next major):
    • adds no inpainting, download or return_file_stubs;
    • still adds framerate: '1/5' to /video/merge and imagemagick_stack: 'v2.0.10' where a Step sets neither (both are still accepted by the contract; the API runs v2.0.10 on v2.0.11 and may return a deprecation warning);
    • forwards the five parameters new to this contract exactly as written, unvalidated, as before;
    • adds no source_language default for the new elevenlabs provider, so its language detection stays on.
  • listStoredAssets() now sends search. An empty, null or omitted search lists everything as before; other invalid values throw before the request. Non-object arguments are rejected as before.
  • Docs and changeset: intent command reference and READMEs regenerated; the changeset lists every type-breaking change.
  • biome.json is unchanged from main.

Size: 55 files, +1,746 / −100. Outside the synced schemas: SDK code and config 6 files (+98 / −8), tests 4 files (+638), changeset (+78), generated docs 3 files.

Type-breaking changes

Verified by building declarations for main and this branch and diffing them. Each has a Type-breaking: bullet in the changeset with who is affected and how to adapt.

  1. Parsed /file/serve Instructions always contain download (default false).
  2. Parsed /image/generate Instructions always contain inpainting (default 'best_effort').
  3. Parsed /transloadit/import Instructions always contain return_file_stubs (default false).
  4. Parsed /video/merge framerate can be undefined (the parse-time default is gone).
  5. /document/split pages also accepts positive integers.
  6. /speech/transcribe and /text/speak provider can be elevenlabs.
  7. Robot unions and Robot name enums include /document/watermark.
  8. imageGenerateModelIdentifiers includes openai/gpt-image-2.6-flare and openai/gpt-image-2.6-sunburst.
  9. Robot metadata: applyCommunityPlanMediaTrim is replaced by planMediaTrim and planWatermarkOutput.
  10. runtimeStackVersions.imagemagick: default is 'v2.0.11', valid is ['v2.0.11', 'v3.0.2'], and the deprecated targets moved accordingly.

No input type accepts less.

Runtime behavior that does change

Stated in the changeset; per CONTRIBUTING.md this is contract validation, not SDK surface:

  • assemblies create --steps, assemblies replay --steps, templates create, templates modify and run now validate the five new parameters instead of forwarding them with an "Unrecognized step parameters" warning. For example download: null is rejected and download: 'false' is sent as false.
  • auth signature and templates sync can now accept input the previous release rejected where the contract widened, for example /document/split with pages: 5.
  • listStoredAssets() with a non-empty search now filters; earlier releases dropped it.

Tests

  • Golden test: the same Steps through auth signature and templates sync produce byte-identical signature params, createTemplate params and written Template files as the previous release (fixture generated from main, including null values, quoted booleans and empty arrays for the new parameters). It failed on the sync commit and passes now.
  • Explicit caller values for the affected parameters pass through unchanged.
  • listStoredAssets: empty, null, real and invalid search; options objects with prototype getters; array and null arguments; a type test for search: null.
  • yarn verify:full and yarn check pass in a clean copy (1,201 node unit tests). yarn parity:transloadit fails here as it does on main: its checked-in fingerprint predates the current release.
  • e2e tests need API credentials and were not run locally.

Review notes

  • Three rounds of automated multi-model review on the local diff. Round 1 found the payload change, the search regression, an incomplete changeset and stale docs; round 2 found that parameters new to the contract were being validated and coerced in the two legacy serializers, and the ElevenLabs language default; round 3 found argument-shape and type regressions in listStoredAssets and changeset precision. All are addressed above; the last fixes have not had another round.
  • Six synced code comments that described server internals were reworded upstream and match here. Four more are borderline and left as synced: the planMediaTrim / planWatermarkOutput JSDoc, "isolated PDF processor" in /document/watermark, the inpainting "boundary" wording, and "Default file-count ceiling enforced per processing or import Job".

🤖 Claimed by kvz on framework1/node-sdk since 2026-11-19 · resume: claude --resume d38be187-7c9b-4ff3-9d1a-6a15c9743991

kvz added 12 commits November 19, 2026 07:43
The sync expanded single-line arrays in biome.json without changing any
setting, and Biome 2.4.16 rejects the expanded file.
The API reworded these comments after the snapshot this sync copied, so the
next sync would otherwise bring the same change again.
Both commands emit default-filled Steps, so the synced contract would change
signed params and synced Templates for unchanged input: new inpainting,
download and return_file_stubs defaults, no framerate for /video/merge and a
newer default ImageMagick stack. Within this major they keep emitting what
6.9.1 emitted; explicit values pass through unchanged. The golden fixture is
recorded from 6.9.1 with dummy credentials.
Earlier releases dropped search before sending. The contract now sends it and
rejects an empty one, so an empty value keeps listing everything instead of
throwing before the request.
List every type-breaking change found by diffing the built declarations,
the additive exports, the Storage search handling and the defaults that
auth signature and templates sync keep emitting. The SDK accepts the older
ImageMagick stacks unchanged rather than aliasing them.
…alizers

6.9.1 forwarded download, inpainting, credentials, return_file_stubs and
speaker_colors as unknown keys, unvalidated and uncoerced. auth signature and
templates sync now do the same instead of rejecting null values, skipping
Template files or turning quoted booleans into booleans. They also stop
filling in the en-US source_language for ElevenLabs, which detects the
language when it is omitted. Other commands keep validating the new
parameters. The new parameters no longer trigger the unrecognized-parameter
warning, since the contract now documents them.
Destructuring the rest of the options read every enumerable getter and lost
inherited prefix and limit values whenever search was empty. Read the
declared fields as the schema parse in 6.9.1 did, and treat a null search
like an omitted one.
Describe which new parameters auth signature and templates sync forward
unchanged, the validation other commands now apply to them, the Storage
search limits, what API2 does with deprecated ImageMagick stacks, and the
changed deprecated stack literal types. Keep provider keys in Template
Credentials rather than presenting them as Step parameters.
…arch type

Reading the declared fields first sent a workspace-wide listing for an array
and threw a TypeError for null; 6.9.1 rejected both with the schema's
ZodError. Non-objects now reach the schema unchanged. The method's input
type also accepts search: null, which it treats as no filter and which
compiled when earlier releases ignored the field.
…earch

Name every command that now validates the new parameters, limit the
unchanged-output promise to input the previous release accepted, and list
the search values that are rejected before sending.
@kvz kvz self-assigned this Nov 19, 2026
@kvz
kvz marked this pull request as ready for review November 19, 2026 19:16
@kvz
kvz requested a review from tim-kos November 19, 2026 19:16

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant