wontopos 2.2.40 → 2.2.42

package/dist/cjs/wontopos.d.cts

@@ -26,10 +26,11 @@
  * and searching call no LLM.
  *
  * Reliability: every call retries transient failures with exponential backoff +
- * jitter, honoring `Retry-After` — 429 always; 408/502/503/504 and connection errors
- * only when a retry can never double-process a write (idempotent calls, or a failure
- * at connect time). Tune with `maxRetries` (0 disables) and `timeoutMs`, or per
- * call site via the `withTimeout()` / `withRetries()` clones.
+ * jitter, honoring `Retry-After` up to 30s — 429 and a 409 that says another write
+ * to the store was in flight, always; 408/502/503/504 and connection errors only when
+ * a retry can never double-process a write (idempotent calls, or a failure at connect
+ * time). Tune with `maxRetries` (0 disables) and `timeoutMs`, or per call site via
+ * the `withTimeout()` / `withRetries()` clones.
  *
  * Debugging: set `WONTOPOS_LOG=debug` to log method/path/status/timing/retries
  * to stderr — never memory content, request bodies, or the API key.
@@ -40,7 +41,7 @@
  * runtime's (never disabled by this SDK; Node 18+ floors TLS at 1.2). Prefer
  * `Client.fromEnv()` over keys in source code.
  */
-/** Test hook — the warn-once set is process-global by design. */
+/** @deprecated Test hook. The warn-once set is process-global by design. */
 export declare function _resetStoreIdWarnings(): void;
 export declare const SEARCH_LIMIT_MIN = 5;
 export declare const SEARCH_LIMIT_MAX = 20;
@@ -53,16 +54,36 @@ export interface RateLimit {
     remaining: number | null;
     reset: number | null;
 }
+/** What a `WosError` carries beyond its status, message and request id. */
+export interface WosErrorInit {
+    /** `error.type` from the service's answer. */
+    type?: string;
+    /** The rest of the service's error object. */
+    details?: Record<string, unknown>;
+    /** `Retry-After`, in seconds (read by `RateLimitError`). */
+    retryAfter?: number;
+    /** The underlying error, kept as the standard `cause`. */
+    cause?: unknown;
+}
 export declare class WosError extends Error {
     readonly status: number;
     /** The server's id for the request when it sent one — include it when contacting support. */
     readonly requestId?: string;
-    constructor(status: number, message: string, requestId?: string);
+    /** `error.type` from the service's answer (e.g. `"conflict_error"`), when it sent one.
+     *  Control characters are removed and it is capped, like the message. */
+    readonly type?: string;
+    /** Every other field of the service's error object — all but `message`, `type` and
+     *  `request_id` — when there is any. Control characters are removed from its keys
+     *  and strings, each string is capped, and when its JSON is over 8192 characters the
+     *  biggest fields are left out. A 501 carries `model` and `endpoint` here. */
+    readonly details?: Record<string, unknown>;
+    constructor(status: number, message: string, requestId?: string, init?: WosErrorInit);
 }
 /** The request never got a response (DNS/TLS/timeout/connection). `status` is 0. */
 export declare class APIConnectionError extends WosError {
 }
-/** 400 — the request was malformed (bad arguments). */
+/** 400 — the request was malformed (bad arguments). 413 (body too large) and 422
+ *  (an idempotency key reused with a different body) arrive as this class too. */
 export declare class BadRequestError extends WosError {
 }
 /** 401 — the API key is missing, wrong, or revoked. */
