@omelhorsite/sdk 0.2.0 → 0.3.0

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

@@ -17,6 +17,14 @@
 import { Resource } from "../http";
 import type { BaseRecord, Id, JsonObject, RequestOptions } from "../types";
 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.
+ */
+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. */
@@ -72,7 +80,24 @@ export interface DynamicQrSettings {
      */
     readonly [key: string]: unknown;
 }
-/** A dynamic QR code. */
+/**
+ * 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.
+ */
 export interface DynamicQr extends Omit<BaseRecord, "id"> {
     /** Integer primary key: a dynamic QR is a `short_links` row. See {@link ShortLinkId}. */
     readonly id: number;
@@ -80,8 +105,19 @@ export interface DynamicQr extends Omit<BaseRecord, "id"> {
     readonly url: string;
     /** Server-assigned UUID the QR image encodes. Not choosable, not renameable. */
     readonly endpoint: string;
-    /** Always `"qr"`. */
-    readonly namespace: 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.
+     */
+    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.
+     */
     readonly user_id: Id | null;
     /** Never `null`: the blueprint substitutes `{}` for an unset bag. */
     readonly settings: DynamicQrSettings & JsonObject;

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

@@ -13,6 +13,16 @@
  */
 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`.
+ */
+export declare const FORM_NAMESPACE = "f";
+/**
+ * Public prefix a published form resolves under, and the prefix
+ * {@link Form.published_url} is built from server-side.
+ */
+export declare const FORM_BASE_URL = "https://omelhor.site/f";
 /**
  * Publication state. Only `"published"` answers on the public side; `"draft"`
  * and `"archived"` both 404 there.
@@ -20,41 +30,96 @@ import type { BaseRecord, FileInput, Id, Json, RequestOptions, Timestamp } from
 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. */
+/**
+ * One choice of a `single_choice`, `multi_choice` or `dropdown` field, AS
+ * 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}.
+ */
 export interface FormSchemaFieldOption {
-    /** Stable within the form. The server mints one when you leave it out. */
+    /** Stable within the form. */
+    readonly id: string;
+    readonly label: string;
+}
+/** One choice as WRITTEN. Omit `id` and the server mints a UUID. */
+export interface FormSchemaFieldOptionInput {
     readonly id?: string;
     readonly label: string;
 }
 /**
- * One field of a form.
+ * One field of a form, AS READ back.
+ *
+ * `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`.
  *
- * `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.
+ * Write with {@link FormSchemaFieldInput}, where all of that is optional.
  */
 export interface FormSchemaField {
-    readonly id?: string;
+    readonly id: string;
     readonly type: FormSchemaFieldType;
+    /** Never `null`; `""` for a field saved without one. */
     readonly label: string;
+    /** Never `null`; `""` for a field saved without one. */
+    readonly description: string;
+    readonly required: boolean;
+    readonly placeholder?: string;
+    /** Only on the three choice types. */
+    readonly options?: FormSchemaFieldOption[];
+    /** Only on `number`, and only when one was set. */
+    readonly min?: number;
+    /** Only on `number`, and only when one was set. */
+    readonly max?: number;
+}
+/**
+ * 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.
+ *
+ * A {@link FormSchemaField} read off a form is assignable here, so the
+ * read-edit-write round trip needs no mapping.
+ */
+export interface FormSchemaFieldInput {
+    /** Omit and the server mints a UUID - which you then have to read back
+     * before you can file an answer under it. */
+    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 options?: FormSchemaFieldOptionInput[];
     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.
+ * 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.
  */
 export interface FormSchema {
     readonly fields: FormSchemaField[];
 }
+/**
+ * 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.
+ */
+export interface FormSchemaInput {
+    readonly fields: FormSchemaFieldInput[];
+}
 /**
  * Styling of a form. Colours must be `#RRGGBB`; images must be `data:image/`
  * URIs under 2 MB. Anything else in here is dropped silently.
@@ -85,9 +150,17 @@ export interface FormSettings {
     readonly thank_you_title?: string;
     readonly thank_you_subtitle?: string;
 }
-/** A hosted form, owner view. */
+/**
+ * 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.
+ */
 export interface Form extends BaseRecord {
     readonly user_id: Id;
+    /** Never `null`; `""` for a form saved without one. Capped at 200 characters. */
     readonly title: string;
     readonly status: FormStatus;
     readonly schema: FormSchema;
@@ -97,12 +170,32 @@ export interface Form extends BaseRecord {
     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;
+    /**
+     * Set the first time the form is published, and never cleared - archiving or
+     * returning a form to draft leaves it standing, so this is "was ever
+     * published", not "is published". Read `status` for that.
+     *
+     * The key is always present; the value is `null` until the first publish.
+     */
+    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.
+     */
     readonly submissions_count: number;
 }
-/** The reduced form a public respondent is allowed to see. */
+/**
+ * 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
+ * timestamps, no `user_id`, no counts and no `status`. Seven keys, always all
+ * seven.
+ */
 export interface PublicForm {
     readonly id: Id;
     readonly title: string;
@@ -115,46 +208,77 @@ export interface PublicForm {
 /**
  * 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.
+ * 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.
+ *
+ * The other seven keys are all declared unconditionally, so all seven are
+ * always present; four of them are nullable columns.
  */
 export interface FormSubmission {
     readonly id: Id;
     readonly form_id: Id;
-    /** The respondent, when they were signed in. */
-    readonly user_id?: Id | null;
+    /** The respondent, or `null` when they answered anonymously. */
+    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.
+     *
+     * Only keys that match a field in the schema survive - anything else is
+     * dropped in silence - so a submission can hold FEWER keys than were sent,
+     * and an optional field nobody filled in is simply absent.
      */
     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;
+    /**
+     * ISO 3166-1 alpha-2, lowercase, resolved from the respondent's IP.
+     * `null` when the lookup found nothing.
+     */
+    readonly country: string | null;
+    /** 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.
+     */
+    readonly completed_at: Timestamp | null;
     readonly created_at: Timestamp;
 }
-/** What `POST /form_attachments` answers with. */
+/**
+ * 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.
+ */
 export interface FormAttachment {
     readonly id: Id;
     readonly filename: string;
+    /** One of `FormAttachment::ALLOWED_TYPES`; 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;
 }
 /**
- * `GET /forms/endpoint_availability`. Read `available`; `suggestions` is only
- * present when the endpoint is well formed but taken.
+ * `GET /forms/endpoint_availability`. Read `available`; the other two keys are
+ * 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
+ * identical, do distinguish the two; see `LinkTreeSlugAvailability`.)
+ * `suggestions` appears only on the well-formed-but-taken branch.
  */
 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;
+    /** Only when `valid` is `false`. */
+    readonly reason?: "invalid";
+    /** Only when `valid` is `true` and `available` is `false`. */
     readonly suggestions?: string[];
 }
 /**
@@ -164,14 +288,20 @@ export interface FormEndpointAvailability {
  * through {@link UpdateFormInput}. `require_login` lives in `settings`.
  */
 export interface CreateFormInput {
-    readonly title: string;
+    /**
+     * 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.
+     */
+    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 schema?: FormSchemaInput;
     readonly theme?: FormTheme;
     readonly settings?: FormSettings;
 }
@@ -184,7 +314,7 @@ 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 schema?: FormSchemaInput;
     readonly theme?: FormTheme;
     readonly settings?: FormSettings;
     /**
@@ -328,4 +458,15 @@ export declare class FormsNamespace extends Resource {
      * anyone holding the id.
      */
     attachment(attachmentId: Id, options?: RequestOptions): Promise<Blob>;
+    /**
+     * The public URL an endpoint is served from. Pure string building, no
+     * request, and the same string the server puts in {@link Form.published_url}.
+     *
+     * Prefer `form.published_url` when you are holding a record - it is the
+     * server's own answer and it is `null` exactly when the pairing is broken,
+     * which this cannot know. Reach for this when all you have is an endpoint:
+     * after {@link endpointAvailability}, or in a client that stores endpoints
+     * rather than forms.
+     */
+    publicUrl(endpoint: string): string;
 }

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

@@ -1,30 +1,41 @@
 /**
  * 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.
+ * `client.ts` imports the namespace classes from the modules themselves rather
+ * than from here, so adding a resource does not serialise on this file;
+ * consumers import the record and input types from here, flattened through
+ * `src/index.ts`.
  *
- * 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.
+ * Re-exports every sibling module so nobody has to touch this file twice: a new
+ * resource means one new file, one line here, and one line in {@link Oms}.
  *
  * 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.
+ * wanted one, and an `export *` collision does NOT fail the build - TypeScript
+ * drops the ambiguous name from the barrel in silence, so the symbol simply
+ * stops existing for consumers. `test/exports.test.ts` walks the re-export
+ * graph and fails on a duplicate, because the compiler will not.
  */
 export * from "./account";
+export * from "./admin";
+export * from "./auth/index";
 export * from "./chests";
+export * from "./content";
 export * from "./dynamicQrs";
 export * from "./forms";
 export * from "./ipLookup";
 export * from "./jobs";
+export * from "./library";
 export * from "./linkTrees";
+export * from "./media";
+export * from "./movies";
+export * from "./music/index";
 export * from "./notepads";
 export * from "./quotas";
+export * from "./realtime";
 export * from "./shortLinks";
+export * from "./social";
 export * from "./storage";
 export * from "./storage/upload";
 export * from "./tickets";

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

@@ -17,9 +17,16 @@ 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
+ * Exactly five keys, always all five. `IpLookuper` answers `{ ip:, **record }`
+ * and nothing else: `country`, `asn` and `organization` are the three the MMDB
+ * builder writes per range, and `network` is stamped on by the reader from the
+ * prefix that matched. Nothing is computed and nothing is filled in for a
  * missing row - a miss is a 400, not a half-empty object.
+ *
+ * The name promises a GeoIP payload and this is not one, so there is no
+ * `city`, no `latitude`/`longitude`, no `timezone` and no `postal`. Those keys
+ * exist in the MaxMind gem's own result API and are all `nil` here, because
+ * the database behind it is the iptoasn.com IP-to-ASN table.
  */
 export interface IpLookupResult {
     /** The address that was looked up, echoed back. For `"mine"`, the resolved one. */
@@ -30,9 +37,18 @@ export interface IpLookupResult {
      * 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. */
+    /**
+     * Autonomous system number, or `0` when the range is not announced. `0` is
+     * the builder's substitute for a non-numeric column, not a real AS, so treat
+     * it as "unknown" rather than looking it up.
+     */
     readonly asn: number;
-    /** Network operator name as the AS registry spells it, e.g. `"GOOGLE"`. */
+    /**
+     * Network operator name as the AS registry spells it, e.g. `"GOOGLE"`.
+     * Whitespace-squished, and the EMPTY STRING when the source table had no
+     * name for the range - never `null`, so test it for length rather than for
+     * presence.
+     */
     readonly organization: string;
     /** The CIDR block the address fell in, e.g. `"8.8.8.0/24"`. */
     readonly network: string;

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

@@ -67,35 +67,70 @@ export declare const JOB_STATUS: Readonly<{
 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. */
+/**
+ * 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.
+ *
+ * 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.
+ */
 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.
+     * 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.
      */
     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".
+     * Enqueue-time arguments. The column is `jsonb DEFAULT '{}'`, so a row whose
+     * enqueuer wrote nothing carries `{}` rather than `null`. Shape depends on
+     * `job_type`.
      */
-    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;
+    readonly payload: Json;
+    /** Set when a worker claimed the job; `null` while it is still `"pending"`. */
+    readonly started_at: Timestamp | null;
+    /** 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".
+     */
+    readonly progress: number;
+    /**
+     * Failure message once `status === "failed"` - and ALSO the reason once
+     * `"canceled"`, because `Job#cancel!` writes it into this same column. 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:
+     *
+     * - upscale: `{ upscale_id, result_url }`;
+     * - background removal: `{ background_removal_id, result_url }`.
+     *
+     * That `result_url` is the same string the tool's own row carries once the
+     * run completes, which is why `awaitToolJob` waits on the job and then
+     * re-reads the typed row instead of digging a URL out of here.
+     */
+    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;
+    readonly creator_id: Id | null;
+    /** Which worker claimed it. `null` until one does. */
+    readonly worker_id: string | null;
 }
 /**
  * How to address a job.
@@ -229,5 +264,11 @@ export declare function jobRef(ref: JobRef | Id): JobRef;
  * `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.
+ *
+ * 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.
  */
 export declare function jobProgress(job: Job): Progress;