wontopos 2.2.45 → 2.2.47

package/dist/cjs/wontopos.d.cts

@@ -14,7 +14,7 @@
  * (`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*
+ * The API key picks *which memory* (your workspace); `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
@@ -22,15 +22,16 @@
  * `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.
+ * memory stored in one language is found by a question asked in another. No language
+ * model reads your stored memories.
  *
  * Reliability: every call retries transient failures with exponential backoff +
  * 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.
+ * a retry can never double-process a write (reads, the DELETE calls, the memory writes,
+ * which carry an idempotency key, 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.
@@ -48,6 +49,8 @@ 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;
+/** @deprecated Test hook. The warn-once set is process-global by design. */
+export declare function _resetRetirementWarnings(): void;
 /** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
 export interface RateLimit {
     limit: number | null;
@@ -89,7 +92,9 @@ 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. */
+/** 402 — no card on file, the balance is depleted, or the month's spend cap for the
+ *  account's tier is reached (`details.reason` is `tier_cap_reached`). Top up to
+ *  continue; a top-up also raises the tier. */
 export declare class PaymentRequiredError extends WosError {
 }
 /** 403 — the key/model isn't allowed to do this. */
@@ -98,8 +103,11 @@ 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 (retried automatically; nothing was
- *  stored), or the store id collides with an existing one (not retried). */
+/** 409: another write to this store was in flight, or the first request under this
+ *  write's idempotency key is still running (both retried automatically; nothing was
+ *  stored); the store id collides with an existing one (not retried); or the first
+ *  request under the key did not come back with an answer, so whether it was stored is
+ *  not known (not retried: check before sending it again under a new key). */
 export declare class ConflictError extends WosError {
     /** The existing store id this one collides with. Set only on a collision, which
      *  retrying cannot fix. */
@@ -182,7 +190,9 @@ export interface StoreResult {
     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". */
+     *  tell "my retry landed" from "my retry was a no-op". This client sets it only for
+     *  a key you passed, and then the earlier request can also be an attempt of this same
+     *  call that the client sent again after an answer that left the outcome open. */
     replayed?: boolean;
     [key: string]: unknown;
 }
@@ -194,8 +204,9 @@ 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). A request
- * body is capped at 10MB.
+ * Both edges must be 700px or more and the long edge at most 2500px, and the image
+ * file at most 7MB; anything else is refused (400) with the reason. 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
@@ -241,8 +252,9 @@ 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`.
+     * on its long edge (2500 at most) 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`. */
@@ -317,7 +329,8 @@ export interface LineageStep {
     is_current?: boolean;
     [key: string]: unknown;
 }
-/** `lineage` → the full chain of edits behind one memory, oldest first. */
+/** `lineage` → the edits that followed one memory, from the id passed forward to the
+ *  version in force, oldest first. */
 export interface LineageResult {
     memory_id?: string;
     chain: LineageStep[];
@@ -360,23 +373,31 @@ export interface SearchResult {
     /** Image memories the answer carried (one by default on an image-capable model,
      *  up to `max_images`); `[]` when there were none. */
     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. */
+    /** Re-ask passes that added memories. Present only when `verify` above 0 was sent;
+     *  lower than you asked for means a pass found nothing new, or could not run. */
     verify_used?: number;
     [key: string]: unknown;
 }
 export interface RecallResult {
+    /** The recent conversation, oldest first. */
     short_term: {
-        turns: unknown[];
+        turns: HistoryTurn[];
         count: number;
+        [key: string]: unknown;
     };
+    /** The stored memories that match the query, best first. */
     long_term: {
         memories: Memory[];
         count: number;
+        [key: string]: unknown;
     };
+    /** The conversation around the best memory, in the order it was said. Each row is
+     *  text that starts with where it sits next to that memory: `[before] `, `[match] `
+     *  or `[after] `. Empty when there is no best memory or `context_limit` is 0. */
     context: {
-        around_top_memory: unknown[];
+        around_top_memory: string[];
         count: number;
+        [key: string]: unknown;
     };
     [key: string]: unknown;
 }
@@ -391,7 +412,7 @@ export interface EngramResult {
     usage?: Usage;
     [key: string]: unknown;
 }
-/** One turn of the short-term window, as `history()` returns it. */
+/** One turn of the short-term window, as `history()` and `recall()` return it. */
 export interface HistoryTurn {
     /** `"user"` or `"assistant"`. */
     role?: string;
@@ -414,7 +435,7 @@ export interface UsageResult {
         output_tokens?: number;
         since?: string;
     };
-    /** The workspace this key belongs to, over the window. */
+    /** The workspace this key belongs to, over the window: every key in it, not only this one. */
     workspace?: {
         workspace_id?: string | null;
         requests?: number;
@@ -542,9 +563,8 @@ export interface SpeakersList {
     [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.
+ * Narrow a search to part of a store. A narrow filter can return fewer than `limit`
+ * even when the store holds more 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
@@ -565,7 +585,8 @@ export interface SearchFilters {
     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. */
+     *  this is the one you usually want. A memory stored without an `event_date` is
+     *  matched by when it was stored. */
     event_from?: string;
     event_to?: string;
     /** Drop matches the engine scored below this importance (0–1). */
@@ -578,9 +599,11 @@ export declare function _resetFilterWarnings(): void;
  *  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. */
+    /** Recall caching. The same query again inside the TTL bills at 0.1×; one that
+     *  extends the cached query bills only its cached part at 0.1×, the new part at the
+     *  write rate and its results at the normal rate. 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";
     };
@@ -591,9 +614,9 @@ export interface SearchOptions {
     /**
      * 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
+     * those and reaches further back. Raising it adds no language model call at any
      * value. Stops early when a pass finds nothing new; `verify_used` in the response
-     * says how many actually ran.
+     * says how many passes added memories.
      *
      * 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
@@ -629,25 +652,24 @@ 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 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.
+ * Every memory write (`add`, `addTurn`, `addBulk`, `update`) carries an idempotency key:
+ * `idempotencyKey` when you pass one, otherwise one this client makes for the call. With
+ * it the client retries the write on 408 / 502 / 503 / 504 and on a dropped connection,
+ * as it does a read: the service answers a repeat with the first attempt's result instead
+ * of storing again, and one that arrives while the first is still running with a 409 to
+ * wait, which is retried as well.
  *
- * 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.
+ * Pass your own key when the retry is yours: a job that died and was re-run, a queue
+ * that redelivers. The service keeps a key for 24 hours and answers a repeat with the
+ * first successful response, marked `replayed: true`; the same key with a different body
+ * is refused (422). A first attempt that failed is not kept, so a repeat of it runs,
+ * unless it did not come back with an answer, so whether it was applied is not known:
+ * then the repeat is refused with a `ConflictError` (409) instead of storing it twice.
+ * Check before sending it again under a new key.
  *
  * 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 best-effort and can be shorter than 10 minutes; it is not a durable
- * de-duplication record.
  */
 export interface WriteOptions {
     idempotencyKey?: string;
@@ -775,6 +797,12 @@ export interface ClientOptions {
      *  (`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;
+    /** Run in a browser page anyway. Off by default: an API key in a page is readable by
+     *  everyone who opens it, and with it every memory in its workspace, so a client in a
+     *  page that would send the key to the service itself is refused. A `baseUrl` of your
+     *  own, a proxy that holds the real key, is not refused. Turn this on only for a local
+     *  demo with a key you will revoke. */
+    dangerouslyAllowBrowser?: boolean;
 }
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export declare class Client {
@@ -796,6 +824,8 @@ export declare class Client {
     private readonly pageRelative;
     /** Whether the caller supplied `fetch`. */
     private readonly customFetch;
+    /** Whether the caller asked to run in a browser page anyway. */
+    private readonly allowBrowser;
     /** The store every call uses unless one passes `userId`. */
     private readonly defaultUser;
     private _rateLimit;
@@ -859,15 +889,16 @@ export declare class Client {
     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.
+    /** Search a store's memories. They come most relevant first; the assistant's own
+     *  words and image memories, when there are any, follow them in their own order.
      *
      *  `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.
      *
-     *  `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
+     *  `limit` bounds `memories`, not the returned array, and each `verify` pass can add
+     *  up to `limit` more. 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 after them 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.
      *
@@ -891,7 +922,7 @@ export declare class Client {
      *     const r = await mem.searchFull("the day we moved", "alice", 10,
      *                                    { max_images: 3, verify: 2 });
      *     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)
+     *     r.verify_used;     // re-ask passes that added memories (each billed for what it added)
      *
      * 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
@@ -928,7 +959,8 @@ export declare class Client {
     }): Promise<EngramResult>;
     /** Recent conversation turns (short-term memory). */
     history(userId?: string): Promise<HistoryTurn[]>;
-    /** Memory counts for a store: { total_memories, short_term_turns }. */
+    /** Memory counts for a store: { total_memories, short_term_turns }. `total_memories`
+     *  can be larger than the number `listMemories` lists. */
     stats(userId?: string): Promise<StatsResult>;
     /**
      * What this key has spent, and what is left — the numbers behind "can I keep going?".
@@ -936,18 +968,17 @@ export declare class Client {
      * 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.
+     * `key` is THIS key's own lifetime spend. `workspace` and `stores` cover the window
+     * for the workspace this key belongs to, every key in it included. `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 id `listMemories` does not return,
-     * or an invalidated memory rejects with `NotFoundError`. Pass `undefined` as
+     * The id is what `add`/`store` or `listMemories` returned. An unknown id or one
+     * from another store 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.
@@ -993,9 +1024,10 @@ export declare class Client {
      * 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
+     * over 1568px (2500 at most) 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;
+     * kept as sent when the re-encode came out bigger — 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.
      *
@@ -1013,10 +1045,10 @@ export declare class Client {
      */
     getImage(userId: string | undefined, memoryId: string): Promise<ImageBytes>;
     /**
-     * Remove the PHOTO from a memory, keeping its text.
+     * Remove the PHOTO from a memory. It can take the whole memory with it.
      *
-     * `preview: true` reports what would happen, including `memory_kept`, and changes
-     * nothing. Retried like `deleteStore`; without `preview`, a 404 after an ambiguous
+     * `preview: true` reports what would happen, including `memory_kept` (`false` when
+     * the memory itself would go), 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 });
@@ -1100,11 +1132,13 @@ export declare class Client {
         skipIds?: string[];
     }): Promise<RevisionsResult>;
     /**
-     * The full chain of edits behind one memory, oldest first.
+     * The edits that followed one memory: from the id you pass forward to the version in
+     * force, 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.
+     * `is_current` marks the version in force. The chain runs forward only, so to answer
+     * "what did this used to say, and when did it change" pass the first version's id;
+     * the current version's id (what `search` returns) comes back alone. `revisions()`
+     * tells you HOW MUCH a store moved, this tells you what happened to one fact.
      */
     lineage(userId: string | undefined, memoryId: string): Promise<LineageResult>;
     /**
@@ -1126,8 +1160,7 @@ export declare class Client {
      * `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, capabilities, retires_at? }, ...]`.
-     *  Needs no API key. */
+    /** Available models: `[{ id, name, available, memory, capabilities, retires_at? }, ...]`. */
     listModels(): Promise<ModelInfo[]>;
     /**
      * The engrams (and delivery forms) the selected model can actually run.
@@ -1160,7 +1193,9 @@ 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. Retried like
+    /** Unregister a person. Their memories stay, and the name can no longer tag a new
+     *  memory or filter a search. The tag goes from stored memories too, except on
+     *  `tablet-2`, which keeps it on memories already stored with it. 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
@@ -1170,6 +1205,11 @@ export declare class Client {
      * this is destructive, so it never falls back to the default store. */
     deleteAll(userId: string): Promise<StatusResult>;
     private post;
+    /** A memory write. It always carries an `Idempotency-Key`, the caller's or one made
+     *  for this call, so an answer that leaves the outcome open (408/502/503/504, a
+     *  dropped connection) can be retried: the service answers the retry with the first
+     *  attempt's result instead of storing again. */
+    private write;
     /** A DELETE that removes something: a 404 after an ambiguous failure says an earlier
      *  attempt may already have removed it. */
     private remove;
@@ -1210,12 +1250,13 @@ export declare class Client {
      *
      * 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.
+     * dropped connections on a call that only reads (an idempotent method, or a POST
+     * that only reads) or a write that carries an idempotency key; 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 a call 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;
     /**