wontopos 2.2.37 → 2.2.39

package/dist/cjs/wontopos.d.cts

@@ -0,0 +1,1054 @@
+/**
+ * Wontopos — long-term memory for AI, in three lines.
+ *
+ *   npm install wontopos
+ *
+ *   import { Client } from "wontopos";
+ *   const mem = new Client({ apiKey: "wos-...", userId: "alice" }); // set the store once
+ *   await mem.createStore();                              // create it (uses the client's userId)
+ *   await mem.add("she prefers tea over coffee");         // no userId needed
+ *   const hits = await mem.search("what does alice drink?");
+ *
+ * Set `userId` once on the client and every call uses it; override any single call
+ * by passing `userId` to it. Stores are explicit: the store must exist first
+ * (`createStore`) or calls return 404. Every account starts with a `default` store,
+ * so with no `userId` anywhere the zero-setup path just works.
+ *
+ * The API key picks *which memory* (your account); `model` picks *which engine*
+ * reads it. Models on the shared pool read the same memory, so you can store with
+ * one and recall with another; `listModels()` reports each model's `memory` as
+ * `"shared"` or `"isolated"`, and an isolated one starts empty. Set a default in
+ * the constructor, or override a single call with
+ * `mem.withModel("tablet-1").recall(...)`.
+ *
+ * Recall quality does not depend on which language a memory was written in: a
+ * memory stored in one language is found by a question asked in another. Storing
+ * 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.
+ *
+ * Debugging: set `WONTOPOS_LOG=debug` to log method/path/status/timing/retries
+ * to stderr — never memory content, request bodies, or the API key.
+ *
+ * Security posture (not configurable off): redirects are refused so the API key
+ * can never follow one to another host; responses over 64MB are refused; the key
+ * is masked in `toJSON`/inspect output. TLS certificate verification is the
+ * 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. */
+export declare function _resetStoreIdWarnings(): void;
+export declare const SEARCH_LIMIT_MIN = 5;
+export declare const SEARCH_LIMIT_MAX = 20;
+/** `recall`'s surrounding-context count. 0 to 20 inclusive; 0 attaches none. */
+export declare const CONTEXT_LIMIT_MIN = 0;
+export declare const CONTEXT_LIMIT_MAX = 20;
+/** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
+export interface RateLimit {
+    limit: number | null;
+    remaining: number | null;
+    reset: number | null;
+}
+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);
+}
+/** 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). */
+export declare class BadRequestError extends WosError {
+}
+/** 401 — the API key is missing, wrong, or revoked. */
+export declare class AuthenticationError extends WosError {
+}
+/** 402 — no card on file or the balance is depleted. Top up to continue. */
+export declare class PaymentRequiredError extends WosError {
+}
+/** 403 — the key/model isn't allowed to do this. */
+export declare class PermissionDeniedError extends WosError {
+}
+/** 404 — the store or resource doesn't exist (create the store first). */
+export declare class NotFoundError extends WosError {
+}
+/** 409 — a concurrent write to the same store. Retry. */
+export declare class ConflictError extends WosError {
+}
+/** 429 — too many requests. Back off and retry (the client already retries these). */
+export declare class RateLimitError extends WosError {
+}
+/**
+ * 5xx — the service failed.
+ *
+ * `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.
+ */
+export declare class ServerError extends WosError {
+}
+export interface Usage {
+    input_tokens?: number;
+    output_tokens?: number;
+    [key: string]: unknown;
+}
+export interface Memory {
+    id?: string;
+    content?: string;
+    /** Cognitive category, e.g. "general". */
+    category?: string;
+    /** Raw closeness to the query — higher is closer. NOT the ranking key: results already
+     *  arrive best-first, and what produces that order is internal and not returned, so
+     *  re-sorting by `similarity` overrides the ranking and makes results worse. Take the
+     *  list in the order given. There is no `score` field. */
+    similarity?: number;
+    /** Importance weight the service assigns to the memory. */
+    importance?: number;
+    /** Month bucket the memory belongs to (e.g. "2026-07"). Omitted when temporal fields are stripped. */
+    time_bucket?: string;
+    /** True if a later memory has superseded this one. */
+    is_superseded?: boolean;
+    /** Id of the memory that superseded this one, or null. */
+    superseded_by?: string | null;
+    /** When the memory was stored (RFC3339). Omitted when temporal fields are stripped. */
+    created_at?: string;
+    /** When the content actually happened (RFC3339), if known. */
+    event_date?: string;
+    /** WHO said it: "me" (the assistant) or a registered person's name. Absent = untagged. */
+    speaker?: string;
+    [key: string]: unknown;
+}
+/** `add` / `store` → `{ id, status }` (`status: "stored" | "stored (async)" | "duplicate"`). */
+export interface StoreResult {
+    id?: string;
+    /** `"stored"`, or `"duplicate"` when nothing was saved. */
+    status?: string;
+    /**
+     * Present when `status` is `"duplicate"`: the id of the memory this write collided with.
+     *
+     * 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.
+     */
+    duplicate_of?: string;
+    /** Present when the store was a duplicate and something (e.g. a speaker tag) was dropped. */
+    note?: string;
+    /** `true` when this response was REPLAYED from a previous request with the same
+     *  `idempotencyKey` — nothing new was stored. Absent on a fresh write. Read it to
+     *  tell "my retry landed" from "my retry was a no-op". */
+    replayed?: boolean;
+    [key: string]: unknown;
+}
+/** `addTurn` / `addBulk` / `delete` / `deleteAll` → `{ status }`. */
+export interface StatusResult {
+    status?: string;
+    [key: string]: unknown;
+}
+/**
+ * An image attached to a memory, passed to `add`/`store` via `opts.image`.
+ *
+ * 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
+ * picture is what gets stored, and handed back by `getImage`. Nothing on our side
+ * ever uses more than 1568, so the extra pixels would be bytes nobody reads. This
+ * is a memory
+ * service, not a photo host: the picture it holds has the resolution of a memory.
+ *
+ * It can also come back in a different FORMAT. Downscaling means re-encoding, and
+ * we write lossless formats as WebP — send a PNG or a GIF over 1568px and `getImage`
+ * hands back `image/webp`; JPEG stays JPEG. So do not name the file from the
+ * extension you uploaded: read `contentType`. Nothing is re-encoded when the image
+ * 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.
+ *
+ * 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. */
+    reference?: string;
+    /**
+     * When the image was TAKEN (RFC3339), if you know it — usually from EXIF.
+     *
+     * 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
+     * happened rather than by when it was uploaded.
+     */
+    taken_at?: string;
+}
+/** `getImage` → the picture the service holds, plus what it actually is. */
+export interface ImageBytes {
+    /**
+     * The image as stored. Write it to a file, or wrap it in a Blob to show it.
+     *
+     * This is the service's copy, not necessarily your upload: anything over 1568px
+     * on its long edge was downscaled on the way in, and re-encoded to WebP unless it
+     * was a JPEG (see `ImageInput`). Take the file extension from `contentType`.
+     */
+    bytes: Uint8Array;
+    /** Sniffed from the BYTES, not from whatever the upload was named — e.g. `image/jpeg`. */
+    contentType: string;
+}
+/** `forgetImage` → what happened, or (with `preview`) what would happen. */
+export interface ImageDeleteResult {
+    /** `"image_deleted"`, or `"preview"` when nothing was touched. */
+    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.
+     */
+    memory_kept?: boolean;
+    /** Plain-language note about the above, when there is something to say. */
+    note?: string | null;
+    /** Only on a preview. */
+    would_delete_image?: boolean;
+    [key: string]: unknown;
+}
+/** `listImages` → one page of image memories, newest first. */
+export interface ImagePage {
+    images: Memory[];
+    /** TOTAL images in the store, not the size of this page. */
+    count?: number;
+    has_more?: boolean;
+    /** Hand these two back as `before` / `skipIds` to get the next page. */
+    next_before?: string | null;
+    next_skip_ids?: string[];
+    [key: string]: unknown;
+}
+/** `revisions` → how much of this store has been edited since it was written. */
+export interface RevisionsResult {
+    /** Memories a transform has touched (supersede, update, retract, image removed). */
+    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. */
+    total?: number;
+    /** What `revised` counts, spelled out by the service. */
+    counts?: string;
+    /** What it does NOT count — deletions leave nothing to count. */
+    excludes?: string;
+    /** Which side was paged, echoed back. Only present when you asked for a page. */
+    include?: "revised" | "unrevised";
+    /** TOTAL memories behind this page, not the size of the page. Only with `include`. */
+    matched?: number;
+    /** One page, at most 20. **Absent unless you asked for it** — see `revisions()`. */
+    memories?: Memory[];
+    has_more?: boolean;
+    /** Hand these two back as `before` / `skipIds` to get the next page. */
+    next_before?: string | null;
+    next_skip_ids?: string[];
+    /** Which order the page is in — by when each memory was STORED, not when it was edited. */
+    ordered_by?: string;
+    [key: string]: unknown;
+}
+/** One link in a memory's supersede chain. */
+export interface LineageStep {
+    memory_id?: string;
+    content?: string;
+    speaker?: string | null;
+    created_at?: string | null;
+    /** When this link was superseded (RFC3339), or null while it is still current. */
+    changed_at?: string | null;
+    /** What happened here — e.g. how the replacement related to this version. */
+    action?: string | null;
+    confidence?: number | null;
+    superseded_by?: string | null;
+    /** True for the one version that is still in force. */
+    is_current?: boolean;
+    [key: string]: unknown;
+}
+/** `lineage` → the full chain of edits behind one memory, oldest first. */
+export interface LineageResult {
+    memory_id?: string;
+    chain: LineageStep[];
+    count?: number;
+    /** True when the chain was longer than the service would walk. */
+    truncated?: boolean;
+    [key: string]: unknown;
+}
+/** `bySpeaker` → one page of what a given person said. */
+export interface SpeakerPage {
+    speaker?: string;
+    memories: Memory[];
+    /** How many underlying records a delete would actually remove, beyond what was returned. */
+    chunks?: number;
+    points_to_delete?: number;
+    returned?: number;
+    has_more?: boolean;
+    next_before?: string | null;
+    next_skip_ids?: string[];
+    [key: string]: unknown;
+}
+/** `update` (supersede) → old and new memory ids. */
+export interface UpdateResult {
+    old_memory_id?: string;
+    new_memory_id?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+/** `searchFull` → everything one search answered with, not just the merged memories.
+ *
+ *  `search` returns the memories and nothing else, which is the right answer for
+ *  almost every call. Two options make it the wrong one: `max_images` asks for
+ *  photos, which arrive in their own field, and `verify` is reported on by
+ *  `verify_used`. Merging away both means paying for a
+ *  search you shaped and never seeing what came of it. */
+export interface SearchResult {
+    /** What others said, and general memories. */
+    memories: Memory[];
+    /** The assistant's own words (speaker "me"); `[]` on a model that does not keep
+     *  them apart. */
+    self_memories: Memory[];
+    /** Image memories, when `max_images` asked for any; `[]` otherwise. */
+    images: Memory[];
+    /** Re-ask passes actually performed. Present only when `verify` was sent; lower
+     *  than you asked for means the store had nothing further to add. */
+    verify_used?: number;
+    [key: string]: unknown;
+}
+export interface RecallResult {
+    short_term: {
+        turns: unknown[];
+        count: number;
+    };
+    long_term: {
+        memories: Memory[];
+        count: number;
+    };
+    context: {
+        around_top_memory: unknown[];
+        count: number;
+    };
+    [key: string]: unknown;
+}
+/** `engram` → the merged multi-hop result. */
+export interface EngramResult {
+    engram?: string;
+    form?: string;
+    user_id?: string;
+    hops?: number;
+    count?: number;
+    memories?: Memory[];
+    usage?: Usage;
+    [key: string]: unknown;
+}
+export interface HistoryTurn {
+    user_msg?: string;
+    assistant_msg?: string;
+    timestamp?: string;
+    [key: string]: unknown;
+}
+/** `usage` → what this key has spent, and what is left to spend. */
+export interface UsageResult {
+    window_days?: number;
+    /** This API key's LIFETIME spend. Never another key's. */
+    key?: {
+        requests?: number;
+        cost_cents?: number;
+        input_tokens?: number;
+        output_tokens?: number;
+        since?: string;
+    };
+    /** The workspace this key belongs to, over the window. */
+    workspace?: {
+        workspace_id?: string | null;
+        requests?: number;
+        cost_cents?: number;
+    };
+    /** Per-store spend over the window, busiest first, and at most 50 rows — a longer
+     *  list is cut, so these need not sum to `workspace`. `other`, when present, is an
+     *  overflow bucket rather than a store. */
+    stores?: {
+        store?: string;
+        requests?: number;
+        cost_cents?: number;
+    }[];
+    /** Prepaid balance left on the ACCOUNT. Negative means overdrawn. */
+    balance_cents?: number;
+    expiring_soon_cents?: number;
+    [key: string]: unknown;
+}
+export interface StatsResult {
+    total_memories?: number;
+    short_term_turns?: number;
+    [key: string]: unknown;
+}
+/** `listMemories` → one page of a store's raw memories (the text you stored, and its metadata). */
+export interface MemoryPage {
+    memories: Memory[];
+    count: number;
+    /** Pass back as `cursor` for the next page; `null` on the last page. */
+    next_cursor: string | null;
+    [key: string]: unknown;
+}
+/** `searchSelf` result: general memories and the assistant's own, kept apart. */
+export interface SelfSearchResult {
+    /** What others said, and general memories. */
+    memories: Memory[];
+    /** The assistant's own words (stored with speaker "me"); `[]` on non-self models. */
+    self_memories: Memory[];
+}
+export interface ModelInfo {
+    id: string;
+    name: string;
+    available: boolean;
+    /** "shared" — reads the common memory pool; "isolated" — its own dedicated store. */
+    memory: "shared" | "isolated";
+}
+/** One entry of the engram / delivery-form catalogue (`listEngrams`). */
+export interface EngramInfo {
+    name: string;
+    description: string;
+    [key: string]: unknown;
+}
+/** `listEngrams` → what the SELECTED model can run. `forms` is empty on models
+ *  without delivery forms; `note` explains an empty `engrams`. */
+export interface EngramCatalog {
+    engrams: EngramInfo[];
+    forms: EngramInfo[];
+    note?: string;
+    /** Anything else the reply carried. Responses widen; the runtime keeps those fields
+     *  and this is what lets a typed caller read them. */
+    [key: string]: unknown;
+}
+/** `createStore` / `deleteStore` → `{ user_id, status }`. */
+export interface StoreOpResult {
+    /** The store id the API actually used — NOT necessarily the one you sent.
+     *  Ids are normalized (see the `note`), so compare this against your input. */
+    user_id?: string;
+    status?: string;
+    /** Present when the API changed your id, explaining how. Read it: two of your
+     *  end users can land in one store if their ids differ only by punctuation. */
+    note?: string;
+    [key: string]: unknown;
+}
+export interface StoreInfo {
+    user_id: string;
+    created_at: string;
+    [key: string]: unknown;
+}
+/** `addSpeaker` / `removeSpeaker` → `{ user_id, speaker, status }`. */
+export interface SpeakerOpResult {
+    user_id?: string;
+    speaker?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+export interface SpeakerInfo {
+    speaker: string;
+    memories: number;
+    created_at?: string;
+    [key: string]: unknown;
+}
+/** `listSpeakers` → registered people with per-person memory counts. */
+export interface SpeakersList {
+    speakers: SpeakerInfo[];
+    count?: number;
+    /** The registration cap for this store (50 to start). */
+    limit?: number;
+    [key: string]: unknown;
+}
+/**
+ * Narrow a search to part of a store. The filter chooses what is searched, not what
+ * is kept afterwards — so a narrow filter still returns your full `limit` when that
+ * many matches sit inside it.
+ *
+ * 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.
+ */
+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. */
+    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`. */
+    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. */
+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
+ *  could not be told from an option that worked. Put a genuinely new one under
+ *  `extra`. */
+export interface SearchOptions {
+    /** Recall caching. A hit inside the TTL bills at 0.1× — but the FIRST call
+     *  writes the cache and bills the query tokens at 2× (`5m`) or 3× (`1h`), so
+     *  this only pays for a query you repeat or extend. Do not enable it globally. */
+    cache_control?: {
+        ttl: "5m" | "1h";
+    };
+    /** Recall only this person's words ("me" or a registered name). */
+    speaker?: string;
+    /** Restrict the search to part of the store — see {@link SearchFilters}. */
+    filters?: SearchFilters;
+    /**
+     * Re-ask passes, 0–3. After the first retrieval the service asks the engine again up
+     * to this many times, each time telling it what was already returned so it skips
+     * those and reaches further back. No LLM runs at any
+     * value. Stops early when a pass finds nothing new; `verify_used` in the response
+     * says how many actually ran.
+     *
+     * Each pass is another engine call and can add up to `limit` more memories, so it
+     * costs more — you are billed for what is delivered. Default 0. Worth it on questions
+     * 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.
+     */
+    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.
+     *
+     * Requires an image-capable model, and is refused (403) on one without it rather
+     * than answering with no images.
+     */
+    max_images?: number;
+    /**
+     * Fields the service accepts that this version does not know about, merged into the
+     * request as written. Every other key is refused, so a typo cannot reach the wire —
+     * `verfy: 3` used to be sent, dropped by the service, and answered normally, leaving
+     * a caller billed for one pass believing they had bought three.
+     */
+    extra?: Record<string, unknown>;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export interface WriteOptions {
+    idempotencyKey?: string;
+    /**
+     * An image to store alongside the text (Tablet 2 and newer).
+     *
+     * `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.
+     */
+    image?: ImageInput;
+}
+export interface ClientOptions {
+    apiKey: string;
+    /** API base URL (defaults to the hosted service). */
+    baseUrl?: string;
+    /** Per-request timeout in ms, applied to each retry attempt (default 30000). */
+    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. */
+    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). */
+    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. */
+    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. */
+    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.
+     *
+     *  Per call, clone: `mem.withSignal(ctrl.signal).recall(...)`. */
+    signal?: AbortSignal;
+    /** The `fetch` used for every request (default: the global `fetch`).
+     *
+     *  This is the seam for anything the runtime cannot express through options.
+     *  The one that matters in practice is a corporate egress proxy: Node's global
+     *  fetch (undici) IGNORES `HTTP_PROXY` / `HTTPS_PROXY`, so behind such a proxy no
+     *  request leaves at all. Pass a proxy-aware fetch and they go through:
+     *
+     *      import { ProxyAgent } from "undici";
+     *      const agent = new ProxyAgent(process.env.HTTPS_PROXY!);
+     *      const mem = new Client({
+     *        apiKey,
+     *        fetch: (url, init) => fetch(url, { ...init, dispatcher: agent } as any),
+     *      });
+     *
+     *  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;
+}
+/** Wontopos memory client. Store and recall memories, isolated per `userId`. */
+export declare class Client {
+    private readonly base;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly apiKey;
+    private readonly model;
+    private readonly maxRetries;
+    private readonly deadlineMs?;
+    private readonly signal?;
+    /** 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;
+    /** The store every call uses unless one passes `userId`. */
+    private readonly defaultUser;
+    private _rateLimit;
+    /** Quota from the MOST RECENT call: `{ limit, remaining, reset }` (or `null` before
+     * the first call). Read it to self-throttle — the client already retries 429s, but
+     * this lets you slow down before hitting the wall. */
+    get rateLimit(): RateLimit | null;
+    constructor(opts: ClientOptions);
+    /** 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. */
+    toJSON(): Record<string, string>;
+    /** Resolve a call's store: the explicit userId, else the client default. */
+    private uid;
+    private clone;
+    /**
+     * A client that uses `model` (sent as `X-WOS-Model`). Use it to set the default
+     * (`new Client({ apiKey, model })`) or to override one call
+     * (`client.withModel("tablet-1").recall(...)`).
+     */
+    withModel(model: string): Client;
+    /** A client bound to `userId` as its default store (everything else kept). */
+    withUser(userId: string): Client;
+    /** A client bound to a caller's `AbortSignal` (everything else kept).
+     *
+     *     const ctrl = new AbortController();
+     *     req.on("close", () => ctrl.abort());
+     *     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;
+    /** 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. */
+    withDeadline(deadlineMs: number): Client;
+    /** A client with a different per-request timeout in ms (everything else kept).
+     * `mem.withTimeout(120_000).addBulk(bigBlob)` — this slow call only. */
+    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).
+     *
+     * `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`. */
+    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.
+     *  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>;
+    /** Supersede an old memory with new content. Payload first, userId last — same shape as add/search. */
+    update(oldMemoryId: string, newContent: string, userId?: string, opts?: WriteOptions): Promise<UpdateResult>;
+    /** 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.
+     *
+     *  `limit` bounds `memories`, not the returned array. On a model that keeps the
+     *  assistant's own words separate (Scroll 1.2+) those come back as well, so the
+     *  array can hold more than `limit`. They were retrieved and billed either way;
+     *  dropping them would only hide what you already paid for. Size a prompt window
+     *  on the array you get back, not on `limit`. `searchSelf()` hands the two back
+     *  apart. */
+    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
+     * 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 `[]`. `userId` may be omitted. */
+    searchSelf(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SelfSearchResult>;
+    /**
+     * Search, and keep every field the answer came with.
+     *
+     * Same request as {@link Client.search} — reach for this one when the options make
+     * the merged array an incomplete answer:
+     *
+     *     const r = await mem.searchFull("the day we moved", "alice", 10,
+     *                                    { max_images: 3, verify: 2 });
+     *     r.images.length;   // the photos, which `search` drops
+     *     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.
+     */
+    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. */
+    recall(query: string, userId?: string, opts?: {
+        form?: string;
+        tz?: number;
+        /**
+         * 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.
+         */
+        limit?: number;
+        /** How much surrounding context is attached around the best match, 0–20. Default 10;
+         *  0 attaches none. Same model floor 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. */
+    engram(name: string, query: string, userId?: string, opts?: {
+        form?: string;
+        tz?: number;
+    }): Promise<EngramResult>;
+    /** Recent conversation turns (short-term memory). */
+    history(userId?: string): Promise<HistoryTurn[]>;
+    /** Memory counts for a store: { total_memories, short_term_turns }. */
+    stats(userId?: string): Promise<StatsResult>;
+    /**
+     * What this key has spent, and what is left — the numbers behind "can I keep going?".
+     *
+     * Free: it carries no charge and skips the balance gate, because an account at zero
+     * still has to be able to find out why. Rate-limited instead.
+     *
+     * Scoped to THIS key: its own lifetime spend, its workspace and stores over the
+     * window. It never returns another key's spend. `balance_cents` is account-wide,
+     * because that is what gates the next call whichever key makes it.
+     *
+     *     const u = await mem.usage(7);
+     *     if (u.balance_cents! < 100) stop();
+     */
+    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. */
+    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.
+     *
+     *     let cursor: string | null = null;
+     *     const all: Memory[] = [];
+     *     do {
+     *       const page = await mem.listMemories(undefined, { cursor: cursor ?? undefined });
+     *       all.push(...page.memories);
+     *       cursor = page.next_cursor;
+     *     } while (cursor);
+     */
+    listMemories(userId?: string, opts?: {
+        limit?: number;
+        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.
+     *
+     *     for await (const m of mem.iterMemories()) console.log(m.id, m.content);
+     */
+    iterMemories(userId?: string, opts?: {
+        pageSize?: number;
+    }): AsyncGenerator<Memory>;
+    /** 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`. */
+    exportImages(userId?: string, opts?: {
+        pageSize?: number;
+    }): Promise<Memory[]>;
+    /**
+     * Fetch the bytes of an image memory — the picture the SERVICE holds.
+     *
+     * Not necessarily your upload, in size OR in format: an image whose long edge was
+     * over 1568px was downscaled to 1568 on the way in and re-encoded — lossless
+     * formats as WebP, so a PNG comes back as `image/webp`; JPEG stays JPEG — and that
+     * smaller picture is what is stored and comes back here. Nothing on our side ever
+     * uses more than 1568, so the extra pixels would be bytes nobody reads.
+     * Keep your own copy for the full-resolution file.
+     *
+     * 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
+     * handing back something empty, so "a memory with no image" never looks the same as
+     * "an image we lost".
+     *
+     *     const { bytes, contentType } = await mem.getImage(undefined, id);
+     *     const ext = contentType.split("/")[1];   // "webp" for a downscaled PNG
+     *     await fs.writeFile(`image.${ext}`, bytes);
+     */
+    getImage(userId: string | undefined, memoryId: string): Promise<ImageBytes>;
+    /**
+     * 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.
+     *
+     *     const p = await mem.forgetImage(undefined, id, { preview: true });
+     *     if (p.memory_kept === false) { /* this would delete the whole memory *\/ }
+     */
+    forgetImage(userId: string | undefined, memoryId: string, opts?: {
+        preview?: boolean;
+    }): Promise<ImageDeleteResult>;
+    /**
+     * List a store's image memories, newest first, and count them.
+     *
+     * `count` is the TOTAL in the store, not the size of the page — so you can show
+     * "142 images" without walking every page. Paging is by cursor, not offset: hand
+     * `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.
+     */
+    listImages(userId?: string, opts?: {
+        limit?: number;
+        before?: string;
+        skipIds?: string[];
+    }): Promise<ImagePage>;
+    /** Async-iterate every image memory, paging under the hood. */
+    iterImages(userId?: string, opts?: {
+        pageSize?: number;
+    }): AsyncGenerator<Memory>;
+    /**
+     * How much of this store has been altered since it was written.
+     *
+     * This one is aimed at the MODEL, not at you. An assistant leaning on its own memory
+     * should be able to ask how far that memory has been edited underneath it — a store
+     * nobody has touched reads differently from one where a third of the facts were
+     * 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".
+     *
+     * 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
+     * asks this mid-conversation, and an answer that grew with the store would be
+     * unusable for exactly the customers who most need to ask.
+     *
+     * To see WHICH memories, ask for one side and page through it — at most 20 per call,
+     * and never both sides in one response:
+     *
+     * ```ts
+     * const { revised, unrevised, total } = await mem.revisions();   // numbers only
+     *
+     * let before: string | undefined, skipIds: string[] | undefined;
+     * for (;;) {
+     *   const p = await mem.revisions(undefined, { include: "revised", before, skipIds });
+     *   for (const m of p.memories ?? []) console.log(m.content);
+     *   if (!p.has_more || !p.next_before) break;
+     *   before = p.next_before;
+     *   skipIds = p.next_skip_ids;
+     * }
+     * ```
+     *
+     * 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.
+     */
+    revisions(userId?: string, opts?: {
+        /**
+         * Omit for counts only. Set it to ALSO get one page of the memories behind that
+         * 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. */
+        limit?: number;
+        /** Cursor: `next_before` from the previous page. */
+        before?: string;
+        /** Cursor: `next_skip_ids` from the previous page. Hand back what you were given. */
+        skipIds?: string[];
+    }): Promise<RevisionsResult>;
+    /**
+     * The full chain of edits behind one memory, oldest first.
+     *
+     * `is_current` marks the version in force. Use it to answer "what did this used to
+     * say, and when did it change" — `revisions()` tells you HOW MUCH a store moved,
+     * this tells you what happened to one fact.
+     */
+    lineage(userId: string | undefined, memoryId: string): Promise<LineageResult>;
+    /**
+     * What one person said, newest first.
+     *
+     * `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`.
+     *
+     * `chunks` / `points_to_delete` report how many internal records a delete would
+     * actually remove — usually more than `returned`, and worth showing to whoever is
+     * about to confirm one.
+     */
+    bySpeaker(speaker: string, userId?: string, opts?: {
+        limit?: number;
+        before?: string;
+        skipIds?: string[];
+    }): Promise<SpeakerPage>;
+    /** Check connectivity AND that the API key works. Resolves `true`, or rejects — an
+     * `AuthenticationError` (bad key), `PaymentRequiredError` (valid key but no card /
+     * depleted balance), or `APIConnectionError` (unreachable). Makes one metered request. */
+    ping(): Promise<boolean>;
+    /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
+    listModels(): Promise<ModelInfo[]>;
+    /**
+     * The engrams (and delivery forms) the selected model can actually run.
+     *
+     * 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.
+     *
+     *   const { engrams, forms } = await mem.listEngrams();
+     */
+    listEngrams(): Promise<EngramCatalog>;
+    /** Create a store — the `userId` you read and write under. Stores are explicit:
+     * a store must exist before you `add` to or `search` it, otherwise those calls
+     * return 404. Idempotent. Every account starts with a `default` store.
+     * Returns `{ user_id, status }` (`status` is `"created"` or `"exists"`). */
+    createStore(userId?: string): Promise<StoreOpResult>;
+    /** List your stores: `[{ user_id, created_at }, ...]` (`default` first). */
+    listStores(): Promise<StoreInfo[]>;
+    /** Delete a store and ALL its memories. Returns `{ user_id, status }`. */
+    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
+     * registration. A store registers up to 50 people to start. */
+    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. */
+    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. */
+    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.
+     */
+    /** 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. */
+    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.
+     *
+     *  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;
+    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. */
+    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. */
+    private readCappedBytes;
+    private request;
+}
+/** Back-compat alias: older code used `WME`. */
+export declare const WME: typeof Client;
+export default Client;