@omelhorsite/sdk 0.1.0

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

@@ -0,0 +1,397 @@
+/**
+ * Downloader: fetches media from a public URL, or finds it from artist plus
+ * title.
+ *
+ * Different from its siblings in five ways worth knowing before writing a line
+ * against it:
+ *
+ * - it uploads nothing, so there is no captcha and no multipart form. It is
+ *   also the one tool with NO anonymous door at all: every endpoint here needs
+ *   a credential;
+ * - its job lives on the yt-dlp sidecar, NOT in the `jobs` table and NOT in the
+ *   database, so poll it with {@link DownloaderNamespace.getJob} and never with
+ *   `oms.jobs`;
+ * - the sidecar's job record has no id in it, so this namespace stamps one on.
+ *   See {@link DownloaderJob.id};
+ * - every URL it is given passes an SSRF guard server-side. A private or
+ *   link-local address comes back as a 400, by design. Do not try to work
+ *   around it;
+ * - {@link DownloaderNamespace.download} is ONE SHOT. Streaming the file
+ *   deletes it from the sidecar, so a second call is a 404. Buffer the blob and
+ *   write it somewhere before you need it twice.
+ *
+ * Limits, all enforced by the backend:
+ *
+ * | | |
+ * |---|---|
+ * | download jobs | 30 an hour |
+ * | previews and artwork lookups | 60 an hour, together |
+ * | all three `POST`s | 20 a minute, shared with every other expensive tool |
+ *
+ * The hourly limits are keyed on the user id, so they follow the account rather
+ * than the machine. Unlike the other tools there is no daily quota and so no
+ * `quota()` here: what bounds this tool is a rate, and the only way to read it
+ * is to hit it. A 429 from the hourly limit and a 429 from the 20-a-minute
+ * throttle are told apart by `retryAfterMs`, which only the latter sets.
+ *
+ * There is nothing metered about a byte of this: a two-hour video costs the
+ * same one job as a three-minute song.
+ */
+import { Resource } from "../../http";
+import type { FileOutput, Id, Progress, RequestOptions, WaitOptions } from "../../types";
+import type { ToolRunOptions } from "./index";
+/**
+ * One downloadable rendition the source offers.
+ *
+ * VIDEO renditions only: the sidecar drops every format whose `vcodec` is
+ * `"none"` before answering, so an audio-only download has no format list to
+ * choose from and `formatId` is not worth passing for one.
+ */
+export interface DownloaderFormat {
+    /** What to pass as {@link CreateDownloadInput.formatId}. */
+    readonly format_id?: string;
+    readonly ext?: string;
+    /** `"1920x1080"`, or built from width and height when the source omits it. */
+    readonly resolution?: string | null;
+    readonly width?: number | null;
+    readonly height?: number | null;
+    readonly fps?: number | null;
+    readonly vcodec?: string;
+    readonly acodec?: string;
+    /** Bytes, exact or approximate. `null` when the source will not say. */
+    readonly filesize?: number | null;
+    /** Total bitrate, kbps. */
+    readonly tbr?: number | null;
+    readonly format_note?: string | null;
+    /** False for a video-only rendition that would need muxing. */
+    readonly has_audio?: boolean;
+    readonly [key: string]: unknown;
+}
+/** One entry of a playlist preview. */
+export interface DownloaderPlaylistTrack {
+    readonly title?: string | null;
+    readonly artist?: string | null;
+    readonly duration_s?: number | null;
+    readonly thumbnails?: ReadonlyArray<{
+        readonly url?: string;
+        readonly [key: string]: unknown;
+    }>;
+    /** Feed this back to {@link DownloaderNamespace.preview} or as a `sourceUrl`. */
+    readonly webpage_url?: string | null;
+    readonly id?: string | null;
+}
+/**
+ * `POST /tools_downloader/preview` - what the source says about a URL.
+ *
+ * Two shapes behind one type, told apart by {@link DownloaderPreview.kind}: a
+ * `"track"` carries the metadata fields, a `"playlist"` carries `count` and
+ * `tracks` and none of the rest. Check `kind` before reading anything else.
+ */
+export interface DownloaderPreview {
+    readonly kind?: "track" | "playlist" | string;
+    readonly title?: string | null;
+    readonly artist?: string | null;
+    readonly album?: string | null;
+    /**
+     * Seconds. Named `duration_s` because that is what the sidecar sends; there
+     * is no `duration` key on this payload.
+     */
+    readonly duration_s?: number | null;
+    /** Every thumbnail the source offers, worst first. */
+    readonly thumbnails?: ReadonlyArray<{
+        readonly url?: string;
+        readonly [key: string]: unknown;
+    }>;
+    readonly webpage_url?: string | null;
+    /** The source's own id for the item, not a job id. */
+    readonly id?: string | null;
+    /** Which yt-dlp extractor matched. */
+    readonly extractor?: string | null;
+    /** Video renditions. Absent on a playlist. */
+    readonly formats?: DownloaderFormat[];
+    /** Entries, on a `"playlist"`. */
+    readonly tracks?: DownloaderPlaylistTrack[];
+    /** How many entries the playlist has. */
+    readonly count?: number | null;
+    readonly [key: string]: unknown;
+}
+/** One cover-art candidate. */
+export interface ArtworkCandidate {
+    /** Full-size image. Pass it as {@link CreateDownloadInput.artworkUrl}. */
+    readonly url: string;
+    /** Smaller version of the same image, for a picker. */
+    readonly thumb_url?: string | null;
+    /** `"itunes"`, `"deezer"` or `"musicbrainz"`. */
+    readonly source?: string;
+    /** Pixels, when the source states them. `null` is common and means unknown. */
+    readonly width?: number | null;
+    readonly height?: number | null;
+    /** Album or track name the candidate was found under. */
+    readonly label?: string | null;
+    /** Artist, or whatever the source offers as a second line. */
+    readonly subtitle?: string | null;
+    readonly [key: string]: unknown;
+}
+/** Arguments for an artwork lookup. Pass either the triple or a free query. */
+export interface ArtworkSearchInput {
+    readonly artist?: string;
+    readonly title?: string;
+    readonly album?: string;
+    /**
+     * Free text, used when neither `artist` nor `title` is given. It is thrown at
+     * the sources as a title with no artist, so the triple beats it when you have
+     * one.
+     */
+    readonly query?: string;
+}
+/** What to fetch. */
+export type DownloaderKind = "audio" | "video";
+/**
+ * Arguments for a download job.
+ *
+ * Either `sourceUrl`, or BOTH `artist` and `title` so the sidecar can search.
+ * Anything else is a 400.
+ */
+export interface CreateDownloadInput {
+    /** Direct URL. Must be public: the SSRF guard rejects private ranges. */
+    readonly sourceUrl?: string;
+    /** Search terms, used when there is no `sourceUrl`. Both are required together. */
+    readonly artist?: string;
+    readonly title?: string;
+    readonly album?: string;
+    /** Which site to search. */
+    readonly source?: string;
+    readonly kind?: DownloaderKind;
+    /**
+     * A `format_id` from {@link DownloaderPreview.formats}. Video only - the
+     * format list never contains an audio-only rendition.
+     */
+    readonly formatId?: string;
+    /** Metadata written into the finished file, overriding what was detected. */
+    readonly overrideTitle?: string;
+    readonly overrideArtist?: string;
+    readonly overrideAlbum?: string;
+    /** Cover art by URL. Same SSRF guard as `sourceUrl`. */
+    readonly artworkUrl?: string;
+    /** Cover art inline, base64, when you already hold the bytes. */
+    readonly artworkDataB64?: string;
+}
+/**
+ * How far along a sidecar download is.
+ *
+ * These are the sidecar's own five strings. Note the two that trip people up:
+ * it finishes on `"complete"` - the same word a tool row uses, NOT the `"done"`
+ * an older draft of this SDK claimed - and it fails on `"failed"`, not
+ * `"error"`.
+ */
+export type DownloaderJobStatus = "queued" | "fetching" | "downloading" | "complete" | "failed";
+/** Statuses a sidecar download never leaves. */
+export declare const DOWNLOADER_TERMINAL_STATUSES: readonly DownloaderJobStatus[];
+/** True once a sidecar download can never change again. */
+export declare function isDownloaderTerminal(status: string): boolean;
+/** A download job, as the sidecar reports it. */
+export interface DownloaderJob {
+    /**
+     * The job id.
+     *
+     * Stamped on by this namespace, not sent by the server: the create call
+     * answers `{ request_id, target }` and the progress call answers a bare
+     * `{ status, message, progress }` with no identifier in it at all. Both are
+     * normalised here so a job can be passed around as one object.
+     */
+    readonly id: Id;
+    /** The sidecar's own name for {@link DownloaderJob.id}, on the create answer. */
+    readonly request_id?: string;
+    /** What the job was pointed at - the URL, or the search string. Create answer only. */
+    readonly target?: string;
+    /**
+     * Absent on the create answer, which carries no status at all. Treat a
+     * missing status as `"queued"`: the sidecar has just registered it.
+     */
+    readonly status?: DownloaderJobStatus | string;
+    /** Fraction in `[0, 1]`, NOT a percentage. `1` once complete. */
+    readonly progress?: number | null;
+    /** Human sentence about the current step, and the failure reason once failed. */
+    readonly message?: string | null;
+    /**
+     * Never sent by this sidecar. The real filename arrives on the download
+     * response instead - see {@link DownloaderNamespace.downloadFile} - and
+     * `message` holds `"saved <name>"` once complete.
+     */
+    readonly filename?: string | null;
+    /**
+     * Failure reason. The sidecar reports it as `message`, so this is normally
+     * absent; read `message` when `status` is `"failed"`.
+     */
+    readonly error?: string | null;
+    /** Metadata the sidecar resolved, present once complete. */
+    readonly title?: string | null;
+    readonly uploader?: string | null;
+    readonly duration_s?: number | null;
+    readonly source_url?: string | null;
+    readonly source_provider?: string | null;
+    readonly source_id?: string | null;
+    readonly audio_codec?: string | null;
+    readonly audio_bitrate_kbps?: number | null;
+    readonly [key: string]: unknown;
+}
+/**
+ * Renders a sidecar download as a {@link Progress}.
+ *
+ * The sidecar's `progress` is a FRACTION, so it is scaled to the 0-100 every
+ * other tool in this SDK reports. `total` stays `undefined` while there is no
+ * number at all, rather than inventing a denominator a spinner would then
+ * render as 0%.
+ */
+export declare function downloaderProgress(job: DownloaderJob): Progress;
+/** The `downloader` tool, reachable as `oms.tools.downloader`. */
+export declare class DownloaderNamespace extends Resource {
+    /**
+     * `POST /tools_downloader/preview` - metadata and available formats for a
+     * URL, without downloading anything.
+     *
+     * Answers a `"track"` or a `"playlist"`; check {@link DownloaderPreview.kind}
+     * before reading anything else. A playlist URL previews as a listing, but
+     * {@link createJob} downloads only what a single `sourceUrl` resolves to, so
+     * feed the entries' `webpage_url` back one at a time.
+     *
+     * SLOW, and slower than the SDK's own default deadline: the sidecar waits up
+     * to 60 seconds for yt-dlp and the transport's default `timeoutMs` is also
+     * 60 seconds, so a source that is merely sluggish aborts client-side just
+     * before the answer. Pass a `timeoutMs` above 60000 for anything but a
+     * well-behaved host.
+     *
+     * NOT retried by default. The controller turns every failure into a 502,
+     * including "this source refuses yt-dlp", which no amount of retrying fixes -
+     * and each attempt spends one of the 60 hourly lookups and parks a server
+     * thread for up to a minute. Pass `retry: {}` to opt back in.
+     *
+     * @throws {OmsApiError} 400 when the URL is blank or fails the SSRF guard,
+     *   502 when the source refuses or yt-dlp cannot read it.
+     * @throws {OmsQuotaError} 429 past 60 lookups an hour, or from the
+     *   20-a-minute expensive-tools throttle - only the second sets
+     *   `retryAfterMs`.
+     * @throws {OmsAuthError} 401 when there is no credential. This tool has no
+     *   anonymous door.
+     */
+    preview(url: string, options?: RequestOptions): Promise<DownloaderPreview>;
+    /**
+     * `POST /tools_downloader/artwork_search` - cover-art candidates.
+     *
+     * Fans out to iTunes, Deezer and MusicBrainz in parallel and returns whatever
+     * answered in time, deduplicated by URL. A source that is slow or down is
+     * skipped silently, so an empty list means "nothing found right now", not
+     * "this record has no cover".
+     *
+     * The controller answers `{ items: [...] }`; this unwraps it.
+     *
+     * NOT retried by default, for the same reason as {@link preview}: a failure
+     * here is a 502 that means an upstream said no, and every attempt costs one
+     * of the 60 hourly lookups.
+     *
+     * @throws {OmsQuotaError} 429 past 60 lookups an hour, or from the
+     *   expensive-tools throttle.
+     * @throws {OmsApiError} 502 when the lookup itself blew up.
+     */
+    artworkSearch(input: ArtworkSearchInput, options?: RequestOptions): Promise<ArtworkCandidate[]>;
+    /**
+     * `POST /tools_downloader/jobs` - starts a download.
+     *
+     * Answers immediately with an id and nothing else - no status, no progress.
+     * The sidecar's own answer is `{ request_id, target }`; this maps
+     * `request_id` onto {@link DownloaderJob.id} so the record matches every
+     * other tool in the SDK, and keeps both original keys alongside it.
+     *
+     * NOT retried by default: replaying this `POST` after a 502 starts a SECOND
+     * download of the same thing and spends another of the 30 hourly jobs, with
+     * the first still running and no way to reach its id. Pass `retry: {}` to opt
+     * back in.
+     *
+     * @throws {OmsApiError} 400 when neither a `sourceUrl` nor an artist+title
+     *   pair was given, or when `sourceUrl` or `artworkUrl` fails the SSRF guard.
+     *   502 when the sidecar refused the job.
+     * @throws {OmsQuotaError} 429 past 30 jobs an hour, or from the 20-a-minute
+     *   expensive-tools throttle - only the second sets `retryAfterMs`.
+     * @throws {OmsAuthError} 401 when there is no credential.
+     */
+    createJob(input: CreateDownloadInput, options?: RequestOptions): Promise<DownloaderJob>;
+    /**
+     * `GET /tools_downloader/jobs/:id` - one poll against the sidecar.
+     *
+     * The sidecar answers a bare `{ status, message, progress }` with no id in
+     * it, so the id you asked with is stamped back on. Once complete the same
+     * payload carries the resolved metadata - title, uploader, duration, codec.
+     *
+     * The sidecar holds jobs in memory with a TTL sweep, so a 404 here means
+     * "unknown or swept", and a process restart loses every job at once.
+     *
+     * @throws {OmsApiError} 404 when the sidecar does not know the id, 502 when
+     *   the sidecar itself is unreachable.
+     */
+    getJob(id: Id, options?: RequestOptions): Promise<DownloaderJob>;
+    /**
+     * Starts a download and waits for it.
+     *
+     * Polls {@link getJob} directly: this job is not in the `jobs` table, so
+     * `oms.jobs.wait` cannot see it. The loop is still `pollUntilTerminal` from
+     * the jobs module - the same one every other tool uses.
+     *
+     * Resolves for `"failed"` as well as `"complete"`, because a source that
+     * refuses is an answer. Check `status` before calling {@link download}, and
+     * read `message` for the reason - the sidecar reports failures there, not in
+     * `error`.
+     *
+     * Pass `waitTimeoutMs` (or a `signal`) to bound the wait; there is no default
+     * deadline. The sidecar gives one download up to 10 minutes of its own before
+     * giving up.
+     *
+     * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapses,
+     *   `code: "aborted"` when the signal fires. Neither cancels the download,
+     *   which keeps running and can still be picked up with {@link getJob}.
+     */
+    run(input: CreateDownloadInput, options?: ToolRunOptions): Promise<DownloaderJob>;
+    /**
+     * Waits for a download somebody else started.
+     *
+     * The half of {@link run} that does not spend one of the 30 hourly jobs -
+     * useful after a `--no-wait` create, or in a second process holding only the
+     * id.
+     */
+    wait(id: Id, options?: WaitOptions): Promise<DownloaderJob>;
+    /**
+     * `GET /tools_downloader/jobs/:id/file` - the finished file, streamed
+     * through Rails from the sidecar.
+     *
+     * ONE SHOT. The sidecar deletes the file as soon as it has finished streaming
+     * it, so a second call to this - or to {@link downloadFile} - is a 404. Write
+     * the blob somewhere before you need it twice.
+     *
+     * Buffers the whole file, because it is a file the caller is about to write
+     * somewhere. That is fine for a song and a real consideration for a two-hour
+     * video, which is the one place in this SDK where `http.raw` and the response
+     * stream are worth reaching for directly.
+     *
+     * Unlike a tool artefact, this URL is a Rails endpoint and NOT a signed
+     * object-store link, so it does carry the bearer token like any other call.
+     *
+     * NOT retried by default, and this is the one download in the SDK where that
+     * is not a style choice: a retry after a torn stream finds a file the sidecar
+     * has already deleted.
+     *
+     * @throws {OmsApiError} 409 when the job is not finished yet, 404 once the
+     *   sidecar has swept it or once this has already been called, 502 when the
+     *   result expired underneath the sidecar or the stream broke.
+     */
+    download(id: Id, options?: RequestOptions): Promise<Blob>;
+    /**
+     * The same one-shot download as {@link download}, keeping the filename.
+     *
+     * The only place the real filename appears: the sidecar's job record does not
+     * carry one, and Rails forwards the sidecar's `Content-Disposition` on this
+     * response and nowhere else. Prefer this over {@link download} whenever the
+     * file is going to disk.
+     *
+     * @throws {OmsApiError} exactly as {@link download}.
+     */
+    downloadFile(id: Id, options?: RequestOptions): Promise<FileOutput>;
+}

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

