@omelhorsite/sdk 0.2.0 → 0.4.0

package/dist/types/resources/tools/captions.d.ts

@@ -37,9 +37,31 @@
  * Read {@link CaptionsNamespace.quota} before uploading, and again once the
  * window is known: the second check is the exact one, and the server refuses a
  * window that would cross the ceiling rather than truncating it.
+ *
+ * **The 250 MiB ceiling is not reachable through {@link CaptionsNamespace.create}.**
+ * Cloudflare rejects any request body over 100 MB with a 413 of its own before
+ * Rails ever sees it, so the backend also exposes a three-call chunked upload -
+ * `POST /caption_jobs/uploads` opens a session and returns a signed
+ * `upload_token` plus a `part_size` (32 MiB), `POST /caption_jobs/uploads/parts?offset=`
+ * streams each raw part under an `X-Upload-Token` header, and
+ * `POST /caption_jobs/uploads/finish` probes the assembled file and creates the
+ * row. {@link CaptionsNamespace.upload} drives whichever of the two a given
+ * file needs, so step 1 is one call again: under
+ * {@link CAPTION_CHUNKED_THRESHOLD} it IS `create`, above it it is
+ * {@link CaptionsNamespace.createChunked}, and both answer the same
+ * `"uploaded"` row. Reach for `create` directly only when the file is known to
+ * be small, and for the three methods under `upload` only to drive the parts
+ * yourself.
+ *
+ * One caveat that is the backend's and not the SDK's: the three chunked routes
+ * carry no `oauth_scope` declaration, and scopes there are default-deny, so an
+ * OAuth access token gets `403 insufficient_scope` on all three (and on
+ * `fonts`). A session or a first-party bearer token reaches them; a token
+ * minted through the OIDC provider does not, and for one of those only
+ * `create` is open.
  */
 import { Resource } from "../../http";
-import type { FileInput, Id, Progress, RequestOptions } from "../../types";
+import type { FileInput, Id, OperationOptions, Progress, RequestOptions } from "../../types";
 import { type SecondsQuota, type ToolCaptcha, type ToolRecord, type ToolRunOptions } from "./index";
 /**
  * Lifecycle of a caption job. Wider than {@link ToolStatus} because the job
@@ -76,6 +98,13 @@ export interface CaptionWord {
     /** Seconds from the video start. Must be `>= t0`. */
     readonly t1: number;
 }
