Add experimental contract-generated ordinary API client

.changeset/contract-ordinary-api.md

@@ -0,0 +1,38 @@
+---
+'@transloadit/node': minor
+'@transloadit/mcp-server': patch
+'transloadit': minor
+---
+
+Add contract-generated ordinary HTTP methods through `client.contract()` and the `/contract`
+entrypoint. The new methods support signed requests or explicit
+bearer authentication. Add explicit `waitForAssembly` and `cancelAndWaitForAssembly` workflows over
+these methods, with source-owned uploader admission, overall deadlines and terminal-status checks.
+Cancellation is one attempt on the owning uploader, never an automatically retried write.
+Add fixed-size `uploadAssemblyFile` and `resumeAssemblyFile` workflows through contract-owned tus
+bindings. Persist a private upload session before bytes are sent; a fresh client checks the file
+digest and server offset before resuming. Recover ambiguous PATCH responses without duplicating
+accepted bytes. Creation never retries. Deferred lengths and concatenation remain outside this
+experimental namespace.
+Workflow status reads retry transient network failures and HTTP 429/5xx within the overall deadline,
+honoring `Retry-After`. Waiting returns `REQUEST_ABORTED` as a finite, unsuccessful typed outcome,
+not an exception or proof that background work stopped. Explicit cancellation still reaches the
+owner once. A later status GET can confirm completion after a failed cancellation, but a repeated
+`REQUEST_ABORTED` does not hide that failure. No terminal response promises worker or billing cleanup.
+Explicitly configured proxy prefixes and loopback endpoints remain supported.
+
+Generated public types retain source documentation. Optional-only params can be omitted, JSON
+response objects fit the exported `JsonValue`, and `ContractResponseError.code` exposes recognized
+public error codes without leaking response content into messages. Add a typed end-to-end example
+and strict packed-package compilation, including the root entry point's Robot declarations.
+
+Add shared executable workflow fixtures for contract-client upload/resume/wait/cancel and local
+Smart CDN signing. Keep ordinary regression coverage for the existing public SDK. Fix its polling deadline to
+abort in-flight status requests and rate-limit retry waits, and reject late success responses as
+`POLLING_TIMED_OUT`, instead of waiting past the caller's budget. This also applies when
+`createAssembly` or `resumeAssemblyUploads` shares its remaining timeout with completion polling.
+The `contract()` adapter rounds
+positive fractional millisecond timeouts up to the next integer rather than rejecting them.
+It rejects an inherited zero request timeout rather than silently changing it to an unbounded
+request. In-flight legacy polling aborts retain got's `AbortError` classification; the polling
+deadline still uses `PollingTimeoutError`.

.gitattributes

@@ -0,0 +1 @@
+/packages/node/src/generated-contract/* linguist-generated=true

.github/workflows/ci.yml

@@ -106,6 +106,7 @@ jobs:
           node-version: 22
       - run: corepack yarn install --immutable
       - run: corepack yarn run pack
+      - run: corepack yarn test:contract-package
       - uses: actions/upload-artifact@v7
         with:
           name: package

.gitignore

@@ -25,6 +25,7 @@ packages/types/src/generated
 packages/zod/src/v3
 packages/zod/src/v4
 packages/transloadit/src
+packages/transloadit/examples/contract-workflow.ts
 packages/transloadit/README.md
 packages/transloadit/CHANGELOG.md
 packages/transloadit/LICENSE

biome.json

@@ -19,7 +19,8 @@
       "!.vscode",
       "!packages/**/dist",
       "!packages/**/node_modules",
