@omelhorsite/sdk 0.2.0 → 0.4.0

package/dist/types/client.d.ts

@@ -14,15 +14,25 @@ import type { TokenSet } from "./auth/tokens";
 import { ApiClient, type TokenProvider } from "./http";
 import { type LocalNamespace } from "./local/index";
 import { AccountNamespace } from "./resources/account";
+import { AdminNamespace } from "./resources/admin";
+import { PasskeysNamespace } from "./resources/auth/passkeys";
+import { AuthSessionsNamespace } from "./resources/auth/sessions";
 import { ChestsNamespace } from "./resources/chests";
+import { ContentNamespace } from "./resources/content";
 import { DynamicQrsNamespace } from "./resources/dynamicQrs";
 import { FormsNamespace } from "./resources/forms";
 import { IpLookupNamespace } from "./resources/ipLookup";
 import { JobsNamespace } from "./resources/jobs";
+import { LibraryNamespace } from "./resources/library";
 import { LinkTreesNamespace } from "./resources/linkTrees";
+import { MediaNamespace } from "./resources/media";
+import { MoviesNamespace } from "./resources/movies";
+import { MusicNamespace } from "./resources/music/index";
 import { NotepadsNamespace } from "./resources/notepads";
 import { QuotasNamespace } from "./resources/quotas";
+import { RealtimeNamespace } from "./resources/realtime";
 import { ShortLinksNamespace } from "./resources/shortLinks";
+import { SocialNamespace } from "./resources/social";
 import { StorageNamespace } from "./resources/storage";
 import { TicketsNamespace } from "./resources/tickets";
 import { ToolsNamespace } from "./resources/tools/index";