@@ -77,12 +98,20 @@ export declare class PermissionDeniedError extends WosError {
 /** 404 — the store or resource doesn't exist. */
 export declare class NotFoundError extends WosError {
 }
-/** 409 — another write to this store was in flight (nothing was stored; retry), or the
- *  store id collides with an existing store's (permanent). */
+/** 409: another write to this store was in flight (retried automatically; nothing was
+ *  stored), or the store id collides with an existing one (not retried). */
 export declare class ConflictError extends WosError {
+    /** The existing store id this one collides with. Set only on a collision, which
+     *  retrying cannot fix. */
+    readonly conflictsWith?: string;
+    constructor(status: number, message: string, requestId?: string, init?: WosErrorInit);
 }
-/** 429 — too many requests. Back off and retry (the client already retries these). */
+/** 429 — too many requests. Back off and retry (the client already retries these,
+ *  unless `Retry-After` asks for more than 30 seconds). */
 export declare class RateLimitError extends WosError {
+    /** Seconds the service asked to wait (`Retry-After`), when it said. */
+    readonly retryAfter?: number;
+    constructor(status: number, message: string, requestId?: string, init?: WosErrorInit);
 }
 /**
  * 5xx — the service failed.
@@ -90,11 +119,9 @@ export declare class RateLimitError extends WosError {
  * `502` / `503` / `504` are transient: the client already retries them for calls
  * where a retry cannot double-process a write, and retrying yourself is reasonable.
  *
- * `501` is NOT transient. It means the engine behind the model you selected does
- * not implement that endpoint at all (the error carries `model` and `endpoint`).
- * Retrying can never succeed — pick a model that supports it (`listModels`) or
- * drop the call. Treating the whole 5xx range as retryable sends a caller into a
- * loop that cannot end.
+ * `501` is NOT transient. It means the model you selected does not implement that
+ * endpoint at all (`details` carries `model` and `endpoint`). Retrying can never
+ * succeed — pick a model that supports it (`listModels`) or drop the call.
  */
 export declare class ServerError extends WosError {
 }
@@ -140,8 +167,7 @@ export interface StoreResult {
      * A genuinely new fact that only varies a detail of one already stored ("no meetings
      * before 10am" next to "no meetings on Fridays") can land here too, so a duplicate is
      * not always a harmless no-op: read this id, and either store one sentence that states
-     * both or `update()` the existing memory with the combined statement. Without it a
-     * dropped write gave the caller nothing to act on.
+     * both or `update()` the existing memory with the combined statement.
      */
     duplicate_of?: string;
     /** Present when the store was a duplicate and something (e.g. a speaker tag) was dropped. */
@@ -160,7 +186,8 @@ export interface StatusResult {
 /**
  * An image attached to a memory, passed to `add`/`store` via `opts.image`.
  *
- * Both edges must be 700px or more; a smaller image is refused (400).
+ * Both edges must be 700px or more; a smaller image is refused (400). A request
+ * body is capped at 10MB.
  *
  * What the service keeps is NOT your original. An image whose long edge is over
  * 1568px is downscaled to 1568 before anything else happens, and that smaller
@@ -176,18 +203,23 @@ export interface StatusResult {
  * already fits within 1568px, and a re-encode that would make the file BIGGER is
  * thrown away and your bytes kept as they were.
  *
- * Keep your own copy if you need the full-resolution file. Either archive it
- * yourself, or put its URL in `reference` — we store that string and never open it.
+ * Keep your own copy if you need the full-resolution file.
  *
  * You are billed for the picture we keep, so downscaling never costs you more.
  */
 export interface ImageInput {
     /** base64 of the image. A `data:image/...;base64,` prefix is accepted and stripped. */
     data: string;
-    /** Where YOUR copy of the original lives. Stored as-is; the service never fetches it. */
+    /**
+     * Where YOUR copy of the image lives. Stored as-is; the service never fetches it.
+     *
+     * When you send one, the service keeps no image bytes: `getImage` answers 404 for
+     * this memory, and you fetch the picture from your own reference.
+     */
     reference?: string;
     /**
-     * When the image was TAKEN (RFC3339), if you know it — usually from EXIF.
+     * When the image was TAKEN, if you know it — usually from EXIF. RFC3339 or a plain
+     * date (`YYYY-MM-DD`); anything else is refused (400) naming the field.
      *
      * Worth passing: an image knows a moment that its caption does not. This fills
      * `metadata.event_date` when that is empty, so "the day we moved" sorts by when it
@@ -214,12 +246,8 @@ export interface ImageDeleteResult {
     status?: string;
     memory_id?: string;
     /**
-     * Whether the MEMORY survives losing its image.
-     *
-     * A captioned image keeps its text and only loses the image. An image stored with no
-     * caption IS the memory, so deleting the image deletes the memory — and the service
-     * says so here rather than silently taking more than you asked for. Call with
-     * `preview: true` first if that distinction matters to you.
+     * Whether the MEMORY survives losing its image. `false` means the delete removed
+     * the whole memory; call with `preview: true` first to find out before it happens.
      */
     memory_kept?: boolean;
     /** Plain-language note about the above, when there is something to say. */
@@ -245,7 +273,7 @@ export interface RevisionsResult {
     revised?: number;
     /** Memories nothing has touched since they were written. Always `total - revised`. */
     unrevised?: number;
-    /** Every memory in the store. Internal records nobody stored directly are not counted. */
+    /** The memories you stored. */
     total?: number;
     /** What `revised` counts, spelled out by the service. */
     counts?: string;
@@ -398,7 +426,9 @@ export interface StatsResult {
 export interface MemoryPage {
     memories: Memory[];
     count: number;
-    /** Pass back as `cursor` for the next page; `null` on the last page. */
+    /** Pass back as `cursor` for the next page; `null` means there is none. It can be
+     *  non-null on the last page, and the next call then returns an empty page. Pass
+     *  back only a cursor the service returned. */
     next_cursor: string | null;
     [key: string]: unknown;
 }
@@ -409,12 +439,31 @@ export interface SelfSearchResult {
     /** The assistant's own words (stored with speaker "me"); `[]` on non-self models. */
     self_memories: Memory[];
 }
+/** What a model can do, as `listModels()` reports it. A model without a feature
+ *  refuses the call that needs it (usually 403) or answers without that part. */
+export interface ModelCapabilities {
+    /** Image memories: `opts.image` on `add`, `max_images`, `getImage`, `listImages`. */
+    images?: boolean;
+    /** `engram()`; `listEngrams()` names the ones this model runs. */
+    engrams?: boolean;
+    /** Delivery forms (`form` / `tz`) on search, recall and engram. */
+    forms?: boolean;
+    /** Re-ask passes (`verify`) on search. */
+    re_ask?: boolean;
+    /** The assistant's own words apart, in `self_memories`. */
+    self_memories?: boolean;
+    /** Speaker names, as the service reports them. */
+    speaker_names?: boolean;
+    [key: string]: boolean | undefined;
+}
 export interface ModelInfo {
     id: string;
     name: string;
     available: boolean;
     /** "shared" — reads the common memory pool; "isolated" — its own dedicated store. */
     memory: "shared" | "isolated";
+    /** What this model can do. Check it before relying on a feature. */
+    capabilities?: ModelCapabilities;
 }
 /** One entry of the engram / delivery-form catalogue (`listEngrams`). */
 export interface EngramInfo {
@@ -480,21 +529,29 @@ export interface SpeakersList {
  * Retrieval behaves the same in every language, so these behave
  * identically in every language. Unlisted keys are dropped by the API rather than
  * rejected, so a typo silently widens the search — spell them exactly.
+ *
+ * Filters apply to `memories`. The assistant's own words (`self_memories`) are not
+ * filtered, and `search` merges them into its answer, so read `searchFull` when a
+ * filtered answer must hold only what matched.
+ *
+ * Every date takes RFC3339 or a plain date (`YYYY-MM-DD`). A plain end date
+ * (`time_to`, `event_to`) covers that whole day in UTC. A value that is not a date
+ * is refused (400) naming the field.
  */
 export interface SearchFilters {
     /** Only these categories (the `category` you see on `listMemories` results). */
     categories?: string[];
-    /** Ingestion-time window, as the API stores it. Plain strings, matched as given. */
+    /** When the memory was stored. */
     time_from?: string;
     time_to?: string;
     /** WHEN THE CONTENT HAPPENED (`metadata.event_date`), not when it was written —
-     *  this is the one you usually want. RFC3339, or a plain `YYYY-MM-DD`. */
+     *  this is the one you usually want. */
     event_from?: string;
     event_to?: string;
     /** Drop matches the engine scored below this importance (0–1). */
     min_importance?: number;
 }
-/** Test hook — the warn-once set is process-global by design. */
+/** @deprecated Test hook. The warn-once set is process-global by design. */
 export declare function _resetFilterWarnings(): void;
 /** Known `search` options. An unknown key is refused before anything is sent — the
  *  service drops keys it does not recognise and answers normally, so a misspelling
@@ -523,23 +580,22 @@ export interface SearchOptions {
      * that need several distinct memories from far apart in the history; it does little
      * on a single-fact lookup.
      *
-     * Requires a re-ask-capable model. Older ones REFUSE the call (403) rather than
-     * quietly charging you for passes that never happened.
+     * Requires a model that lists `re_ask` in its `listModels()` capabilities; any
+     * other refuses the call (403) rather than charging for passes that never happened.
      */
     verify?: number;
     /**
      * How many image memories the answer may carry, 0–5. Omit it and the service uses
-     * 1; `0` asks for none. The MCP server defaults its own tool to 0 instead, so most
-     * searches through it carry no image rows.
-     * Out of range is refused, not clamped — silently cutting 5 to 1 would leave you
-     * believing you got five.
+     * 1; `0` asks for none. Out of range is refused before the request, not clamped —
+     * silently cutting 6 to 5 would leave you believing you got six.
      *
-     * Requires an image-capable model, and is refused (403) on one without it rather
-     * than answering with no images.
+     * Requires a model that lists `images` in its capabilities, and is refused (403)
+     * on one without it rather than answering with no images.
      */
     max_images?: number;
-    /** Delivery form, "memoir" or "archive" (Scroll 1.2+): how each memory's time is
-     *  rendered. The service refuses an unknown one (400). */
+    /** Delivery form, "memoir" or "archive": how each memory's time is rendered. Needs a
+     *  model that lists `forms` in its capabilities. The service refuses an unknown
+     *  form (400). */
     form?: string;
     /** Your UTC offset in hours, for rendering times in `form`. */
     tz?: number;
@@ -554,69 +610,128 @@ export interface SearchOptions {
  * Per-call options for a write.
  *
  * `idempotencyKey` makes repeating THIS EXACT write safe: the API replays the first
- * response instead of storing again, for 10 minutes, and answers 422 if the same key
- * arrives with a different body. Use it when a retry is your own (a job that died and
- * was re-run, a queue that redelivers). The SDK retries a write on exactly one
- * status: 429, which the service answers before it processes anything, so nothing
- * was stored. It never retries a write on 408 / 502 / 503 / 504 or a dropped body,
- * where the first attempt may already have landed — without a key the client cannot
- * know whether it did.
+ * response instead of storing again, for up to 10 minutes, and answers 422 if the
+ * same key arrives with a different body. Use it when a retry is your own (a job that
+ * died and was re-run, a queue that redelivers). The SDK retries a write on 429, and
+ * on a 409 that says another write to the store was in flight: the service answers
+ * both before it processes anything, so nothing was stored. It never retries a write
+ * on 408 / 502 / 503 / 504 or a dropped body, where the write may already have been
+ * applied — without a key the client cannot know whether it was.
+ *
+ * The key covers a retry sent after the first attempt finished. A retry that overlaps
+ * a first attempt still running can run twice, so wait for the first to fail before
+ * re-sending.
  *
  * The key must be UNIQUE PER LOGICAL WRITE — derive it from the thing being stored
  * (`` `import:${row.id}` ``), never a constant, or the second write replays the first
  * and is silently lost. Format: 1-128 chars of `[A-Za-z0-9._:-]`, checked locally.
  *
- * The window is in-memory on the API, so a deploy or restart clears it early. It is a
- * guard against a retry storm, not a durable ledger.
+ * The window is best-effort and can be shorter than 10 minutes; it is not a durable
+ * de-duplication record.
  */
 export interface WriteOptions {
     idempotencyKey?: string;
     /**
-     * An image to store alongside the text (Tablet 2 and newer).
+     * An image to store alongside the text. Needs a model that lists `images` in its
+     * `listModels()` capabilities; any other refuses the write rather than store the
+     * caption and quietly drop the image.
      *
-     * `content` may be empty when you pass one — then the image IS the memory and is
-     * searchable on its own. Older models have no image channel and will reject the
-     * write rather than store the caption and quietly drop the image.
+     * A caption is required: the service refuses empty `content` (400) even with an
+     * image attached.
      */
     image?: ImageInput;
 }
+/** The part of an `AbortSignal` the client uses, for a runtime that declares none. */
+export interface AbortSignalShape {
+    readonly aborted: boolean;
+    addEventListener(type: "abort", listener: () => void): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+}
+/** The runtime's own `AbortSignal` type when it declares one (the DOM lib,
+ *  `@types/node`), otherwise {@link AbortSignalShape}. `AbortController#signal` fits. */
+export type AbortSignalLike = typeof globalThis extends {
+    AbortSignal: {
+        prototype: infer S;
+    };
+} ? S : AbortSignalShape;
+/** The `init` the client passes to `fetch`. */
+export interface FetchInitLike {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal: AbortSignalLike;
+    redirect: "manual";
+}
+/** The part of a `fetch` response the client reads. */
+export interface FetchResponseLike {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly type?: string;
+    readonly url?: string;
+    readonly redirected?: boolean;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    readonly body?: {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+            cancel(reason?: unknown): Promise<void>;
+        };
+        cancel(reason?: unknown): Promise<void>;
+    } | null;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/** The runtime's own `fetch` type when it declares one (the DOM lib, `@types/node`),
+ *  otherwise a structural signature, so these types need neither. */
+export type FetchLike = typeof globalThis extends {
+    fetch: infer F;
+} ? F : (url: string, init: FetchInitLike) => Promise<FetchResponseLike>;
 export interface ClientOptions {
     apiKey: string;
-    /** API base URL (defaults to the hosted service). */
+    /** API base URL (defaults to the hosted service): an http or https URL or, where
+     *  the runtime has a page, a URL relative to it. Whitespace at either end is
+     *  trimmed; whitespace, a control character or a backslash left in it after that is
+     *  refused.
+     *  A relative URL where the runtime has no page (server-side rendering) fails the
+     *  first call that uses it, or goes to `fetch` as given when you pass one. */
     baseUrl?: string;
-    /** Per-request timeout in ms, applied to each retry attempt (default 30000). */
+    /** Per-request timeout in ms, applied to each retry attempt (default 30000). A
+     *  value that is not a positive number means the default; values above 2147483647
+     *  are clamped to it. */
     timeoutMs?: number;
     /** Default model for every call (sent as `X-WOS-Model`). See `listModels()`. */
     model?: string;
-    /** Default store for every call. Override per call by passing `userId`. Defaults
-     * to the account's built-in `default` store. */
+    /** Default store for every call. Override per call by passing `userId`. Leave it
+     * out to use the account's built-in `default` store; passing it as `undefined` is
+     * refused, because that is usually a lookup that found nothing. */
     userId?: string;
-    /** How many times to retry transient failures before throwing — 429 always;
-     * 408/502/503/504 and connection errors only when a retry can never
-     * double-process a write. 0 disables retries (default 2). */
+    /** How many times to retry transient failures before throwing — 429 and a 409
+     * that says another write was in flight, always; 408/502/503/504 and connection
+     * errors only when a retry can never double-process a write. 0 disables retries
+     * (default 2). */
     maxRetries?: number;
-    /** Alias of `maxRetries`. The Python SDK calls this option `retries`, and these
-     *  SDKs are published in lockstep as "the same surface" — so code ported between
-     *  them silently lost its retry setting instead of failing loudly (an unknown
-     *  key on an options object is not an error in TS at runtime). Both names work;
-     *  `maxRetries` wins if somehow both are given. */
+    /** Alias of `maxRetries`. `maxRetries` wins when both are given. */
     retries?: number;
     /** A total budget for one call, in ms, across every attempt.
      *
      *  `timeoutMs` bounds ONE attempt. At the defaults — 30s, two retries — a single
      *  call can hold a connection for 30s + backoff + 30s + backoff + 30s, over a
-     *  minute, and a server handler awaiting it has no way to say "I only have five
-     *  seconds". This is that way. Unset means no overall budget. */
+     *  minute. Unset means no overall budget. A retry whose wait does not fit in what
+     *  is left is not made: the call fails with the error of the last response. A
+     *  value that is not a positive number means no budget; values above 2147483647
+     *  are clamped to it. */
     deadlineMs?: number;
     /** The caller's `AbortSignal` — cancel work already in flight.
      *
      *  The SDK aborts on its own timeout; this is the seam for the caller's reason.
-     *  When someone closes the chat window, the recall that window asked for should
-     *  end, and the backoff sleep waiting to retry it should end too, instead of
-     *  running to completion and billing for an answer nobody will read.
+     *  When someone closes the chat window, the recall that window asked for ends, and
+     *  so does a backoff sleep waiting to retry it.
      *
      *  Per call, clone: `mem.withSignal(ctrl.signal).recall(...)`. */
-    signal?: AbortSignal;
+    signal?: AbortSignalLike;
     /** The `fetch` used for every request (default: the global `fetch`).
      *
      *  This is the seam for anything the runtime cannot express through options.
@@ -633,8 +748,12 @@ export interface ClientOptions {
      *
      *  It is also how you add instrumentation or drive the client in a test without
      *  a network. Retries, timeouts, redirect refusal and the size cap all still
-     *  apply — this replaces the transport, not the client's rules. */
-    fetch?: typeof fetch;
+     *  apply — this replaces the transport, not the client's rules. Pass
+     *  `init.redirect` through unchanged: a fetch that follows a redirect sends the
+     *  key to wherever it points, and an answer it reports as redirected
+     *  (`res.redirected`) is refused. A fetch that sends the request to another URL
+     *  on purpose, such as a proxy that rewrites it, is fine. */
+    fetch?: FetchLike;
 }
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export declare class Client {
@@ -649,6 +768,13 @@ export declare class Client {
     /** Transport. Held as a field (not read off `globalThis` per call) so a caller
      * who passes one gets it for every request, including from cloned clients. */
     private readonly fetchImpl;
+    /** Whether `baseUrl` carries userinfo, which network errors must not show. */
+    private readonly userinfo;
+    /** Whether `baseUrl` did not resolve to a URL at construction: a relative one where
+     *  the runtime had no page. */
+    private readonly pageRelative;
+    /** Whether the caller supplied `fetch`. */
+    private readonly customFetch;
     /** The store every call uses unless one passes `userId`. */
     private readonly defaultUser;
     private _rateLimit;
@@ -660,7 +786,7 @@ export declare class Client {
     /** A client whose key comes from `WONTOPOS_API_KEY` (or `WOS_API_KEY`) — keeps
      * keys out of source code. Node/Bun/Deno-with-env only. */
     static fromEnv(opts?: Omit<ClientOptions, "apiKey">): Client;
-    /** Never expose the key: `JSON.stringify(client)` gets the redacted view. */
+    /** Never expose the key or a URL password: `JSON.stringify(client)` gets the redacted view. */
     toJSON(): Record<string, string>;
     /** Resolve a call's store: the explicit userId, else the client default. */
     private uid;
@@ -680,7 +806,7 @@ export declare class Client {
      *     const r = await mem.withSignal(ctrl.signal).recall(q, user);
      *
      * Aborting ends the request in flight AND any backoff sleep waiting to retry it. */
-    withSignal(signal: AbortSignal): Client;
+    withSignal(signal: AbortSignalLike): Client;
     /** A client with a total budget per call, across every retry (everything else
      * kept). `mem.withDeadline(5_000).search(q)` inside a handler that has five
      * seconds. */
@@ -690,19 +816,23 @@ export declare class Client {
     withTimeout(timeoutMs: number): Client;
     /** A client with a different retry budget (everything else kept). 0 disables retries. */
     withRetries(maxRetries: number): Client;
-    /** Store one memory. `metadata` optional — e.g. `{ event_date: "2026-03-01" }` for when the
-     * content actually happened. A plain date works (read as UTC midnight); a full RFC3339
-     * timestamp also works; older examples here show the long form.
-     * `metadata.speaker`: "me" = the assistant's own words, or a person's name (up to 50 per store).
+    /** Store one memory. `metadata` optional — the service keeps only these keys and
+     * drops any other (this client warns once per unknown key):
+     * - `event_date`: when the content actually happened, RFC3339 or a plain date
+     *   (`YYYY-MM-DD`, read as UTC midnight); anything else is refused (400) naming the field.
+     * - `speaker`: "me" = the assistant's own words, or a person's name (up to 50 per store).
+     * - `category`, `conversation_id`.
      *
      * `opts.idempotencyKey`: see {@link WriteOptions} — pass one to make YOUR retry
      * of this exact write safe to repeat. */
     add(content: string, userId?: string, metadata?: Record<string, unknown>, opts?: WriteOptions): Promise<StoreResult>;
-    /** Alias of `add` — store one memory. Same surface as the Python SDK's `store`. */
+    /** Alias of `add` — store one memory. */
     store(content: string, userId?: string, metadata?: Record<string, unknown>, opts?: WriteOptions): Promise<StoreResult>;
     /** Store a conversation turn (user + assistant). Payload first, userId last — same shape as add/search. */
     addTurn(userMsg: string, assistantMsg: string, userId?: string, opts?: WriteOptions): Promise<StatusResult>;
     /** Bulk-ingest a large blob of text in one call. For backfilling.
+     *  `timestamp` must be RFC3339 (`2026-05-02T09:00:00Z`): a plain date or any other
+     *  string is ignored, and the memory is filed at upload time.
      *  The call most worth an `opts.idempotencyKey`: a backfill that dies halfway and is
      *  re-run would otherwise ingest the whole blob a second time. */
     addBulk(content: string, userId?: string, category?: string, timestamp?: string, opts?: WriteOptions): Promise<StatusResult>;
@@ -711,22 +841,25 @@ export declare class Client {
     /** Search a store's memories. Returns them most relevant first.
      *
      *  `limit` is 5-20, and out of range is refused rather than clamped: asking for 50
-     *  and silently receiving 20 reads as "that is all there is". The default is 10, so
-     *  a call that passes no count is unaffected. Before 2.2.35 the count was sent on
-     *  unchecked.
+     *  and silently receiving 20 reads as "that is all there is". The default is 10.
+     *
+     *  `limit` bounds `memories`, not the returned array. The assistant's own words (on
+     *  a model that lists `self_memories` in its capabilities) and image memories (one
+     *  unless `max_images` says otherwise, on a model that lists `images`) come back in
+     *  it as well, so it can hold more than `limit`. They are billed either way. Size a
+     *  prompt window on the array you get back, not on `limit`. `searchFull()` hands the
+     *  fields back apart.
      *
-     *  `limit` bounds `memories`, not the returned array. The assistant's own words
-     *  (Scroll 1.2+) and image memories (Tablet 2+, one unless `max_images` says
-     *  otherwise) come back in it as well, so it can hold more than `limit`. They are
-     *  billed either way. Size a prompt window on the array you get back, not on
-     *  `limit`. `searchFull()` hands the fields back apart. */
+     *  `filters` apply to `memories` only; the assistant's own words merged in here are
+     *  not filtered. */
     search(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<Memory[]>;
-    /** Search a self-memory model (Scroll 1.2+): both fields from ONE call. Returns
-     * `{ memories, self_memories }` — `memories` is what others said and general
+    /** Search, with the assistant's own words kept apart: both fields from ONE call.
+     * Returns `{ memories, self_memories }` — `memories` is what others said and general
      * memories, `self_memories` is the assistant's OWN words (stored with speaker
      * "me"), kept apart so whoever reads them never confuses who said what. On a model
-     * that does not keep them apart, `self_memories` is `[]`. Image memories are not
-     * included; `search` and `searchFull` carry them. `userId` may be omitted. */
+     * that does not list `self_memories` in its capabilities, `self_memories` is `[]`.
+     * Image memories are not included; `search` and `searchFull` carry them. `filters`
+     * apply to `memories` only. `userId` may be omitted. */
     searchSelf(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SelfSearchResult>;
     /**
      * Search, and keep every field the answer came with.
@@ -739,13 +872,15 @@ export declare class Client {
      *     r.images.length;   // the photos, apart from the text memories
      *     r.verify_used;     // how many re-ask passes actually ran (you are billed per pass)
      *
-     * Both options need Tablet 2 or newer and are refused (403) on an older engine
-     * rather than accepted and ignored.
+     * Each option needs a model that lists it in its `listModels()` capabilities
+     * (`images`, `re_ask`) and is refused (403) on any other rather than accepted and
+     * ignored. `filters` apply to `memories`; `self_memories` are not filtered.
      */
     searchFull(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SearchResult>;
     /** One-call LLM context: short-term turns + long-term matches + surrounding context.
-     * `form` ("memoir"/"archive", Scroll 1.2+) renders each long-term memory's time in
-     * that form; `tz` is your UTC-offset hours for that rendering. */
+     * `form` ("memoir"/"archive", on a model that lists `forms` in its capabilities)
+     * renders each long-term memory's time in that form; `tz` is your UTC-offset hours
+     * for that rendering. */
     recall(query: string, userId?: string, opts?: {
         form?: string;
         tz?: number;
@@ -753,19 +888,19 @@ export declare class Client {
          * Long-term memories to recall, 5–20. Default 10. Out of range is refused, not
          * clamped — asking for 20 and silently getting 10 reads as "that is all there is".
          *
-         * Needs a limit-aware model. An older one recalls a fixed ten no matter what you
-         * send, so the API refuses the call (403) rather than answering with a number you
-         * did not ask for.
+         * A model that does not take a recall count refuses the call (403) rather than
+         * answering with a number you did not ask for.
          */
         limit?: number;
         /** How much surrounding context is attached around the best match, 0–20. Default 10;
-         *  0 attaches none. Same model floor as `limit`. */
+         *  0 attaches none. Refused (403) by the same models as `limit`. */
         context_limit?: number;
     }): Promise<RecallResult>;
     /** Run a built-in engram ("deep_recall" | "timeline" | "gather" | "equilibrium" |
      * "tone_stabilizer"; the service is the authority — an unknown name comes back with
      * the list it accepts). Returns the merged result.
-     * `form`/`tz` render memory times (memoir/archive) on Scroll 1.2+, same as search/recall. */
+     * `form`/`tz` render memory times (memoir/archive) on a model that lists `forms` in
+     * its capabilities, same as search/recall. */
     engram(name: string, query: string, userId?: string, opts?: {
         form?: string;
         tz?: number;
@@ -790,13 +925,17 @@ export declare class Client {
     usage(days?: number): Promise<UsageResult>;
     /** Fetch ONE memory by id — the text you stored, and its metadata.
      * The id is what `add`/`store` or `listMemories` returned. Same visibility as
-     * `listMemories`: an id from another store, an internal record id, or an
-     * invalidated memory rejects with `NotFoundError`. Pass `undefined` as `userId` for
-     * the default store — it is positional here, not omittable as it is in Python. */
+     * `listMemories`: an id from another store, an id `listMemories` does not return,
+     * or an invalidated memory rejects with `NotFoundError`. Pass `undefined` as
+     * `userId` for the default store — it is positional here. */
     get(userId: string | undefined, memoryId: string): Promise<Memory>;
     /** List a store's stored memories — the text you stored, plus its metadata.
      * Paginated: pass the returned `next_cursor` back as `cursor` for the next
-     * page; a `null` cursor means the last page. Use it to browse or export a store.
+     * page, and only a cursor the service returned. A `null` cursor means there is no
+     * next page; a non-null one can still be followed by an empty page. Use it to
+     * browse or export a store.
+     *
+     * `limit` is 1-500 (default 100); anything else is refused before the request.
      *
      *     let cursor: string | null = null;
      *     const all: Memory[] = [];
@@ -811,7 +950,11 @@ export declare class Client {
         cursor?: string;
     }): Promise<MemoryPage>;
     /** Async-iterate every stored memory in a store, paging under the hood — no cursor
-     * bookkeeping. The text you stored and its metadata only.
+     * bookkeeping. The text you stored and its metadata only. `pageSize` is 1-500.
+     *
+     * A walk that cannot reach the end of the store (the service hands back a cursor it
+     * already gave after a non-empty page, or the page ceiling is reached) throws rather
+     * than end with part of the store.
      *
      *     for await (const m of mem.iterMemories()) console.log(m.id, m.content);
      */
@@ -821,7 +964,7 @@ export declare class Client {
     /** Collect ALL of a store's memories into an array (the text you stored, and its metadata). */
     exportMemories(userId?: string): Promise<Memory[]>;
     /** Collect ALL of a store's image memories into an array — the image-side pair of
-     *  `exportMemories`. */
+     *  `exportMemories`. `pageSize` is 5-20. */
     exportImages(userId?: string, opts?: {
         pageSize?: number;
     }): Promise<Memory[]>;
@@ -837,9 +980,9 @@ export declare class Client {
      *
      * The type is sniffed from the bytes themselves rather than from whatever the file
      * was called, so name the file from `contentType` rather than from what you sent.
-     * When the format changed, the response also carries `x-wos-image-converted-from`
-     * naming what you uploaded. Rejects with `NotFoundError` when this memory has no
-     * image, or when the service keeps no image bytes at all — it says "no" instead of
+     * Rejects with `NotFoundError` when this memory has no image, or when the service
+     * keeps no image bytes for it — which is always the case for an image stored with
+     * `reference`: fetch that one from your own reference. It says "no" instead of
      * handing back something empty, so "a memory with no image" never looks the same as
      * "an image we lost".
      *
@@ -851,10 +994,9 @@ export declare class Client {
     /**
      * Remove the PHOTO from a memory, keeping its text.
      *
-     * Except when there is no text: an image stored without a caption *is* the memory, so
-     * deleting the image deletes it. That is the one case worth checking before you
-     * commit, which is what `preview` is for — it reports `memory_kept` and changes
-     * nothing.
+     * `preview: true` reports what would happen, including `memory_kept`, and changes
+     * nothing. Retried like `deleteStore`; without `preview`, a 404 after an ambiguous
+     * failure carries the same note.
      *
      *     const p = await mem.forgetImage(undefined, id, { preview: true });
      *     if (p.memory_kept === false) { /* this would delete the whole memory *\/ }
@@ -870,13 +1012,16 @@ export declare class Client {
      * `next_before` and `next_skip_ids` back as `before` / `skipIds`. The pair exists
      * because several images can share a timestamp, and a timestamp alone would either
      * repeat them or skip them.
+     *
+     * `limit` is 5-20; anything else is refused before the request.
      */
     listImages(userId?: string, opts?: {
         limit?: number;
         before?: string;
         skipIds?: string[];
     }): Promise<ImagePage>;
-    /** Async-iterate every image memory, paging under the hood. */
+    /** Async-iterate every image memory, paging under the hood. `pageSize` is 5-20.
+     *  Like `iterMemories`, a walk that cannot reach the end throws. */
     iterImages(userId?: string, opts?: {
         pageSize?: number;
     }): AsyncGenerator<Memory>;
@@ -889,9 +1034,8 @@ export declare class Client {
      * rewritten. Free, and it never reaches the retrieval path.
      *
      * Counts memories a transform touched (supersede, update, retract, image removed).
-     * Deletions are NOT counted: a deleted memory leaves nothing to count. Neither are
-     * the internal records derived from what you stored — nobody stored those directly,
-     * so they do not belong in a ratio that answers "how much of MY memory changed".
+     * Deletions are NOT counted: a deleted memory leaves nothing to count. `total`
+     * counts the memories you stored.
      *
      * By default this returns COUNTS ONLY, and the answer is the same size for a store
      * of a hundred memories and a store of a hundred million. That is deliberate: a model
@@ -917,10 +1061,8 @@ export declare class Client {
      * Pages are ordered by when each memory was STORED, not by when it was edited.
      * The response says so in `ordered_by`.
      *
-     * Served from `/api/v1/won/*`, not `/api/v1/memory/*`. Won is the surface for calls
-     * a model makes ABOUT its memory rather than calls an application makes WITH it, and
-     * the address says so. The old path still answers, for clients published before
-     * 2026-08-18, and both share one rate-limit budget.
+     * Served from `/api/v1/won/revisions`: `/api/v1/won/*` holds the calls a model makes
+     * ABOUT its memory rather than calls an application makes WITH it.
      */
     revisions(userId?: string, opts?: {
         /**
@@ -928,7 +1070,8 @@ export declare class Client {
          * number. One side per call — there is no way to ask for both lists at once.
          */
         include?: "revised" | "unrevised";
-        /** Memories per page. 20 is both the default and the ceiling; more is rejected. */
+        /** Memories per page, 5-20; 20 is the default. Anything else is refused before
+         *  the request. */
         limit?: number;
         /** Cursor: `next_before` from the previous page. */
         before?: string;
@@ -948,7 +1091,7 @@ export declare class Client {
      *
      * `speaker` is the tag written at store time (`metadata.speaker`) — `"me"` for the
      * assistant's own words, otherwise a person's name. Same cursor paging as
-     * `listImages`.
+     * `listImages`; `limit` is 5-20.
      *
      * `points_to_delete` is the count to show before anyone confirms a delete of this
      * speaker's memories.
@@ -969,9 +1112,9 @@ export declare class Client {
      *
      * Ask rather than hard-code: a name copied from the docs freezes a caller to the
      * catalogue as it was that day, and anything added later stays invisible. The
-     * service is the authority. What
-     * comes back depends on the model (delivery forms need Scroll 1.2+), so pass
-     * `withModel()` if you want another model's catalogue.
+     * service is the authority. What comes back depends on the model (`forms` is empty
+     * on one that does not list `forms` in its capabilities), so pass `withModel()` if
+     * you want another model's catalogue.
      *
      *   const { engrams, forms } = await mem.listEngrams();
      */
@@ -984,7 +1127,10 @@ export declare class Client {
     /** List your stores: `[{ user_id, created_at, canonical_id? }, ...]` (`default`
      *  first). Each `user_id` is the id the store was created with. */
     listStores(): Promise<StoreInfo[]>;
-    /** Delete a store and ALL its memories. Returns `{ user_id, status }`. */
+    /** Delete a store and ALL its memories. Returns `{ user_id, status }`.
+     *  A delete retried after an ambiguous failure (408/502/503/504 or a dropped
+     *  connection) that then answers 404 rejects with a `NotFoundError` saying an
+     *  earlier attempt may already have deleted it. */
     deleteStore(userId: string): Promise<StoreOpResult>;
     /** Register a person for this store. Speakers are explicit: register once, then
      * store with `{ speaker }`. `"me"` (the assistant itself) never needs
@@ -992,67 +1138,82 @@ export declare class Client {
     addSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** The store's registered people, each with its memory count. */
     listSpeakers(userId?: string): Promise<SpeakersList>;
-    /** Unregister a person. Their memories stay; the name tag goes. */
+    /** Unregister a person. Their memories stay; the name tag goes. Retried like
+     *  `deleteStore`, with the same note on a 404 after an ambiguous failure. */
     removeSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** Delete a single memory by id. Pass `undefined` as `userId` for the default
-     *  store — it is positional here, not omittable as it is in Python. */
+     *  store — it is positional here. */
     delete(userId: string | undefined, memoryId: string): Promise<StatusResult>;
     /** Delete ALL memories for a store (GDPR erase). `userId` is required on purpose -
      * this is destructive, so it never falls back to the default store. */
     deleteAll(userId: string): Promise<StatusResult>;
     private post;
-    /**
-     * One request that answers with BYTES rather than JSON.
-     *
-     * Only `/memory/image` does this, and it is why this cannot go through `request()`:
-     * that path reads the body as text and insists the result parses to a JSON object.
-     * Feeding it a JPEG would throw "invalid JSON in response" — a confusing error for a
-     * call that actually succeeded.
-     *
-     * Errors still arrive as JSON, so those are handed back to the normal machinery: on
-     * a non-2xx we re-read the body as text and reuse `errorFor`, which keeps 404
-     * (`NotFoundError`) and 401 behaving the same as everywhere else.
-     */
+    /** A DELETE that removes something: a 404 after an ambiguous failure says an earlier
+     *  attempt may already have removed it. */
+    private remove;
     /** Where this call's budget runs out, or `undefined` when it has none. Computed
      *  once per call, not per attempt — a budget recomputed each attempt is not a
      *  budget. */
     private deadlineAt;
     /** The abort wiring for ONE attempt: this SDK's per-attempt timeout, the caller's
      *  signal, and whatever is left of the overall deadline — whichever fires first.
-     *
-     *  One function, two callers (`request` and `requestBytes`), because a guard living
-     *  in one of two request paths is exactly how `getImage` ended up with no retry loop
-     *  while the module doc promised every call had one. */
+     *  With no time left it throws `answer` (the refusal that led here), or the
+     *  deadline error when there is none. */
     private beginAttempt;
     /** What to say when an attempt was cut short. The three reasons need different
      *  words: a timeout may have landed server-side, a cancellation certainly did not
      *  matter to the caller, and an exhausted budget is the caller's own setting. */
     private abortMessage;
-    /** Sleep between attempts — but wake the moment the caller aborts, and give up
-     *  rather than wait out a backoff the budget cannot cover. A backoff that runs to
-     *  completion after the caller gave up wastes exactly as long as the request it was
-     *  waiting to repeat.
+    /** Whether a wait of `ms` still leaves time before the deadline. */
+    private fits;
+    /** Sleep between attempts, waking the moment the caller aborts. */
+    private pause;
+    /** The error for a request that got no answer. The message names the cause code
+     *  (ECONNREFUSED, ENOTFOUND, CERT_HAS_EXPIRED, …) and never carries the query
+     *  string, which can hold a store id, or the base URL's userinfo. With either in
+     *  the URL the transport error is not kept as the cause, since its own message can
+     *  quote the URL. */
+    private networkError;
+    /** A redirect: a 3xx, or one a custom fetch followed. Where a custom fetch sent the
+     *  request (`res.url`) is its own business. */
+    private isRedirected;
+    /** The error an answer carries: the service's message (control characters removed,
+     *  capped), request id, `type` and the rest of its error object. `unread` says why
+     *  the body is missing, when it could not be read. */
+    private errorFromAnswer;
+    /**
+     * Send one call, retrying what can be retried, and return the answer with its body
+     * read (under the same timeout, so a body that trickles in cannot stall the call).
+     * The error body of an answer about to be retried gets at most a second.
+     *
+     * Retried: 429, and a 409 whose error carries `retry_after_ms` (another write to the
+     * store was in flight; nothing was stored), on every method; 408/502/503/504 and
+     * dropped connections on idempotent methods; connect failures on every method. A
+     * retry whose wait is over the cap, or does not fit the deadline, is not made: the
+     * call fails with the error of the response it has. So does a retry the deadline
+     * leaves no time to send, and the retry of an idempotent method or of a POST that
+     * only reads that the deadline cuts short. Any other retry cut short stays a status-0
+     * deadline error: a write may have been applied.
+     */
+    private send;
+    /**
+     * One request that answers with BYTES rather than JSON.
      *
-     *  Clamping the wait to what is left and retrying anyway is the same answer as
-     *  having no deadline at all: the call still spends the whole allowance, and the one
-     *  attempt it buys has nothing left to finish in. If the wait does not fit, the
-     *  budget is already decided. */
-    private backoffSleep;
+     * Only `/memory/image` does this: `request()` insists the body parses to a JSON
+     * object, and a JPEG would come back as "invalid JSON in response" for a call that
+     * succeeded. Retries, timeouts and errors are the same as every other call's.
+     */
     private requestBytes;
     /** Validate an idempotency key BEFORE the network. The API answers a malformed
      *  key with a 400, which on a retry path reads as "my write failed" when in fact
      *  it was never attempted — cheaper and clearer to reject it here. */
     private idemHeader;
-    /** Seconds→ms to sleep before retry `attempt` (0-based). Honors Retry-After. */
+    /** Milliseconds to sleep before retry `attempt` (0-based): exponential with jitter,
+     *  or what a valid `Retry-After` asks for. */
     private backoffMs;
     /** Read the body with a hard size cap, so a broken/hostile endpoint can't
-     * make the process buffer gigabytes. */
-    private readCapped;
-    /** The same cap, for a body that is not text.
-     *
-     * `arrayBuffer()` would buffer whatever arrives. The cap exists for a hostile or
-     * broken `baseUrl`, and an endpoint that returns megabytes is where that costs the
-     * most. One implementation, two callers, so they cannot drift. */
+     * make the process buffer gigabytes. With `withinMs`, a body still arriving after
+     * that long is dropped and the read fails. */
     private readCappedBytes;
     private request;
 }