# human-video-ts

The TypeScript client for the controlled human-video API (`/v1/human-video`).

`client.ts` is **generated** from the server's declared API surface and is not
edited by hand. A hand-written client is a consumer nobody wrote a contract for:
it drifts from the server a commit at a time, and the drift stays invisible
until somebody else's integration breaks.

- Surface: `apps/oshun/bff/src/generation/human-video-api-surface.ts`
- Generator: `apps/oshun/bff/src/generation/human-video-sdk-generator.ts`
- Drift guard: the generator's spec regenerates and compares against this file,
  so adding an endpoint without regenerating fails a test.

## What the generated methods carry

Three things the surface knows, which a naive client drops:

- **Idempotency.** Every mutation sends a key by default. A caller who forgets
  one pays for a second render on a timeout, and the key is bound to the request
  body, so a retry with a changed body is refused rather than silently replaying
  the first response.
- **Preconditions in the type.** A deciding method — approving, releasing,
  correcting — takes `ifMatch` as a required parameter. Not a runtime check: a
  client that discovers at runtime it needed an ETag has already made the call.
- **Retractions take no `ifMatch` at all.** Withdrawing a consent, withdrawing a
  release and deleting an asset are deliberately unguarded, so nobody can pass a
  stale ETag and have a takedown refused.

## Two things worth reading before you integrate

**"Complete" is not "ready."** The provider reporting `completed` means the
render finished — not that sync, exact speech or identity were checked. Those
run afterwards and some takes fail every one of them. Wait for a stage with a
decision in it: `awaiting-review`, `releasable`, `cancelled`, `expired`.

**Cancelling a submitted render recovers nothing.** There is no cancel endpoint
upstream; the render finishes on the provider's hardware and is billed. Cancel
stops us waiting and prevents release. That is why cancellation is its own verb
and there is no `DELETE` on a job.

## Examples

| Example                                | What it shows                                                           |
| -------------------------------------- | ----------------------------------------------------------------------- |
| `examples/exact-audio-active-scene.ts` | supply and approve the exact audio, then perform to it                  |
| `examples/multi-reference-cast.ts`     | build a reference set and read its findings before spending             |
| `examples/multi-speaker-dialogue.ts`   | a two-hander with per-line speaker binding                              |
| `examples/polling-and-webhooks.ts`     | poll with backoff; verify a webhook; treat the webhook as the fast path |
| `examples/shot-regeneration.ts`        | preview what a regeneration invalidates, then accept the losses         |
