@omelhorsite/sdk 0.1.0

package/dist/types/resources/tickets.d.ts

@@ -0,0 +1,236 @@
+/**
+ * The `tickets` namespace: support tickets and the message thread on each one.
+ *
+ * A ticket is `POST /tickets` with a subject plus an optional first message;
+ * everything after that is a `TicketMessage` on `/ticket_messages`. Attachments
+ * are data URIs on create (the backend caps them at 10 files / 10 MiB total,
+ * images and video only) and are read back one blob at a time.
+ *
+ * This is the namespace an agent reaches for when something went wrong, so
+ * `create()` is deliberately one call: subject, body and screenshots all land
+ * in the same request.
+ */
+import { type ApiClient, Resource } from "../http";
+import type { FileInput, Id, Paginated, PageParams, RequestOptions, Timestamp } from "../types";
+/** Lifecycle of a ticket. */
+export type TicketStatus = "open" | "closed";
+/**
+ * Identifier of a ticket. A NUMBER, not the opaque string every other resource
+ * uses: `tickets` is one of the two tables that kept an auto-increment primary
+ * key, so the API renders `id` as a JSON number here. That is why {@link Ticket}
+ * does not extend `BaseRecord`.
+ */
+export type TicketId = number;
+/** Identifier of a ticket message. A number, for the same reason as {@link TicketId}. */
+export type TicketMessageId = number;
+/** Longest subject the backend accepts. Anything longer is a 400. */
+export declare const TICKET_SUBJECT_MAX_LENGTH = 200;
+/** Longest message body the backend accepts. Anything longer is a 400. */
+export declare const TICKET_MESSAGE_MAX_LENGTH = 4000;
+/** Most attachments one `create` may carry. The backend keeps the first ten. */
+export declare const TICKET_MAX_ATTACHMENTS = 10;
+/** Ceiling on the decoded bytes of all attachments in one `create`. */
+export declare const TICKET_MAX_ATTACHMENT_BYTES: number;
+/** MIME prefixes the backend accepts as a ticket attachment. */
+export declare const TICKET_ATTACHMENT_TYPES: readonly ["image/", "video/"];
+/**
+ * Free-form context the client attaches at create time. The backend keeps only
+ * these four keys and drops anything else, so do not smuggle payloads through.
+ */
+export interface TicketContext {
+    readonly provider?: string;
+    readonly error?: string;
+    readonly path?: string;
+    readonly source?: string;
+}
+/** One file hanging off a ticket, as the blueprint renders it. */
+export interface TicketAttachment {
+    /** Address it with {@link TicketsNamespace.attachment}. Numeric, like {@link TicketId}. */
+    readonly blob_id: number;
+    readonly filename: string;
+    readonly content_type: string;
+    readonly byte_size: number;
+    /** Derived from `content_type`; never anything else today. */
+    readonly kind: "image" | "video";
+}
+/** A support ticket. */
+export interface Ticket {
+    readonly id: TicketId;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly subject: string;
+    readonly status: TicketStatus;
+    readonly user_id: Id;
+    /** Bumped by every message. The listing is ordered on it, newest first. */
+    readonly last_activity_at: Timestamp;
+    /** Always rendered; `{}` when nothing was attached at create time. */
+    readonly context: TicketContext | null;
+    readonly attachments: TicketAttachment[];
+    /**
+     * The thread. Present on `get`, `create` and `update` (which render the
+     * `:extended` view) and absent from `list`, which renders the default view.
+     */
+    readonly ticket_messages?: TicketMessage[];
+}
+/** One message in a ticket thread. */
+export interface TicketMessage {
+    readonly id: TicketMessageId;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly ticket_id: TicketId;
+    /** Always the sender's own id: the server ignores any value you send. */
+    readonly sender_id: Id;
+    readonly content: string;
+    /** Whether the sender is a member of staff. */
+    readonly sender_admin: boolean;
+}
+/** Arguments for opening a ticket. */
+export interface CreateTicketInput {
+    /** At most {@link TICKET_SUBJECT_MAX_LENGTH} characters. */
+    readonly subject: string;
+    /**
+     * Body of the first message. Optional: a subject alone opens a ticket.
+     *
+     * The backend creates this message without a bang, so a body that fails
+     * validation (over {@link TICKET_MESSAGE_MAX_LENGTH}) is dropped and the
+     * ticket is still created. The SDK checks the length first so that never
+     * happens silently.
+     */
+    readonly initialMessage?: string;
+    readonly context?: TicketContext;
+    /**
+     * Files to attach. The SDK turns each one into the data URI the endpoint
+     * expects, so every attachment is buffered in memory.
+     *
+     * Backend caps: {@link TICKET_MAX_ATTACHMENTS} files,
+     * {@link TICKET_MAX_ATTACHMENT_BYTES} in total, `image/*` and `video/*`
+     * only - and an attachment that breaks any of them is dropped in SILENCE,
+     * with the ticket still answering 201. The SDK therefore validates before
+     * sending and raises rather than let a screenshot disappear.
+     */
+    readonly attachments?: FileInput[];
+}
+/** Fields that can change after a ticket exists. */
+export interface UpdateTicketInput {
+    readonly status?: TicketStatus;
+}
+/** Filters for {@link TicketsNamespace.list}. */
+export interface ListTicketsParams extends PageParams {
+    readonly status?: TicketStatus;
+    /** Administrators only: someone else's tickets. */
+    readonly userId?: Id;
+}
+/** Filters for {@link TicketMessagesNamespace.list}. */
+export interface ListTicketMessagesParams extends PageParams {
+    readonly ticketId: TicketId;
+}
+/** Arguments for replying to a ticket. */
+export interface CreateTicketMessageInput {
+    readonly ticketId: TicketId;
+    /** At most {@link TICKET_MESSAGE_MAX_LENGTH} characters. */
+    readonly content: string;
+}
+/** The message thread of a ticket, reachable as `oms.tickets.messages`. */
+export declare class TicketMessagesNamespace extends Resource {
+    /**
+     * `GET /ticket_messages?exact_search[ticket_id]=...` - the thread, oldest
+     * first.
+     *
+     * A thread you can already see whole through {@link TicketsNamespace.get}
+     * does not need this; reach for it when a thread is long enough to page.
+     */
+    list(params: ListTicketMessagesParams, options?: RequestOptions): Promise<Paginated<TicketMessage>>;
+    /**
+     * `POST /ticket_messages` - replies to a ticket.
+     *
+     * The sender is always the caller: `sender_id` cannot be forged. A closed
+     * ticket refuses replies with 401, so reopen it first.
+     *
+     * Not retried by default: a replayed reply would post the message twice.
+     */
+    create(input: CreateTicketMessageInput, options?: RequestOptions): Promise<TicketMessage>;
+    /**
+     * `DELETE /ticket_messages/:id`. Administrators only; the author of a
+     * message cannot take it back.
+     */
+    delete(id: TicketMessageId, options?: RequestOptions): Promise<void>;
+}
+/** The `tickets` namespace, reachable as `oms.tickets`. */
+export declare class TicketsNamespace extends Resource {
+    /** The message thread of a ticket. */
+    readonly messages: TicketMessagesNamespace;
+    constructor(http: ApiClient);
+    /**
+     * `GET /tickets` - your tickets, most recently active first. An
+     * administrator sees everyone's and can narrow with `userId`.
+     *
+     * The rows carry no `ticket_messages`: the listing renders the default
+     * view. Call {@link get} for the thread.
+     */
+    list(params?: ListTicketsParams, options?: RequestOptions): Promise<Paginated<Ticket>>;
+    /** `GET /tickets/:id` - the ticket with its whole message thread. */
+    get(id: TicketId, options?: RequestOptions): Promise<Ticket>;
+    /**
+     * `POST /tickets` - opens a ticket, with its first message and its
+     * screenshots, in ONE request.
+     *
+     * ```ts
+     * await oms.tickets.create({
+     *   subject: "Upload fails at 90%",
+     *   initialMessage: "Every file over 2 GB stops at the same point.",
+     *   context: { source: "cli", path: "/tools/storage" },
+     *   attachments: [file(png, "screenshot.png")],
+     * });
+     * ```
+     *
+     * Attachments are encoded as data URIs here, so they are buffered whole;
+     * see {@link CreateTicketInput.attachments} for the caps the SDK enforces
+     * before sending.
+     *
+     * Not retried by default: a replayed create would open a second ticket.
+     */
+    create(input: CreateTicketInput, options?: RequestOptions): Promise<Ticket>;
+    /**
+     * `PATCH /tickets/:id` - today the only mutable field is `status`.
+     *
+     * Anything else in the body is dropped in silence and still answers 200
+     * with the untouched record, so read the returned ticket rather than
+     * inferring success from the status code.
+     */
+    update(id: TicketId, input: UpdateTicketInput, options?: RequestOptions): Promise<Ticket>;
+    /** Convenience over {@link update} with `status: "closed"`. */
+    close(id: TicketId, options?: RequestOptions): Promise<Ticket>;
+    /**
+     * Convenience over {@link update} with `status: "open"`. A closed ticket
+     * refuses new messages, so reopen before replying.
+     */
+    reopen(id: TicketId, options?: RequestOptions): Promise<Ticket>;
+    /**
+     * `DELETE /tickets/:id`. Administrators only: the owner of a ticket can
+     * close it but not destroy it, and gets 401 if they try.
+     */
+    delete(id: TicketId, options?: RequestOptions): Promise<void>;
+    /**
+     * `GET /tickets/:id/attachment/:blob_id` - one attachment's bytes.
+     *
+     * The endpoint answers 302 towards object storage and `fetch` follows it.
+     * The redirect is cross-origin, so the platform drops the `Authorization`
+     * header on the way: the credential never reaches the storage host.
+     *
+     * Take `blobId` from {@link TicketAttachment.blob_id}; the filename and
+     * content type are on the same record, which is why this hands back bare
+     * bytes.
+     */
+    attachment(id: TicketId, blobId: number, options?: RequestOptions): Promise<Blob>;
+}
+/**
+ * Encodes a file as a `data:<mime>;base64,<...>` URI.
+ *
+ * Exported because several endpoints take images as data URIs rather than as
+ * uploads (ticket attachments, a link tree avatar, a form theme's background),
+ * and the alternative is every caller writing this loop again.
+ *
+ * Buffers the whole file: a data URI has no streaming form. Base64 also costs
+ * a third more bytes than the original, which matters against the caps.
+ */
+export declare function dataUrlFromFile(input: FileInput): Promise<string>;

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

