@omelhorsite/sdk 0.2.0 → 0.4.0

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

@@ -46,24 +46,57 @@ import { type EditsQuota, type ToolCaptcha, type ToolRecord, type ToolRunOptions
 export type JumpstyleDensity = "chill" | "normal" | "hyper";
 /** The three the backend accepts. Anything else is silently read as `"normal"`. */
 export declare const JUMPSTYLE_DENSITIES: readonly JumpstyleDensity[];
-/** A jumpstyle edit. */
+/**
+ * Lifecycle of a jumpstyle edit.
+ *
+ * Narrower than {@link ToolStatus}: `JumpstyleJob::STATUSES` has only three
+ * entries and `"pending"` is not one of them. The controller forwards the files
+ * to the sidecar inside the create request and saves the row already
+ * `"processing"`, so there is no state in which an edit exists but has not
+ * started.
+ */
+export type JumpstyleStatus = "processing" | "complete" | "failed";
+/**
+ * A jumpstyle edit.
+ *
+ * Both routes that answer with one - `POST /jumpstyle_jobs` and
+ * `GET /jumpstyle_jobs/:id` - render the `:extended` view, so every key below
+ * is present on every response.
+ *
+ * The first four columns are nullable in the schema but written by the
+ * controller on every create, so a row the API can produce always carries
+ * them. `density` and `rapid_fire` are `NOT NULL` with defaults on top of that.
+ */
 export interface JumpstyleJob extends ToolRecord {
-    readonly track_filename?: string | null;
-    readonly n_clips?: number | null;
-    /** Seconds of output. */
-    readonly duration?: number | null;
-    /** The seed that produced this cut. Reuse it to reproduce the edit. */
-    readonly seed?: number | null;
-    readonly density?: string | null;
-    readonly rapid_fire?: boolean | null;
-    /** BPM that was forced, when one was. */
-    readonly bpm?: number | null;
-    /** BPM the sidecar detected, or the forced one once the run settles. */
-    readonly detected_bpm?: number | null;
-    /** What the sidecar is doing right now. `null` unless processing. */
-    readonly stage?: string | null;
-    /** The finished video, once the status is `"complete"`. */
-    readonly output_url?: string | null;
+    readonly status: JumpstyleStatus;
+    /** Uploaded track's name; `"track"` when the upload carried none. */
+    readonly track_filename: string;
+    /** How many clips were sent. At most 20. */
+    readonly n_clips: number;
+    /** Seconds of output, clamped by the server to `[10, 60]`. */
+    readonly duration: number;
+    /**
+     * The seed that produced this cut. Reuse it to reproduce the edit - it is
+     * the ONLY way to, and the server rolls a fresh one whenever it is not
+     * given one.
+     */
+    readonly seed: number;
+    /** `NOT NULL DEFAULT 'normal'`. An unrecognised request value lands here as `"normal"`. */
+    readonly density: JumpstyleDensity | string;
+    /** `NOT NULL DEFAULT false`. */
+    readonly rapid_fire: boolean;
+    /** BPM that was forced at create time, or `null` when detection was left to run. */
+    readonly bpm: number | null;
+    /**
+     * While processing: the BPM the sidecar has detected, or `null` if it has not
+     * yet. Once the row settles: whatever `bpm` holds, forced or not. So this
+     * changes meaning at the moment the run ends.
+     */
+    readonly detected_bpm: number | null;
+    /** What the sidecar is doing right now, read live. `null` unless processing. */
+    readonly stage: string | null;
+    /** Signed URL of the finished video once complete and attached, `null` otherwise. */
+    readonly output_url: string | null;
 }
 /** Arguments for starting an edit. */
 export interface CreateJumpstyleInput extends ToolCaptcha {

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

@@ -36,22 +36,44 @@
 import { Resource } from "../../http";
 import type { FileInput, Id, RequestOptions } from "../../types";
 import { type SecondsQuota, type ToolCaptcha, type ToolModel, type ToolRecord, type ToolRunOptions } from "./index";
-/** A transcription run. */
+/**
+ * A transcription run.
+ *
+ * Both routes that answer with one - `POST /transcriptions` and
+ * `GET /transcriptions/:id` - render the `:extended` view, so every key below
+ * is present on every response, the five `:extended` ones included. What
+ * changes as the run progresses is the VALUE, not the key set: polling a
+ * pending run and polling a finished one return the same shape.
+ */
 export interface Transcription extends ToolRecord {
+    /** Never `null`: the column is `NOT NULL` and the controller rejects an
+     * unknown model with a 400 before the row is built. */
     readonly model_id: string;
-    /** Audio duration charged against the quota. */
+    /**
+     * Audio duration charged against the quota, rounded UP at create time. Never
+     * `null` (`NOT NULL DEFAULT 0`), and it is what was spent even if the run
+     * later fails.
+     */
     readonly duration_seconds: number;
-    /** Language that was requested, or `null` when it was auto-detected. */
-    readonly language?: string | null;
-    /** Language the model actually detected. */
-    readonly detected_language?: string | null;
-    readonly has_original?: boolean;
-    /** The transcript. Only shipped once the status is `"complete"`. */
-    readonly text?: string | null;
-    /** SubRip subtitles, once complete. */
-    readonly srt_url?: string | null;
-    /** WebVTT subtitles, once complete. */
-    readonly vtt_url?: string | null;
+    /** Language that was requested, or `null` when it was left to detection. */
+    readonly language: string | null;
+    /** Language the model actually detected, or `null` before it has. */
+    readonly detected_language: string | null;
+    /**
+     * Whether the uploaded audio is still attached. A real boolean, never
+     * `null`: the field is computed as `original_audio.attached?`.
+     */
+    readonly has_original: boolean;
+    /**
+     * The transcript, or `null`. Shipped ONLY once the status is `"complete"` -
+     * deliberately, so that polling a long run does not drag the whole text
+     * across the wire every few seconds.
+     */
+    readonly text: string | null;
+    /** Signed SubRip URL once complete and attached, `null` otherwise. */
+    readonly srt_url: string | null;
+    /** Signed WebVTT URL once complete and attached, `null` otherwise. */
+    readonly vtt_url: string | null;
 }
 /** Arguments for starting a transcription. */
 export interface CreateTranscriptionInput extends ToolCaptcha {

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

@@ -19,11 +19,31 @@ import { type ToolCaptcha, type ToolJobHandle, type ToolRecord, type ToolRunOpti
  * allow-list of strings; `4` and `"4"` are not the same request.
  */
 export type UpscaleScale = "2" | "3" | "4";
-/** An upscale run. */
+/**
+ * An upscale run.
+ *
+ * Both routes that answer with one - `POST /upscales` and `GET /upscales/:id` -
+ * render the `:extended` view, so `result_url` is always PRESENT and simply
+ * `null` until the run completes. There is no default-view variant of this
+ * record reachable through the API.
+ *
+ * `progress_percent`, inherited from {@link ToolRecord}, is never sent for this
+ * tool: `UpscaleBlueprint` has no such field. Progress for an upscale lives on
+ * the {@link Job} row that {@link UpscaleCreated.job_id} names.
+ */
 export interface Upscale extends ToolRecord {
+    /**
+     * One of `"2"`, `"3"`, `"4"` - a string, because the column is a string and
+     * the allow-list is `%w[2 3 4]`. Never `null`: `NOT NULL DEFAULT '4'`.
+     */
     readonly scale: string;
-    /** URL of the enlarged image, once the status is `"complete"`. */
-    readonly result_url?: string | null;
+    /**
+     * Signed URL of the enlarged PNG, or `null`. `null` covers three different
+     * situations - the run has not finished, it failed, or the 24-hour sweep
+     * took the attachment - which is why {@link UpscaleNamespace.resultUrl}
+     * exists rather than a bare read of this field.
+     */
+    readonly result_url: string | null;
 }
 /** What `POST /upscales` answers with. */
 export type UpscaleCreated = Upscale & ToolJobHandle;

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

@@ -35,28 +35,45 @@ import type { FileInput, Id, Progress, RequestOptions } from "../../types";
 import { type SecondsQuota, type ToolCaptcha, type ToolModel, type ToolRecord, type ToolRunOptions } from "./index";
 /** Which stem to fetch. */
 export type VocalStem = "vocals" | "instrumental";
-/** A vocal separation run. */
+/**
+ * A vocal separation run.
+ *
+ * Both routes that answer with one - `POST /vocal_separations` and
+ * `GET /vocal_separations/:id` - render the `:extended` view, so every key
+ * below is present on every response. Only the values move.
+ */
 export interface VocalSeparation extends ToolRecord {
+    /** Never `null`: `NOT NULL`, and an unknown model is a 400 before the row exists. */
     readonly model_id: string;
-    /** Audio duration charged against the quota. */
+    /** Audio duration charged against the quota, rounded up at create time. */
     readonly duration_seconds: number;
-    /** Set when the run came from the music library rather than an upload. */
-    readonly song_id?: Id | null;
-    readonly song_title?: string | null;
-    readonly has_original?: boolean;
-    readonly has_vocals?: boolean;
-    readonly has_instrumental?: boolean;
+    /**
+     * Set when the run came from the music library rather than an upload.
+     *
+     * A **number**, not a string. `vocal_separations.song_id` is a `bigint`
+     * pointing at `songs`, which is one of the few tables in this API that kept
+     * an integer primary key - so this is the one id in the tools family that is
+     * not an {@link Id}. Comparing it against a string never matches.
+     */
+    readonly song_id: number | null;
+    /** Title of that song, or `null` for an uploaded run. */
+    readonly song_title: string | null;
+    /** Real booleans, never `null`: each is an `attached?` call on the record. */
+    readonly has_original: boolean;
+    readonly has_vocals: boolean;
+    readonly has_instrumental: boolean;
     /**
      * Live runs queued ahead of this one; `0` means next up. `null` once the run
      * is processing or terminal.
      */
-    readonly queue_position?: number | null;
+    readonly queue_position: number | null;
     /**
-     * Stem URLs, once complete. Both stay `null` for a song-owned separation,
-     * whose stems live on the song as filesystem nodes instead.
+     * Signed stem URLs once complete, `null` otherwise - and permanently `null`
+     * for a song-owned separation, whose stems are written onto the song as
+     * filesystem nodes and never attached to this row.
      */
-    readonly vocals_url?: string | null;
-    readonly instrumental_url?: string | null;
+    readonly vocals_url: string | null;
+    readonly instrumental_url: string | null;
 }
 /** Arguments for starting a separation. */
 export interface CreateVocalSeparationInput extends ToolCaptcha {

package/dist/types/types.d.ts

@@ -2,8 +2,17 @@
  * Primitives shared by every namespace of the SDK.
  *
  * Nothing here touches the platform: no `node:*`, no `process`, no `console`.
- * Files are values (Blob / Uint8Array / ReadableStream), never paths - the core
- * has no filesystem. Turning a path into a {@link FileInput} is the CLI's job.
+ * Files are normally values (Blob / Uint8Array / ReadableStream), never paths -
+ * the core has no filesystem, and turning a path into a {@link FileInput} is the
+ * CLI's job.
+ *
+ * React Native is the one exception, and it is the platform's exception rather
+ * than a relaxation of ours: a file the user picked there is a
+ * {@link NativeFile} descriptor `{ uri, name, type }` whose bytes live behind a
+ * `file://` / `content://` / `ph://` URI that only the RN runtime can resolve.
+ * It is still not a path the SDK reads - the SDK never reads it. It is handed
+ * back to RN's own `FormData`, which resolves it natively while building the
+ * multipart body. See {@link FileInput} and {@link NativeFile}.
  */
 /** Any JSON value the API can send or receive. */
 export type Json = string | number | boolean | null | Json[] | {
@@ -19,21 +28,86 @@ export type JsonObject = {
  * behind an authenticating proxy.
  */
 export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * A file picked on React Native, exactly as the platform hands it over.
+ *
+ * This is the shape `expo-file-system`'s picker returns and the shape the app
+ * already builds by hand (`oms-music/src/features/settings/pickers.ts`,
+ * `features/playlist/artworkPicker.ts`), and it is a DESCRIPTOR, not bytes: the
+ * URI is a `file://`, `content://` or `ph://` handle into the device, and
+ * nothing in JavaScript can turn it into a `Blob` without a native module.
+ *
+ * The SDK therefore never reads it. It appends the object VERBATIM to a
+ * `FormData`, because RN's `FormData` is not the web one: `getParts()` sees an
+ * entry whose value is an object with a `uri` and emits a file part from it,
+ * and the native networking layer streams the file off disk while building the
+ * multipart body. Handing RN a `Blob` instead is the thing that does not work -
+ * on Android it silently uploads an empty or truncated part.
+ *
+ * The three fields are exactly the three RN reads. `size` is carried because
+ * pickers report it and the SDK's own ceilings want it, and it is harmless:
+ * RN spreads the object into the part and ignores what it does not know.
+ *
+ * ## Where it works, and where it does not
+ *
+ * - `postForm` / any multipart endpoint: yes, on RN. On a web or Bun runtime
+ *   the same object is REJECTED with a `TypeError` rather than stringified into
+ *   `"[object Object]"`, which is what a plain `FormData.append` would do to it.
+ *   See `supportsNativeFormDataFiles` in `http.ts`.
+ * - Storage direct upload (`resources/storage/upload.ts`): NO. That path
+ *   `PUT`s the bytes to a presigned URL and MD5s them first, and neither is
+ *   possible without reading the file. On RN, read it into bytes first (Expo's
+ *   `File#bytes()`), or use a native uploader. {@link readFileInput} throws a
+ *   message saying so rather than failing at the object store.
+ */
+export interface NativeFile {
+    /** Platform handle to the bytes: `file://`, `content://`, `ph://`. */
+    readonly uri: string;
+    /** Filename the server should store. RN sends it as the part's `filename`. */
+    readonly name: string;
+    /**
+     * MIME type. Pickers report `""` for some `content://` URIs, which is why the
+     * app falls back to a per-kind constant before it gets here; do the same, as
+     * Rails infers the container format from the part's content type for several
+     * of the tools.
+     */
+    readonly type?: string;
+    /** Byte length when the picker reported one. Ignored by RN, used by the SDK. */
+    readonly size?: number;
+}
+/**
+ * True when `value` is a {@link NativeFile} descriptor.
+ *
+ * The test is `uri` and `name` both being strings, which no other form value
+ * satisfies: a {@link FileInput} carries `data` + `filename`, and everything
+ * else in a form bag is a primitive. Deliberately tolerant of a missing `type`,
+ * because a `content://` pick on Android genuinely arrives without one and
+ * refusing it would lose the upload over a field RN treats as optional.
+ */
+export declare function isNativeFile(value: unknown): value is NativeFile;
 /**
  * Bytes handed to the SDK for upload.
  *
- * `data` is a value, never a path. `filename` is required because the API
- * derives the stored name and, for some tools, the container format from it.
+ * `data` is a value, never a path - with the one platform exception,
+ * {@link NativeFile}, which is a descriptor RN resolves for us and which only
+ * works on a multipart endpoint. `filename` is required because the API derives
+ * the stored name and, for some tools, the container format from it.
  *
  * `ReadableStream` is accepted for symmetry with the platform, but note that
  * multipart form bodies have to be materialised: {@link readFileInput} buffers
  * a stream into a Blob before it can be appended to a `FormData`. For anything
  * large, prefer the storage direct-upload path, which streams straight to the
  * object store and never passes through Rails.
+ *
+ * On React Native there is no need to wrap a picked file in one of these at
+ * all: pass the picked `{ uri, name, type }` object straight into the form bag
+ * and the transport appends it verbatim. Wrapping it is for the case where the
+ * name the server should store differs from the name on the device, in which
+ * case `filename` wins and is what RN sends as the part's filename.
  */
 export interface FileInput {
-    /** The bytes. */
-    readonly data: Blob | Uint8Array | ReadableStream<Uint8Array>;
+    /** The bytes, or a {@link NativeFile} descriptor on React Native. */
+    readonly data: Blob | Uint8Array | ReadableStream<Uint8Array> | NativeFile;
     /** Name the server should store, e.g. `"take-3.wav"`. Required. */
     readonly filename: string;
     /** MIME type. Defaults to the Blob's own type, then `application/octet-stream`. */
@@ -60,6 +134,14 @@ export interface FileOutput {
  *
  * Buffers a `ReadableStream` fully - see the note on {@link FileInput}. Uses
  * only platform APIs, so it runs in an isolate.
+ *
+ * @throws {TypeError} for a {@link NativeFile}. There is no honest Blob to
+ *   return: the bytes are behind a device URI that only the RN runtime can
+ *   open, and returning an empty Blob would upload an empty file with a 200 on
+ *   it. Multipart endpoints never reach here - `buildFormData` appends a native
+ *   descriptor verbatim instead - so the throw belongs to the byte-hungry
+ *   callers (the storage direct-upload driver, which must also MD5 the body),
+ *   and it names the way out rather than just refusing.
  */
 export declare function readFileInput(input: FileInput): Promise<{
     blob: Blob;
@@ -69,8 +151,13 @@ export declare function readFileInput(input: FileInput): Promise<{
 /**
  * Convenience constructor for a {@link FileInput}. Prefer it over an object
  * literal so the `filename`-is-required rule stays visible at the call site.
+ *
+ * A {@link NativeFile} is accepted and needs this only when the server should
+ * store a different name than the device used; otherwise pass the picked object
+ * straight into the form bag. When wrapped, `filename` and `contentType` are
+ * what go on the wire - the descriptor's own `name` and `type` are overridden.
  */
-export declare function file(data: Blob | Uint8Array | ReadableStream<Uint8Array>, filename: string, options?: {
+export declare function file(data: Blob | Uint8Array | ReadableStream<Uint8Array> | NativeFile, filename: string, options?: {
     contentType?: string;
     size?: number;
 }): FileInput;
@@ -79,6 +166,37 @@ export declare function file(data: Blob | Uint8Array | ReadableStream<Uint8Array
  *
  * `total` is `undefined` whenever the size is genuinely unknown (a stream
  * upload, a server-side render with no ETA). Do not fake it with a guess.
+ *
+ * ## What `phase: "upload"` can and cannot promise
+ *
+ * It ticks once per COMPLETED transfer, never per byte, and that is a property
+ * of `fetch` rather than a decision this SDK is free to revisit. No `fetch` -
+ * browser, React Native or Worker - exposes request-body progress. The web
+ * frontend gets a real byte counter in its 36 `onUploadProgress` call sites
+ * because axios is XHR underneath, and XHR is the only API that has ever
+ * reported bytes as they leave.
+ *
+ * There is therefore ONE mechanism in this SDK, not two: `resources/storage/upload.ts`
+ * ticks per finished transfer (one per 32 MiB part on the multipart tier, one
+ * per file on the direct tier), and a host that wants byte-level granularity
+ * hands an XHR-backed {@link FetchLike} to `UploadManagerOptions.fetch` and
+ * keeps the rest of the driver. That escape hatch is documented there with a
+ * working recipe, and it is available in exactly the runtimes that have XHR:
+ *
+ * - browser: yes, `xhr.upload.onprogress`;
+ * - React Native: yes. RN's own `fetch` is a thin layer over its `XMLHttpRequest`,
+ *   and `xhr.upload.onprogress` fires there for both `Blob` and
+ *   {@link NativeFile} parts - it is the same event `expo-file-system`'s
+ *   uploader surfaces;
+ * - Worker isolate: no. There is no XHR, so per-transfer ticks are the ceiling.
+ *
+ * `supportsUploadProgress()` in `http.ts` answers that question at runtime so a
+ * caller can hide a byte-accurate bar rather than let it sit at 0% and jump.
+ *
+ * The thing not to do is count bytes as they are handed to the runtime: a
+ * stream request body reports what was buffered, not what was acknowledged,
+ * which is the lie that parks a bar at 100% for a minute. It also breaks the
+ * presigned PUTs outright - see the module note in `storage/upload.ts`.
  */
 export interface Progress {
     /** What is happening right now. */
@@ -100,15 +218,39 @@ export interface RequestOptions {
      */
     readonly signal?: AbortSignal;
     /**
-     * Deadline in milliseconds for the whole call, retries included. Overrides
-     * the client default. `0` disables the deadline.
+     * Deadline in milliseconds for ONE ATTEMPT. Overrides the client default.
+     * `0` disables it.
+     *
+     * Not the deadline for the whole call: the transport starts a fresh one per
+     * attempt, so a call that retries can take up to `maxAttempts` times this
+     * plus the backoff between them (and a `429` waits out `Retry-After`, which
+     * this API sets from a one-minute window). To bound the wall clock, pass a
+     * {@link RequestOptions.signal} you abort yourself, or `retry: false`.
+     *
+     * The deadline covers getting a response, not draining it: it is disposed as
+     * soon as the headers arrive, which is what lets `raw()` and `streamText()`
+     * hold a stream open for longer than `timeoutMs`. A stream needs its own
+     * silence limit instead - `streamText` has one.
      */
     readonly timeoutMs?: number;
     /** Extra request headers. Merged over the client's, under `Authorization`. */
     readonly headers?: Record<string, string>;
     /**
-     * Per-call retry override. `false` disables retries entirely - pass it for
-     * any non-idempotent create you would rather see fail than duplicate.
+     * Per-call retry override, and the ONLY way to put a mutating request in
+     * scope for a retry.
+     *
+     * By default only safe methods are replayed after an ambiguous failure (a
+     * torn connection, a 5xx); a `POST` is not, because a replay after a lost
+     * answer is how one create becomes two records. Passing an object here -
+     * `{}` is enough, it inherits {@link DEFAULT_RETRY} - says you have looked at
+     * this specific endpoint and decided a duplicate is acceptable.
+     *
+     * `false` disables retrying completely, `429` included. Pass it for a call
+     * that mints something under a fresh random identifier per attempt (a short
+     * link, a notepad, a chest): a retry there does not duplicate the answer, it
+     * leaves an orphan behind and hands you the wrong one.
+     *
+     * See the retry policy documented on `ApiClient`.
      */
     readonly retry?: RetryOptions | false;
 }
@@ -138,15 +280,75 @@ export interface ResolvedRetry {
 /** Defaults applied when a caller says nothing about retrying. */
 export declare const DEFAULT_RETRY: ResolvedRetry;
 /**
- * Query parameters. Nested objects and arrays are encoded the way Rails reads
- * them (`search[status]=open`, `ids[]=1&ids[]=2`) - see `encodeQuery` in
- * `http.ts`. `undefined` and `null` values are dropped, not sent as empty.
+ * One value in a query string.
+ *
+ * Nested objects and arrays are encoded the way Rails reads them
+ * (`search[status]=open`, `ids[]=1&ids[]=2`). Three values do NOT encode
+ * literally, and `encodeQuery` in `http.ts` carries the full argument:
+ *
+ * - `undefined` is dropped. It means "I am not filtering on this column".
+ * - `null` is sent as the backend's `\b` null sentinel and comes back out of
+ *   `CrudActions` as SQL `NULL`. It means "filter where this column IS NULL".
+ *   The two are not interchangeable, and getting them the wrong way round is
+ *   the difference between one folder and somebody's entire tree.
+ * - a `Date` is sent as its ISO-8601 string, which is the only shape the Rails
+ *   date filters parse (`String#to_date_safe`).
  */
-export type QueryValue = string | number | boolean | null | undefined | QueryValue[] | {
+export type QueryValue = string | number | boolean | Date | null | undefined | QueryValue[] | {
     [key: string]: QueryValue;
 };
 /** A bag of query parameters. */
 export type QueryParams = Record<string, QueryValue>;
+/**
+ * Hard ceiling the backend applies to a page size, mirroring
+ * `QueryModifier::MAX_PAGE_SIZE`.
+ *
+ * The server clamps silently - `size = [size, MAX_PAGE_SIZE].min` - so asking
+ * for 1200 returns 500 rows and no indication that a ceiling was hit. The SDK
+ * therefore clamps to the same number BEFORE the request, so that the size it
+ * reports back in {@link Paginated.pageSize} is the size the rows were actually
+ * counted against. See {@link resolvePageSize}.
+ */
+export declare const MAX_PAGE_SIZE = 500;
+/**
+ * Page size the SDK asks for when the caller says nothing.
+ *
+ * Deliberately below {@link MAX_PAGE_SIZE}: a `list()` is usually the first
+ * screen of something, and 500 rows of expanded records is a slow first paint.
+ * Note this is NOT the server's own default - a request with no page modifier
+ * at all gets `QueryModifier::DEFAULT_PAGE_SIZE` (500) forced on it by
+ * `CrudActions#index_modifiers_params` - but the SDK always sends one.
+ */
+export declare const DEFAULT_PAGE_SIZE = 100;
+/**
+ * Normalises a requested page size into the one the server will actually use.
+ *
+ * Two different failures are handled differently on purpose:
+ *
+ * - **above the ceiling** is clamped, not rejected. The request still succeeds
+ *   and paging still reaches every row, so failing it would break a working
+ *   call for nothing. What must not happen is the caller being told it got the
+ *   size it asked for: that is how `pageSize: 1200` yielded 500 items and
+ *   `hasMore: false`, dropping 700 rows without a word.
+ * - **not a usable size at all** (`NaN`, `Infinity`, zero, negative) throws.
+ *   There is nothing sensible to clamp such a value to, and it is not merely
+ *   wrong on the client: `pageModifier` would put `"1:NaN"` on the wire,
+ *   `QueryModifier#apply_pagination` reads that as size `0`, bails out before
+ *   `limit`/`offset` are applied, and the endpoint answers with the WHOLE
+ *   table. A typo would turn a listing into an unbounded scan holding a Puma
+ *   thread and a DB connection.
+ *
+ * @throws {TypeError} when `pageSize` is not a finite number of at least 1.
+ */
+export declare function resolvePageSize(pageSize?: number): number;
+/**
+ * Normalises a requested page number. Pages are 1-based on the server
+ * (`offset = (number - 1) * size`), so page `0` is page 1 - and a
+ * {@link Paginated} that reported `page: 0` would fetch page 1 twice.
+ *
+ * @throws {TypeError} when `page` is not a finite number.
+ */
+export declare function resolvePageNumber(page?: number): number;
 /**
  * Paging arguments accepted by every `list()` method.
  *
@@ -157,7 +359,26 @@ export type QueryParams = Record<string, QueryValue>;
 export interface PageParams {
     /** 1-based page number. Defaults to 1. */
     readonly page?: number;
-    /** Items per page. Server maximum is 500. */
+    /**
+     * Items per page. Defaults to {@link DEFAULT_PAGE_SIZE}.
+     *
+     * {@link MAX_PAGE_SIZE} is the ceiling and it is enforced on both sides: ask
+     * for more and you get the ceiling, with {@link Paginated.pageSize} reporting
+     * the size you actually got rather than the one you asked for. To read more
+     * than 500 rows, page through them - `collect` and `pages` do it for you.
+     *
+     * A size the server could not parse is NOT clamped, it throws: `0`, a
+     * negative, `NaN` and `Infinity` all raise a `TypeError` before the request
+     * is built. This is deliberate and it is not defensive tidiness. `"1:NaN"`
+     * on the wire makes `QueryModifier#apply_pagination` read the size as zero
+     * and bail out before `limit`/`offset` are applied, so the endpoint answers
+     * with the WHOLE table: one typo turns a listing into an unbounded scan
+     * holding a Puma thread and a database connection. Failing at the call site
+     * is the only place that mistake is still cheap.
+     *
+     * Narrower than 0.2.0, which clamped `0` to 1 and let `NaN` through onto
+     * the wire. See {@link resolvePageSize}.
+     */
     readonly pageSize?: number;
     /** `"column:asc"` or `"column:desc"`, passed through as `modifiers[order]`. */
     readonly order?: string;
@@ -176,7 +397,12 @@ export interface Paginated<T> {
     readonly items: T[];
     /** 1-based number of this page. */
     readonly page: number;
-    /** Page size that was requested. */
+    /**
+     * The page size the server actually applied, which is NOT necessarily the
+     * one that was requested: it is clamped to {@link MAX_PAGE_SIZE}. Read this
+     * rather than the number you passed in - they differ exactly when the
+     * difference matters.
+     */
     readonly pageSize: number;
     /** True when this page came back full, so another page may exist. */
     readonly hasMore: boolean;
@@ -189,6 +415,12 @@ export type PageLoader<T> = (params: Required<Pick<PageParams, "page" | "pageSiz
  * Builds a {@link Paginated} from the raw array the API returned plus the
  * loader that can fetch the next page. Resource modules use this instead of
  * hand-rolling the shape.
+ *
+ * @throws {TypeError} when `pageSize` is not a finite number of at least 1, or
+ *   `page` is not finite. Both go through {@link resolvePageSize} /
+ *   {@link resolvePageNumber}, which reject rather than clamp - see
+ *   {@link PageParams.pageSize} for why an unparseable size is dangerous
+ *   enough to be worth a throw.
  */
 export declare function createPage<T>(items: T[], page: number, pageSize: number, load: PageLoader<T>): Paginated<T>;
 /** Walks every page of a listing, yielding one page at a time. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omelhorsite/sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "TypeScript SDK for the omelhorsite API. Isolate-safe: no node builtins, no environment access, no stdout.",
   "type": "module",
   "license": "UNLICENSED",
@@ -25,6 +25,7 @@
     "typecheck:tests": "tsc --noEmit -p tsconfig.test.json"
   },
   "devDependencies": {
+    "@types/bun": "^1.4.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {