@omelhorsite/sdk 0.1.0

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

@@ -0,0 +1,331 @@
+/**
+ * The `forms` namespace: hosted forms and the submissions they collect.
+ *
+ * A form has an owner-facing side (create, edit the schema, read submissions)
+ * and a public side addressed by ENDPOINT rather than by id
+ * (`GET /forms/by_endpoint/:endpoint`, `POST /form_submissions`), which is what
+ * an anonymous respondent hits. The SDK exposes both; the public calls work
+ * without a credential unless the form turns `settings.require_login` on.
+ *
+ * The endpoint is not a column on the form: it lives on a short link paired
+ * with it, which is why renaming it is a real operation and why availability
+ * has its own lookup.
+ */
+import { type ApiClient, Resource } from "../http";
+import type { BaseRecord, FileInput, Id, Json, RequestOptions, Timestamp } from "../types";
+/**
+ * Publication state. Only `"published"` answers on the public side; `"draft"`
+ * and `"archived"` both 404 there.
+ */
+export type FormStatus = "draft" | "published" | "archived";
+/** Kinds of field the builder understands. Anything else is dropped. */
+export type FormSchemaFieldType = "short_text" | "long_text" | "email" | "number" | "single_choice" | "multi_choice" | "dropdown" | "statement" | "image";
+/** One choice of a `single_choice`, `multi_choice` or `dropdown` field. */
+export interface FormSchemaFieldOption {
+    /** Stable within the form. The server mints one when you leave it out. */
+    readonly id?: string;
+    readonly label: string;
+}
+/**
+ * One field of a form.
+ *
+ * `id` is the key answers are filed under - NOT the label. Leave it out on
+ * create and the server mints a UUID, which you then have to read back before
+ * you can submit anything.
+ */
+export interface FormSchemaField {
+    readonly id?: string;
+    readonly type: FormSchemaFieldType;
+    readonly label: string;
+    readonly description?: string;
+    readonly required?: boolean;
+    readonly placeholder?: string;
+    /** Only meaningful on the three choice types. */
+    readonly options?: FormSchemaFieldOption[];
+    /** Only meaningful on `number`. */
+    readonly min?: number;
+    /** Only meaningful on `number`. */
+    readonly max?: number;
+}
+/**
+ * The field definition of a form. The server rebuilds this from scratch on
+ * every write, keeping only the keys above, so anything extra is lost without
+ * a word.
+ */
+export interface FormSchema {
+    readonly fields: FormSchemaField[];
+}
+/**
+ * Styling of a form. Colours must be `#RRGGBB`; images must be `data:image/`
+ * URIs under 2 MB. Anything else in here is dropped silently.
+ */
+export interface FormTheme {
+    readonly bg_color?: string;
+    readonly fg_color?: string;
+    readonly accent_color?: string;
+    readonly card_color?: string;
+    readonly mode?: "light" | "dark" | "custom";
+    readonly font?: "inter" | "cantarell" | "system";
+    /** `data:image/...` or `null` to clear. */
+    readonly bg_image?: string | null;
+    /** `data:image/...` or `null` to clear. */
+    readonly logo_image?: string | null;
+}
+/** Behaviour switches. Like the theme, unknown keys are dropped. */
+export interface FormSettings {
+    readonly layout?: "one_per_screen" | "single_page";
+    /** Makes the public form and its submissions require a credential. */
+    readonly require_login?: boolean;
+    readonly show_progress?: boolean;
+    readonly collect_email?: boolean;
+    /** These five are truncated to 500 characters. */
+    readonly welcome_title?: string;
+    readonly welcome_subtitle?: string;
+    readonly submit_label?: string;
+    readonly thank_you_title?: string;
+    readonly thank_you_subtitle?: string;
+}
+/** A hosted form, owner view. */
+export interface Form extends BaseRecord {
+    readonly user_id: Id;
+    readonly title: string;
+    readonly status: FormStatus;
+    readonly schema: FormSchema;
+    readonly theme: FormTheme;
+    readonly settings: FormSettings;
+    /** Public path segment, e.g. `"contacto"`. `null` if the pairing is broken. */
+    readonly endpoint: string | null;
+    /** Shareable short URL, or `null` while there is no endpoint. */
+    readonly published_url: string | null;
+    /** Set the first time the form is published, and never cleared. */
+    readonly published_at?: Timestamp | null;
+    readonly views_count: number;
+    readonly submissions_count: number;
+}
+/** The reduced form a public respondent is allowed to see. */
+export interface PublicForm {
+    readonly id: Id;
+    readonly title: string;
+    readonly schema: FormSchema;
+    readonly theme: FormTheme;
+    readonly settings: FormSettings;
+    readonly endpoint: string;
+    readonly require_login: boolean;
+}
+/**
+ * One answered form.
+ *
+ * Deliberately has no `updated_at`: a submission is never edited, and the
+ * blueprint leaves the field out rather than render a lie.
+ */
+export interface FormSubmission {
+    readonly id: Id;
+    readonly form_id: Id;
+    /** The respondent, when they were signed in. */
+    readonly user_id?: Id | null;
+    /**
+     * Answers keyed by {@link FormSchemaField.id}. An `image` answer is
+     * `{ attachment_id, filename }`; a `number` is a float; a `multi_choice` is
+     * an array of strings; everything else is a string.
+     */
+    readonly answers: Record<string, Json>;
+    /** Resolved from the respondent's IP. */
+    readonly country?: string | null;
+    /** Parsed from the respondent's user agent. */
+    readonly device_name?: string | null;
+    readonly completed_at?: Timestamp | null;
+    readonly created_at: Timestamp;
+}
+/** What `POST /form_attachments` answers with. */
+export interface FormAttachment {
+    readonly id: Id;
+    readonly filename: string;
+    readonly content_type: string;
+    /** Absolute URL that serves the bytes inline, no credential required. */
+    readonly url: string;
+}
+/**
+ * `GET /forms/endpoint_availability`. Read `available`; `suggestions` is only
+ * present when the endpoint is well formed but taken.
+ */
+export interface FormEndpointAvailability {
+    readonly endpoint: string;
+    /** Whether it matches the format and is not reserved. */
+    readonly valid: boolean;
+    readonly available: boolean;
+    /** `"invalid"` when the format or the reserved list rejected it. */
+    readonly reason?: string;
+    readonly suggestions?: string[];
+}
+/**
+ * Arguments for creating a form.
+ *
+ * The form always starts as a `"draft"`: `status` is not writable here, only
+ * through {@link UpdateFormInput}. `require_login` lives in `settings`.
+ */
+export interface CreateFormInput {
+    readonly title: string;
+    /**
+     * Public path segment. Lowercased, 1 to 64 characters of `[a-z0-9_-]`
+     * starting and ending alphanumeric, and never one of `new create index
+     * admin api login signup help`.
+     */
+    readonly endpoint: string;
+    readonly schema?: FormSchema;
+    readonly theme?: FormTheme;
+    readonly settings?: FormSettings;
+}
+/**
+ * Fields that can change afterwards. A true PATCH: only the keys you pass are
+ * touched, and each of `schema`, `theme` and `settings` is replaced wholesale
+ * rather than merged.
+ */
+export interface UpdateFormInput {
+    readonly title?: string;
+    /** Renames the paired short link, so the old public URL stops working. */
+    readonly endpoint?: string;
+    readonly schema?: FormSchema;
+    readonly theme?: FormTheme;
+    readonly settings?: FormSettings;
+    /**
+     * An unrecognised status is IGNORED in silence and still answers 200 with
+     * the old value, so read the returned form rather than trusting the code.
+     */
+    readonly status?: FormStatus;
+}
+/** Arguments for answering a form. */
+export interface SubmitFormInput {
+    /** The form's public endpoint, not its id. */
+    readonly endpoint: string;
+    /**
+     * Answers keyed by {@link FormSchemaField.id}. Keys that are not in the
+     * schema are discarded in silence, so send ids, never labels.
+     */
+    readonly answers: Record<string, Json>;
+    /**
+     * Files for `image` fields, keyed by the same field id. The SDK uploads each
+     * one to `POST /form_attachments` first and folds the resulting
+     * `{ attachment_id }` into `answers`, which is the shape the endpoint reads.
+     *
+     * Authenticated callers, in practice. Each of those uploads is a separate
+     * request an anonymous caller has to pass a captcha for, and a Turnstile
+     * token is single-use: one token cannot cover both an upload and the
+     * submission. An anonymous caller uploads each file through
+     * {@link FormSubmissionsNamespace.uploadAttachment} with its own fresh
+     * token, then writes `{ attachment_id }` into `answers` by hand.
+     */
+    readonly files?: Record<string, FileInput>;
+    /**
+     * Turnstile token. Required while the caller is anonymous, ignored
+     * otherwise. Single-use: one token pays for one request.
+     */
+    readonly captchaToken?: string;
+}
+/** Arguments for staging one file against a public form. */
+export interface UploadFormAttachmentInput {
+    /** The form's public endpoint. */
+    readonly endpoint: string;
+    /** JPEG, PNG, WebP, GIF or HEIC, up to 8 MB. */
+    readonly file: FileInput;
+    /**
+     * Turnstile token. Required while the caller is anonymous, ignored
+     * otherwise. Single-use: one token pays for one upload.
+     */
+    readonly captchaToken?: string;
+}
+/** Filters for {@link FormSubmissionsNamespace.list}. */
+export interface ListFormSubmissionsParams {
+    readonly formId: Id;
+}
+/** Submissions of a form, reachable as `oms.forms.submissions`. */
+export declare class FormSubmissionsNamespace extends Resource {
+    /**
+     * `GET /form_submissions?form_id=...` - the answers, newest first. Owner
+     * only.
+     *
+     * Not paginated: the endpoint takes no page modifier and hard-caps itself at
+     * the 500 most recent, so a busy form silently loses its tail. That is why
+     * this returns an array rather than a `Paginated` that could never advance.
+     */
+    list(params: ListFormSubmissionsParams, options?: RequestOptions): Promise<FormSubmission[]>;
+    /**
+     * `POST /form_submissions` - answers a published form.
+     *
+     * Anonymous unless the form sets `settings.require_login`, in which case an
+     * anonymous caller gets 401. Answers are coerced to the type each field
+     * declares and the whole payload is capped at 200 000 bytes of JSON.
+     *
+     * Answers only the new submission's id: the server does not echo the record
+     * back, and the respondent has no permission to read it afterwards.
+     *
+     * Not retried by default: a replayed submission would be recorded twice.
+     */
+    create(input: SubmitFormInput, options?: RequestOptions): Promise<{
+        id: Id;
+    }>;
+    /**
+     * `POST /form_attachments` - stages one image against a published form and
+     * hands back the id an `image` answer refers to.
+     *
+     * Called for you by {@link create} when you pass `files`; reach for it
+     * directly only to upload before the rest of the answers are ready.
+     * Throttled to 30 an hour per IP for anonymous callers.
+     */
+    uploadAttachment(input: UploadFormAttachmentInput, options?: RequestOptions): Promise<FormAttachment>;
+}
+/** The `forms` namespace, reachable as `oms.forms`. */
+export declare class FormsNamespace extends Resource {
+    /** Answers to a form, and the files staged against one. */
+    readonly submissions: FormSubmissionsNamespace;
+    constructor(http: ApiClient);
+    /**
+     * `GET /forms` - the forms you own, most recently edited first, each with
+     * its submission count.
+     *
+     * Not paginated and not filterable: the endpoint takes no modifiers and
+     * answers with the whole set.
+     */
+    list(options?: RequestOptions): Promise<Form[]>;
+    /** `GET /forms/:id` - the full definition, owner view. */
+    get(id: Id, options?: RequestOptions): Promise<Form>;
+    /**
+     * `GET /forms/by_endpoint/:endpoint` - the respondent's view. Answers only
+     * for a published form; a draft is a 404.
+     *
+     * Every call INCREMENTS the form's `views_count`. Do not use it to poll for
+     * changes, and do not call it on behalf of the owner: use {@link get}.
+     *
+     * @throws {OmsAuthError} 401 when the form requires a login and there is none.
+     */
+    getPublic(endpoint: string, options?: RequestOptions): Promise<PublicForm>;
+    /**
+     * `GET /forms/endpoint_availability` - whether an endpoint is free, with
+     * alternatives when it is not. The server is still the authority: create can
+     * lose a race and answer 400.
+     */
+    endpointAvailability(endpoint: string, options?: RequestOptions): Promise<FormEndpointAvailability>;
+    /** {@link endpointAvailability} reduced to its verdict. */
+    endpointAvailable(endpoint: string, options?: RequestOptions): Promise<boolean>;
+    /**
+     * `POST /forms` - creates the form and reserves its endpoint in one
+     * transaction. The form starts as a draft; publish it with
+     * {@link update}.
+     *
+     * Not retried by default: a replayed create would fail on the endpoint being
+     * taken by its own first attempt.
+     */
+    create(input: CreateFormInput, options?: RequestOptions): Promise<Form>;
+    /** `PATCH /forms/:id`. Only the keys you pass are touched. */
+    update(id: Id, input: UpdateFormInput, options?: RequestOptions): Promise<Form>;
+    /** Convenience over {@link update} with `status: "published"`. */
+    publish(id: Id, options?: RequestOptions): Promise<Form>;
+    /** `DELETE /forms/:id`. Takes the submissions and the endpoint with it. */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /**
+     * `GET /form_attachments/:id` - one file a respondent uploaded.
+     *
+     * Served inline with `X-Content-Type-Options: nosniff`, and readable by
+     * anyone holding the id.
+     */
+    attachment(attachmentId: Id, options?: RequestOptions): Promise<Blob>;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Every resource namespace, in one place.
+ *
+ * `client.ts` imports the namespace classes from here indirectly (it imports
+ * the modules themselves, so a namespace can be dropped in without editing an
+ * aggregator), and consumers import the record and input types from here.
+ *
+ * Re-exports every sibling module so nobody has to touch this file again: a new
+ * resource means one new file plus one line in {@link Oms}, and no edit to a
+ * file another agent may also be holding.
+ *
+ * Naming rule that keeps `export *` unambiguous: every exported name is
+ * prefixed by its domain (`ShortLink`, `ShortLinkStats`, `CreateShortLinkInput`).
+ * A bare `Stats` or `CreateInput` would collide the moment a second resource
+ * wanted one, and TypeScript reports that as an error at this file, not at the
+ * file that caused it.
+ */
+export * from "./account";
+export * from "./chests";
+export * from "./dynamicQrs";
+export * from "./forms";
+export * from "./ipLookup";
+export * from "./jobs";
+export * from "./linkTrees";
+export * from "./notepads";
+export * from "./shortLinks";
+export * from "./storage";
+export * from "./storage/upload";
+export * from "./tickets";
+export * from "./tools/index";

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

@@ -0,0 +1,63 @@
+/**
+ * The `ipLookup` namespace: network metadata for an IP address.
+ *
+ * Works anonymously. The special argument `"mine"` asks the backend what IP it
+ * sees the caller coming from, which is the only way for a client behind NAT
+ * or a proxy to learn its own public address.
+ *
+ * The name promises more than the service delivers, and it is worth knowing
+ * before you build a UI on it: the database behind `IpLookuper` is built by
+ * `backend/bin/create_mmdb` from the iptoasn.com IP-to-ASN table, NOT from a
+ * GeoIP City database. It knows the country, the autonomous system and the
+ * network - it does not know the city, the coordinates or the timezone, and no
+ * amount of asking will make those appear.
+ */
+import { Resource } from "../http";
+import type { RequestOptions } from "../types";
+/**
+ * What the lookup service knows about an address.
+ *
+ * Every field comes straight out of the MMDB record, so the shape is exactly
+ * what the backend read: no field is computed and none is filled in for a
+ * missing row - a miss is a 400, not a half-empty object.
+ */
+export interface IpLookupResult {
+    /** The address that was looked up, echoed back. For `"mine"`, the resolved one. */
+    readonly ip: string;
+    /**
+     * ISO 3166-1 alpha-2, **lowercase** (`"pt"`, `"us"`), or the literal
+     * `"unknown"` when the source table had no country for the range. Uppercase
+     * it yourself before feeding it to a flag or a locale lookup.
+     */
+    readonly country: string;
+    /** Autonomous system number, or `0` when the range is not announced. */
+    readonly asn: number;
+    /** Network operator name as the AS registry spells it, e.g. `"GOOGLE"`. */
+    readonly organization: string;
+    /** The CIDR block the address fell in, e.g. `"8.8.8.0/24"`. */
+    readonly network: string;
+}
+/** The `ipLookup` namespace, reachable as `oms.ipLookup`. */
+export declare class IpLookupNamespace extends Resource {
+    /**
+     * `GET /ip_lookup/:ip` - looks up any IPv4 or IPv6 address.
+     *
+     * Anonymous. Counts against the general anonymous ceiling (120/min per IP)
+     * or the authenticated one (600/min per session) when a token is set.
+     *
+     * @param ip The address, or the literal `"mine"` (prefer {@link mine} for
+     *   that, it reads better at the call site).
+     * @throws {OmsApiError} 400 `Invalid IP address` when the argument does not
+     *   parse as an address, and also when it parses but the database has no row
+     *   for it. The two cases are not distinguishable from the response.
+     */
+    get(ip: string, options?: RequestOptions): Promise<IpLookupResult>;
+    /**
+     * `GET /ip_lookup/mine` - the public address the backend sees this client
+     * arriving from.
+     *
+     * Behind Cloudflare the backend reads `CF-Connecting-IP`, so this is the
+     * client's real address, not the edge's.
+     */
+    mine(options?: RequestOptions): Promise<IpLookupResult>;
+}

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

@@ -0,0 +1,233 @@
+/**
+ * The `jobs` namespace: the one place a background job is polled.
+ *
+ * Every asynchronous tool (upscale, background removal, transcription, vocal
+ * separation, captions, jumpstyle) enqueues a job and hands back a `job_id`
+ * plus, for an anonymous caller, a `watch_token`. That token grants read access
+ * to exactly one job and is the reason `GET /jobs/:id` is reachable without a
+ * credential.
+ *
+ * Every tool namespace that returns a job delegates its `wait()` to
+ * {@link JobsNamespace.wait}, so the polling policy lives here once. Do not
+ * write a second polling loop inside a tool module.
+ *
+ * Only two tools enqueue through the generic `jobs` table - background removal
+ * and upscale. The other five are polled by re-reading their own row, which is
+ * still not a reason to write a loop there: {@link pollUntilTerminal} is the
+ * same engine with a different `poll` function, and that is what those modules
+ * call.
+ *
+ * The loop is deliberately dumb and bounded:
+ *
+ * - the first poll happens immediately, with no initial pause;
+ * - each pause is {@link POLL_BACKOFF_FACTOR} times the last, capped at
+ *   {@link MAX_POLL_INTERVAL_MS}, so a five-second job costs a handful of
+ *   requests and a ninety-minute one does not cost eleven thousand;
+ * - there is no jitter. A poll loop is one client watching one job; the place a
+ *   herd actually forms is a 429, and `Retry-After` is honoured by the
+ *   transport, which is where that belongs;
+ * - `waitTimeoutMs` is the caller's deadline and has NO default. A job that the
+ *   server never terminalises would otherwise hang an isolate forever, so pass
+ *   one - or a `signal` - whenever the caller is not a person watching a
+ *   terminal.
+ *
+ * Three outcomes, and they are different types on purpose:
+ *
+ * | What happened | How it arrives |
+ * |---|---|
+ * | The work finished, well or badly | resolves with a {@link Job}; read `status` |
+ * | The client gave up first | throws {@link OmsTimeoutError} with `code: "timeout"` |
+ * | The caller aborted | throws {@link OmsTimeoutError} with `code: "aborted"` |
+ *
+ * A job that ends `"failed"` is an ANSWER, not a transport error: the request
+ * cycle worked perfectly and the work did not. Only the caller knows whether
+ * that deserves an exception.
+ */
+import { Resource } from "../http";
+import type { BaseRecord, Id, Json, JobStatus, Paginated, PageParams, Progress, RequestOptions, Timestamp, WaitOptions } from "../types";
+/**
+ * The five status strings, spelled the way the backend spells them.
+ *
+ * `complete`, not `completed`. `canceled`, one L. Reach for this object instead
+ * of typing the literal: a loop that waits for `"completed"` waits forever.
+ */
+export declare const JOB_STATUS: Readonly<{
+    readonly pending: "pending";
+    readonly processing: "processing";
+    readonly complete: "complete";
+    readonly failed: "failed";
+    readonly canceled: "canceled";
+}>;
+/**
+ * Statuses a job never leaves.
+ *
+ * Note `canceled` is here and has no equivalent on a tool row: a job can be
+ * cancelled out from under a tool whose own row is still `"pending"`.
+ */
+export declare const JOB_TERMINAL_STATUSES: readonly JobStatus[];
+/** True once this status can never change again. */
+export declare function isJobTerminal(status: string): boolean;
+/** A background job. */
+export interface Job extends BaseRecord {
+    readonly status: JobStatus;
+    /**
+     * Feature-level kind of the run. Today the backend only ever writes
+     * `"omsvs"` (vocal separation) or `"unknown"`, which is the column default
+     * every generic enqueue gets - including the upscale and background-removal
+     * proxies. It is NOT the worker's class name.
+     */
+    readonly job_type: string;
+    /** Enqueue-time arguments, when the enqueuer wrote any. Shape depends on `job_type`. */
+    readonly payload?: Json;
+    /** Set when a worker claimed the job. */
+    readonly started_at?: Timestamp | null;
+    readonly finished_at?: Timestamp | null;
+    /**
+     * Percentage, an integer in `[0, 100]`. The column is `NOT NULL DEFAULT 0`,
+     * so it is a real number from the moment the row exists and 0 means "not
+     * started", never "unknown".
+     */
+    readonly progress?: number | null;
+    /** Failure message, set once `status === "failed"` (or a cancellation reason). */
+    readonly error?: string | null;
+    /** Worker-specific payload; shape depends on `job_type`. */
+    readonly result?: Json;
+    /** Who enqueued it. `null` for a job with no owner, e.g. an anonymous tool run. */
+    readonly creator_id?: Id | null;
+    /** Which worker claimed it. */
+    readonly worker_id?: string | null;
+}
+/**
+ * How to address a job.
+ *
+ * An authenticated caller needs only the id. An anonymous one must also present
+ * the `watchToken` the tool handed back at enqueue time.
+ */
+export interface JobRef {
+    readonly id: Id;
+    /** Signed token scoped to this one job. Required when anonymous. */
+    readonly watchToken?: string;
+}
+/** Filters for {@link JobsNamespace.list}. */
+export interface ListJobsParams extends PageParams {
+    readonly status?: JobStatus | JobStatus[];
+    readonly jobType?: string | string[];
+}
+/** Pause before the second poll, in milliseconds. */
+export declare const DEFAULT_POLL_INTERVAL_MS = 1000;
+/** Ceiling for one pause, in milliseconds. */
+export declare const MAX_POLL_INTERVAL_MS = 15000;
+/** Each pause is this many times the last one, until the ceiling. */
+export declare const POLL_BACKOFF_FACTOR = 1.5;
+/**
+ * Everything {@link pollUntilTerminal} needs to watch something finish.
+ *
+ * Generic over the record because the seven tools are polled two different
+ * ways - two through `GET /jobs/:id`, five through their own `show` - and only
+ * `poll` and `terminal` differ between them. Nothing else about the loop does,
+ * which is exactly why there is one loop.
+ */
+export interface PollUntilTerminalOptions<T> extends WaitOptions {
+    /**
+     * Reads the current state. Called once immediately, then again after every
+     * pause. It is handed the request-shaped half of these options (signal,
+     * per-request timeout, headers, retry), never the wait-shaped half.
+     */
+    readonly poll: (options: RequestOptions) => Promise<T>;
+    /** True once `state` can never change again. */
+    readonly terminal: (state: T) => boolean;
+    /**
+     * Maps a state onto a {@link Progress} for `onProgress`. Its `status` is also
+     * what the timeout message quotes, so a run that gave up says what it was
+     * last doing.
+     */
+    readonly progress?: (state: T) => Progress;
+    /** What is being waited on, for the timeout message: `"job 3f2a"`. */
+    readonly label?: string;
+}
+/**
+ * Polls until `terminal` says so, then returns the final state.
+ *
+ * This is THE polling loop of the SDK. A resource module supplies `poll` and
+ * `terminal`; it does not supply a `while`.
+ *
+ * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapsed,
+ *   `code: "aborted"` when the caller's signal fired.
+ * @throws {OmsApiError} whatever `poll` throws - a 404 once a finished job's
+ *   24-hour retention expires, a 401 for an anonymous caller with no watch
+ *   token. A polling loop is not the place to swallow those.
+ */
+export declare function pollUntilTerminal<T>(options: PollUntilTerminalOptions<T>): Promise<T>;
+/**
+ * Same loop as {@link pollUntilTerminal}, but yields every state it observes -
+ * including the terminal one, which is also the generator's return value.
+ *
+ * For a host that would rather render each step than take a callback. Breaking
+ * out of the `for await` stops the loop; nothing is left running.
+ */
+export declare function watchUntilTerminal<T>(options: PollUntilTerminalOptions<T>): AsyncGenerator<T, T, undefined>;
+/** The `jobs` namespace, reachable as `oms.jobs`. */
+export declare class JobsNamespace extends Resource {
+    /**
+     * `GET /jobs` - your jobs. Requires a credential; a watch token cannot list.
+     *
+     * An admin sees every job, a signed-in user sees the ones they created, and
+     * an anonymous caller sees an empty page - never a 401, because the scope is
+     * empty rather than forbidden.
+     *
+     * @throws {OmsApiError} 400 naming the key when a filter is not on the
+     *   controller's allowlist (`id`, `job_type`, `status`, `created_at`,
+     *   `updated_at`, `finished_at`).
+     */
+    list(params?: ListJobsParams, options?: RequestOptions): Promise<Paginated<Job>>;
+    /**
+     * `GET /jobs/:id` - one poll, no waiting.
+     *
+     * A `watchToken` is sent as `?watch_token=`, which is the only way an
+     * anonymous caller reaches a job. The server checks the signature resolves to
+     * the job named in the path, so the token cannot be pointed at another id.
+     *
+     * @throws {OmsApiError} 404 when the job is gone, which for a finished job
+     *   also happens once its retention window expires. A wrong, expired or
+     *   missing watch token is the same 404, not a 401: the controller never says
+     *   whether the id exists.
+     */
+    get(ref: JobRef | Id, options?: RequestOptions): Promise<Job>;
+    /**
+     * Polls until the job reaches a terminal state, then returns it.
+     *
+     * The polling policy belongs here, not in the callers: start at
+     * `pollIntervalMs`, back off towards a ceiling, stop at `waitTimeoutMs`, and
+     * abort immediately if the caller's `signal` fires. `onProgress` is called on
+     * every poll so a host can drive a spinner.
+     *
+     * Resolves for `"complete"`, `"failed"` AND `"canceled"` - a job that ended
+     * badly is an answer, not a transport error. Check `job.status` before
+     * reading `job.result`.
+     *
+     * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapses
+     *   first, `code: "aborted"` when the caller's signal fires.
+     */
+    wait(ref: JobRef | Id, options?: WaitOptions): Promise<Job>;
+    /**
+     * Yields the job's state on every poll until it finishes, for a host that
+     * wants to render each step rather than take a callback.
+     *
+     * The terminal state is both the last value yielded and the generator's
+     * return value, so neither `for await` nor a manual `next()` loop can miss
+     * it.
+     */
+    watch(ref: JobRef | Id, options?: WaitOptions): AsyncGenerator<Job, Job, undefined>;
+    /** The one description of "watching a job", shared by `wait` and `watch`. */
+    private pollPlan;
+}
+/** Normalises the two ways a job can be addressed into the object form. */
+export declare function jobRef(ref: JobRef | Id): JobRef;
+/**
+ * Renders a job as a {@link Progress}.
+ *
+ * `total` is 100 rather than `undefined` because `progress` is a percentage the
+ * server always has: the column is `NOT NULL DEFAULT 0`, so there is no
+ * "unknown" to be honest about.
+ */
+export declare function jobProgress(job: Job): Progress;