-      "!packages/node/src/alphalib"
+      "!packages/node/src/alphalib",
+      "!packages/node/src/generated-contract"
     ]
   },
   "formatter": {

docs/prompts/2026-09-29-contract-finality.md

@@ -0,0 +1,41 @@
+# Contract workflow finality follow-up for #517
+
+Why: runtime investigation distinguished a finite client outcome from backend cleanup. The user
+approved returning typed `REQUEST_ABORTED` from ordinary waiting, while still attempting explicit
+cancellation and preserving a failed cancellation request. This is not merge/release approval.
+
+- [x] Read PR context; no outstanding review threads. Preserve existing SDK APIs and native tus safety.
+- [x] Reproduce the new lifecycle cases against the old implementation before changing it.
+- [x] Implement finite ordinary wait, explicit cancel after an aborted connection, and preservation
+      of a failed DELETE when a later GET still reports `REQUEST_ABORTED`.
+- [x] Merge latest main, including the Viewer changes and release; immutable install passes.
+- [x] Regenerate from committed API2 producer `f13c20fe24`; generated contract SHA-256
+      `a72c65901795052a96036a2fa6beed7ac1885299fb3d6dfec8a011e2efc6f819`.
+- [x] All 216 focused native/shared tests and full `yarn check` pass. Both packed package names
+      pass strict installed-consumer compilation, including exact optional properties and no
+      skipped declaration checks. The workstation Yarn wrapper selects Node 26; CI covers its
+      configured runtime matrix separately.
+- [x] Exact-head CI on `2c29613e2ad2651399a5c632ca5569b5d3de7da7`: all 11 checks pass in
+      run `36625686355`, including the Edge fixture and Node 20/22/24. The previous registry quota
+      failure and stale generated wrapper README are resolved on this head.
+- [x] Triage the completed Opus report: synchronize the generated wrapper, document that uploader
+      origins are additive, and explain that upload deadlines include hashing and persistence.
+      Correct the PR's claim that legacy behavior is unchanged: the separately tested polling
+      deadline repair also affects `createAssembly` and `resumeAssemblyUploads`. The changeset
+      already describes that behavior change.
+- [ ] Complete multi-model council. This attempt's Codex reviewer and arbiter hit provider quota;
+      the Opus report alone is not council approval. Retry when capacity is available.
+- [ ] Post-documentation checks and exact-head CI.
+
+Review dispositions: preserving the synchronous `client.contract()` API requires its runtime
+dependency; a dynamic import would change that API. Most generated source is erased types, so
+source-file size is not an import-cost measurement. Keep the opt-in subpath and existing root
+compile checks. This checklist is maintainer documentation, not shipped API/schema prose. Receipt
+field names remain an explicit next producer-policy follow-up, with real-server receipt acceptance
+already covered; do not duplicate that inventory in another test adapter.
+
+Canonical program history and cross-repository receipts remain in API2's
+`docs/prompts/2026-07-09-handover-sdks-branch-restructure.md` on `sdk-next`.
+No new live credentialed tests, merge or release in this follow-up.
+
+https://github.com/transloadit/node-sdk/pull/517

package.json

@@ -28,13 +28,14 @@
     "pack": "node scripts/pack-transloadit.ts",
     "parity:transloadit": "node scripts/prepare-transloadit.ts && node scripts/fingerprint-pack.ts packages/transloadit --ignore-scripts --quiet --out /tmp/transloadit-after.json && node scripts/verify-fingerprint.ts --current /tmp/transloadit-after.json --diff",
     "test:img:fixture": "node scripts/test-img-next-fixture.ts",
+    "test:contract-package": "node scripts/test-contract-package.ts",
     "test:sdk:edge": "node scripts/test-sdk-edge.ts",
-    "test:unit": "vitest run ./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 && 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/withProcess.test.ts ./scripts/img-next-fixture.test.ts ./scripts/knip.test.ts ./scripts/prepare-contract-dist.test.ts ./scripts/publish-release.test.ts ./scripts/release-run.test.ts ./scripts/sdk-edge.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:e2e": "yarn workspace @transloadit/node test:e2e",
     "test": "yarn workspace @transloadit/node test",
     "tsc:img": "yarn workspace @transloadit/viewer lint:ts",
-    "tsc:node": "yarn tsc:utils && node ./node_modules/typescript/bin/tsc -b packages/node/tsconfig.build.json && chmod +x packages/node/dist/cli.js",
+    "tsc:node": "yarn tsc:utils && node ./node_modules/typescript/bin/tsc -b packages/node/tsconfig.build.json && node scripts/prepare-contract-dist.ts && chmod +x packages/node/dist/cli.js",
     "tsc:types": "yarn workspace @transloadit/types generate && node ./node_modules/typescript/bin/tsc -b packages/types/tsconfig.build.json",
     "tsc:utils": "yarn workspace @transloadit/utils lint:ts",
     "tsc:zod": "yarn workspace @transloadit/zod sync && node ./node_modules/typescript/bin/tsc -b packages/zod/tsconfig.build.json"