@omelhorsite/sdk 0.4.0 → 0.4.1

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

@@ -31,7 +31,7 @@ export interface Chest extends BaseRecord {
     readonly expires_at: Timestamp;
     /** Owner, when the chest was created by a signed-in user. */
     readonly creator_id?: Id | null;
-    /** Present on every read: `find_or_create` renders the `:extended` view. */
+    /** Present on every read. */
     readonly chest_entries?: ChestEntry[];
 }
 /** One item inside a chest: a note, or a file. */
@@ -112,7 +112,7 @@ export declare class ChestEntriesNamespace extends Resource {
     constructor(http: ApiClient);
     /**
      * Adds an entry. A note is one request; a file goes through
-     * {@link createWithUpload}, because a chest never takes bytes through Rails.
+     * {@link createWithUpload}, because a chest never takes bytes through the API.
      *
      * ```ts
      * await oms.chests.entries.create({ chestId, name: "notes", content: "..." });
@@ -128,9 +128,9 @@ export declare class ChestEntriesNamespace extends Resource {
      * 3. the PUT goes straight to object storage, with no `Authorization`;
      * 4. `POST /chest_entries/:id/attach_blob` binds the bytes to the entry.
      *
-     * Step 2 may be called ONCE per entry: a second call raises an unhandled
-     * `ArgumentError` server-side and comes back as a 500, so a naive retry is
-     * worse than useless. The SDK therefore treats the whole thing as atomic -
+     * Step 2 may be called ONCE per entry: a second call comes back as a 500, so
+     * a naive retry is worse than useless. The SDK therefore treats the whole
+     * thing as atomic -
      * anything that fails after step 1 destroys the half-built entry (releasing
      * the space it reserved) before rethrowing, so a retry starts clean.
      *
@@ -141,28 +141,25 @@ export declare class ChestEntriesNamespace extends Resource {
     /**
      * `GET /chest_entries/:id/data` - the entry's bytes.
      *
-     * SENT WITH NO CREDENTIAL, deliberately. `ChestEntriesController` lists
-     * `data` in `allow_unauthenticated_access`, and the action itself is three
-     * lines: find the entry by id, check that something is attached, redirect.
-     * It never looks at the chest name, the chest token, or who is asking. The
-     * ENTRY ID IS THE WHOLE CAPABILITY - which is worth knowing for its own sake,
-     * and which also means a credential on this request could not possibly change
-     * the answer.
-     *
-     * That matters because sending one breaks the call in a browser. The action
-     * answers `302` to `minio.omelhorsite.pt`, and following that hop replaces the
-     * request's origin with an opaque one (Fetch standard: a cross-origin
-     * redirect of a CORS request whose origin already differs from the current
-     * URL's origin), so the store sees `Origin: null` and answers
-     * `Access-Control-Allow-Origin: *`. Wildcard plus credentials is illegal, so a
-     * client built with `sessionCookie: true` - the production web app - would
-     * have the browser reject the bytes with an opaque "Failed to fetch". Asking
-     * anonymously sidesteps it: `*` is fine for an uncredentialed request.
-     *
-     * Two shapes come back and both are handled here. Against MinIO it is the
-     * `302`. Against a Disk service (dev, test) presigning raises `ArgumentError`
-     * and the controller falls back to `send_data`, so the bytes arrive inline
-     * from Rails with a `Content-Disposition`. Either way this returns the bytes.
+     * SENT WITH NO CREDENTIAL, deliberately. The endpoint checks only that the
+     * entry exists and has bytes attached - never the chest name, the chest
+     * token, or who is asking. The ENTRY ID IS THE WHOLE CAPABILITY - which is
+     * worth knowing for its own sake, and which also means a credential on this
+     * request could not possibly change the answer.
+     *
+     * That matters because sending one breaks the call in a browser. The
+     * endpoint answers `302` to the object store, and following that hop
+     * replaces the request's origin with an opaque one (Fetch standard: a
+     * cross-origin redirect of a CORS request whose origin already differs from
+     * the current URL's origin), so the store sees `Origin: null` and answers
+     * `Access-Control-Allow-Origin: *`. Wildcard plus credentials is illegal, so
+     * a client built with `sessionCookie: true` would have the browser reject
+     * the bytes with an opaque "Failed to fetch". Asking anonymously sidesteps
+     * it: `*` is fine for an uncredentialed request.
+     *
+     * Two shapes come back and both are handled here: the `302` to the object
+     * store, or the bytes inline with a `Content-Disposition`. Either way this
+     * returns the bytes.
      *
      * Going around the transport costs the usual thing: no retry, no per-call
      * deadline, only the caller's `signal`. Use {@link downloadUrl} when the
@@ -177,10 +174,9 @@ export declare class ChestEntriesNamespace extends Resource {
      * new tab.
      *
      * Synchronous and credential-free, because the endpoint is: the entry id is
-     * the only thing it checks. The frontend's older helper appended a `?token=`
-     * here; this deliberately does not, because a session token in a URL that
-     * ends up in markup, in a shared link and in an access log buys precisely
-     * nothing on a route that never reads it.
+     * the only thing it checks. No `?token=` is appended, because a session
+     * token in a URL that ends up in markup, in a shared link and in an access
+     * log buys precisely nothing on a route that never reads it.
      *
      * Treat the URL as a bearer capability all the same. Anyone holding it can
      * pull the file until the chest expires, so it is exactly as shareable as the

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

@@ -2,9 +2,9 @@
  * The `dynamicQrs` namespace: QR codes whose destination can be changed after
  * the code has been printed.
  *
- * Under the hood each one is a `ShortLink` in the reserved `"qr"` namespace
- * with a server-minted UUID endpoint, plus the styling the renderer needs. It
- * is a separate resource because the endpoint is not user-chosen, the payload
+ * Each one is a short link in the reserved `"qr"` namespace with a
+ * server-minted UUID endpoint, plus the styling a renderer needs. It is a
+ * separate resource because the endpoint is not user-chosen, the payload
  * carries `settings`, and the plain short-link listing filters system
  * namespaces out - a dynamic QR will never appear in `oms.shortLinks.list()`.
  *
@@ -20,30 +20,28 @@ import { type ShortLinkId, type ShortLinkStats } from "./shortLinks";
 /**
  * The reserved short-link namespace every dynamic QR lives in.
  *
- * `ShortLink::DYNAMIC_QR_NAMESPACE`. It is not a user choice and it never
- * changes on a record, which is why {@link DynamicQr.namespace} is typed as
- * this literal rather than as a string.
+ * It is not a user choice and it never changes on a record, which is why
+ * {@link DynamicQr.namespace} is typed as this literal rather than as a string.
  */
 export declare const DYNAMIC_QR_NAMESPACE = "qr";
 /** Public prefix a dynamic QR resolves under. */
 export declare const DYNAMIC_QR_BASE_URL = "https://omelhor.site/qr";
-/** Module shapes `DynamicQrs::SettingsSanitizer` accepts. Anything else is dropped. */
+/** Module shapes the server accepts. Anything else is dropped. */
 export type DynamicQrStyle = "classic" | "rounded" | "dots" | "extraRounded" | "classy" | "classyRounded";
 /**
  * Styling of a dynamic QR.
  *
- * The backend runs this bag through `DynamicQrs::SettingsSanitizer`, which
- * **silently drops** every key it does not recognise and every value that fails
- * its check - a bad `style`, a colour that is not `#rrggbb`. An unknown or
- * malformed key is therefore a no-op, not an error, and the only way to know
- * what stuck is to read `settings` back off the response.
+ * The server **silently drops** every key it does not recognise and every
+ * value that fails its check - a bad `style`, a colour that is not `#rrggbb`.
+ * An unknown or malformed key is therefore a no-op, not an error, and the only
+ * way to know what stuck is to read `settings` back off the response.
  *
  * The two exceptions that DO fail loudly are `logo` and `bg_image`: a value
  * that is neither `null`/`""` nor a `data:image/...` URI under the size cap is
  * a 400.
  *
- * The SDK does not render any of this; it is what the web tool's renderer
- * consumes. `oms.local.qr` draws a plain symbol from the matrix instead.
+ * The SDK does not render any of this. `oms.local.qr` draws a plain symbol
+ * from the matrix instead.
  */
 export interface DynamicQrSettings {
     /** Module shape. Values outside {@link DynamicQrStyle} are dropped. */
@@ -75,51 +73,38 @@ export interface DynamicQrSettings {
     /** How the background image sits against `bg_color`. Anything but `"replace"` reads as `"behind"`. */
     readonly bg_image_mode?: "replace" | "behind";
     /**
-     * The stored bag is free-form JSON, so a code saved by an older version of
-     * the web tool can carry keys this interface does not name.
+     * The stored bag is free-form JSON, so a code saved by an older client can
+     * carry keys this interface does not name.
      */
     readonly [key: string]: unknown;
 }
 /**
  * A dynamic QR code.
  *
- * `DynamicQrBlueprint` renders `ApplicationBlueprint`'s three automatic keys
- * (`id`, `created_at`, `updated_at`) plus exactly five more, and that is the
- * whole record. Two keys a client migrating off the old web service will
- * expect are NOT here and never were on this endpoint: `website_id` and
- * `website_managed`. They are residue of the websites feature, which was
- * extracted out of this backend entirely - there is no such column on
- * `short_links` and no such field on any blueprint, so anything declaring them
- * has been reading `undefined`.
- *
- * The blueprint is also never resolved automatically. A dynamic QR IS a
- * `ShortLink`, and `ShortLinkBlueprint` already owns that name with a
- * different shape (associations, no `settings`), so every call site passes
- * this blueprint explicitly. That is why the two records disagree about which
- * fields exist even though they are rows in one table.
+ * Eight keys, and that is the whole record. There is no `website_id` and no
+ * `website_managed`. A dynamic QR is a short link, but the two records carry
+ * different fields: this one has `settings` and no associations.
  */
 export interface DynamicQr extends Omit<BaseRecord, "id"> {
-    /** Integer primary key: a dynamic QR is a `short_links` row. See {@link ShortLinkId}. */
+    /** Integer primary key: a dynamic QR is a short link. See {@link ShortLinkId}. */
     readonly id: number;
     /** Current destination. Changing it re-points every printed copy at once. */
     readonly url: string;
     /** Server-assigned UUID the QR image encodes. Not choosable, not renameable. */
     readonly endpoint: string;
     /**
-     * Always {@link DYNAMIC_QR_NAMESPACE}. The controller writes it on create
-     * and nothing can change it afterwards, and the listing scope filters on it,
-     * so a record that reached you through this namespace cannot hold anything
-     * else.
+     * Always {@link DYNAMIC_QR_NAMESPACE}. Set on create, never changeable, and
+     * the listing filters on it, so a record that reached you through this
+     * namespace cannot hold anything else.
      */
     readonly namespace: typeof DYNAMIC_QR_NAMESPACE;
     /**
-     * Owner. The column is nullable because anonymous short links exist, but
-     * every route on this resource requires a credential and the controller
-     * always sets the owner, so in practice this is never `null` for a dynamic
-     * QR.
+     * Owner. Nullable because anonymous short links exist, but every route on
+     * this resource requires a credential and always sets the owner, so in
+     * practice this is never `null` for a dynamic QR.
      */
     readonly user_id: Id | null;
-    /** Never `null`: the blueprint substitutes `{}` for an unset bag. */
+    /** Never `null`: `{}` for an unset bag. */
     readonly settings: DynamicQrSettings & JsonObject;
 }
 /** Arguments for creating a dynamic QR. */
@@ -132,7 +117,7 @@ export interface CreateDynamicQrInput {
 /**
  * Fields that can change afterwards.
  *
- * `settings` is **merged** into the stored bag by the backend, not replaced, so
+ * `settings` is **merged** into the stored bag server-side, not replaced, so
  * an update can never unset a key by omitting it. To clear one, send it
  * explicitly with the value that means empty (`null` for `logo`/`bg_image`).
  */
@@ -146,10 +131,9 @@ export declare class DynamicQrsNamespace extends Resource {
      * `GET /dynamic_qrs` - every code you own, newest first.
      *
      * Returns a plain array rather than a page object, and that is not an
-     * oversight: this controller does not use `CrudActions` and ignores
-     * `modifiers[page]` entirely, so it always answers with the complete set. A
-     * `Paginated` here would be a fiction with a `next()` that refetched
-     * everything.
+     * oversight: the endpoint ignores `modifiers[page]` entirely and always
+     * answers with the complete set. A `Paginated` here would be a fiction with
+     * a `next()` that refetched everything.
      *
      * @throws {OmsAuthError} 401 when anonymous.
      */

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

@@ -7,16 +7,12 @@
  * 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.
+ * The endpoint belongs to a short link paired with the form, 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";
-/**
- * The reserved short-link namespace a published form is served under.
- * `Form::NAMESPACE` / `ShortLink::FORM_NAMESPACE`.
- */
+/** The reserved short-link namespace a published form is served under. */
 export declare const FORM_NAMESPACE = "f";
 /**
  * Public prefix a published form resolves under, and the prefix
@@ -35,9 +31,8 @@ export type FormSchemaFieldType = "short_text" | "long_text" | "email" | "number
  * READ back off a form.
  *
  * `id` is not optional here even though it is optional when writing: the
- * sanitiser mints `SecureRandom.uuid` for any option that arrives without one,
- * so a stored option always has one. Write with
- * {@link FormSchemaFieldOptionInput}.
+ * server mints a UUID for any option that arrives without one, so a stored
+ * option always has one. Write with {@link FormSchemaFieldOptionInput}.
  */
 export interface FormSchemaFieldOption {
     /** Stable within the form. */
@@ -54,13 +49,13 @@ export interface FormSchemaFieldOptionInput {
  *
  * `id` is the key answers are filed under - NOT the label.
  *
- * Four of these keys are non-optional because `Forms::InputSanitizer#field`
- * writes them on EVERY field it keeps, whatever arrived: `id` (minted when
- * absent), `type`, `label` and `description` (both coerced with `.to_s`, so an
- * absent one is stored as `""`, not dropped) and `required` (cast to a real
- * boolean). The three that stay optional are genuinely absent from the stored
- * object when unused: `placeholder` is only kept when present, `options` only
- * for the three choice types, and `min`/`max` only for `number`.
+ * Five of these keys are non-optional because the server writes them on EVERY
+ * field it keeps, whatever arrived: `id` (minted when absent), `type`, `label`
+ * and `description` (an absent one is stored as `""`, not dropped) and
+ * `required` (always a real boolean). The rest are genuinely absent from the
+ * stored object when unused: `placeholder` is only kept when present,
+ * `options` only for the three choice types, and `min`/`max` only for
+ * `number`.
  *
  * Write with {@link FormSchemaFieldInput}, where all of that is optional.
  */
@@ -84,8 +79,8 @@ export interface FormSchemaField {
  * One field as WRITTEN.
  *
  * Every key but `type` may be omitted. `type` may not: a field whose type is
- * not one of `Form::FIELD_TYPES` is dropped from the schema in silence, which
- * looks exactly like a field that was never sent.
+ * not one of {@link FormSchemaFieldType} is dropped from the schema in
+ * silence, which looks exactly like a field that was never sent.
  *
  * A {@link FormSchemaField} read off a form is assignable here, so the
  * read-edit-write round trip needs no mapping.
@@ -105,8 +100,8 @@ export interface FormSchemaFieldInput {
 }
 /**
  * The field definition of a form, as read. Always `{ fields: [...] }`, never
- * `null` and never a bare array: the column is `NOT NULL DEFAULT
- * '{"fields":[]}'` and the sanitiser rebuilds the envelope on every write.
+ * `null` and never a bare array: a new form starts with an empty envelope and
+ * the server rebuilds it on every write.
  */
 export interface FormSchema {
     readonly fields: FormSchemaField[];
@@ -114,8 +109,8 @@ export interface FormSchema {
 /**
  * The field definition as written. The server rebuilds it from scratch keeping
  * only the keys {@link FormSchemaFieldInput} names, so anything extra is lost
- * without a word - and a write that is not a Hash at all is silently read as
- * `{ fields: [] }`, which empties the form rather than failing.
+ * without a word - and a write that is not an object at all is silently read
+ * as `{ fields: [] }`, which empties the form rather than failing.
  */
 export interface FormSchemaInput {
     readonly fields: FormSchemaFieldInput[];
@@ -153,10 +148,9 @@ export interface FormSettings {
 /**
  * A hosted form, owner view.
  *
- * One shape, not two: `FormsController` renders `form.render` with no view on
- * index, show, create AND update, so the `:extended` view `ApplicationBlueprint`
- * declares is never reached here and there is no richer variant to ask for.
- * Every key below is therefore on every response.
+ * One shape, not two: index, show, create AND update all answer the same
+ * record, and there is no richer variant to ask for. Every key below is on
+ * every response.
  */
 export interface Form extends BaseRecord {
     readonly user_id: Id;
@@ -180,19 +174,14 @@ export interface Form extends BaseRecord {
     readonly published_at: Timestamp | null;
     /** Bumped by every `getPublic` call, the SDK's included. Never `null`. */
     readonly views_count: number;
-    /**
-     * Answers recorded. Computed per request - batched into one grouped COUNT
-     * for a whole listing, one COUNT for a single render - so it is always
-     * current and never cached.
-     */
+    /** Answers recorded. Computed per request, so it is always current. */
     readonly submissions_count: number;
 }
 /**
  * The reduced form a public respondent is allowed to see.
  *
- * NOT a subset of {@link Form}: the controller builds this hash by hand rather
- * than rendering a blueprint view, so it carries `require_login` - which is not
- * a field on `Form` at all, only a key inside `settings` - and carries no
+ * NOT a subset of {@link Form}: it carries `require_login` - which is not a
+ * field on `Form` at all, only a key inside `settings` - and carries no
  * timestamps, no `user_id`, no counts and no `status`. Seven keys, always all
  * seven.
  */
@@ -208,14 +197,10 @@ export interface PublicForm {
 /**
  * One answered form.
  *
- * Deliberately has no `updated_at`: a submission is never edited, and
- * `FormSubmissionBlueprint` is the one blueprint in the API that inherits
- * `Blueprinter::Base` directly rather than `ApplicationBlueprint`, precisely so
- * that the automatic `updated_at` cannot creep in. Do not add it here on the
- * assumption that every record has one.
+ * Deliberately has no `updated_at`: a submission is never edited. Do not add
+ * it here on the assumption that every record has one.
  *
- * The other seven keys are all declared unconditionally, so all seven are
- * always present; four of them are nullable columns.
+ * All seven keys are always present; four of them are nullable.
  */
 export interface FormSubmission {
     readonly id: Id;
@@ -240,23 +225,18 @@ export interface FormSubmission {
     /** Parsed from the respondent's user agent. `null` when unparseable. */
     readonly device_name: string | null;
     /**
-     * When the answers were recorded. The controller writes `Time.current` on
-     * every submission it creates, so this is `null` only for a row predating
-     * that - but the column is nullable, so check before formatting it.
+     * When the answers were recorded. Set on every submission the API creates,
+     * so this is `null` only for an old row - but it is nullable, so check
+     * before formatting it.
      */
     readonly completed_at: Timestamp | null;
     readonly created_at: Timestamp;
 }
-/**
- * What `POST /form_attachments` answers with.
- *
- * Built by hand in the controller rather than by a blueprint, so this is the
- * literal four-key hash it renders and there is no `created_at` to read.
- */
+/** What `POST /form_attachments` answers with. Four keys, no `created_at`. */
 export interface FormAttachment {
     readonly id: Id;
     readonly filename: string;
-    /** One of `FormAttachment::ALLOWED_TYPES`; a save with anything else is a 400. */
+    /** JPEG, PNG, WebP, GIF or HEIC; a save with anything else is a 400. */
     readonly content_type: string;
     /** Absolute URL that serves the bytes inline, no credential required. */
     readonly url: string;
@@ -266,8 +246,8 @@ export interface FormAttachment {
  * conditional and mutually exclusive.
  *
  * `reason` appears only on the rejected branch and only ever holds
- * `"invalid"` - the controller has a single rejection reason for forms,
- * covering both a bad shape and a reserved word. (Link trees, which look
+ * `"invalid"` - the server has a single rejection reason for forms, covering
+ * both a bad shape and a reserved word. (Link trees, which look
  * identical, do distinguish the two; see `LinkTreeSlugAvailability`.)
  * `suggestions` appears only on the well-formed-but-taken branch.
  */
@@ -289,10 +269,9 @@ export interface FormEndpointAvailability {
  */
 export interface CreateFormInput {
     /**
-     * Optional, despite being the thing a person names the form by: the
-     * controller runs it through `.to_s.strip` and the model only validates its
-     * LENGTH (200 maximum), so an omitted title saves an untitled form rather
-     * than failing. Pass one.
+     * Optional, despite being the thing a person names the form by: the server
+     * trims it and only validates its LENGTH (200 maximum), so an omitted title
+     * saves an untitled form rather than failing. Pass one.
      */
     readonly title?: string;
     /**

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

@@ -11,11 +11,10 @@
  * {@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.
+ * Only two tools hand back a generic job - background removal and upscale.
+ * The other five are polled by re-reading their own record, 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:
  *
@@ -47,7 +46,7 @@ import { Resource } from "../http";
 import type { ListParams } from "../listing";
 import type { BaseRecord, Id, Json, JobStatus, Paginated, Progress, RequestOptions, Timestamp, WaitOptions } from "../types";
 /**
- * The five status strings, spelled the way the backend spells them.
+ * The five status strings, spelled the way the API 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.
@@ -71,31 +70,24 @@ export declare function isJobTerminal(status: string): boolean;
 /**
  * A background job.
  *
- * `JobBlueprint` declares thirteen fields and nothing else, so EVERY key below
- * is present on every response. A `?` here would mean "the server sometimes
- * leaves this out", and it never does; what varies is the VALUE, because most
- * of these are nullable columns that fill in as the job moves.
+ * EVERY key below is present on every response. A `?` here would mean "the
+ * server sometimes leaves this out", and it never does; what varies is the
+ * VALUE, because most of these are nullable and fill in as the job moves.
  *
- * Two keys are deliberately NOT here, and a client migrating off the old web
- * service will expect them: `updater_id` and `destroyer_id`. Both columns
- * exist on the `jobs` table and both are indexed, but `JobBlueprint` renders
- * NEITHER, so anything declaring them has been reading `undefined` for as long
- * as it has existed. Declaring them here would only move the lie.
+ * There is no `updater_id` and no `destroyer_id`; anything declaring them
+ * reads `undefined`.
  */
 export interface Job extends BaseRecord {
     readonly status: JobStatus;
     /**
-     * Feature-level kind of the run. `Job::JOB_TYPES` holds exactly two strings:
-     * `"omsvs"` (vocal separation) and `"unknown"`, which is the column default
-     * every generic enqueue gets - the upscale and background-removal proxies
-     * included. It is NOT the worker's class name, and a third value cannot
-     * appear without a model change, because an inclusion validation rejects it.
+     * Feature-level kind of the run: `"omsvs"` (vocal separation) or
+     * `"unknown"`, which is what every generic enqueue gets - the upscale and
+     * background-removal runs included. It is NOT the name of the work done.
      */
     readonly job_type: string;
     /**
-     * Enqueue-time arguments. The column is `jsonb DEFAULT '{}'`, so a row whose
-     * enqueuer wrote nothing carries `{}` rather than `null`. Shape depends on
-     * `job_type`.
+     * Enqueue-time arguments. `{}` rather than `null` when the enqueuer wrote
+     * nothing. Shape depends on `job_type`.
      */
     readonly payload: Json;
     /** Set when a worker claimed the job; `null` while it is still `"pending"`. */
@@ -103,22 +95,20 @@ export interface Job extends BaseRecord {
     /** Set when the job reached a terminal state, cancellation included. */
     readonly finished_at: Timestamp | null;
     /**
-     * Percentage, an integer in `[0, 100]`. The column is `NOT NULL DEFAULT 0`
-     * and the model validates the range, so this is a real number from the
-     * moment the row exists: `0` means "not started", never "unknown".
+     * Percentage, an integer in `[0, 100]`. A real number from the moment the
+     * row exists: `0` means "not started", never "unknown".
      */
     readonly progress: number;
     /**
      * Failure message once `status === "failed"` - and ALSO the reason once
-     * `"canceled"`, because `Job#cancel!` writes it into this same column. A
+     * `"canceled"`, because a cancellation writes its reason here too. A
      * non-null `error` therefore does not by itself mean the work failed. Read
      * `status`.
      */
     readonly error: string | null;
     /**
-     * Whatever the worker returned, stored by `ApplicationJob`'s
-     * `around_perform`. Shape depends on `job_type`, and the two proxies worth
-     * naming both answer an object carrying a signed download link:
+     * Whatever the work returned. Shape depends on `job_type`, and the two
+     * tools worth naming both answer an object carrying a signed download link:
      *
      * - upscale: `{ upscale_id, result_url }`;
      * - background removal: `{ background_removal_id, result_url }`.
@@ -213,9 +203,8 @@ export declare class JobsNamespace extends Resource {
      * 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`).
+     * @throws {OmsApiError} 400 naming the key when a filter is not one of
+     *   `id`, `job_type`, `status`, `created_at`, `updated_at`, `finished_at`.
      */
     list(params?: ListJobsParams, options?: RequestOptions): Promise<Paginated<Job>>;
     /**
@@ -227,7 +216,7 @@ export declare class JobsNamespace extends Resource {
      *
      * @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
+     *   missing watch token is the same 404, not a 401: the server never says
      *   whether the id exists.
      */
     get(ref: JobRef | Id, options?: RequestOptions): Promise<Job>;
@@ -265,13 +254,12 @@ 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.
+ * server always has: there is no "unknown" to be honest about.
  *
  * The `typeof` guard is not defensive typing for its own sake. `Job.progress`
- * is declared non-nullable because the column is, but this function is also
- * handed rows that came off `JobChannel` and rows a host deserialised itself,
- * and reading `undefined` as `NaN%` would put a broken number on a progress
- * bar rather than a zero.
+ * is declared non-nullable, but this function is also handed rows that came
+ * off the realtime job channel and rows a host deserialised itself, and
+ * reading `undefined` as `NaN%` would put a broken number on a progress bar
+ * rather than a zero.
  */
 export declare function jobProgress(job: Job): Progress;