+/**
+ * An RGB triple, each channel clamped to `[0, 255]` server-side.
+ *
+ * The controller reads the key only when the array has EXACTLY three entries;
+ * two or four is dropped in silence, which costs a whole render to discover.
+ */
+export type CaptionRgb = readonly [number, number, number] | readonly number[];
 /**
  * Look of the burned-in captions.
  *
@@ -89,8 +118,22 @@ export interface CaptionWord {
  * back as the nearest end of it rather than as a 400.
  */
 export interface CaptionStyle {
+    /**
+     * A font KEY from {@link CaptionsNamespace.fonts}, never a path: the sidecar
+     * resolves the key against the faces installed in its image, so a caller
+     * cannot point the renderer at a file. Must match `/\A[a-z0-9_-]{1,40}\z/`;
+     * anything else is dropped and the renderer uses its own default.
+     */
+    readonly font?: string;
     /** Font size as a fraction of the video height. Clamped to `[0.03, 0.09]`. */
     readonly fontscale?: number;
+    /**
+     * Outline thickness as a fraction of the font size. Clamped to `[0, 0.3]`,
+     * and `0` is a legitimate choice meaning no outline at all - which is why
+     * the controller reads this key whenever it is PRESENT rather than when it
+     * is truthy, unlike every other numeric key here.
+     */
+    readonly stroke_factor?: number;
     /** Vertical placement, `0` top to `1` bottom. Clamped to `[0.3, 0.9]`. */
     readonly pos?: number;
     /** Words on screen at once. Clamped to `[1, 6]`. */
@@ -103,32 +146,64 @@ export interface CaptionStyle {
     readonly preset?: "veryfast" | "medium" | "slow";
     /**
      * Colour of the word currently being sung, as `[r, g, b]`, each clamped to
-     * `[0, 255]`. Ignored unless it has exactly three entries.
+     * `[0, 255]`. Named after its default rather than after its job. Ignored
+     * unless the array has exactly three entries.
      */
-    readonly yellow?: readonly [number, number, number] | readonly number[];
+    readonly yellow?: CaptionRgb;
+    /** Colour of the words that are not highlighted. Same three-entry rule. */
+    readonly white?: CaptionRgb;
+    /** Colour of the outline. Same three-entry rule. */
+    readonly stroke?: CaptionRgb;
     readonly [key: string]: unknown;
 }
-/** A caption job. */
+/**
+ * A caption job.
+ *
+ * Every route that answers with one - create, the chunked upload's finish
+ * call, show, transcribe and render - renders the `:extended` view, so every
+ * key below is present on every response.
+ *
+ * Five of the columns are `NOT NULL` with a numeric default, so `width`,
+ * `height`, `fps`, `duration` and `transcribed_seconds` are always real
+ * numbers. On a row whose upload has only just been probed they are the probed
+ * values; the sidecar's precise metadata overwrites them a moment later.
+ */
 export interface CaptionJob extends ToolRecord {
     readonly status: CaptionStatus;
+    /** Original upload name. The controller substitutes `"video.mp4"` for a
+     * blank one, so this is never empty in practice. */
     readonly filename: string;
-    readonly width?: number | null;
-    readonly height?: number | null;
-    readonly fps?: number | null;
-    /** Seconds of video, probed at upload. */
-    readonly duration?: number | null;
-    readonly language?: string | null;
-    /** The transcribed window, seconds from the video start. */
-    readonly window_start?: number | null;
-    readonly window_end?: number | null;
-    /** Seconds charged against the quota so far. Accumulates across windows. */
-    readonly transcribed_seconds?: number | null;
-    /** Timed words. Present from `"transcribed"` onwards. */
-    readonly words?: CaptionWord[] | null;
-    /** What the renderer is doing right now. `null` unless rendering. */
-    readonly render_stage?: string | null;
-    /** The finished video, once the status is `"complete"`. */
-    readonly output_url?: string | null;
+    /** Pixels. `NOT NULL DEFAULT 0`, so `0` means "not probed yet", not unknown. */
+    readonly width: number;
+    readonly height: number;
+    /** `NOT NULL DEFAULT 0.0`. */
+    readonly fps: number;
+    /** Seconds of video, probed at upload. `NOT NULL DEFAULT 0.0`. */
+    readonly duration: number;
+    /** Language of the last transcribe call, `"auto"` included. `null` before the first. */
+    readonly language: string | null;
+    /** The transcribed window, seconds from the video start. `null` before the first transcribe. */
+    readonly window_start: number | null;
+    readonly window_end: number | null;
+    /**
+     * Seconds charged against the quota so far, accumulated across every window
+     * transcribed on this job. `NOT NULL DEFAULT 0`.
+     */
+    readonly transcribed_seconds: number;
+    /**
+     * Timed words, from `"transcribed"` onwards.
+     *
+     * `null` and not `[]` when there are none: the column is `NOT NULL DEFAULT
+     * '[]'`, but the blueprint renders `words.presence`, and `[].presence` is
+     * `nil` in Ruby. So an empty list arrives as `null`, and the key is present
+     * either way.
+     */
+    readonly words: CaptionWord[] | null;
+    /** What the renderer is doing right now, read live off the sidecar. `null`
+     * unless the status is `"rendering"`. */
+    readonly render_stage: string | null;
+    /** Signed URL of the finished video once complete and attached, `null` otherwise. */
+    readonly output_url: string | null;
 }
 /** Arguments for uploading a video. */
 export interface CreateCaptionJobInput extends ToolCaptcha {
@@ -168,6 +243,190 @@ export interface RenderCaptionInput {
  * nothing.
  */
 export declare function captionProgress(record: CaptionJob): Progress;
+/**
+ * Largest file the backend will accept, chunked or not: 250 MiB exactly.
+ *
+ * Mirrors `CaptionJobsController::MAX_FILE_SIZE`. Not checked client-side on
+ * purpose - the server owns the number, and the chunked path finds out in one
+ * cheap round trip because {@link CaptionsNamespace.startUpload} is given the
+ * size before a single byte moves.
+ */
+export declare const CAPTION_MAX_UPLOAD_BYTES: number;
+/**
+ * Where {@link CaptionsNamespace.upload} stops using one `POST` and starts
+ * using the three-call path: 64 MiB.
+ *
+ * This is a CLIENT-SIDE choice, not a protocol constant, and it is the same
+ * one the web tool makes (`frontend/services/CaptionsService.ts`). Cloudflare's
+ * ceiling is on the whole request, and a `multipart/form-data` envelope rides
+ * on top of the file's own bytes, so the switch sits well under the cap rather
+ * than at it. Below it a single request is one round trip and one probe; above
+ * it a single request is a 413 that says nothing useful.
+ *
+ * Override it per call with {@link UploadCaptionVideoInput.chunkedThreshold} -
+ * for instance `0`, to exercise the chunked path on a small file.
+ */
+export declare const CAPTION_CHUNKED_THRESHOLD: number;
+/**
+ * Part size, 32 MiB. The same number as the storage tier's, and by coincidence
+ * rather than by sharing: `CaptionJobsController::PART_SIZE` copied it.
+ *
+ * It is BOTH the size the server reports in the session and the ceiling the
+ * server validates each part against, and the controller validates against its
+ * own constant rather than against the session it minted. See
+ * {@link resolveCaptionPartSize} for what that means when the two disagree.
+ */
+export declare const CAPTION_PART_SIZE: number;
+/**
+ * Parts in flight at once by default.
+ *
+ * Three, as the web tool uses. A single sequential stream leaves a home
+ * connection idle between round trips; three fills it without holding an unfair
+ * number of the API's threads, and every part in flight parks one Rails thread
+ * for as long as it takes to arrive - these bytes pass THROUGH Rails on their
+ * way to the sidecar, unlike a storage upload.
+ */
+export declare const CAPTION_UPLOAD_CONCURRENCY = 3;
+/**
+ * How long an upload session stays usable: six hours, from
+ * `CaptionJobsController::UPLOAD_TOKEN_TTL`.
+ *
+ * The window for a resume. Past it the token verifies as expired and every
+ * call answers 400 "Invalid or expired upload session", parts already sent
+ * included - there is no way to re-mint a token for a half-uploaded file,
+ * because the new session would carry a new job id.
+ */
+export declare const CAPTION_UPLOAD_TOKEN_TTL_MS: number;
+/**
+ * What `POST /caption_jobs/uploads` answers.
+ *
+ * `upload_token` is a CREDENTIAL: a signed `(job_id, size, filename)` triple,
+ * and the only thing standing between a stranger and writing bytes into this
+ * job. It is not a job id and there is no job yet - the row is created by
+ * `finish`, out of the id sealed inside the token - so it cannot be handed to
+ * {@link CaptionsNamespace.get} and there is nothing to poll until then.
+ */
+export interface CaptionUploadSession {
+    /** Signed session token. Goes in the `X-Upload-Token` header on both later calls. */
+    readonly upload_token: string;
+    /** Bytes per part, and the ceiling the server validates each part against. */
+    readonly part_size: number;
+    /** `ceil(size / part_size)`, so a caller can size a progress bar before slicing. */
+    readonly part_count: number;
+}
+/** Arguments for opening a chunked upload session. */
+export interface StartCaptionUploadInput extends ToolCaptcha {
+    /**
+     * EXACT byte length of the file.
+     *
+     * Not an estimate and not a ceiling: the number is sealed into the token and
+     * every part is checked against it, so a declared size below the real one
+     * makes the last part fail with 400 "Part exceeds declared size", and a
+     * declared size above it leaves the sidecar waiting for bytes that never
+     * come and `finish` probing a truncated file.
+     */
+    readonly size: number;
+    /** Stored name. Trimmed to 255 characters, and `"video.mp4"` when blank. */
+    readonly filename?: string;
+}
+/**
+ * Arguments for {@link CaptionsNamespace.upload} and
+ * {@link CaptionsNamespace.createChunked}.
+ */
+export interface UploadCaptionVideoInput extends ToolCaptcha {
+    /**
+     * The video.
+     *
+     * For the chunked path this has to be sliceable, which means real bytes: a
+     * `Blob`/`File` on the web or in Bun, a `Uint8Array` anywhere. A React
+     * Native `{ uri, name, type }` descriptor is NOT sliceable - see the note on
+     * {@link CaptionsNamespace.createChunked}.
+     */
+    readonly video: FileInput;
+    /** Overrides {@link CAPTION_CHUNKED_THRESHOLD} for this call only. */
+    readonly chunkedThreshold?: number;
+    /** Overrides {@link CAPTION_UPLOAD_CONCURRENCY} for this call only. */
+    readonly concurrency?: number;
+    /**
+     * Continues an upload that was cut off, rather than starting a new one.
+     *
+     * Present or not, this is what decides the path: a resume always goes
+     * chunked, whatever the file's size and threshold say. The session is only
+     * good for {@link CAPTION_UPLOAD_TOKEN_TTL_MS} from when it was minted.
+     */
+    readonly resume?: CaptionUploadResume;
+}
+/** A chunked upload picked up where it stopped. */
+export interface CaptionUploadResume {
+    /**
+     * The session from the interrupted attempt, or just its `upload_token`.
+     *
+     * Keep the whole session where you can. A bare token has no `part_size`, so
+     * the driver slices with {@link CAPTION_PART_SIZE} instead - which is the
+     * server's own number today, and therefore the same offsets, but it stops
+     * being true the day the backend changes it.
+     */
+    readonly session: CaptionUploadSession | string;
+    /**
+     * Byte offsets already accepted, so their bytes are not sent twice.
+     *
+     * Offsets, not part numbers, and they must be multiples of the session's
+     * `part_size` - they are the same numbers the driver sliced with, which is
+     * what {@link UploadCaptionOptions.onPart} reports. Anything else is simply
+     * not in the list of offsets to skip and its part is sent again, which costs
+     * bandwidth and breaks nothing.
+     *
+     * Omit it to re-send every part. That is always correct, just slower: a part
+     * is written at its own offset, so sending it twice is idempotent.
+     */
+    readonly uploaded?: readonly number[];
+}
+/**
+ * Options for the two driving methods: everything a request takes, plus the
+ * two callbacks that make a 250 MiB upload watchable.
+ */
+export interface UploadCaptionOptions extends OperationOptions {
+    /**
+     * Called after each part the server has ACCEPTED, with the offset it was
+     * written at and its length.
+     *
+     * The point of it is resuming: collect these offsets, and hand them back as
+     * {@link CaptionUploadResume.uploaded} if the run is cut off.
+     */
+    readonly onPart?: (offset: number, length: number) => void;
+}
+/**
+ * Byte length of a video about to be uploaded, or `undefined` when it cannot be
+ * known without reading it.
+ *
+ * `undefined` has exactly two causes, and both matter: a `ReadableStream`,
+ * which has no length until it is drained, and a React Native picker that
+ * reported no `size` for a `content://` URI. Neither can be sized cheaply, so
+ * {@link CaptionsNamespace.upload} sends them down the single-request path and
+ * lets the server judge - which is the right guess for a phone pick and the
+ * wrong one for a 200 MiB stream, so pass `video.size` when you know it.
+ */
+export declare function captionUploadSize(video: FileInput): number | undefined;
+/**
+ * The size to slice parts with, from what the session reported.
+ *
+ * Follows the storage driver's rule - slice with the number the SERVER named,
+ * never with the SDK's copy of it - but with a ceiling the storage tier does
+ * not need, because the two ends of this protocol read the number from
+ * different places. `start_upload` reports `PART_SIZE` from the session it is
+ * minting, while `upload_part` validates `length <= PART_SIZE` against the
+ * CONTROLLER CONSTANT. They are the same constant today and can only disagree
+ * mid-deploy, and the disagreement is one-sided: honouring a larger reported
+ * size would make every part a 400 "Invalid part", while capping at the size
+ * this SDK knows the validator uses only sends smaller parts, which is always
+ * legal. So the reported number wins downwards and loses upwards.
+ *
+ * A missing, zero or nonsense `part_size` falls back to
+ * {@link CAPTION_PART_SIZE}. Note the web tool falls back to its 64 MiB
+ * threshold instead, which is above the validator's ceiling - a fallback that
+ * would reject every part if it ever fired.
+ */
+export declare function resolveCaptionPartSize(reported: number | undefined): number;
 /** The `captions` tool, reachable as `oms.tools.captions`. */
 export declare class CaptionsNamespace extends Resource {
     /**
@@ -184,6 +443,24 @@ export declare class CaptionsNamespace extends Resource {
      * ceiling rather than truncating it.
      */
     quota(options?: RequestOptions): Promise<SecondsQuota>;
+    /**
+     * `GET /caption_jobs/fonts` - the font KEYS the renderer has, for
+     * {@link CaptionStyle.font}.
+     *
+     * Plain strings, not objects and not display names: they are the keys the
+     * sidecar resolves against the faces installed in its image, which is the
+     * whole reason a caller cannot pass a path.
+     *
+     * The controller answers `{ fonts: [...] }`; this unwraps it. It also
+     * NEVER fails: a sidecar that is down or slow is caught and answered as an
+     * empty list with a 200, so `[]` means "could not ask right now" just as
+     * much as it means "no fonts", and the two are not distinguishable. Do not
+     * treat an empty answer as a reason to refuse a render - omitting `font`
+     * lets the renderer use its own default.
+     *
+     * Cached server-side for ten minutes, so polling it buys nothing.
+     */
+    fonts(options?: RequestOptions): Promise<string[]>;
     /**
      * `POST /caption_jobs` - step 1. Uploads the video and probes it.
      *
@@ -308,6 +585,156 @@ export declare class CaptionsNamespace extends Resource {
      * @throws {OmsError} explaining which of the three reasons there is no URL.
      */
     outputUrl(record: CaptionJob): string;
+    /**
+     * Step 1 for any video, picking the path by size. Prefer this over
+     * {@link create} unless you control what the caller can hand you.
+     *
+     * Under {@link CAPTION_CHUNKED_THRESHOLD} it is exactly {@link create}: one
+     * `POST`, one probe, one round trip. At or above it, it is
+     * {@link createChunked}. The answer is the same `"uploaded"` row either way,
+     * because `finish` and `create` render the same `:extended` view - so the
+     * caller's step 2 does not need to know which path ran.
+     *
+     * The size comes from {@link captionUploadSize}, which cannot always find
+     * one: a `ReadableStream` and some React Native picks have no length until
+     * they are read. Those go down the single-request path, which is right for a
+     * phone pick and wrong for a large stream, so pass `video.size` whenever you
+     * know it rather than letting a 413 teach you.
+     *
+     * `onProgress` is honest about which path ran and reports COMPLETED
+     * transfers, never bytes handed to the runtime - the whole file as one tick
+     * on the direct path, one tick per 32 MiB part on the chunked one. `fetch`
+     * has no upload-progress event in any of the three runtimes this SDK targets;
+     * see the module note in `storage/upload.ts` for why neither XHR nor a
+     * counting stream body is the answer inside the core.
+     *
+     * Rate limit: the direct path and the chunked path's opening call both count
+     * against the expensive-tools bucket, 20 a minute shared with every other
+     * tool. The parts and the finish do not.
+     */
+    upload(input: UploadCaptionVideoInput, options?: UploadCaptionOptions): Promise<CaptionJob>;
+    /**
+     * Step 1 in three calls, for a video too big for one request.
+     *
+     * Opens a session, sends the parts (three at a time by default, in whatever
+     * order the pool finishes them), then finishes - and `finish` is what probes
+     * the assembled file and creates the row, so this resolves with the same
+     * `"uploaded"` row {@link create} would have answered.
+     *
+     * Nothing is cleaned up on failure and nothing needs to be: the controller
+     * deletes the sidecar's copy itself when `finish` rejects the file, and a run
+     * abandoned before `finish` leaves only a partial file on the sidecar's disk
+     * with no row pointing at it. There is no client-visible way to abort a
+     * session - the backend has `CaptionsClient.abort_upload` but no route onto
+     * it - so an abandoned upload is simply abandoned.
+     *
+     * **React Native cannot take this path.** The bytes have to be sliced, and a
+     * picked `{ uri, name, type }` is a handle into the device that only a native
+     * module can open - so this throws for one rather than uploading an empty
+     * file with a 200 on it. What works on a phone is {@link create} (the
+     * transport hands the descriptor to RN's own `FormData` verbatim and the
+     * platform streams it off disk), which caps out at Cloudflare's ~100 MB. Past
+     * that the only ways through are reading the file into a `Uint8Array` first -
+     * Expo's `new File(uri).bytes()`, which means the whole video in the JS heap,
+     * so it is not a plan for 250 MiB - or shrinking the video on the device.
+     *
+     * Resuming: pass {@link CaptionUploadResume} with the earlier session and the
+     * offsets {@link UploadCaptionOptions.onPart} reported. Skipping is only an
+     * optimisation, because a part is written at its own offset and re-sending it
+     * is idempotent; the session itself expires after
+     * {@link CAPTION_UPLOAD_TOKEN_TTL_MS}.
+     *
+     * @throws {OmsError} `invalid_request` for a React Native descriptor, or for
+     *   an empty file - which the server would answer as "Invalid size", after a
+     *   round trip that had nothing to carry.
+     * @throws {OmsApiError} 413 over 250 MiB, raised by the opening call before
+     *   any bytes move; 400 from `finish` when the assembled file does not decode
+     *   or runs past 20 minutes; 400 "Invalid or expired upload session" once the
+     *   token is six hours old.
+     * @throws {OmsAuthError} 401 when anonymous and the captcha is missing or
+     *   bad. It is checked when the session is opened, not when the bytes land,
+     *   so a bad token costs one round trip rather than the whole upload.
+     */
+    createChunked(input: UploadCaptionVideoInput, options?: UploadCaptionOptions): Promise<CaptionJob>;
+    /**
+     * `POST /caption_jobs/uploads` - opens a chunked upload session.
+     *
+     * Public so a caller can drive the three calls itself, which is the supported
+     * way to get byte-level progress: wrap XHR (or a native uploader) around
+     * {@link uploadPart}'s job and keep the session and the finish from here.
+     *
+     * Three things happen here and nowhere else in the flow: the captcha is
+     * verified, the 250 MiB ceiling is checked against the DECLARED size, and the
+     * job id is minted - early, because the sidecar needs an id to write parts
+     * under and the row cannot exist until the file is whole. So a session is not
+     * a job: nothing is in the database yet, and {@link get} has nothing to find
+     * until {@link finishUpload} returns.
+     *
+     * NOT retried by default. A replay opens a SECOND sidecar upload under a
+     * second job id and hands back a second token, and the first is then orphaned
+     * on the sidecar's disk with no route to abort it.
+     *
+     * Rate limit: 20 a minute, shared with every other expensive tool - the same
+     * bucket `POST /caption_jobs` counts against, since this is its twin.
+     *
+     * @throws {OmsApiError} 413 when `size` is over 250 MiB, 400 when it is not
+     *   positive, 503 when the captions sidecar is down.
+     * @throws {OmsAuthError} 401 when anonymous and the captcha is missing or bad.
+     * @throws {OmsQuotaError} 429 from the expensive-tools throttle. No daily
+     *   quota is spent by an upload - only a transcribed window is metered.
+     */
+    startUpload(input: StartCaptionUploadInput, options?: RequestOptions): Promise<CaptionUploadSession>;
+    /**
+     * `POST /caption_jobs/uploads/parts?offset=` - one part, as raw bytes.
+     *
+     * The body is the part itself, `application/octet-stream`, with no envelope:
+     * not a form field, not base64, not JSON. Rails never reads it into a string
+     * - it streams the request body straight through to the sidecar - so a 32 MiB
+     * part costs 32 MiB of socket rather than 32 MiB of Ruby heap, and that is
+     * why the endpoint takes bytes rather than a multipart part.
+     *
+     * RETRIED BY DEFAULT, which no other writing method in this SDK is. The
+     * server writes the part at the offset the query names, so a replay is the
+     * same bytes in the same place: there is no record to duplicate and no
+     * position to lose. Pass `retry: false` to opt out. For the same reason the
+     * parts may go in any order and in parallel, and a part sent twice is not an
+     * error.
+     *
+     * `part` must not be longer than the session's `part_size` (see
+     * {@link resolveCaptionPartSize}) and `offset + part.length` must not run
+     * past the size declared when the session was opened. Both are 400s whose
+     * text does not distinguish them from each other.
+     *
+     * @param session The session from {@link startUpload}, or its token.
+     * @param offset Byte offset of this part in the whole file, from `0`.
+     * @returns The byte count the sidecar acknowledged, from `{ received }`.
+     * @throws {OmsApiError} 400 for an over-long part, an offset past the
+     *   declared size, or a token that has expired (six hours); 503 when the
+     *   sidecar is down.
+     */
+    uploadPart(session: CaptionUploadSession | string, offset: number, part: Blob | Uint8Array, options?: RequestOptions): Promise<number>;
+    /**
+     * `POST /caption_jobs/uploads/finish` - assembles, probes and creates the row.
+     *
+     * This is where a chunked upload becomes a job: the sidecar joins the parts,
+     * ffprobe reads the result, and only then is a `CaptionJob` written, with the
+     * id that was sealed into the token at the start. The answer is the same
+     * `:extended` view {@link create} returns, in `"uploaded"`.
+     *
+     * It is also where a bad upload is caught. A file that does not decode, or
+     * one over 20 minutes, is a 400 - and the controller deletes the sidecar's
+     * copy before answering, so there is nothing to clean up and nothing to
+     * retry: the parts are gone with it.
+     *
+     * NOT retried by default. The row is created with a fixed id, so a replay
+     * that lands after a lost answer fails on the id already existing and reports
+     * a 400 for an upload that worked.
+     *
+     * @throws {OmsApiError} 400 when the assembled file cannot be read or runs
+     *   past 20 minutes, 400 "Invalid or expired upload session" for a token that
+     *   is over six hours old, 503 when the sidecar is down.
+     */
+    finishUpload(session: CaptionUploadSession | string, options?: RequestOptions): Promise<CaptionJob>;
     /**
      * Waits for a started step to settle, reusing the one polling loop.
      *

package/dist/types/resources/tools/downloader.d.ts

@@ -394,4 +394,25 @@ export declare class DownloaderNamespace extends Resource {
      * @throws {OmsApiError} exactly as {@link download}.
      */
     downloadFile(id: Id, options?: RequestOptions): Promise<FileOutput>;
+    /**
+     * The unauthenticated URL of the file endpoint. Pure string building, no
+     * request.
+     *
+     * Deliberately does NOT carry a credential, which makes it useless for
+     * handing to an `<a download>` or a `<video src>`: the route needs one, and
+     * an anonymous request to it is a 401. It is here so a caller can log or
+     * display the address, and so the shape of the endpoint is documented
+     * somewhere other than inside {@link downloadFile}.
+     *
+     * The web app builds a *usable* browser URL by appending its session token
+     * as a `?token=` query parameter. The SDK will not do that: the transport
+     * holds the token so it can put it in an `Authorization` header, and copying
+     * it into a URL puts it in browser history, in the Referer, and in every
+     * proxy log between here and the API. A host that genuinely needs a
+     * browser-followable link should call {@link downloadFile} and hand the
+     * blob to a local object URL instead.
+     *
+     * Remember the endpoint is ONE SHOT whichever way it is reached.
+     */
+    fileUrl(id: Id): string;
 }

package/dist/types/resources/tools/index.d.ts

@@ -57,30 +57,72 @@ export * from "./vocalSeparation";
 export type ToolStatus = "pending" | "processing" | "complete" | "failed";
 /** Terminal states. A row in one of these will never change again. */
 export declare const TOOL_TERMINAL_STATUSES: readonly ToolStatus[];
-/** Fields every tool row carries. */
+/**
+ * Fields every tool row carries.
+ *
+ * All six blueprints in the family declare `status`, `error`, `finished_at`,
+ * `user_id` and `ip_address` in their DEFAULT view, and every route that
+ * answers with a tool row renders `:extended`, which inherits the default
+ * view's fields. So those five keys are always present; four of them hold a
+ * nullable column and are `null` rather than missing.
+ *
+ * `progress_percent` is the exception and is optional on purpose: it is an
+ * `:extended`-only field on FOUR of the six - transcription, vocal separation,
+ * captions and jumpstyle, the ones with a sidecar to ask - and does not exist
+ * at all on upscale or background removal, whose progress lives on the {@link
+ * Job} row instead. `toolProgress` reads it defensively for exactly that
+ * reason.
+ */
 export interface ToolRecord extends BaseRecord {
     readonly status: ToolStatus | string;
-    /** Failure message, set once the status is `"failed"`. */
-    readonly error?: string | null;
-    readonly finished_at?: Timestamp | null;
-    readonly user_id?: string | null;
-    /** Set instead of `user_id` for an anonymous run. */
-    readonly ip_address?: string | null;
-    /** Percentage the sidecar reports while running. `null` when idle or done. */
+    /** Failure message, set once the status is `"failed"`. `null` otherwise. */
+    readonly error: string | null;
+    /** Set when the run reached a terminal state; `null` before that. */
+    readonly finished_at: Timestamp | null;
+    /** The owner, or `null` for an anonymous run. */
+    readonly user_id: string | null;
+    /**
+     * The address an anonymous run was started from, and `null` for a run with
+     * an owner - the controllers write one or the other, never both, and the
+     * models validate that at least one is set.
+     *
+     * It is also the credential for an anonymous run: `accessible_by?` matches
+     * this against the reader's own address, which is why picking up an
+     * anonymous run from a different network is a 401.
+     */
+    readonly ip_address: string | null;
+    /**
+     * Percentage the sidecar reports while running, `null` when idle or done -
+     * and absent entirely on upscale and background removal, which have no such
+     * field. See the note on this interface.
+     */
     readonly progress_percent?: number | null;
 }
 /**
  * Handle for polling an enqueued run.
  *
- * `job_id` and `watch_token` come back from the tools that enqueue through the
- * generic job table (upscale, background removal). The token is what lets an
- * anonymous caller poll `GET /jobs/:id`; the other tools are polled by reading
- * their own row instead.
+ * Both keys come back from the two tools that enqueue through the generic job
+ * table (upscale, background removal), and BOTH are always present on their
+ * create response: the controllers merge them onto the rendered row
+ * unconditionally. `watch_token` is nullable rather than absent, because
+ * `signed_id` is called on a tracking row that may not have been found.
+ *
+ * The token is what lets an anonymous caller poll `GET /jobs/:id`. The other
+ * five tools are polled by reading their own row and answer neither key, which
+ * is why this is a separate interface mixed into their `Created` types rather
+ * than part of {@link ToolRecord}.
  */
 export interface ToolJobHandle {
-    readonly job_id?: string;
-    /** Signed, scoped to this one job. Required when anonymous. */
-    readonly watch_token?: string;
+    readonly job_id: string;
+    /**
+     * Signed and scoped to this one job, and expiring with the tool's retention
+     * window. Required when anonymous.
+     *
+     * `null` when the tracking row could not be read back after enqueue, which
+     * leaves an anonymous caller with no way to poll at all - the job id alone
+     * is a 404 without a credential.
+     */
+    readonly watch_token: string | null;
 }
 /** Mixed into every create input: the anonymous caller's captcha. */
 export interface ToolCaptcha {