@@ -0,0 +1,99 @@
+/**
+ * Background removal: cuts the subject out of an image.
+ *
+ * `POST /background_removals` enqueues a proxy job and answers immediately with
+ * a row plus a `job_id` and, for an anonymous caller, a `watch_token`. Poll
+ * through `oms.jobs` with that handle, or use {@link BackgroundRemovalNamespace.run}.
+ *
+ * Backend limits: 15 MiB, and an image bomb (absurd pixel count for its byte
+ * size) is rejected with a 400 before any work starts.
+ *
+ * This tool has no daily quota - it is one of the two that the `Quotas`
+ * catalogue does not meter - so there is no `quota()` here to call first.
+ */
+import { Resource } from "../../http";
+import type { FileInput, Id, RequestOptions } from "../../types";
+import { type ToolCaptcha, type ToolJobHandle, type ToolRecord, type ToolRunOptions } from "./index";
+/** A background removal run. */
+export interface BackgroundRemoval extends ToolRecord {
+    /** URL of the cut-out PNG, once the status is `"complete"`. */
+    readonly result_url?: string | null;
+}
+/** What `POST /background_removals` answers with. */
+export type BackgroundRemovalCreated = BackgroundRemoval & ToolJobHandle;
+/** Arguments for starting a run. */
+export interface CreateBackgroundRemovalInput extends ToolCaptcha {
+    /** The image. Backend cap: 15 MiB. */
+    readonly file: FileInput;
+}
+/** The `backgroundRemoval` tool, reachable as `oms.tools.backgroundRemoval`. */
+export declare class BackgroundRemovalNamespace extends Resource {
+    /**
+     * The one polling loop, reached through the jobs namespace.
+     *
+     * Built here rather than injected so every namespace keeps the same
+     * one-argument constructor `client.ts` relies on. It is a stateless wrapper
+     * over the same transport, so there is nothing to share.
+     */
+    private readonly jobs;
+    /**
+     * `POST /background_removals` - enqueues a run and returns straight away.
+     *
+     * NOT retried by default, unlike most of the SDK. The transport's policy
+     * replays a `POST` that died with a 502, and here that would re-upload the
+     * image and start a second run on a sidecar that serialises them. Pass
+     * `retry: {}` to opt back in.
+     *
+     * @throws {OmsApiError} 400 when the image is too large or looks like a bomb.
+     * @throws {OmsAuthError} 401 when anonymous and the captcha is missing or bad.
+     */
+    create(input: CreateBackgroundRemovalInput, options?: RequestOptions): Promise<BackgroundRemovalCreated>;
+    /**
+     * `GET /background_removals/:id` - one poll.
+     *
+     * Ownership is the caller's session, or - for an anonymous run - the IP the
+     * run was started from. Reading someone else's run is a 401, not a 404.
+     *
+     * @throws {OmsApiError} 404 once the 24-hour retention sweep has taken it.
+     * @throws {OmsAuthError} 401 when the run belongs to someone else, which
+     *   includes an anonymous run being read from a different address.
+     */
+    get(id: Id, options?: RequestOptions): Promise<BackgroundRemoval>;
+    /**
+     * Creates a run and waits for it, reporting progress along the way.
+     *
+     * Delegates the polling to `oms.jobs.wait` with the handle the create call
+     * returned; it does not open a second polling loop.
+     *
+     * Resolves with a `"failed"` row rather than throwing when the work failed -
+     * the request cycle worked, the work did not, and only the caller knows
+     * whether that is an exception. Pass `waitTimeoutMs` (or a `signal`) to bound
+     * the wait; there is no default deadline.
+     *
+     * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapses,
+     *   `code: "aborted"` when the signal fires. Neither cancels the run: pick it
+     *   up later with {@link get}.
+     */
+    run(input: CreateBackgroundRemovalInput, options?: ToolRunOptions): Promise<BackgroundRemoval>;
+    /**
+     * Downloads the cut-out image of a finished run.
+     *
+     * Two calls: one to read the row for its `result_url`, one to fetch the
+     * signed URL itself with no credential attached. Pass the row you already
+     * have to {@link resultUrl} plus {@link fetchToolArtifact} if you would
+     * rather not pay for the first.
+     *
+     * @throws {OmsError} `conflict` when the run has not finished,
+     *   `invalid_request` when it failed, `not_found` when the artefact is gone.
+     */
+    download(id: Id, options?: RequestOptions): Promise<Blob>;
+    /**
+     * The signed URL of a finished run's PNG, from a row you already hold.
+     *
+     * Good for handing to a browser or a player instead of moving the bytes. It
+     * is a credential: anyone holding it can read the image.
+     *
+     * @throws {OmsError} explaining which of the three reasons there is no URL.
+     */
+    resultUrl(record: BackgroundRemoval): string;
+}

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

