Add bearer token support and typed Assembly Notification payloads

[varadekd]

Problem

This SDK drifts from the Transloadit API in a few concrete, verifiable ways: AssemblyInfo is missing roughly 50 fields present in the current Assembly Status schema (region, instance, websocket_url, update_stream_url, account/notify/tus-upload details, per-job error diagnostics), three of its fields (ClientAgent, ClientIp, ClientReferer) have no json tag and have therefore never populated from API responses, there's no support for the OAuth2 bearer-token flow (POST /token), and there's no typed representation of the Assembly Notification webhook payload — users currently parse and verify it by hand.

Approach

Each gap is fixed by diffing the hand-written types against the public OpenAPI spec (https://api2.transloadit.com/openapi.json) field-by-field, rather than guessing. A contract_test.go fetches that spec and asserts the /token and webhook schemas match what these types assume, so future drift fails CI instead of surfacing as a silent gap again.

We evaluated generating these types with oapi-codegen or a custom generator, but the two schemas these fixes touch are small (under 10 required fields combined) and not shaped like the other ~290 schemas in the spec (which are content-hash-named and not meant for direct codegen). A generator would be more code than it generates here, so these are hand-written, with the contract test providing the drift-detection a generator pipeline would otherwise give.

Backward compatibility

Fully additive. No existing field, method, or behavior changes shape. AssemblyInfo's new fields are appended; existing ones are untouched. AssemblyNotificationPayload and BearerToken/BearerTokenRequest are new types; IssueBearerToken and ParseAssemblyNotification are new functions. AddStep's map[string]interface{} signature is unchanged.

How to review

• assembly.go: diff review against the field list in the spec (linked in the doc comment) — mechanical, just new struct fields.
• bearer_token.go / webhook.go: the actual new logic — small, each under 60 lines.
• contract_test.go: the drift-detection mechanism; worth checking it actually asserts something meaningful (it does — run it, it hits the live spec).
• Tests mock HTTP via httptest, following the existing pattern in list_request_signature_test.go; no credentials needed for anything new.

Test evidence

gofmt, go vet, and the full test suite pass. The 11 pre-existing tests that need real TRANSLOADIT_KEY/TRANSLOADIT_SECRET are unaffected (verified identical failure set against unmodified main when run without credentials).

Spec issues found (worth reporting to Transloadit)

• Three different HMAC algorithms across the API with no documented rationale: SHA-384 for request signing, SHA-256 for Smart CDN, SHA-1 for webhook signatures.
• The Assembly Status schema has both assembly_id (snake_case, documented) and a second, undocumented assemblyId (camelCase) property, plus stray step/previousStep fields — likely legacy artifacts worth cleaning up or documenting.
• Component schema names in the spec are SHA-256 content hashes (Schema_) rather than human-readable names, which makes the spec unusable for off-the-shelf codegen tools without a remapping layer.

Follow-ups (explicitly out of scope here)

• Typed Robot parameter structs are not feasible from the public spec today — it only lists Robot names, not per-Robot parameter shapes (confirmed by exhaustive search of all 295 schemas). Separately, the maintainers already have two in-flight draft PRs (Generated endpoint markers and devdock examples #45, Add native contract-generated ordinary API client #47) building Robot typing from an internal contract system.
• FileInfo has its own drift against the spec's richer file-result shape (asset_id, sha256, thumbhash, workspace, etc.) — left untouched here to keep this PR scoped; worth a follow-up.
• SSE (update_stream_url) is exposed as an opaque string in the spec with no further schema — not enough to build typed support yet.