@@ -87,10 +97,32 @@ export interface OmsOptions {
  * const oms = new Oms({ token: "..." });
  * const me = await oms.account.me();
  * const link = await oms.shortLinks.create({ url: "https://example.com" });
+ * const songs = await oms.music.songs.list({ artist: "Nina Simone" });
+ * const cable = oms.realtime.connect({ token, socket: (u) => new WebSocket(u) });
  * ```
  *
- * Isolate-safe: no `node:*`, no environment, no stdout. A file is always a
- * value (`Blob` / `Uint8Array` / `ReadableStream`), never a path.
+ * ## 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
+ * kind. Picking the wrong one shows up as a `403 insufficient_scope`, or on the
+ * cable as a connection that is silently anonymous.
+ *
+ * ## Isolate-safe
+ *
+ * No `node:*`, no environment, no stdout, and `fetch` is injectable. A file is
+ * normally a VALUE (`Blob` / `Uint8Array` / `ReadableStream`), never a path,
+ * because turning a path into bytes is the host's job.
+ *
+ * The one exception is React Native, which cannot produce a usable `Blob` from
+ * a picked file: there, pass the picker's `{ uri, name, type }`
+ * ({@link NativeFile}) straight into a form bag and the transport appends it
+ * verbatim for RN's networking layer to stream off disk. That works on
+ * multipart endpoints only - the storage direct-upload path has to read and MD5
+ * the bytes, so it rejects a `NativeFile` with a message saying so rather than
+ * failing at the object store.
  */
 export declare class Oms {
     /**
@@ -99,8 +131,12 @@ export declare class Oms {
      * the SDK to add one call.
      */
     readonly http: ApiClient;
-    /** Signing in, refreshing, revoking, and the RFC 8628 device grant. */
+    /** OAuth: refreshing, revoking, the RFC 8628 device grant, OIDC discovery. */
     readonly auth: AuthNamespace;
+    /** Password sign-in, sign-up, and the emailed six-digit ceremonies. */
+    readonly sessions: AuthSessionsNamespace;
+    /** WebAuthn credentials: register one, sign in with one, list, revoke. */
+    readonly passkeys: PasskeysNamespace;
     /** The signed-in user, their profile, and their usage report. */
     readonly account: AccountNamespace;
     /** Support tickets and their message threads. */
@@ -127,6 +163,27 @@ export declare class Oms {
     readonly quotas: QuotasNamespace;
     /** The metered media tools, each with its own daily quota. */
     readonly tools: ToolsNamespace;
+    /** Songs, artists, playlists, imports, jams and the music assistant. */
+    readonly music: MusicNamespace;
+    /** The canonical bytes of the music library, by media id. */
+    readonly media: MediaNamespace;
+    /** Direct messages, friendships and blocks, group chats. */
+    readonly social: SocialNamespace;
+    /** The book library: uploads, shelves, annotations, the study assistant. */
+    readonly library: LibraryNamespace;
+    /** Stremio addons, collections and watch progress. Session credential only. */
+    readonly movies: MoviesNamespace;
+    /** Blogs, notifications, feedback, jokes, site config and the status page. */
+    readonly content: ContentNamespace;
+    /** OAuth client registration for anyone, plus the `/admin/*` routes. */
+    readonly admin: AdminNamespace;
+    /**
+     * The ActionCable 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
+     * that method for why.
+     */
+    readonly realtime: RealtimeNamespace;
     /**
      * Pure client-side helpers that touch no network and need no credential
      * (password generation, QR encoding). Also exported standalone as `local`,

package/dist/types/http.d.ts

@@ -5,10 +5,122 @@
  * calls `fetch`, `AbortController`, `FormData`, `Blob` and `setTimeout` only -
  * all of which a Cloudflare Worker provides. `fetch` itself is injected, so a
  * host can wrap it (proxy, cache, test double) without patching a global.
+ *
+ * ## 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:
+ *
+ * | capability                        | browser | React Native | Worker / Bun |
+ * | --------------------------------- | ------- | ------------ | ------------ |
+ * | `supportsResponseStreaming()`     | yes     | **no**       | yes          |
+ * | `supportsUploadProgress()` (XHR)  | yes     | yes          | **no**       |
+ * | `supportsNativeFormDataFiles()`   | no      | **yes**      | no           |
+ *
+ * Read them at the point of use, not once at module load: a host may install a
+ * polyfill after the SDK is imported, and in RN the fetch implementation is
+ * swapped by libraries often enough that a cached answer goes stale.
  */
-import { type FetchLike, type FileInput, type FileOutput, type QueryParams, type RequestOptions, type ResolvedRetry, type RetryOptions } from "./types";
+import { type FetchLike, type FileInput, type FileOutput, type NativeFile, type QueryParams, type RequestOptions, type ResolvedRetry, type RetryOptions } from "./types";
 /** Production API root. Override only for a local backend or a test double. */
 export declare const DEFAULT_BASE_URL = "https://backend.omelhorsite.pt";
+/**
+ * What the runtime this code woke up in can actually do.
+ *
+ * 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.
+ */
+export interface TransportCapabilities {
+    /** `fetch` hands back a readable body that can be consumed as it arrives. */
+    readonly responseStreaming: boolean;
+    /** `XMLHttpRequest` is present, so byte-level upload progress is reachable. */
+    readonly uploadProgress: boolean;
+    /** `FormData` is React Native's, so a {@link NativeFile} can be appended. */
+    readonly nativeFormDataFiles: boolean;
+}
+/** All three capability probes at once. */
+export declare function transportCapabilities(): TransportCapabilities;
+/**
+ * Whether a response body can be read INCREMENTALLY on this runtime.
+ *
+ * This is the question a caller has to answer before it offers a token-by-token
+ * 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.
+ *
+ * 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
+ * `textStreaming` blob response type, `react-native-fetch-api`) either need
+ * `XMLHttpRequest`'s `onprogress` plumbed by hand or a different fetch
+ * altogether. Which is why this is a capability check and not a feature.
+ *
+ * ## What a caller does with the answer
+ *
+ * Pick a PRESENTATION, not a protocol. Both paths hit the same endpoint and
+ * read the same bytes; the difference is whether they arrive in pieces:
+ *
+ * ```ts
+ * if (supportsResponseStreaming()) {
+ *   for await (const chunk of oms.http.streamText("POST", path, { body })) render(chunk);
+ * } else {
+ *   const whole = await oms.http.raw("POST", path, { body }).then((r) => r.text());
+ *   render(whole);                       // one paint, after the server is done
+ * }
+ * ```
+ *
+ * {@link ApiClient.streamText} already contains that fork, so the usual answer
+ * 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 three probes are all needed. `ReadableStream` existing does not mean
+ * `fetch` produces one (a polyfilled global over RN's fetch is exactly that
+ * case), `Response.prototype` having `body` does not mean it is non-null on a
+ * given response - `streamText` still checks the instance - and `TextDecoder`
+ * is what turns the chunks into text on the way out.
+ */
+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.
+ *
+ * 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
+ * Bun's server runtime. See {@link Progress} for the whole argument and
+ * `UploadManagerOptions.fetch` for the recipe - this only reports whether that
+ * recipe can be used here, so a UI can decide between a real bar and a
+ * per-file tick.
+ *
+ * The SDK never uses XHR itself. It cannot: the core has to load in an isolate.
+ */
+export declare function supportsUploadProgress(): boolean;
+/**
+ * Whether this runtime's `FormData` accepts a {@link NativeFile} descriptor.
+ *
+ * React Native's `FormData` is not the web one. `append(name, value)` stores
+ * the value as it is, and `getParts()` later reads `value.uri`, `value.name`
+ * and `value.type` off it to build a file part that the native layer streams
+ * from disk. The web `FormData` instead coerces any non-`Blob` to a string, so
+ * the same object silently becomes the literal text `"[object Object]"` in a
+ * text field - a 200 response and an upload that never happened.
+ *
+ * Detected by the presence of `getParts` on the prototype, with
+ * `navigator.product === "ReactNative"` as the second opinion. Not by a
+ * `Platform.OS` import, which would drag `react-native` into a package that has
+ * to load in a Worker.
+ */
+export declare function supportsNativeFormDataFiles(): boolean;
 /**
  * Supplies the bearer token for each request.
  *
@@ -59,9 +171,23 @@ export interface ApiClientOptions {
     readonly sessionCookie?: boolean;
     /** Headers merged into every request, below per-call headers. */
     readonly headers?: Record<string, string>;
-    /** Default deadline for one call, retries included. `0` disables it. */
+    /**
+     * Default deadline for ONE ATTEMPT, not for the whole call. `0` disables it.
+     *
+     * Each attempt gets a fresh one, so a call that retries can take up to
+     * `maxAttempts` times this plus the backoff. It also stops at the response
+     * headers rather than at the last byte, which is what lets `raw()` and
+     * `streamText()` hold a body open for longer. See {@link RequestOptions.timeoutMs}.
+     */
     readonly timeoutMs?: number;
-    /** Default backoff policy, or `false` to never retry. */
+    /**
+     * Shape of the default backoff: how many attempts, how long between them.
+     *
+     * It does not widen WHICH requests are eligible - that stays "safe methods,
+     * plus a 429 on anything". Only a per-call `retry` can put a mutator in
+     * scope. `false` turns retrying off completely, for every method and every
+     * status. See the retry policy on {@link ApiClient}.
+     */
     readonly retry?: RetryOptions | false;
     /**
      * Value for the `X-Oms-Client` header, e.g. `"oms-cli/0.3.1"`. The SDK does
@@ -72,8 +198,15 @@ export interface ApiClientOptions {
 }
 /** Body accepted by `post`/`patch`. `undefined` sends no body at all. */
 export type JsonBody = unknown;
-/** One field of a multipart form. */
-export type FormFieldValue = string | number | boolean | FileInput | null | undefined;
+/**
+ * One field of a multipart form.
+ *
+ * {@link NativeFile} is here so that a React Native caller can pass the object
+ * its picker returned straight through - `form.image = picked` - without
+ * wrapping it. It is appended verbatim on RN and rejected loudly elsewhere; see
+ * {@link buildFormData}.
+ */
+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[]`).
@@ -86,16 +219,88 @@ export interface GetOptions extends RequestOptions {
 /**
  * HTTP client for the omelhorsite API.
  *
- * Retry policy, deliberately narrow:
- * - a `fetch` rejection (DNS, TLS, reset) is retried;
- * - `5xx` is retried;
- * - `429` is retried, waiting exactly what `Retry-After` asked for;
- * - every other `4xx` fails immediately, on any method.
+ * ## Retry policy
+ *
+ * What may be retried depends on WHY the attempt failed and on WHICH method
+ * made it, because those two together decide whether a replay can duplicate
+ * work the server already did:
+ *
+ * | outcome                              | GET / HEAD | POST / PATCH / PUT / DELETE |
+ * | ------------------------------------ | ---------- | --------------------------- |
+ * | `fetch` rejection (DNS, TLS, reset)  | retried    | **not** retried             |
+ * | `5xx`                                | retried    | **not** retried             |
+ * | `429`                                | retried    | retried                     |
+ * | every other `4xx`                    | fails      | fails                       |
+ *
+ * The first two rows are ambiguous: a reset connection and a 502 from a proxy
+ * both mean "no usable answer", never "nothing happened". A `POST` that the
+ * server committed before the response was lost is indistinguishable from one
+ * 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.
+ *
+ * ## Opting a mutator back in
+ *
+ * Pass a `retry` object AT THE CALL SITE and it applies whatever the method:
+ *
+ * ```ts
+ * await oms.tools.downloader.create(input, { retry: {} });  // POST, retried
+ * ```
+ *
+ * A client-wide `new Oms({ retry })` deliberately does NOT do this. It sets the
+ * SHAPE of the backoff (attempts, delays, jitter) for whatever is eligible; it
+ * is not a statement about any one endpoint, and "every POST in this process
+ * may be replayed" is not a decision anybody makes correctly in a constructor.
+ * `retry: false` still disables everything, `429` included, and stays the right
+ * answer for a call whose failure mode is minting something (a short link, a
+ * 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.
  *
- * The policy applies to all verbs, `POST` included. That is the documented
- * behaviour, and it means a `POST` that the server processed before dying with
- * a 502 can be replayed. Pass `retry: false` on any create where a duplicate
- * is worse than a failure.
+ * 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.
  */
 export declare class ApiClient {
     /** API root with no trailing slash. */
@@ -137,13 +342,79 @@ export declare class ApiClient {
      * media file or an SSE endpoint. Retry and auth still apply.
      *
      * The caller owns the body and must consume or cancel it.
+     *
+     * `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
+     * phone. Test with {@link supportsResponseStreaming} first, or use
+     * {@link ApiClient.streamText}, which contains that fork already.
      */
     raw(method: string, path: string, options?: GetOptions & {
         body?: BodyInit;
     }): Promise<Response>;
+    /**
+     * Reads a response body as text, in pieces where the runtime allows it and in
+     * one piece where it does not.
+     *
+     * 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:
+     *
+     * - browser and Bun: one yield per network chunk, as it lands;
+     * - React Native: ONE yield, containing everything, after the server has
+     *   finished. `fetch` there cannot do better - see
+     *   {@link supportsResponseStreaming} - and pretending otherwise by slicing
+     *   the finished body into fake chunks would only make a UI claim to be live.
+     *
+     * 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.
+     *
+     * ## The silence limit exists because of an outage
+     *
+     * 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.
+     *
+     * 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()`
+     * read is covered by the caller's `signal`.
+     *
+     * The body is always released: the reader is cancelled on every exit,
+     * including an abandoned `for await` (a `break` runs the generator's
+     * `finally`). An abandoned reader holds the connection open.
+     *
+     * @example
+     * ```ts
+     * let buffer = "";
+     * for await (const chunk of oms.http.streamText("POST", `/books/${id}/chat`, { body })) {
+     *   buffer += chunk;
+     *   // ... pull whole lines out of `buffer`, leave the partial one behind
+     * }
+     * ```
+     */
+    streamText(method: string, path: string, options?: GetOptions & {
+        body?: JsonBody;
+        silenceTimeoutMs?: number;
+    }): AsyncGenerator<string, void, undefined>;
     /**
      * `GET` that reads the whole response as a {@link FileOutput}, taking the
      * filename from `Content-Disposition` when the server sent one.
+     *
+     * Reads the body into memory in every runtime, React Native included, where
+     * `Response#blob()` needs RN's `BlobModule` and produces a Blob whose bytes
+     * live on the native side. For a large media file on a phone that is the
+     * wrong tool: ask for a signed URL and hand it to the player or to a native
+     * downloader instead of pulling it through JavaScript.
      */
     download(path: string, options?: GetOptions): Promise<FileOutput>;
     /** Absolute URL for a path, with the query string applied. */
@@ -165,24 +436,167 @@ export declare abstract class Resource {
     protected readonly http: ApiClient;
     constructor(http: ApiClient);
 }
+/**
+ * The backend'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.
+ *
+ * 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.
  *
  * - `{ page: 2 }`                     -> `page=2`
  * - `{ ids: ["a", "b"] }`             -> `ids%5B%5D=a&ids%5B%5D=b`
  * - `{ search: { status: "open" } }`  -> `search%5Bstatus%5D=open`
- * - `undefined` / `null` values are dropped, never sent as an empty string.
+ * - `{ since: new Date(...) }`        -> `since=2026-08-29T09%3A00%3A00.000Z`
+ * - `{ parent_id: null }`             -> `parent_id=%08`, the null sentinel
+ * - `undefined` values are dropped entirely.
+ *
+ * ## Why `null` and `undefined` are not the same thing here
+ *
+ * They are the two answers to two different questions, and a query string can
+ * only express one of them without help:
+ *
+ * - `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`.
+ *
+ * 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.
+ *
+ * The sentinel is written at every depth, even though the server only decodes
+ * it one level inside a filter bucket (`search`, `exact_search`, `modifiers`,
+ * `extra_options`). Anywhere else it stays the literal character and matches no
+ * row - an empty result, which is the safe way to be wrong. Compare that with
+ * dropping the key, which is an over-broad result nobody notices.
+ *
+ * ## 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.
+ *
+ * ## 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.
+ *
+ * `[` 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
+ * `NSURL`/`URLComponents` a string with a raw bracket in the query and it
+ * re-percent-encodes THE WHOLE QUERY to make it valid - including the `%` signs
+ * of anything already encoded. `search[title]=Caf%C3%A9` comes back out as
+ * `search%5Btitle%5D=Caf%25C3%25A9`, and the server dutifully searches for the
+ * literal text `Caf%C3%A9`, which matches nothing. The failure is a silent
+ * empty list on one platform, which is the most expensive kind to find.
+ *
+ * `encodeURIComponent` handles this by encoding brackets already; the point of
+ * writing it down is that nothing here may "simplify" the encoder into
+ * `encodeURI`, a template literal, or a hand-built `key[sub]=value`, all of
+ * which emit raw brackets. `test/react-native.test.ts` pins it.
+ *
+ * @throws {TypeError} for an invalid `Date`. `toISOString()` would throw a bare
+ *   `RangeError` from deep inside the transport; failing loudly at the boundary
+ *   beats sending `Invalid Date` and getting an unfiltered page back.
  */
 export declare function encodeQuery(params: QueryParams): string;
+/**
+ * Methods whose replay cannot duplicate work, so a lost answer may simply be
+ * 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.
+ */
+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"`).
- * Page size is clamped to the server maximum so a caller cannot silently ask
- * for more and get 500 back without knowing.
+ *
+ * Both halves go through `resolvePageSize` / `resolvePageNumber`, which is the
+ * same pair `createPage` uses. That is the point: the size on the wire and the
+ * size `Paginated.pageSize` reports have to be one number, or a caller who asks
+ * for 1200 gets the server's 500 rows measured against their own 1200 and is
+ * 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.
  */
 export declare function pageModifier(page?: number, pageSize?: number): string;
-/** Turns a {@link FormFields} bag into a `FormData`, buffering any streams. */
+/**
+ * Turns a {@link FormFields} bag into a `FormData`, buffering any streams.
+ *
+ * `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
+ * add a step that changes nothing. In a query the absent key means "no filter",
+ * which is a different answer entirely.
+ *
+ * The one thing this cannot express is clearing a column through a multipart
+ * UPDATE, where absent means "leave it alone". No endpoint takes one - the SDK
+ * sends multipart to the tools and to `POST /books` only - and if one appears,
+ * pass {@link NULL_SENTINEL} as the field value explicitly.
+ *
+ * ## React Native files
+ *
+ * A {@link NativeFile} - the `{ uri, name, type }` a picker returns - is
+ * appended VERBATIM, as the object it is. That is the whole trick: RN's
+ * `FormData` keeps the value untouched and its `getParts()` turns an entry with
+ * a `uri` into a file part that the native layer streams off disk. Converting
+ * it to anything first is what breaks it.
+ *
+ * On a runtime whose `FormData` is the web one, the same object would be
+ * coerced to the string `"[object Object]"` and uploaded as a text field: a
+ * 200, a stored record, and no file. So it throws there instead
+ * ({@link supportsNativeFormDataFiles}), and for the same reason any other
+ * unrecognised object throws rather than being stringified - a descriptor that
+ * lost its `name` in transit is a typo, not a form value.
+ */
 export declare function buildFormData(fields: FormFields): Promise<FormData>;
-/** Narrows an unknown form value to a {@link FileInput}. */
+/**
+ * Narrows an unknown form value to a {@link FileInput}.
+ *
+ * A {@link NativeFile} in `data` counts: it is a legitimate `FileInput` on RN,
+ * it just cannot be turned into bytes. Callers that need bytes should test with
+ * `isNativeFile(input.data)` rather than trusting this, or let
+ * `readFileInput` throw the message that explains the way out.
+ */
 export declare function isFileInput(value: unknown): value is FileInput;
 /** Fills in whatever a partial {@link RetryOptions} left out. */
 export declare function resolveRetry(options: RetryOptions | undefined): ResolvedRetry;
@@ -193,6 +607,17 @@ export declare function backoffDelay(attempt: number, retry: ResolvedRetry): num
  * `setTimeout`, which a Worker isolate provides.
  */
 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.
+ *
+ * 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
+ * weights are paged in before anything is generated) while still being shorter
+ * than a user's patience. The proxy usually drops a silent stream first; this
+ * is the backstop for when nothing else closes the connection.
+ */
+export declare const DEFAULT_STREAM_SILENCE_MS = 45000;
 /**
  * Combines a deadline with the caller's signal into one signal.
  *

package/dist/types/index.d.ts

@@ -14,7 +14,10 @@
  * 1. It runs in a Cloudflare-Worker-class isolate. No `node:*`, no `process`,
  *    no filesystem, no stdout. `fetch` is injectable through the constructor.
  * 2. Files are values - `Blob`, `Uint8Array`, `ReadableStream` - never paths.
- *    Turning a path into bytes is the host's job.
+ *    Turning a path into bytes is the host's job. React Native is the single
+ *    exception, and only on multipart endpoints: a picked `{ uri, name, type }`
+ *    (`NativeFile`) goes to the wire verbatim because RN's `FormData` streams
+ *    it off disk and a `Blob` there uploads truncated.
  * 3. The TYPES are the public interface. In code mode a model reads the `.d.ts`
  *    and nothing else, so a name or a JSDoc line carries as much weight as the
  *    behaviour behind it.
@@ -26,6 +29,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";