Add experimental contract-generated ordinary API client

[kvz]

Why

Exercise the API2 canonical contract in a maintained SDK, rather than treating a generated OpenAPI probe as the finished product. This adds an experimental low-level client without replacing existing upload, tus or polling APIs.

Changes

• Generate all 37 canonical ordinary HTTP methods and their input/result/error wire types directly from API2's serialized contract.json.
• Add Transloadit.contract() and the @transloadit/node/contract entrypoint. Preserve existing methods, endpoint prefixes, timeouts and client identification.
• Sign exact serialized params with source-owned HMAC metadata; support explicit bearer and Basic token calls, query/form/DELETE/multipart bodies, optional/null/false/zero values and runtime-derived built-in Template IDs.
• Preserve caller-owned upload constraints while managing credentials internally. Require HTTPS outside loopback, reject redirects, and bound response decoding.
• Keep exhaustive target/category coverage and exact contract digest alongside generated output. Unsupported feature/TUS surfaces remain visible gaps.

Scope and verification

The namespace is experimental and single-attempt: legacy gotRetry/maxRetries policies are not inherited. It is not a lifecycle/tus replacement or SDK release. Types describe wire shapes, not a complete runtime JSON Schema validator.

Native wire tests pass, including fail-first council regressions. Final yarn check and yarn verify:full pass after the second council review reported no issues. Exact-head CI is fully green for 30cb8807dab7b8098ba8eb5c53635c84e08b98cc, including Node 20/22/24, both verification jobs, E2E, build, release dry run, Supabase Edge and the Next.js fixture.

API2's cross-repository canary fetches exact source commits and hashes, deletes/regenerates outputs, strict-compiles with exactOptionalPropertyTypes, and exercises owned devdock resources. It passes with this native source, including built-in Template list/get and multipart file digests. No production credentials are used by that canary.

Generated files must be changed through API2 contracts sdks --target typescript, never edited here. Maintainer pointers and the source contract SHA are committed.

Companion PRs

• Producer: https://github.com/transloadit/api2/pull/9252
• Go consumer: Add native contract-generated ordinary API client go-sdk#47

Land the producer first. No SDK release or deployment is part of these PRs.

The shared review checklist, findings/dispositions and footprint receipt are maintained in API2's repodocs/prompts/2026-09-25-sdk-contract.md, alongside the canonical living program document. There were no open GitHub review threads at the final SDK review checkpoint.

[kvz]

Verification footprint for 30cb8807dab7b8098ba8eb5c53635c84e08b98cc against 34970b60c770a34c3dc227ad9ecb1ec9283ecd77:

799 authored additions; 29,488 generated additions; 2 deletions. Generated classifications and destructive regeneration procedure are recorded in the shared API2 receipt and maintainer guide. Generated lines are not a claim of native/runtime proof; both SDK CI and API2's local-native acceptance passed separately.

Raw canonical numstat (additions, deletions, path):

9	0	.changeset/contract-ordinary-api.md
1	0	.gitattributes
2	1	biome.json
36	0	packages/node/README.md
1	0	packages/node/package.json
20	1	packages/node/src/Transloadit.ts
297	0	packages/node/src/contractTransport.ts
13485	0	packages/node/src/generated-contract/client.ts
15894	0	packages/node/src/generated-contract/coverage.json
45	0	packages/node/src/generated-contract/manifest.json
27	0	packages/node/src/generated-contract/wire-vectors.json
162	0	packages/node/test/contractCanary.ts
271	0	packages/node/test/unit/contract-client.test.ts
36	0	packages/transloadit/README.md
1	0	packages/transloadit/package.json

[kvz]

Final source footprint and review receipt

The approved first-party SDK slice is implemented. Existing SDK entrypoints remain intact; the new namespaces are experimental. No SDK release, deployment or merge was performed.

Repository	Base	Final source head	Authored additions	Generated additions	Deletions	Files
API2	c449a7b1f871e12e30a2a544fce1739187d83cf8	8e601e6ffd274fb9f7c00032a3e2b30b3cd0f3ae	2,993	398	143	27
Node SDK	34970b60c770a34c3dc227ad9ecb1ec9283ecd77	30cb8807dab7b8098ba8eb5c53635c84e08b98cc	799	29,488	2	15
Go SDK	b567a3eefef5ce3e74767ba239cb00cbaf33ac2c	1897a050f4ba658787abbd9e113c2468c03f0ba0	1,363	84,283	1	11
Total			5,155	114,169	146	53

Measured with the canonical text/Myers/no-renames/no-indent-heuristic numstat command from the living document. Generated ownership: API2's generated contract; each SDK's client/manifest/coverage/vectors; Node's existing legacy-package README/package projection. All native transport, tests, documentation and receipt additions count as authored. The conservative historical authored lower bound is now 59,141, not a fully reconciled program total or an additional footprint authorization. The last API2 increment is the targeted cold-artifact test-budget correction and its CI receipt; production and generated SDK bytes are unchanged.

All council findings have dispositions and fail-first evidence in API2's repodocs/prompts/2026-09-25-sdk-contract.md (six producer, five Go, two Node rounds). Final guards are deliberately narrow and fail closed. Full yarn check, exact-byte generation checks, native wire/race/vet/example checks, actual Go 1.15 tests and both devdock SDK suites pass.

All three exact-head CI runs are now green: API2 36161865722, Node 36136692611, and Go 36153479049. The prescribed API2 watcher finished with all checks passed on September 25 at 17:34 UTC. The generator suite passed in 2.8 minutes under coverage and the actual native SDK server canary in 30.5 seconds. API2 changed-line coverage is 93.62% (514/549); the unchanged 80% gate passed. No review threads were open at this final checkpoint.

The green API2 run also reports two already nonblocking cloud-image .flaky.vitest.ts failures: Fal's visual-diff artifact upload and SVG generation's upstream 503. Their sources, fixtures, thresholds and classification are unchanged. No new test skip or failure waiver was added. The preceding related SDK regression timeout was fixed and passed, not classified as unrelated. All three PRs are ready for review; no merge, SDK release or deployment was performed.

Before landing: API2 main has since advanced by one Slack-workflow/test commit, 8e5c2e0dfe8a2e2f963324a7ec9140179945c165 (#9258). API2 is mergeable but behind and still needs review; integrate and validate that main update before merging. The exact-head CI and footprint receipt above remain unchanged. Node and Go are cleanly mergeable.

Producer first, then consumers:

• https://github.com/transloadit/api2/pull/9252
• Add experimental contract-generated ordinary API client #517
• Add native contract-generated ordinary API client go-sdk#47