@@ -0,0 +1,318 @@
+/**
+ * Captions: karaoke subtitles burned into a video.
+ *
+ * The only tool with three steps rather than one, and they must go in order:
+ *
+ * 1. {@link CaptionsNamespace.create} uploads the video. The status becomes
+ *    `"uploaded"` and the server reports the probed dimensions and duration.
+ * 2. {@link CaptionsNamespace.transcribe} transcribes ONE window of it. The
+ *    quota is charged on that window, not on the whole file. The status walks
+ *    `"transcribing"` -> `"transcribed"` and the words land on the row.
+ * 3. {@link CaptionsNamespace.render} burns the words in. The status walks
+ *    `"rendering"` -> `"complete"` and `output_url` appears.
+ *
+ * Between steps the row must be idle: calling one while another is running is
+ * a 409, not a queue. That is why steps 2 and 3 WAIT before they return -
+ * 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:
+ *
+ * | | |
+ * |---|---|
+ * | file size | 250 MiB (`413`) |
+ * | video length | 20 minutes (`400`) |
+ * | one transcribed window | 15 minutes (`400`) |
+ * | words per render | 3000, 80 characters each |
+ * | daily quota, anonymous | 15 minutes of transcribed window |
+ * | daily quota, signed in | 60 minutes of transcribed window |
+ * | `POST` on any of the three steps | 20 a minute, shared with every other expensive tool |
+ *
+ * The upload itself spends no quota - only a transcribed window does - but the
+ * 20-minute cap on the video exists because a render re-encodes the WHOLE file,
+ * captioned part or not. So a 19-minute video with a 30-second window is a
+ * cheap transcription and an expensive render, and only the first of those is
+ * metered.
+ *
+ * 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.
+ */
+import { Resource } from "../../http";
+import type { FileInput, Id, 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
+ * has two distinct pieces of work.
+ */
+export type CaptionStatus = "uploaded" | "transcribing" | "transcribed" | "rendering" | "complete" | "failed";
+/**
+ * The two statuses with a sidecar call 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
+ * finished, which is the whole point of a three-step tool.
+ */
+export declare const CAPTION_BUSY_STATUSES: readonly CaptionStatus[];
+/** True while a step is running and the job will refuse another one. */
+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
+ * 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
+ * saving, so an edited list can be sent straight back.
+ */
+export interface CaptionWord {
+    /** The word itself. Trimmed and truncated to 80 characters server-side. */
+    readonly text: string;
+    /** Seconds from the video start. */
+    readonly t0: number;
+    /** Seconds from the video start. Must be `>= t0`. */
+    readonly t1: number;
+}
+/**
+ * Look of the burned-in captions.
+ *
+ * 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.
+ *
+ * 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 {
+    /** Font size as a fraction of the video height. Clamped to `[0.03, 0.09]`. */
+    readonly fontscale?: 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]`. */
+    readonly max_words?: number;
+    /** Seconds of silence that starts a new caption chunk. Clamped to `[0.1, 1.0]`. */
+    readonly gap?: number;
+    /** x264 quality, lower is better and bigger. Clamped to `[16, 30]`. */
+    readonly crf?: number;
+    /** x264 speed. Anything outside these three is ignored. */
+    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.
+     */
+    readonly yellow?: readonly [number, number, number] | readonly number[];
+    readonly [key: string]: unknown;
+}
+/** A caption job. */
+export interface CaptionJob extends ToolRecord {
+    readonly status: CaptionStatus;
+    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;
+}
+/** Arguments for uploading a video. */
+export interface CreateCaptionJobInput extends ToolCaptcha {
+    /** The video. Sent as the `video` form field. Backend caps: 250 MiB, 20 minutes. */
+    readonly video: FileInput;
+}
+/** Arguments for transcribing a window. */
+export interface TranscribeCaptionInput {
+    /** Seconds from the video start. */
+    readonly start: number;
+    /** Seconds from the video start. Must exceed `start` and be at most 15 minutes past it. */
+    readonly end: number;
+    /** ISO language, or `"auto"`. Defaults to `"auto"`. */
+    readonly language?: string;
+}
+/** Arguments for rendering. */
+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
+     * characters each.
+     *
+     * Omitting costs one extra `GET`: the render endpoint has no fallback of its
+     * own and refuses a request with no word list, so the SDK reads the row and
+     * sends its words back. See {@link CaptionsNamespace.render}.
+     */
+    readonly words?: CaptionWord[];
+    readonly style?: CaptionStyle;
+}
+/**
+ * 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
+ * `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;
+/** The `captions` tool, reachable as `oms.tools.captions`. */
+export declare class CaptionsNamespace extends Resource {
+    /**
+     * `GET /caption_jobs/quota` - seconds of transcription spent and left today.
+     *
+     * Cheap and anonymous-safe. Counts seconds of transcribed WINDOW, not
+     * seconds of uploaded video: a job that was uploaded and never transcribed
+     * has spent nothing. `limit_seconds` and `remaining_seconds` are `null`
+     * exactly when `unlimited` is `true`.
+     *
+     * Worth reading twice - once before the upload, so 250 MiB is not spent on a
+     * budget that is already gone, and once when the window is known, because
+     * that check is exact and the server refuses a window that would cross the
+     * ceiling rather than truncating it.
+     */
+    quota(options?: RequestOptions): Promise<SecondsQuota>;
+    /**
+     * `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.
+     *
+     * NOT retried by default: replaying this `POST` after a 502 re-uploads up to
+     * 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.
+     * @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.
+     */
+    create(input: CreateCaptionJobInput, options?: RequestOptions): Promise<CaptionJob>;
+    /**
+     * `GET /caption_jobs/:id` - one poll.
+     *
+     * Carries `progress_percent` while transcribing or rendering, `render_stage`
+     * while rendering, `words` from `"transcribed"` onwards and `output_url`
+     * once `"complete"`.
+     *
+     * @throws {OmsApiError} 404 once the 24-hour retention sweep has taken it.
+     * @throws {OmsAuthError} 401 when the job belongs to someone else, which
+     *   includes an anonymous job being read from a different address.
+     */
+    get(id: Id, options?: RequestOptions): Promise<CaptionJob>;
+    /**
+     * `POST /caption_jobs/:id/transcribe` - step 2, on one window.
+     *
+     * WAITS: the request only moves the row to `"transcribing"`, and this
+     * resolves once it has settled on `"transcribed"` or `"failed"`. Returning
+     * the busy row instead would hand the caller something whose only use is to
+     * cause a 409 on the next call.
+     *
+     * Windows accumulate. Transcribing a second window replaces `words` with the
+     * 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.
+     *
+     * Resolves with a `"failed"` row rather than throwing when the transcription
+     * itself failed - including the common case of a window with no speech in
+     * it, which fails rather than returning an empty word list.
+     *
+     * @throws {OmsApiError} 409 when the job is already busy, 400 for a window
+     *   that is inverted, past the end of the video, longer than 15 minutes, or
+     *   longer than the whole daily quota.
+     * @throws {OmsQuotaError} 429 when this window would cross the daily ceiling,
+     *   or from the expensive-tools throttle.
+     * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapses,
+     *   `code: "aborted"` when the signal fires. Neither cancels the step: the
+     *   quota is spent either way and the words still land on the row.
+     */
+    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.
+     *
+     * WAITS, like {@link transcribe}, and for the same reason.
+     *
+     * Omitting `words` costs an extra `GET`. The endpoint has no fallback of its
+     * own - it refuses a request whose word list is missing or empty, even for a
+     * job whose row is full of words - so the SDK reads the row and sends those
+     * back. That is the documented behaviour of `RenderCaptionInput.words`, and
+     * it is cheaper to pay one `GET` here than to make every caller learn it.
+     *
+     * A render re-encodes the whole video, so this is the slow step: a
+     * twenty-minute file is minutes of x264 regardless of how short the
+     * captioned part is.
+     *
+     * Resolves with a `"failed"` row rather than throwing when the render failed.
+     *
+     * @throws {OmsError} `conflict` when there are no words to render at all -
+     *   raised here, before the request, so the message says "transcribe first"
+     *   rather than repeating the server's phrasing of it.
+     * @throws {OmsApiError} 409 when the job is already busy, 400 for a word
+     *   whose timings fall outside the video or for more than 3000 of them.
+     * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapses,
+     *   `code: "aborted"` when the signal fires. Neither cancels the render.
+     */
+    render(id: Id, input?: RenderCaptionInput, options?: ToolRunOptions): Promise<CaptionJob>;
+    /**
+     * `DELETE /caption_jobs/:id` - drops the row and the sidecar's copy.
+     *
+     * 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.
+     *
+     * @throws {OmsApiError} 404 when it is already gone.
+     * @throws {OmsAuthError} 401 when the job belongs to someone else.
+     */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /**
+     * Downloads the rendered video of a finished job.
+     *
+     * Two calls: one to read the row for its `output_url`, one to fetch the
+     * signed URL itself with NO credential attached. Hand a row you already hold
+     * to {@link outputUrl} plus `fetchToolArtifact` if you would rather not pay
+     * for the first.
+     *
+     * @throws {OmsError} `conflict` when the job has not been rendered yet -
+     *   which includes a job that is merely `"transcribed"`, `invalid_request`
+     *   when the render failed, `not_found` when the artefact is gone.
+     */
+    download(id: Id, options?: RequestOptions): Promise<Blob>;
+    /**
+     * The signed URL of the rendered video, from a row you already hold.
+     *
+     * It is a credential: anyone holding it can watch the video.
+     *
+     * @throws {OmsError} explaining which of the three reasons there is no URL.
+     */
+    outputUrl(record: CaptionJob): string;
+    /**
+     * Waits for a started step to settle, reusing the one polling loop.
+     *
+     * `terminal` here is "not busy" rather than "finished": step 2 settles on
+     * `"transcribed"`, which is idle and very much not the end of the job.
+     */
+    private settle;
+}