@omelhorsite/sdk 0.3.0 → 0.4.1

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

@@ -16,7 +16,7 @@
  * handing back a busy row would just guarantee the caller's next call is the
  * 409. Use {@link CaptionsNamespace.get} to poll a job somebody else started.
  *
- * Limits, all enforced by the backend:
+ * Limits, all enforced server-side:
  *
  * | | |
  * |---|---|
@@ -39,8 +39,8 @@
  * 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 -
+ * Any single request body over roughly 100 MB is answered 413 before the API
+ * sees it, so the API 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
@@ -53,12 +53,9 @@
  * 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.
+ * One caveat: an OAuth access token gets `403 insufficient_scope` on the three
+ * chunked routes and on `fonts`; of the upload paths, only `create` is open to
+ * one. A session token reaches them all.
  */
 import { Resource } from "../../http";
 import type { FileInput, Id, OperationOptions, Progress, RequestOptions } from "../../types";
@@ -69,7 +66,7 @@ import { type SecondsQuota, type ToolCaptcha, type ToolRecord, type ToolRunOptio
  */
 export type CaptionStatus = "uploaded" | "transcribing" | "transcribed" | "rendering" | "complete" | "failed";
 /**
- * The two statuses with a sidecar call in flight.
+ * The two statuses with work in flight.
  *
  * A job in one of these refuses new work with a 409. Note this is NOT the
  * complement of "terminal": `"uploaded"` and `"transcribed"` are idle but not
@@ -82,12 +79,12 @@ export declare function isCaptionBusy(status: string): boolean;
  * One timed word of the transcript.
  *
  * `text`, `t0`, `t1` - NOT `word`, `start`, `end`. These are the keys the
- * render endpoint permits and the keys the transcriber writes onto the row, so
+ * render endpoint permits and the keys a transcription writes onto the row, so
  * a word object built any other way is silently dropped server-side and the
  * render fails with "No words to render".
  *
  * Timings are seconds from the START OF THE VIDEO, not from the start of the
- * transcribed window: the backend shifts them onto the video clock before
+ * transcribed window: the server shifts them onto the video clock before
  * saving, so an edited list can be sent straight back.
  */
 export interface CaptionWord {
@@ -101,8 +98,8 @@ export interface CaptionWord {
 /**
  * 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.
+ * The server 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[];
 /**
@@ -110,19 +107,19 @@ export type CaptionRgb = readonly [number, number, number] | readonly number[];
  *
  * Open bag, because the renderer gains options without an SDK release and
  * unknown keys are dropped server-side rather than rejected. The named keys are
- * the ones the controller's allow-list actually permits today; anything else -
- * a font name, a hex colour - is accepted by the request and then thrown away,
- * which is worth knowing before spending a render on it.
+ * the ones the server permits today; anything else - a font name, a hex
+ * colour - is accepted by the request and then thrown away, which is worth
+ * knowing before spending a render on it.
  *
  * Every numeric key is CLAMPED, not validated: a value outside the range comes
  * 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.
+     * A font KEY from {@link CaptionsNamespace.fonts}, never a path: the
+     * renderer resolves the key against its installed faces, so a caller cannot
+     * point it 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]`. */
@@ -130,8 +127,8 @@ export interface CaptionStyle {
     /**
      * 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.
+     * the server 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]`. */
@@ -160,25 +157,22 @@ export interface CaptionStyle {
  * 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.
+ * call, show, transcribe and render - answers the same shape, 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.
+ * `width`, `height`, `fps`, `duration` and `transcribed_seconds` are always
+ * real numbers: `0` until the probe fills them in.
  */
 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. */
+    /** Original upload name. The server substitutes `"video.mp4"` for a blank
+     * one, so this is never empty in practice. */
     readonly filename: string;
-    /** Pixels. `NOT NULL DEFAULT 0`, so `0` means "not probed yet", not unknown. */
+    /** Pixels. `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`. */
+    /** Seconds of video, probed at upload. */
     readonly duration: number;
     /** Language of the last transcribe call, `"auto"` included. `null` before the first. */
     readonly language: string | null;
@@ -187,27 +181,25 @@ export interface CaptionJob extends ToolRecord {
     readonly window_end: number | null;
     /**
      * Seconds charged against the quota so far, accumulated across every window
-     * transcribed on this job. `NOT NULL DEFAULT 0`.
+     * transcribed on this job.
      */
     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.
+     * `null` and not `[]` when there are none, 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"`. */
+    /** What the renderer is doing right now, read live. `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 {
-    /** The video. Sent as the `video` form field. Backend caps: 250 MiB, 20 minutes. */
+    /** The video. Sent as the `video` form field. Caps: 250 MiB, 20 minutes. */
     readonly video: FileInput;
 }
 /** Arguments for transcribing a window. */
@@ -223,7 +215,7 @@ export interface TranscribeCaptionInput {
 export interface RenderCaptionInput {
     /**
      * Words to burn in. Omit to use the words already on the row; pass an edited
-     * array to fix what the model misheard. Backend cap: 3000 words, 80
+     * array to fix what the transcription misheard. Cap: 3000 words, 80
      * characters each.
      *
      * Omitting costs one extra `GET`: the render endpoint has no fallback of its
@@ -237,59 +229,55 @@ export interface RenderCaptionInput {
  * Renders a caption job as a {@link Progress}, render stage included.
  *
  * Same liberty as the vocal separator takes with the queue position: the
- * sidecar's stage is folded into `status` - `"rendering (encoding)"` - because
+ * render stage is folded into `status` - `"rendering (encoding)"` - because
  * `status` is the only part of a {@link Progress} a host renders as text, and a
  * whole-file re-encode is long enough that "rendering" alone tells a person
  * nothing.
  */
 export declare function captionProgress(record: CaptionJob): Progress;
 /**
- * Largest file the backend will accept, chunked or not: 250 MiB exactly.
+ * Largest file the server 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.
+ * 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.
+ * This is a CLIENT-SIDE choice, not a protocol constant. The ~100 MB 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.
+ * Part size, 32 MiB. The same number as the storage tier's, by coincidence
+ * rather than by sharing.
  *
  * 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.
+ * server validates each part against. 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.
+ * Three. A single sequential stream leaves a home connection idle between
+ * round trips; three fills it without holding an unfair share of the API,
+ * since these bytes pass THROUGH the API on their way to storage, 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`.
+ * How long an upload session stays usable: six hours.
  *
  * 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
@@ -322,7 +310,7 @@ export interface StartCaptionUploadInput extends ToolCaptcha {
      * 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
+     * declared size above it leaves the server waiting for bytes that never
      * come and `finish` probing a truncated file.
      */
     readonly size: number;
@@ -364,7 +352,7 @@ export interface CaptionUploadResume {
      * 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.
+     * being true the day the server changes it.
      */
     readonly session: CaptionUploadSession | string;
     /**
@@ -413,18 +401,16 @@ export declare function captionUploadSize(video: FileInput): number | undefined;
  * 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.
+ * different places: the session reports a `part_size`, while each part is
+ * validated against the server's own constant. They are the same 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.
+ * {@link CAPTION_PART_SIZE}.
  */
 export declare function resolveCaptionPartSize(reported: number | undefined): number;
 /** The `captions` tool, reachable as `oms.tools.captions`. */
@@ -448,15 +434,15 @@ export declare class CaptionsNamespace extends Resource {
      * {@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.
+     * renderer resolves against its installed faces, 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.
+     * The endpoint answers `{ fonts: [...] }`; this unwraps it. It also NEVER
+     * fails: a renderer that is down or slow is 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.
      */
@@ -464,11 +450,6 @@ export declare class CaptionsNamespace extends Resource {
     /**
      * `POST /caption_jobs` - step 1. Uploads the video and probes it.
      *
-     * The bytes go to the captions sidecar, which keeps the file; Rails stores
-     * only the row and, at the end, the rendered output. That is also why a
-     * caption job cannot be resumed after the sidecar's volume is wiped: the row
-     * survives and the video does not, and step 2 then fails.
-     *
      * Answers with the row in `"uploaded"`, carrying the probed `width`,
      * `height`, `fps` and `duration`. Nothing is running yet, so this call does
      * not wait.
@@ -477,8 +458,8 @@ export declare class CaptionsNamespace extends Resource {
      * 250 MiB and leaves an orphan job behind. Pass `retry: {}` to opt back in.
      *
      * @throws {OmsApiError} 413 over 250 MiB, 400 over 20 minutes or when the
-     *   file cannot be read, 503 when the captions sidecar is down - in which
-     *   case the row is destroyed rather than left dangling.
+     *   file cannot be read, 503 when the captions service is unavailable - in
+     *   which case no job is left behind.
      * @throws {OmsQuotaError} 429 from the expensive-tools throttle. The upload
      *   itself spends no daily quota.
      * @throws {OmsAuthError} 401 when anonymous and the captcha is missing or bad.
@@ -508,8 +489,8 @@ export declare class CaptionsNamespace extends Resource {
      * new window's words and ADDS its seconds to `transcribed_seconds`, so
      * re-transcribing costs quota every time and does not give you both windows.
      *
-     * `language` defaults to `"auto"` server-side. Whisper detects well enough
-     * that a hint is worth passing only when it has already got it wrong.
+     * `language` defaults to `"auto"` server-side. Detection is good enough that
+     * a hint is worth passing only when it has already got it wrong.
      *
      * Resolves with a `"failed"` row rather than throwing when the transcription
      * itself failed - including the common case of a window with no speech in
@@ -526,9 +507,7 @@ export declare class CaptionsNamespace extends Resource {
      */
     transcribe(id: Id, input: TranscribeCaptionInput, options?: ToolRunOptions): Promise<CaptionJob>;
     /**
-     * `POST /caption_jobs/:id/render` - step 3. Named `render` here even though
-     * the route is `start_render`, because `render` clashes with Rails' own
-     * method and that is the backend's problem, not the SDK's.
+     * `POST /caption_jobs/:id/render` - step 3.
      *
      * WAITS, like {@link transcribe}, and for the same reason.
      *
@@ -554,11 +533,10 @@ export declare class CaptionsNamespace extends Resource {
      */
     render(id: Id, input?: RenderCaptionInput, options?: ToolRunOptions): Promise<CaptionJob>;
     /**
-     * `DELETE /caption_jobs/:id` - drops the row and the sidecar's copy.
+     * `DELETE /caption_jobs/:id` - drops the job and its uploaded video.
      *
-     * Best effort on the sidecar's side: the row goes either way. Worth calling
-     * on a job you have finished with, because the uploaded video sits on the
-     * sidecar's disk until the 24-hour sweep otherwise.
+     * Worth calling on a job you have finished with; otherwise the video is
+     * kept until the 24-hour sweep.
      *
      * @throws {OmsApiError} 404 when it is already gone.
      * @throws {OmsAuthError} 401 when the job belongs to someone else.
@@ -592,8 +570,8 @@ export declare class CaptionsNamespace extends Resource {
      * 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.
+     * because `finish` and `create` answer the same shape - 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
@@ -621,20 +599,19 @@ export declare class CaptionsNamespace extends Resource {
      * 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.
+     * Nothing is cleaned up on failure and nothing needs to be: the server
+     * discards the parts itself when `finish` rejects the file, and a run
+     * abandoned before `finish` leaves no job behind. There is no way to abort
+     * a session, 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 -
+     * platform streams it off disk), which caps out at the ~100 MB request
+     * limit. 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.
      *
@@ -665,20 +642,19 @@ export declare class CaptionsNamespace extends Resource {
      *
      * 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.
+     * job id is minted - early, but the job itself does not exist until the file
+     * is whole. So a session is not a job: {@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.
+     * NOT retried by default. A replay opens a SECOND session under a second job
+     * id and hands back a second token, and the first is then orphaned with no
+     * way 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.
+     *   positive, 503 when the captions service is unavailable.
      * @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.
@@ -688,10 +664,7 @@ export declare class CaptionsNamespace extends Resource {
      * `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.
+     * not a form field, not base64, not JSON.
      *
      * 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
@@ -707,24 +680,23 @@ export declare class CaptionsNamespace extends Resource {
      *
      * @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 }`.
+     * @returns The byte count the server 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.
+     *   captions service is unavailable.
      */
     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"`.
+     * This is where a chunked upload becomes a job: the parts are joined and
+     * probed, and only then is a `CaptionJob` created, with the id that was
+     * sealed into the token at the start. The answer is the same shape
+     * {@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.
+     * one over 20 minutes, is a 400 - and the server discards the parts before
+     * answering, so there is nothing to clean up and nothing to retry.
      *
      * 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
@@ -732,7 +704,7 @@ export declare class CaptionsNamespace extends Resource {
      *
      * @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.
+     *   is over six hours old, 503 when the captions service is unavailable.
      */
     finishUpload(session: CaptionUploadSession | string, options?: RequestOptions): Promise<CaptionJob>;
     /**

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

@@ -1,13 +1,13 @@
 /**
  * Upscaling: enlarges an image without turning it to mush.
  *
- * Same shape as background removal: `POST /upscales` enqueues a proxy job and
+ * Same shape as background removal: `POST /upscales` enqueues a job and
  * answers with a row plus a `job_id` and, when anonymous, a `watch_token`.
  *
- * Backend limits: 20 MiB, and the scale must be one the upscaler advertises.
+ * Limits: 20 MiB, and the scale must be one of `"2"`, `"3"`, `"4"`.
  *
- * Like background removal, this tool is not metered by the `Quotas` catalogue,
- * so there is no `quota()` to call first.
+ * Like background removal, this tool has no daily quota, so there is no
+ * `quota()` to call first.
  */
 import { Resource } from "../../http";
 import type { FileInput, Id, RequestOptions } from "../../types";
@@ -15,7 +15,7 @@ import { type ToolCaptcha, type ToolJobHandle, type ToolRecord, type ToolRunOpti
 /**
  * Enlargement factor, as the string the API expects.
  *
- * A string and not a number because the backend compares it against an
+ * A string and not a number because the server compares it against an
  * allow-list of strings; `4` and `"4"` are not the same request.
  */
 export type UpscaleScale = "2" | "3" | "4";
@@ -23,19 +23,15 @@ export type UpscaleScale = "2" | "3" | "4";
  * An upscale run.
  *
  * Both routes that answer with one - `POST /upscales` and `GET /upscales/:id` -
- * render the `:extended` view, so `result_url` is always PRESENT and simply
- * `null` until the run completes. There is no default-view variant of this
- * record reachable through the API.
+ * answer the same shape, so `result_url` is always PRESENT and simply `null`
+ * until the run completes.
  *
  * `progress_percent`, inherited from {@link ToolRecord}, is never sent for this
- * tool: `UpscaleBlueprint` has no such field. Progress for an upscale lives on
- * the {@link Job} row that {@link UpscaleCreated.job_id} names.
+ * tool. Progress for an upscale lives on the {@link Job} row that
+ * {@link UpscaleCreated.job_id} names.
  */
 export interface Upscale extends ToolRecord {
-    /**
-     * One of `"2"`, `"3"`, `"4"` - a string, because the column is a string and
-     * the allow-list is `%w[2 3 4]`. Never `null`: `NOT NULL DEFAULT '4'`.
-     */
+    /** One of `"2"`, `"3"`, `"4"` - a string. Never `null`; defaults to `"4"`. */
     readonly scale: string;
     /**
      * Signed URL of the enlarged PNG, or `null`. `null` covers three different
@@ -49,9 +45,9 @@ export interface Upscale extends ToolRecord {
 export type UpscaleCreated = Upscale & ToolJobHandle;
 /** Arguments for starting a run. */
 export interface CreateUpscaleInput extends ToolCaptcha {
-    /** The image. Backend cap: 20 MiB. */
+    /** The image. Cap: 20 MiB. */
     readonly file: FileInput;
-    /** Defaults to `"4"`, which is what the backend picks when none is sent. */
+    /** Defaults to `"4"`, which is what the server picks when none is sent. */
     readonly scale?: UpscaleScale;
 }
 /** The `upscale` tool, reachable as `oms.tools.upscale`. */