@omelhorsite/sdk 0.3.0 → 0.4.1

package/dist/types/auth/device.d.ts

@@ -1,7 +1,7 @@
 /**
  * OAuth 2.0 Device Authorization Grant (RFC 8628).
  *
- * This is how a CLI or an MCP server signs a person in without ever handling
+ * This is how a terminal or a headless client signs a person in without ever handling
  * their password: the client asks for a code, the person opens a URL in a real
  * browser and approves, and the client polls the token endpoint until the
  * approval lands.

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

@@ -36,7 +36,7 @@ export * from "./device";
 export * from "./tokens";
 /** Who the current credential belongs to. */
 export interface WhoAmI {
-    /** `users.id`. The stable identifier; matches the OIDC `sub` claim. */
+    /** The stable user identifier; matches the OIDC `sub` claim. */
     readonly id: string;
     /** Current handle. Mutable - never key anything on it. */
     readonly handle: string;
@@ -107,7 +107,7 @@ export declare class AuthNamespace extends Resource {
     }, options?: RequestOptions): Promise<void>;
     /**
      * Reads the OIDC claims of the current credential from
-     * `GET /oauth/userinfo`. `sub` is `users.id`.
+     * `GET /oauth/userinfo`. `sub` is the user's stable `id`.
      *
      * Needs the `openid` scope; without it the answer is 403. Members whose
      * value is null or empty are omitted from the response, so read defensively.

package/dist/types/auth/tokens.d.ts

@@ -2,15 +2,15 @@
  * Token providers: where the transport gets a bearer token from.
  *
  * The core has no storage. A provider is either a constant, or a thing the
- * host wired to its own store (the CLI's config file, a Worker KV namespace, a
+ * host wired to its own store (a config file, a Worker KV namespace, a
  * browser's memory). Nothing here reads a file or an environment variable.
  *
  * Two credential shapes exist today and both are just bearer tokens on the
  * wire:
- * - a legacy opaque session token (a UUID minted by `Session`), which never
- *   expires and carries no scopes;
- * - an OAuth 2 / OIDC access token from doorkeeper, which does expire and does
- *   carry scopes, and which comes with a refresh token.
+ * - a legacy opaque session token (a UUID), which never expires and carries no
+ *   scopes;
+ * - an OAuth 2 / OIDC access token, which does expire and does carry scopes,
+ *   and which comes with a refresh token.
  *
  * {@link TokenSet} models the second. The first is just a string.
  *
@@ -23,7 +23,7 @@ import { OmsError } from "../errors";
 import { type ApiClient, type TokenProvider } from "../http";
 import type { RequestOptions } from "../types";
 /**
- * An OAuth 2 token response, as doorkeeper returns it.
+ * An OAuth 2 token response, as the token endpoint returns it.
  *
  * `expiresAt` is absolute epoch milliseconds, not the `expires_in` seconds the
  * server sends, so a stored set stays correct across a restart.
@@ -45,8 +45,8 @@ export interface TokenSet {
 /** Claims the SDK reads out of an OIDC id token. */
 export interface IdentityClaims {
     /**
-     * Stable user identifier: `users.id`. Never the handle and never the email,
-     * both of which the user can change.
+     * Stable user identifier: the user's `id`, as `oms.account.me()` reports it.
+     * Never the handle and never the email, both of which the user can change.
      */
     readonly sub: string;
     readonly iss?: string;
@@ -87,8 +87,8 @@ export declare const DEFAULT_REFRESH_SKEW_MS = 60000;
 /**
  * Wraps a constant token. This is what `new Oms({ token })` builds.
  *
- * Accepts both credential kinds: an opaque session UUID and a doorkeeper
- * access token look identical on the wire.
+ * Accepts both credential kinds: an opaque session UUID and an OAuth access
+ * token look identical on the wire.
  */
 export declare function staticToken(token: string | null): TokenProvider;
 /**
@@ -304,8 +304,8 @@ export declare class OmsOAuthError extends OmsError {
  * Recognises an OAuth error inside whatever the transport threw.
  *
  * Deliberately narrow: only 400 and 401 bodies are read as OAuth errors. A 429
- * comes from rack-attack with the body `{"error":"rate_limited"}`, and that
- * `error` key is NOT an OAuth code - reading it as one abandons a perfectly
+ * carries the body `{"error":"rate_limited"}`, and that `error` key is NOT an
+ * OAuth code - reading it as one abandons a perfectly
  * live device flow. It stays an {@link OmsQuotaError} and the caller handles
  * it as a rate limit.
  *
@@ -316,8 +316,8 @@ export declare function oauthErrorFrom(thrown: unknown): OmsOAuthError | undefin
 export interface InsufficientScope {
     /**
      * The scopes the endpoint needed. EMPTY when the server named none, which
-     * means the endpoint has not been opened to OAuth clients at all - a backend
-     * gap, not a client bug. The two cases must read differently to the user.
+     * means the endpoint accepts no OAuth token at all - a server-side gap, not
+     * a client bug. The two cases must read differently to the user.
      */
     readonly required: string[];
     /** The `realm` parameter, when present. */
@@ -342,7 +342,7 @@ export declare function readInsufficientScope(error: unknown): InsufficientScope
  *
  * The OAuth endpoints do not take JSON, which is why this exists next to
  * `ApiClient.post` rather than using it. Blank values are dropped rather than
- * sent empty, because doorkeeper reads `""` as a present-but-invalid parameter.
+ * sent empty, because the server reads `""` as a present-but-invalid parameter.
  *
  * Retries are OFF and stay off. Replaying `POST /oauth/token` after a lost
  * response is not safe: the server may have rotated the refresh token already,

package/dist/types/client.d.ts

@@ -41,7 +41,7 @@ import type { FetchLike, RetryOptions } from "./types";
  * Anything accepted as a credential by {@link Oms}.
  *
  * A bare string is either kind of bearer token the API takes: a legacy opaque
- * `Session` UUID or an OAuth access token. A function is called on every
+ * session UUID or an OAuth access token. A function is called on every
  * request. A {@link TokenProvider} additionally gets a chance to refresh on a
  * 401 - see `auth/tokens.ts`.
  */
@@ -66,7 +66,7 @@ export interface OmsOptions {
      * by name.
      *
      * ```ts
-     * // in the omelhorsite web app, served from the same site as the API
+     * // on a first-party page, served from the same site as the API
      * const oms = new Oms({ sessionCookie: true });
      * ```
      */
@@ -75,13 +75,13 @@ export interface OmsOptions {
     readonly baseUrl?: string;
     /**
      * The fetch to talk through. Defaults to `globalThis.fetch`. Injecting one is
-     * how a Worker adds a cache, how a test swaps in a double, and how the CLI
+     * how a Worker adds a cache, how a test swaps in a double, and how a host
      * adds a proxy - the SDK never patches a global.
      */
     readonly fetch?: FetchLike;
     /** Headers merged into every request, below per-call headers. */
     readonly headers?: Record<string, string>;
-    /** Default deadline for one call including its retries. `0` disables it. */
+    /** Default deadline for one attempt; a retry gets a fresh one. `0` disables it. */
     readonly timeoutMs?: number;
     /** Default backoff policy, or `false` to never retry. */
     readonly retry?: RetryOptions | false;
@@ -103,10 +103,10 @@ export interface OmsOptions {
  *
  * ## Two credentials, two namespaces
  *
- * `oms.sessions` mints the opaque `Session` token the website and the mobile
- * apps use, which carries the whole account. `oms.auth` runs OAuth, whose
- * tokens are scoped and, because `enforce_oauth_scope!` denies by omission,
- * cannot reach most of the API at all. `oms.realtime` accepts only the first
+ * `oms.sessions` mints the opaque session token, which carries the whole
+ * account. `oms.auth` runs OAuth, whose tokens are scoped and, because an
+ * endpoint with no declared scope refuses every OAuth token, cannot reach most
+ * of the API at all. `oms.realtime` accepts only the first
  * kind. Picking the wrong one shows up as a `403 insufficient_scope`, or on the
  * cable as a connection that is silently anonymous.
  *
@@ -178,9 +178,9 @@ export declare class Oms {
     /** OAuth client registration for anyone, plus the `/admin/*` routes. */
     readonly admin: AdminNamespace;
     /**
-     * The ActionCable connection: playback handoff, jams, notifications, job
+     * The WebSocket connection: playback handoff, jams, notifications, job
      * progress. Opens nothing until {@link RealtimeNamespace.connect} is called,
-     * and wants a `Session` token rather than the client's own credential - see
+     * and wants a session token rather than the client's own credential - see
      * that method for why.
      */
     readonly realtime: RealtimeNamespace;

package/dist/types/errors.d.ts

@@ -8,15 +8,15 @@
  * The API answers with at least four different error body shapes, so anything
  * that reads an error body must go through {@link normalizeErrorBody}:
  *
- * - a bare JSON string:            `"Image too large"`            (ResponseHelpers)
- * - a sentence from ActiveModel:   `"Name can't be blank and ..."` (error_messages)
+ * - a bare JSON string:            `"Image too large"`
+ * - a validation sentence:         `"Name can't be blank and ..."`
  * - an object with `error`:        `{"error":"rate_limited","retry_after":37}`
  * - an object of field errors:     `{"errors":{"url":["is invalid"]}}`
  * - plain text / HTML:             short-link 404 pages, proxy errors
  */
 /** Machine-readable code carried by every SDK error. */
 export type OmsErrorCode = "api_error" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "invalid_request" | "quota_exceeded" | "rate_limited" | "server_error" | "timeout" | "aborted" | "network" | "unsupported" | "unknown";
-/** Extra context attached to an error, useful for logs and for the CLI. */
+/** Extra context attached to an error, useful for logs. */
 export interface OmsErrorContext {
     /** HTTP method of the failing request, when there was one. */
     readonly method?: string;
@@ -38,9 +38,9 @@ export declare class OmsError extends Error {
      * This class's own name, as a LITERAL.
      *
      * `this.name = new.target.name` would be the obvious way to do this and it
-     * is wrong here: `bun build --minify` renames the classes, so the shipped
-     * `oms` binary reported `name: "A"` in its JSON error envelope while a dev
-     * run reported `OmsNetworkError`. A minifier renames identifiers, never
+     * is wrong here: `bun build --minify` renames the classes, so a minified
+     * build reported `name: "A"` in its JSON error envelope while a dev run
+     * reported `OmsNetworkError`. A minifier renames identifiers, never
      * string literals or property names, so a static literal survives the build.
      *
      * Every subclass shadows this, and `new.target` is the constructor that was
@@ -95,9 +95,6 @@ export declare class OmsApiError extends OmsError {
 }
 /**
  * 401 or 403: the credential is missing, expired, or not allowed to do this.
- *
- * The CLI turns this into "run `oms auth login`"; the MCP server turns it into
- * a device-flow prompt.
  */
 export declare class OmsAuthError extends OmsApiError {
     static readonly errorName: string;
@@ -107,10 +104,10 @@ export declare class OmsAuthError extends OmsApiError {
 /**
  * 429, or a documented daily-quota rejection.
  *
- * Two different producers land here and they do not look alike:
- * rack-attack answers `{"error":"rate_limited","retry_after":37}` with a
- * `Retry-After` header, while a controller quota gate answers a bare string
- * such as `"Daily edit quota reached (5/day)"` with no header at all. Read
+ * Two different producers land here and they do not look alike: a rate limit
+ * answers `{"error":"rate_limited","retry_after":37}` with a `Retry-After`
+ * header, while a daily quota answers a bare string such as
+ * `"Daily edit quota reached (5/day)"` with no header at all. Read
  * {@link retryAfterMs}; it is `undefined` in the second case.
  */
 export declare class OmsQuotaError extends OmsApiError {
@@ -160,7 +157,7 @@ export interface NormalizedError {
     readonly message: string;
     /** A code the server named itself (`{"error":"rate_limited"}`), if any. */
     readonly serverCode: string | undefined;
-    /** Per-field messages, when the body was shaped like ActiveModel errors. */
+    /** Per-field messages, when the body was a field-to-messages map. */
     readonly fieldErrors: Record<string, string[]> | undefined;
 }
 /**
@@ -179,7 +176,7 @@ export interface NormalizedError {
 export declare function normalizeErrorBody(body: unknown, fallback?: string): NormalizedError;
 /**
  * Reads a `Retry-After` header. RFC 9110 allows both delay-seconds and an
- * HTTP-date; rack-attack sends seconds, but a proxy in front may not.
+ * HTTP-date; the API sends seconds, but a proxy in front may not.
  *
  * @returns Milliseconds to wait, or `undefined` when the header is absent or junk.
  */

package/dist/types/http.d.ts

@@ -8,11 +8,10 @@
  *
  * ## Three runtimes, and where they stop agreeing
  *
- * The same transport runs in a browser (the Next.js frontend), in React Native
- * (the Expo app) and in Bun (the CLI and the MCP server). They agree on
- * `fetch`, `AbortController`, `Headers`, `FormData` and `setTimeout`. They do
- * NOT agree on three things, each of which has a named capability check here
- * rather than a `try` and a shrug:
+ * The same transport runs in a browser, in React Native and in Bun or a Worker
+ * isolate. They agree on `fetch`, `AbortController`, `Headers`, `FormData` and
+ * `setTimeout`. They do NOT agree on three things, each of which has a named
+ * capability check here rather than a `try` and a shrug:
  *
  * | capability                        | browser | React Native | Worker / Bun |
  * | --------------------------------- | ------- | ------------ | ------------ |
@@ -32,7 +31,7 @@ export declare const DEFAULT_BASE_URL = "https://backend.omelhorsite.pt";
  *
  * Answered by probing the globals, never by sniffing a platform name, and
  * recomputed on every call so a polyfill installed after import is seen. See
- * the table in the module note for how the three clients score.
+ * the table in the module note for how the three runtimes score.
  */
 export interface TransportCapabilities {
     /** `fetch` hands back a readable body that can be consumed as it arrives. */
@@ -51,9 +50,7 @@ export declare function transportCapabilities(): TransportCapabilities;
  * UI, and it has a hard "no" on React Native. RN's `fetch` is its
  * `XMLHttpRequest` with a whatwg-fetch shim over it: the whole body is
  * accumulated by the native layer and handed over at the end, `response.body`
- * is `undefined`, and there is no `ReadableStream` in the runtime at all -
- * confirmed by grep over `oms-music/src`, which mentions neither
- * `ReadableStream` nor `getReader` anywhere.
+ * is `undefined`, and there is no `ReadableStream` in the runtime at all.
  *
  * That is not a gap to polyfill. Nothing that runs in JS can make the native
  * networking layer emit partial bodies, and the shims that claim to (RN's
@@ -79,10 +76,9 @@ export declare function transportCapabilities(): TransportCapabilities;
  * is to call it and use this only to decide what the UI PROMISES: a typing
  * indicator that never types is worse than a spinner that admits it is waiting.
  *
- * The consumer this was designed against is the frontend's `BookChatService`,
- * which reads an SSE-shaped body (`data: {"delta": "..."}` lines) off
- * `POST /books/:id/chat`. Framing the lines is the domain's job; this and
- * `streamText` only promise decoded text in order.
+ * The typical consumer reads an SSE-shaped body (`data: {"delta": "..."}`
+ * lines) off `POST /books/:id/chat`. Framing the lines is the caller's job;
+ * this and `streamText` only promise decoded text in order.
  *
  * The three probes are all needed. `ReadableStream` existing does not mean
  * `fetch` produces one (a polyfilled global over RN's fetch is exactly that
@@ -93,7 +89,7 @@ export declare function transportCapabilities(): TransportCapabilities;
 export declare function supportsResponseStreaming(): boolean;
 /**
  * Whether `XMLHttpRequest` is available, which is the only route to byte-level
- * UPLOAD progress in any of the three clients.
+ * UPLOAD progress on any runtime.
  *
  * True in a browser and in React Native (RN's networking is XHR underneath and
  * `xhr.upload.onprogress` fires there); false in a Worker-class isolate and in
@@ -209,7 +205,7 @@ export type JsonBody = unknown;
 export type FormFieldValue = string | number | boolean | FileInput | NativeFile | null | undefined;
 /**
  * Fields of a multipart form. An array value is appended once per entry with a
- * `[]` suffix, which is how Rails reads a list (`clips[]`).
+ * `[]` suffix (`clips[]`), which is how the API reads a list.
  */
 export type FormFields = Record<string, FormFieldValue | FormFieldValue[]>;
 /** Options for a request that carries a query string. */
@@ -238,12 +234,11 @@ export interface GetOptions extends RequestOptions {
  * it never saw, so replaying it is how one `create` call becomes two records.
  * Safe methods carry no such risk, which is the whole reason the split exists.
  *
- * `429` is the exception, and it is safe on every method because of how this
- * particular backend produces one. It comes either from `Rack::Attack`, which
- * answers from middleware before the router is reached, or from a
- * `too_many_requests!` guard that every controller places BEFORE the write it
- * protects. A 429 is therefore proof the request was refused rather than
- * performed, and waiting out `Retry-After` and trying again is exactly right.
+ * `429` is the exception, and it is safe on every method because this API only
+ * ever answers one BEFORE performing the request: a rate-limited request is
+ * refused, never carried out. A 429 is therefore proof the request was refused
+ * rather than performed, and waiting out `Retry-After` and trying again is
+ * exactly right.
  *
  * ## Opting a mutator back in
  *
@@ -262,45 +257,18 @@ export interface GetOptions extends RequestOptions {
  * notepad) under a fresh random identifier on each attempt.
  *
  * This is narrower than the SDK's 0.2.0 behaviour, which retried 5xx on every
- * verb. Nothing in `resources/` relied on that: every call site that mentions
- * retry is turning it OFF.
- *
- * ## Why this and not the mobile app's rule
- *
- * `oms-music/src/api/retryPolicy.ts` states the rule the app arrived at after
- * the empty-Home bug: **retry for TIME, never for a RESPONSE**. A transport
- * failure (a `fetch` that throws, DNS, the iOS radio still waking) is time and
- * is worth asking again; a `4xx` is an answer and asking again does not change
- * it; a `5xx` gets one extra go for a deploy or a blinking proxy; `429` gets
- * none. Two attempts, `error.status >= 500` as the whole predicate.
- *
- * That rule is right for what it governs and wrong to copy here, for one
- * reason: it sits under react-query, where every retried operation is a QUERY.
- * "Repeat any transport error" is safe when the thing being repeated is a read.
- * This SDK carries the writes too, and the app's own mutations do NOT go
- * through that policy. Applying it verbatim would replay a `POST /songs` whose
- * answer was lost on a lift ride and mint the record twice, which is precisely
- * the failure the method split above exists to prevent. So the SDK keeps the
- * axis the app does not have to think about (the METHOD) and agrees with it on
- * the axis it does: a `4xx` is never retried anywhere.
- *
- * On `429` the two genuinely disagree, and the disagreement is deliberate on
- * both sides. The app declines because its ceiling-aware screens would rather
- * show "slow down" at once than sit on a hidden `Retry-After` sleep, and
- * because react-query re-throws a parked error before the network is even
- * consulted. The SDK retries because it also serves the CLI and the MCP server,
- * where the right move on a rate limit is to wait the header out and continue,
- * and because this backend's `429` provably precedes the write (Rack::Attack in
- * middleware, `too_many_requests!` ahead of every guarded action). A mobile
- * host that wants the app's behaviour asks for it per call - `retry: false` -
- * or, at the client, gets the closest match with `new Oms({ retry: { maxAttempts: 2 } })`:
- * one extra attempt, safe methods only, exactly the app's shape.
- *
- * One consequence to design around rather than discover: a retried `429` obeys
- * `Retry-After`, this API sets it from a one-minute window, and `timeoutMs`
- * bounds ONE attempt rather than the call. A rate-limited call can therefore
- * take minutes of wall clock. Anything with a user watching it should pass a
- * `signal` it can abort, or turn retrying off.
+ * verb.
+ *
+ * ## Rate limits and wall clock
+ *
+ * A retried `429` obeys `Retry-After`, this API sets it from a one-minute
+ * window, and `timeoutMs` bounds ONE attempt rather than the call. A
+ * rate-limited call can therefore take minutes of wall clock. A UI with a
+ * person watching it may rather show "slow down" at once than sit on a hidden
+ * sleep: pass a `signal` it can abort, turn retrying off per call with
+ * `retry: false`, or cap it at the client with
+ * `new Oms({ retry: { maxAttempts: 2 } })` - one extra attempt, safe methods
+ * only.
  */
 export declare class ApiClient {
     /** API root with no trailing slash. */
@@ -328,7 +296,7 @@ export declare class ApiClient {
     delete<T>(path: string, options?: GetOptions): Promise<T>;
     /**
      * `POST` a `multipart/form-data` body, parsed as JSON. Use this for every
-     * endpoint that takes an upload through Rails (the tools). Storage uploads
+     * endpoint that takes a multipart upload (the tools). Storage uploads
      * do NOT go through here - they are presigned and go straight to the object
      * store; see `resources/storage/upload.ts`.
      *
@@ -345,7 +313,7 @@ export declare class ApiClient {
      *
      * `response.body` is NOT a promise this method can make: React Native has no
      * `ReadableStream` and leaves it undefined, so any code reaching for
-     * `.body.getReader()` here works in the browser and the CLI and throws on a
+     * `.body.getReader()` here works in a browser and in Bun and throws on a
      * phone. Test with {@link supportsResponseStreaming} first, or use
      * {@link ApiClient.streamText}, which contains that fork already.
      */
@@ -359,7 +327,7 @@ export declare class ApiClient {
      * This is the primitive a streaming endpoint is built on. It promises exactly
      * two things - decoded text, in order, with nothing lost - and deliberately
      * promises nothing about chunk boundaries, because they are not the same on
-     * the three clients:
+     * the three runtimes:
      *
      * - browser and Bun: one yield per network chunk, as it lands;
      * - React Native: ONE yield, containing everything, after the server has
@@ -370,20 +338,18 @@ export declare class ApiClient {
      * So a caller must not assume a chunk is a frame, a line, or a whole
      * anything: a `data:` line can arrive split across two chunks, and on RN a
      * hundred of them arrive as one string. Buffer, then split on your own
-     * delimiter. `BookChatService` in the frontend is the reference reader (SSE
-     * `data:` lines carrying `{ delta, done, error }`) and shows the shape of it;
-     * framing belongs to the domain module, not here.
+     * delimiter. The book chat endpoint, for instance, answers SSE `data:` lines
+     * carrying `{ delta, done, error }`; framing them belongs to the caller, not
+     * here.
      *
-     * ## The silence limit exists because of an outage
+     * ## The silence limit
      *
-     * A stalled sidecar answered `200` and then said nothing for two minutes at a
-     * time, and `await reader.read()` has no deadline of its own, so the chat
-     * panel span for as long as the tab stayed open. `timeoutMs` does not help:
-     * it is disposed once the headers arrive (it has to be, or no stream could
-     * outlive it). `silenceTimeoutMs` bounds the gap BETWEEN chunks instead and
-     * raises {@link OmsTimeoutError} when nothing arrives for that long. It has
-     * to sit well clear of a cold model's first token; 45s is the number the
-     * frontend settled on and the default here.
+     * A server can answer `200` and then say nothing for minutes, and
+     * `await reader.read()` has no deadline of its own. `timeoutMs` does not
+     * help: it is disposed once the headers arrive (it has to be, or no stream
+     * could outlive it). `silenceTimeoutMs` bounds the gap BETWEEN chunks instead
+     * and raises {@link OmsTimeoutError} when nothing arrives for that long. It
+     * has to sit well clear of a cold model's first token; 45s is the default.
      *
      * Pass `0` to disable it, and mean it: an unbounded read is a spinner with no
      * way out. It does not apply on the buffered path, where the single `text()`
@@ -437,29 +403,25 @@ export declare abstract class Resource {
     constructor(http: ApiClient);
 }
 /**
- * The backend's null sentinel: a single backspace character, `U+0008`.
+ * The API's null sentinel: a single backspace character, `U+0008`.
  *
  * A query string has no way to say `null`. `?parent_id=` is the empty string,
  * `?parent_id=null` is the four-letter word "null", and omitting the key
  * entirely says something else again. So the API picked a character no real
- * value ever contains and decodes it back to `nil` on arrival:
- * `CrudActions#define_option_param_getter` runs
- * `value.transform_values! { |v| v == "\b" ? nil : v }` over every filter
- * bucket, and `GroupChatsController`, `GroupChatMessagesController` and
- * `BookServices::Creator` each repeat the same test on the fields they read by
- * hand.
- *
- * Where that `nil` lands is what makes it worth having. `Searchable.exact_search`
- * is `where(params)`, so `exact_search[parent_id]` set to the sentinel becomes
- * `WHERE parent_id IS NULL` - the only way to ask for the storage root nodes,
- * for a comment with no parent, for anything unassigned.
+ * value ever contains and decodes it back to null on arrival, inside every
+ * filter bucket and in the handful of body fields that accept it.
+ *
+ * Where that null lands is what makes it worth having: `exact_search[parent_id]`
+ * set to the sentinel becomes `WHERE parent_id IS NULL` - the only way to ask
+ * for the storage root nodes, for a comment with no parent, for anything
+ * unassigned.
  *
  * Exported because it is part of the wire format, not because you should need
  * it: {@link encodeQuery} writes it for you whenever a query value is `null`.
  */
 export declare const NULL_SENTINEL = "\b";
 /**
- * Encodes query parameters the way Rails parses them.
+ * Encodes query parameters the way the API parses them.
  *
  * - `{ page: 2 }`                     -> `page=2`
  * - `{ ids: ["a", "b"] }`             -> `ids%5B%5D=a&ids%5B%5D=b`
@@ -476,16 +438,14 @@ export declare const NULL_SENTINEL = "\b";
  * - `undefined` means "I am not filtering on this column". Dropping the key is
  *   the correct encoding.
  * - `null` means "filter where this column IS NULL". There is no literal for
- *   that in a URL, so it goes out as {@link NULL_SENTINEL} and the backend
- *   turns it back into `nil`.
+ *   that in a URL, so it goes out as {@link NULL_SENTINEL} and the server
+ *   turns it back into null.
  *
- * Encoding `null` as "drop the key" - which this function used to do - is the
- * dangerous direction. The filter simply vanishes and `Searchable.exact_search`
- * returns early (`return self unless params.present?`), so the endpoint answers
- * with the UNFILTERED set: a request for the root of somebody's drive comes
- * back as their entire tree. That failure has bitten this API before, from the
- * other end, and is why `CrudActions#reject_unknown_filter_keys!` now 400s on a
- * key it does not recognise rather than quietly widening the query.
+ * Encoding `null` as "drop the key" is the dangerous direction. The filter
+ * simply vanishes and the endpoint answers with the UNFILTERED set: a request
+ * for the root of somebody's drive comes back as their entire tree. For the
+ * same reason the API answers `400` to a filter key it does not recognise
+ * rather than quietly widening the query.
  *
  * The sentinel is written at every depth, even though the server only decodes
  * it one level inside a filter bucket (`search`, `exact_search`, `modifiers`,
@@ -495,20 +455,17 @@ export declare const NULL_SENTINEL = "\b";
  *
  * ## Dates
  *
- * A `Date` reaches `typeof value === "object"` like anything else, and
- * `Object.entries(new Date())` is `[]`, so before this branch existed a date
- * filter did not merely arrive malformed - the key disappeared and the listing
- * came back unfiltered. ISO-8601 is what the server reads:
- * `QuerySearcher#date_search` runs `String#to_date_safe` (`Date.parse`) over
- * the value and turns an unparseable one into `nil`, which silently drops that
- * side of the range. Bodies need no equivalent branch, because `JSON.stringify`
- * already calls `Date.prototype.toJSON` and emits the same string.
+ * A `Date` is sent as its ISO-8601 string, which is what the server's date
+ * filters parse. An unparseable value is silently treated as absent, which
+ * drops that side of the range. Bodies need no equivalent branch, because
+ * `JSON.stringify` already calls `Date.prototype.toJSON` and emits the same
+ * string.
  *
  * ## The brackets are percent-encoded, and that is load-bearing
  *
  * `search[title]` goes out as `search%5Btitle%5D`, never as raw `[` and `]`.
- * Both parse identically in Rails, so this looks like the kind of noise someone
- * tidies away on a quiet afternoon. It is not, and the reason is iOS.
+ * Both parse identically on the server, so this looks like the kind of noise
+ * someone tidies away on a quiet afternoon. It is not, and the reason is iOS.
  *
  * `[` and `]` are not legal in a URI query (RFC 3986 reserves them for the host
  * component). Every browser tolerates them; Apple's URL stack does not. Give
@@ -534,16 +491,16 @@ export declare function encodeQuery(params: QueryParams): string;
  * asked for again.
  *
  * `PUT` and `DELETE` are idempotent by RFC 9110 and are still absent, because
- * idempotent is not the same as harmless to replay HERE. Rails' `destroy` is
- * behind a `find_by` that answers `404` the second time, so a `DELETE` retried
- * after a torn connection reports "not found" for a row it deleted perfectly
- * well - a success turned into an error the caller then acts on.
+ * idempotent is not the same as harmless to replay HERE. A `DELETE` answers
+ * `404` the second time, so one retried after a torn connection reports "not
+ * found" for a row it deleted perfectly well - a success turned into an error
+ * the caller then acts on.
  */
 export declare const SAFE_METHODS: ReadonlySet<string>;
 /** True when {@link SAFE_METHODS} contains `method`, case-insensitively. */
 export declare function isSafeMethod(method: string): boolean;
 /**
- * Builds the `modifiers[page]` string the backend expects (`"2:100"`).
+ * Builds the `modifiers[page]` string the API expects (`"2:100"`).
  *
  * Both halves go through `resolvePageSize` / `resolvePageNumber`, which is the
  * same pair `createPage` uses. That is the point: the size on the wire and the
@@ -552,9 +509,8 @@ export declare function isSafeMethod(method: string): boolean;
  * told `hasMore: false` while 700 rows sit behind it.
  *
  * @throws {TypeError} for a page size that is not a finite number of at least
- *   1. `"1:NaN"` on the wire reads as size `0` in
- *   `QueryModifier#apply_pagination`, which skips `limit`/`offset` altogether
- *   and returns the entire table.
+ *   1. `"1:NaN"` on the wire reads as size `0` on the server, which then skips
+ *   pagination altogether and returns the entire table.
  */
 export declare function pageModifier(page?: number, pageSize?: number): string;
 /**
@@ -563,8 +519,8 @@ export declare function pageModifier(page?: number, pageSize?: number): string;
  * `null` and `undefined` fields are OMITTED, which is the opposite of what
  * {@link encodeQuery} does with `null` and is right for the same reason it is
  * right there: what the receiver reads from an absent field. A multipart body
- * only ever feeds a create here, and an absent field means `params[:x]` is
- * `nil` - already the value a sentinel would decode to, so writing one would
+ * only ever feeds a create here, and an absent field is read as null on the
+ * server - already the value a sentinel would decode to, so writing one would
  * add a step that changes nothing. In a query the absent key means "no filter",
  * which is a different answer entirely.
  *
@@ -609,7 +565,7 @@ export declare function backoffDelay(attempt: number, retry: ResolvedRetry): num
 export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
 /**
  * How long {@link ApiClient.streamText} will wait for the NEXT chunk before it
- * gives up: 45 seconds, the number the frontend's `BookChatService` arrived at.
+ * gives up: 45 seconds.
  *
  * It is a silence limit, not a total: a stream that keeps producing runs as
  * long as it likes. The value has to clear a cold model's first token (the

package/dist/types/index.d.ts

@@ -8,8 +8,7 @@
  * const link = await oms.shortLinks.create({ url: "https://example.com" });
  * ```
  *
- * This package is the product; the CLI and the MCP server are two clients of
- * it. Three rules make that work, and they are not negotiable:
+ * Three rules shape the package, and they are not negotiable:
  *
  * 1. It runs in a Cloudflare-Worker-class isolate. No `node:*`, no `process`,
  *    no filesystem, no stdout. `fetch` is injectable through the constructor.
@@ -29,6 +28,7 @@ export * from "./auth/index";
 export * from "./client";
 export * from "./errors";
 export * from "./http";
+export * from "./listing";
 export * from "./local/index";
 export * from "./resources/index";
 export * from "./types";

package/dist/types/internal/attachments.d.ts

@@ -0,0 +1,17 @@
+/** Attachment helpers shared by the message families. Not part of the public surface. */
+import type { ApiClient } from "../http";
+import type { FileInput, NativeFile, RequestOptions } from "../types";
+/**
+ * Byte length of an attachment, when it is knowable without reading anything.
+ * `undefined` for a stream with no declared `size` and for a picker that
+ * reported none.
+ */
+export declare function attachmentSize(file: FileInput | NativeFile): number | undefined;
+/**
+ * Follows an attachment redirect. In a browser in cookie mode the redirect
+ * to object storage fails CORS and surfaces as a bare network error; that
+ * case is turned into an error that says what to do instead.
+ */
+export declare function followAttachment(http: ApiClient, path: string, what: string, options: RequestOptions): Promise<Blob>;
+/** The bearer token the transport would send, or `null` when there is none (cookie mode). */
+export declare function tokenOf(http: ApiClient): Promise<string | null>;