@@ -0,0 +1,215 @@
+/**
+ * The `tools` namespace: the metered media tools.
+ *
+ * Every tool here shares four traits, and this file owns the types for them so
+ * the seven sibling modules never redefine them:
+ *
+ * - it accepts an upload through Rails as `multipart/form-data`, not through
+ *   the storage direct-upload path;
+ * - it is asynchronous: the create call answers with a row in `"pending"` and
+ *   the work happens on a sidecar;
+ * - it has a daily quota, metered in seconds for the audio and video tools and
+ *   in edits for jumpstyle, and smaller for an anonymous caller;
+ * - an anonymous caller must pass a Turnstile token
+ *   ({@link ToolCaptcha.captchaToken}, sent as `cf_turnstile_token`).
+ *
+ * A trap worth naming once, because it is not the one it looks like: a tool row
+ * and its {@link Job} row are TWO records with two different ids, and both
+ * spell a finished run `"complete"`. What differs is the set of states - a job
+ * has a fifth, `"canceled"`, that no tool row can ever hold - and which of the
+ * two a given tool is polled through. Compare against
+ * {@link TOOL_TERMINAL_STATUSES} / {@link isToolTerminal} and against
+ * `JOB_TERMINAL_STATUSES` / `isJobTerminal`, never against a literal you typed
+ * from memory.
+ *
+ * Two tools (background removal, upscale) hand back a `job_id` and are waited
+ * on through `oms.jobs`; the other five are waited on by re-reading their own
+ * row. Neither case opens a loop here: both go through `pollUntilTerminal`
+ * from the jobs module.
+ *
+ * Re-exports every sibling module so nobody has to touch this file again.
+ */
+import { type ApiClient, Resource } from "../../http";
+import type { BaseRecord, OperationOptions, Progress, QuotaStatus, RequestOptions, Timestamp, WaitOptions } from "../../types";
+import { type JobsNamespace } from "../jobs";
+import { BackgroundRemovalNamespace } from "./backgroundRemoval";
+import { CaptionsNamespace } from "./captions";
+import { DownloaderNamespace } from "./downloader";
+import { JumpstyleNamespace } from "./jumpstyle";
+import { TranscriptionNamespace } from "./transcription";
+import { UpscaleNamespace } from "./upscale";
+import { VocalSeparationNamespace } from "./vocalSeparation";
+export * from "./backgroundRemoval";
+export * from "./captions";
+export * from "./downloader";
+export * from "./jumpstyle";
+export * from "./transcription";
+export * from "./upscale";
+export * from "./vocalSeparation";
+/**
+ * Lifecycle of a tool row.
+ *
+ * Note `"complete"`, not `"completed"`: that spelling belongs to
+ * {@link Job}. Captions add their own intermediate states on top.
+ */
+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. */
+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. */
+    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.
+ */
+export interface ToolJobHandle {
+    readonly job_id?: string;
+    /** Signed, scoped to this one job. Required when anonymous. */
+    readonly watch_token?: string;
+}
+/** Mixed into every create input: the anonymous caller's captcha. */
+export interface ToolCaptcha {
+    /**
+     * Cloudflare Turnstile token, sent as `cf_turnstile_token`. Required when
+     * there is no credential; ignored when there is one.
+     */
+    readonly captchaToken?: string;
+}
+/** A daily quota metered in seconds of media. */
+export interface SecondsQuota extends QuotaStatus {
+    readonly used_seconds: number;
+    /** `null` when the account is unlimited. */
+    readonly limit_seconds: number | null;
+    /** `null` when the account is unlimited. */
+    readonly remaining_seconds: number | null;
+}
+/** A daily quota metered in finished edits. */
+export interface EditsQuota extends QuotaStatus {
+    readonly used_edits: number;
+    readonly limit_edits: number | null;
+    readonly remaining_edits: number | null;
+}
+/** One selectable model of a tool. */
+export interface ToolModel {
+    readonly id: string;
+    /** i18n key for the display name. The SDK does not translate. */
+    readonly translation_key?: string;
+    /** True on the model the server picks when none is named. */
+    readonly default?: boolean;
+}
+/**
+ * Options for a tool's `run()`: the upload half and the waiting half at once.
+ *
+ * `onProgress` fires as bytes move and again on every poll. `waitTimeoutMs` and
+ * `pollIntervalMs` are passed straight through to the jobs module's loop, which
+ * is the only loop involved.
+ *
+ * Note what `timeoutMs` does NOT mean here: it bounds one HTTP call, not the
+ * run. A ninety-minute separation with `timeoutMs: 60_000` is fine - each poll
+ * is a second-long request. Use `waitTimeoutMs` (or a `signal`) to bound the
+ * run itself.
+ */
+export interface ToolRunOptions extends OperationOptions, WaitOptions {
+}
+/** True once a tool row can never change again. */
+export declare function isToolTerminal(status: string): boolean;
+/**
+ * Renders a tool row as a {@link Progress}.
+ *
+ * `total` is `undefined` while `progress_percent` is null, which is most of a
+ * run's life: the backend only fills it in while the sidecar is actually
+ * working, and inventing a denominator would be a lie a spinner then renders.
+ */
+export declare function toolProgress(record: ToolRecord): Progress;
+/**
+ * The captcha form field, or nothing.
+ *
+ * Sent as `cf_turnstile_token`, and only when the caller supplied one: an empty
+ * string is not the same as an absent key to the Turnstile verifier.
+ */
+export declare function toolCaptchaFields(input: ToolCaptcha): Record<string, string>;
+/**
+ * Picks an artefact URL off a finished row, or explains why there is not one.
+ *
+ * A tool row carries its outputs as URLs that are null until the run completes,
+ * so "no URL" has three different causes and a caller deserves to be told which
+ * one. Never returns an empty string.
+ *
+ * @param what Name of the artefact for the message: `"result"`, `"vocals"`.
+ * @throws {OmsError} `invalid_request` when the run failed, `conflict` when it
+ *   has not finished yet, `not_found` when it finished without one - which
+ *   after 24 hours means the retention sweep took it.
+ */
+export declare function requireToolArtifact(record: ToolRecord, url: string | null | undefined, what: string): string;
+/**
+ * Fetches an artefact URL and buffers it.
+ *
+ * Sent on the injected transport with NO `Authorization` header, deliberately
+ * and for the same reason `storage.download` does it: these URLs are signed
+ * ActiveStorage links that redirect to the object store, and the store rejects
+ * a request that arrives with two authentication schemes. The signature in the
+ * URL is the credential.
+ *
+ * Buffers the whole artefact, because every one of them is a file a caller is
+ * about to write somewhere. Only the caller's `signal` is honoured - the
+ * transport's retry and per-request deadline do not apply to a bare `fetch`.
+ *
+ * @throws {OmsApiError} carrying the store's status when the URL has expired or
+ *   the artefact has been swept.
+ */
+export declare function fetchToolArtifact(http: ApiClient, url: string, options?: RequestOptions): Promise<Blob>;
+/**
+ * Waits for a run that enqueued through the generic `jobs` table, then reads
+ * the tool's own row back.
+ *
+ * Only background removal and upscale take this path - they are the two tools
+ * whose create call answers with a `job_id` and a `watch_token`. The job row is
+ * what carries progress and what an anonymous caller is allowed to read; the
+ * TOOL row is the typed answer, and it is written first (the worker marks the
+ * run complete or failed inside `perform`, and the job is settled around it),
+ * so re-reading after the job settles never races.
+ *
+ * When the server gave no `job_id` - no tracking row was minted - this falls
+ * back to polling the tool's own row, which is what the other five tools do
+ * anyway. Either way there is exactly one loop, and it lives in the jobs
+ * module.
+ *
+ * @param reread Reads the tool row. Called after the job settles.
+ * @param label What to call this in a timeout message: `"the upscale"`.
+ * @throws {OmsError} `server_error` when the job ended without completing AND
+ *   left the tool row untouched - a cancelled or crashed worker. A run that
+ *   genuinely failed comes back as a row with `status: "failed"`, because that
+ *   is an answer.
+ */
+export declare function awaitToolJob<T extends ToolRecord>(jobs: JobsNamespace, created: T & ToolJobHandle, reread: (options: RequestOptions) => Promise<T>, options: ToolRunOptions, label: string): Promise<T>;
+/** The `tools` namespace, reachable as `oms.tools`. */
+export declare class ToolsNamespace extends Resource {
+    /** Cuts the subject out of an image. */
+    readonly backgroundRemoval: BackgroundRemovalNamespace;
+    /** Enlarges an image without the mush. */
+    readonly upscale: UpscaleNamespace;
+    /** Speech to text, with SRT and VTT output. */
+    readonly transcription: TranscriptionNamespace;
+    /** Splits a track into vocals and instrumental. */
+    readonly vocalSeparation: VocalSeparationNamespace;
+    /** Karaoke captions burned into a video. */
+    readonly captions: CaptionsNamespace;
+    /** Beat-synced clip edits over a track. */
+    readonly jumpstyle: JumpstyleNamespace;
+    /** Fetches media from a public URL. */
+    readonly downloader: DownloaderNamespace;
+    constructor(http: ApiClient);
+}