wontopos 2.2.38 → 2.2.40

package/README.md

@@ -80,12 +80,12 @@ const hits = await mem.search("...the conversation so far...", "alice", 10,
 
 Built in, no configuration needed:
 
-- **Automatic retries** — 429 always, and 502 / 503 or a connection error only when a
-  retry cannot double-process a write. The writes and the searches are POSTs, and a
-  502 on one of those may have been returned *after* the service already stored and
-  billed it, so those get 429 and connect-level failures only. The reads and the
+- **Automatic retries** — 429 always, and 408 / 502 / 503 / 504 or a connection error
+  only when a retry cannot double-process a write. The writes and the searches are
+  POSTs, and any of those four may have been returned *after* the write already
+  landed, so those get 429 and connect-level failures only. The reads and the
   deletes that address a whole store — `listStores`, `listSpeakers`, `deleteStore`,
-  `removeSpeaker`, `forgetImage` — are GET or DELETE and do retry a 502. Twice, with
+  `removeSpeaker`, `forgetImage` — are GET or DELETE and do retry all four. Twice, with
   exponential backoff + jitter, honoring the server's `Retry-After`. Tune with
   `new Client({ maxRetries })`; `0` disables.
 - **Redirects refused** — the API key never follows a 3xx to another host.
@@ -106,9 +106,7 @@ Built in, no configuration needed:
 ### Behind a corporate proxy
 
 Node's global `fetch` (undici) ignores `HTTP_PROXY` / `HTTPS_PROXY`, so behind an
-egress proxy this SDK could not connect at all — while the Python and Rust SDKs went
-through, because `requests` and `reqwest` both read those variables. Pass a
-proxy-aware `fetch` and the three behave the same:
+egress proxy no request leaves at all. Pass a proxy-aware `fetch` and they go through:
 
 This one needs `npm i undici` — Node's global `fetch` is built on undici, but the
 package itself is not installed for you.
@@ -211,7 +209,7 @@ data to fix it.
 ## Changelog
 
 The three clients release in lockstep — same version, same surface, same day. Patch
-releases are additive. Four inside 2.2 were not, deliberately and each with its
+releases are additive. Six inside 2.2 were not, deliberately and each with its
 reason; the changelog lists them.
 
 See [CHANGELOG.md](https://github.com/wontopos/wontopos-node/blob/main/CHANGELOG.md).

package/dist/cjs/wontopos.d.cts

@@ -26,8 +26,8 @@
  * and searching call no LLM.
  *
  * Reliability: every call retries transient failures with exponential backoff +
- * jitter, honoring `Retry-After` — 429 always; 502/503 and connection errors only
- * when a retry can never double-process a write (idempotent calls, or a failure
+ * 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.
  *
@@ -74,10 +74,11 @@ 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). */
+/** 404 — the store or resource doesn't exist. */
 export declare class NotFoundError extends WosError {
 }
-/** 409 — a concurrent write to the same store. Retry. */
+/** 409 — another write to this store was in flight (nothing was stored; retry), or the
+ *  store id collides with an existing store's (permanent). */
 export declare class ConflictError extends WosError {
 }
 /** 429 — too many requests. Back off and retry (the client already retries these). */
@@ -86,8 +87,8 @@ export declare class RateLimitError extends WosError {
 /**
  * 5xx — the service failed.
  *
- * `502` / `503` are transient: the client already retries them for calls where a
- * retry cannot double-process a write, and retrying yourself is reasonable.
+ * `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`).
@@ -159,6 +160,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).
+ *
  * 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
@@ -291,8 +294,8 @@ export interface LineageResult {
 export interface SpeakerPage {
     speaker?: string;
     memories: Memory[];
-    /** How many underlying records a delete would actually remove, beyond what was returned. */
     chunks?: number;
+    /** The count to show before anyone confirms a delete of this speaker's memories. */
     points_to_delete?: number;
     returned?: number;
     has_more?: boolean;
@@ -307,20 +310,17 @@ export interface UpdateResult {
     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. */
+/** `searchFull` → everything one search answered with. `search` returns every memory
+ *  as one array; this keeps the fields apart and adds `verify_used`, the report on
+ *  the `verify` option. */
 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. */
+    /** 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. */
@@ -428,21 +428,27 @@ 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. */
+    /** The store id. `createStore` answers with the id as you sent it. */
     user_id?: string;
+    /** The normalized form the store is filed under, when it differs from `user_id`. */
+    canonical_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. */
+    /** Present when the API filed your id under a normalized form, explaining how. */
     note?: string;
     [key: string]: unknown;
 }
 export interface StoreInfo {
+    /** The id the store was created with — pass it back as `userId`. */
     user_id: string;
     created_at: string;
+    /** The normalized form the store is filed under, when it differs from `user_id`. */
+    canonical_id?: string;
     [key: string]: unknown;
 }
 /** `addSpeaker` / `removeSpeaker` → `{ user_id, speaker, status }`. */
@@ -532,11 +538,15 @@ export interface SearchOptions {
      * 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). */
+    form?: string;
+    /** Your UTC offset in hours, for rendering times in `form`. */
+    tz?: 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.
+     * request as written. Every other key is refused, so a typo cannot reach the wire.
+     * The store, the query and the count always win over a copy in here.
      */
     extra?: Record<string, unknown>;
 }
@@ -548,9 +558,9 @@ export interface SearchOptions {
  * 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 502 / 503 or a dropped body, where the
- * request may already have been stored and billed — without a key it cannot know
- * whether that first attempt landed.
+ * 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
@@ -582,8 +592,8 @@ export interface ClientOptions {
      * to the account's built-in `default` store. */
     userId?: string;
     /** How many times to retry transient failures before throwing — 429 always;
-     * 502/503 and connection errors only when a retry can never double-process a
-     * write. 0 disables retries (default 2). */
+     * 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
@@ -611,10 +621,8 @@ export interface ClientOptions {
      *
      *  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
-     *  this SDK could not connect at all — while the Python and Rust SDKs went
-     *  through, because `requests` and `reqwest` both read those variables. Pass a
-     *  proxy-aware fetch and the three behave the same again:
+     *  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!);
@@ -696,7 +704,7 @@ export declare class Client {
     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 re-ingest and re-bill the whole blob. */
+     *  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>;
@@ -707,18 +715,18 @@ export declare class Client {
      *  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. */
+     *  `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. */
     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. */
+     * that does not keep them apart, `self_memories` is `[]`. Image memories are not
+     * included; `search` and `searchFull` carry them. `userId` may be omitted. */
     searchSelf(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SelfSearchResult>;
     /**
      * Search, and keep every field the answer came with.
@@ -728,7 +736,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, which `search` drops
+     *     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
@@ -812,6 +820,11 @@ export declare class Client {
     }): 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.
      *
@@ -937,9 +950,8 @@ export declare class Client {
      * 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.
+     * `points_to_delete` is the count to show before anyone confirms a delete of this
+     * speaker's memories.
      */
     bySpeaker(speaker: string, userId?: string, opts?: {
         limit?: number;
@@ -969,7 +981,8 @@ export declare class Client {
      * 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). */
+    /** 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 }`. */
     deleteStore(userId: string): Promise<StoreOpResult>;

package/dist/cjs/wontopos.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WME = exports.Client = exports.ServerError = exports.RateLimitError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.PaymentRequiredError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionError = exports.WosError = exports.CONTEXT_LIMIT_MAX = exports.CONTEXT_LIMIT_MIN = exports.SEARCH_LIMIT_MAX = exports.SEARCH_LIMIT_MIN = void 0;
 exports._resetStoreIdWarnings = _resetStoreIdWarnings;
 exports._resetFilterWarnings = _resetFilterWarnings;
-const VERSION = "2.2.38";
+const VERSION = "2.2.40";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -18,7 +18,7 @@ function logDebug(msg) {
 const DEFAULT_BASE_URL = "https://api.wontopos.com";
 const DEFAULT_MODEL = "tablet-2";
 const RETRY_ALWAYS = new Set([429]);
-const RETRY_IF_IDEMPOTENT = new Set([502, 503]);
+const RETRY_IF_IDEMPOTENT = new Set([408, 502, 503, 504]);
 const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
 const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
@@ -40,8 +40,9 @@ const warnedStoreIds = new Set();
 function warnIfStoreIdCollapses(id) {
     if (!id || warnedStoreIds.has(id))
         return;
+    const valid = STORE_ID_FORMAT.test(id);
     const normalized = normalizeStoreId(id);
-    if (normalized === id)
+    if (valid && normalized === id)
         return;
     warnedStoreIds.add(id);
     while (warnedStoreIds.size > WARNED_STORE_IDS_MAX) {
@@ -50,10 +51,27 @@ function warnIfStoreIdCollapses(id) {
             break;
         warnedStoreIds.delete(oldest);
     }
-    console.warn(`wontopos: store id ${JSON.stringify(id)} is stored as ${JSON.stringify(normalized)} ` +
-        `(lowercased, and anything outside [a-z0-9_] becomes "_"). Ids that differ only by case or ` +
-        `punctuation share ONE store and therefore one set of memories — if these ids come from your ` +
-        `end users, normalize them yourself first so two people can never collide.`);
+    if (!valid) {
+        console.warn(`wontopos: store id ${JSON.stringify(id)} is not a valid store id: use 1-64 ASCII letters, ` +
+            `digits, ".", "_" and "-", starting with a letter or digit. Creating it is refused (400).`);
+        return;
+    }
+    console.warn(`wontopos: store id ${JSON.stringify(id)} normalizes to ${JSON.stringify(normalized)}. ` +
+        `Ids that differ only by case name this same store; one that differs only by punctuation ` +
+        `cannot be created beside it (409) and is not found when used (404). If these ids come from ` +
+        `your end users, normalize them yourself first so two people never compete for one name.`);
+}
+const STORE_ID_FORMAT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const NOT_METADATA = new Set(["userid", "storeid", "idempotencykey"]);
+function checkMetadataKeys(metadata) {
+    if (metadata == null || typeof metadata !== "object")
+        return;
+    for (const k of Object.keys(metadata)) {
+        if (NOT_METADATA.has(k.toLowerCase().replace(/[\s_.-]/g, ""))) {
+            throw new Error(`${JSON.stringify(k)} is not a metadata field: pass the store as userId and an ` +
+                `idempotency key as opts.idempotencyKey. Nothing was sent.`);
+        }
+    }
 }
 function _resetStoreIdWarnings() {
     warnedStoreIds.clear();
@@ -141,13 +159,24 @@ function parseRateLimit(h) {
 const asList = (x) => (Array.isArray(x) ? x : []);
 const asObj = (x) => (x != null && typeof x === "object" && !Array.isArray(x) ? x : {});
 const asRecords = (x) => asList(x).filter((m) => m != null && typeof m === "object" && !Array.isArray(m));
+const memoryFromGet = (r) => {
+    const o = asObj(r);
+    if (o.memory != null && typeof o.memory === "object" && !Array.isArray(o.memory))
+        return o.memory;
+    return typeof o.id === "string" ? o : {};
+};
 function mergeResults(r) {
-    const main = asRecords(r?.memories);
-    const mine = asRecords(r?.self_memories);
-    if (mine.length === 0)
-        return main;
-    const seen = new Set(main.map((m) => m.id).filter((id) => typeof id === "string"));
-    return main.concat(mine.filter((m) => !(typeof m.id === "string" && seen.has(m.id))));
+    const out = asRecords(r?.memories);
+    const seen = new Set(out.map((m) => m.id).filter((id) => typeof id === "string"));
+    for (const m of [...asRecords(r?.self_memories), ...asRecords(r?.images)]) {
+        if (typeof m.id === "string") {
+            if (seen.has(m.id))
+                continue;
+            seen.add(m.id);
+        }
+        out.push(m);
+    }
+    return out;
 }
 function withForm(body, form, tz) {
     if (form !== undefined)
@@ -219,10 +248,11 @@ const KNOWN_FILTER_KEYS = new Set([
 ]);
 const warnedFilterKeys = new Set();
 const KNOWN_SEARCH_KEYS = new Set([
-    "cache_control", "speaker", "filters", "verify", "max_images", "extra",
+    "cache_control", "speaker", "filters", "verify", "max_images", "form", "tz", "extra",
 ]);
 const RESERVED_SEARCH_KEYS = new Set(["user_id", "query", "max_results"]);
 const KNOWN_RECALL_KEYS = new Set(["form", "tz", "limit", "context_limit"]);
+const KNOWN_ENGRAM_KEYS = new Set(["form", "tz"]);
 function checkSearchOpts(opts) {
     checkOpts(opts, KNOWN_SEARCH_KEYS, "search");
 }
@@ -237,8 +267,7 @@ function checkOpts(opts, known, what) {
         const near = [...known].find((n) => n !== "extra" && editWithin(k, n, 2));
         throw new Error(`unknown ${what} option ${JSON.stringify(k)}` +
             (near ? ` — did you mean ${JSON.stringify(near)}?` : "") +
-            `. The service drops keys it does not know and answers anyway, so this would ` +
-            `have looked like it worked.` +
+            `. It would have had no effect, and the call would have looked like it worked.` +
             (known.has("extra")
                 ? ` Pass it under \`extra\` if the service accepts it and this client does not know it yet.`
                 : ""));
@@ -407,25 +436,26 @@ class Client {
     withRetries(maxRetries) {
         return this.clone({ maxRetries });
     }
-    add(content, userId, metadata = {}, opts = {}) {
+    async add(content, userId, metadata = {}, opts = {}) {
+        checkMetadataKeys(metadata);
         const body = { user_id: this.uid(userId), content, metadata };
         if (opts.image !== undefined)
             body.image = normalizeImage(opts.image);
         return this.post("/api/v1/memory/store", body, opts.idempotencyKey);
     }
-    store(content, userId, metadata = {}, opts = {}) {
+    async store(content, userId, metadata = {}, opts = {}) {
         return this.add(content, userId, metadata, opts);
     }
-    addTurn(userMsg, assistantMsg, userId, opts = {}) {
+    async addTurn(userMsg, assistantMsg, userId, opts = {}) {
         return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, opts.idempotencyKey);
     }
-    addBulk(content, userId, category = "general", timestamp, opts = {}) {
+    async addBulk(content, userId, category = "general", timestamp, opts = {}) {
         const body = { user_id: this.uid(userId), content, category };
         if (timestamp)
             body.timestamp = timestamp;
         return this.post("/api/v1/memory/bulk-store", body, opts.idempotencyKey);
     }
-    update(oldMemoryId, newContent, userId, opts = {}) {
+    async update(oldMemoryId, newContent, userId, opts = {}) {
         return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, opts.idempotencyKey);
     }
     async search(query, userId, limit = 10, opts = {}) {
@@ -470,14 +500,15 @@ class Client {
         }
         return this.post("/api/v1/memory/recall", withForm(body, opts.form, opts.tz));
     }
-    engram(name, query, userId, opts = {}) {
+    async engram(name, query, userId, opts = {}) {
+        checkOpts(opts, KNOWN_ENGRAM_KEYS, "engram");
         return this.post("/api/v1/engram/run", withForm({ name, user_id: this.uid(userId), query }, opts.form, opts.tz));
     }
     async history(userId) {
         const r = await this.post("/api/v1/memory/history", { user_id: this.uid(userId) });
         return asRecords(r.turns);
     }
-    stats(userId) {
+    async stats(userId) {
         return this.post("/api/v1/memory/stats", { user_id: this.uid(userId) });
     }
     async usage(days = 7) {
@@ -486,13 +517,13 @@ class Client {
         }
         return this.request("GET", `/api/v1/won/usage?days=${days}`);
     }
-    get(userId, memoryId) {
+    async get(userId, memoryId) {
         if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the id that add/store or listMemories returned.");
         }
-        return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId.trim() }).then((r) => asObj(r.memory));
+        return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId.trim() }).then(memoryFromGet);
     }
-    listMemories(userId, opts = {}) {
+    async listMemories(userId, opts = {}) {
         const body = { user_id: this.uid(userId), limit: opts.limit ?? 100 };
         if (opts.cursor)
             body.cursor = opts.cursor;
@@ -520,13 +551,19 @@ class Client {
             out.push(m);
         return out;
     }
-    getImage(userId, memoryId) {
+    async exportImages(userId, opts = {}) {
+        const out = [];
+        for await (const m of this.iterImages(userId, opts))
+            out.push(m);
+        return out;
+    }
+    async getImage(userId, memoryId) {
         if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the id that add/store or listImages returned.");
         }
         return this.requestBytes("/api/v1/memory/image", { user_id: this.uid(userId), memory_id: memoryId.trim() });
     }
-    forgetImage(userId, memoryId, opts = {}) {
+    async forgetImage(userId, memoryId, opts = {}) {
         if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the id of the memory whose image you want removed.");
         }
@@ -535,7 +572,7 @@ class Client {
             body.preview = true;
         return this.request("DELETE", "/api/v1/memory/image", body);
     }
-    listImages(userId, opts = {}) {
+    async listImages(userId, opts = {}) {
         const body = { user_id: this.uid(userId) };
         if (opts.limit !== undefined)
             body.limit = opts.limit;
@@ -565,7 +602,7 @@ class Client {
         throw new Error(`stopped after ${MAX_PAGES} pages — the store did not end. This is a truncated ` +
             `answer, not the whole store.`);
     }
-    revisions(userId, opts = {}) {
+    async revisions(userId, opts = {}) {
         const body = {};
         if (opts.include !== undefined)
             body.include = opts.include;
@@ -578,13 +615,13 @@ class Client {
         body.user_id = this.uid(userId);
         return this.post("/api/v1/won/revisions", body);
     }
-    lineage(userId, memoryId) {
+    async lineage(userId, memoryId) {
         if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the memory whose history you want.");
         }
         return this.post("/api/v1/memory/lineage", { user_id: this.uid(userId), memory_id: memoryId.trim() });
     }
-    bySpeaker(speaker, userId, opts = {}) {
+    async bySpeaker(speaker, userId, opts = {}) {
         if (!speaker || typeof speaker !== "string" || speaker.trim() === "") {
             throw new Error('speaker is required — "me" for the assistant, or a person\'s name.');
         }
@@ -608,41 +645,42 @@ class Client {
     async listEngrams() {
         const data = await this.request("GET", "/api/v1/engram");
         return {
+            ...data,
             engrams: asRecords(data.engrams),
             forms: asRecords(data.forms),
             note: typeof data.note === "string" ? data.note : undefined,
         };
     }
-    createStore(userId) {
+    async createStore(userId) {
         return this.post("/api/v1/memory/collection", { user_id: this.uid(userId) });
     }
     async listStores() {
         const r = await this.request("GET", "/api/v1/memory/collections");
         return asRecords(r.collections);
     }
-    deleteStore(userId) {
+    async deleteStore(userId) {
         if (typeof userId !== "string" || !userId.trim())
             throw new Error("userId is required (a non-blank string) — deleteStore never falls back to the default store.");
         warnIfStoreIdCollapses(userId);
         return this.request("DELETE", "/api/v1/memory/collection", { user_id: userId });
     }
-    addSpeaker(speaker, userId) {
+    async addSpeaker(speaker, userId) {
         return this.post("/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
     }
     async listSpeakers(userId) {
         const r = await this.request("GET", `/api/v1/memory/speakers?user_id=${encodeURIComponent(this.uid(userId))}`);
         return { ...r, speakers: asRecords(r?.speakers) };
     }
-    removeSpeaker(speaker, userId) {
+    async removeSpeaker(speaker, userId) {
         return this.request("DELETE", "/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
     }
-    delete(userId, memoryId) {
+    async delete(userId, memoryId) {
         if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required (non-blank). To delete every memory in a store, call deleteAll(userId) explicitly.");
         }
         return this.post("/api/v1/memory/forget", { user_id: this.uid(userId), memory_id: memoryId.trim() });
     }
-    deleteAll(userId) {
+    async deleteAll(userId) {
         if (typeof userId !== "string" || !userId.trim())
             throw new Error("userId is required (a non-blank string) for deleteAll — anything else would wipe the default store.");
         warnIfStoreIdCollapses(userId);
@@ -777,7 +815,9 @@ class Client {
                     if (e?.name === "AbortError" || att.signal.aborted) {
                         throw new APIConnectionError(0, this.abortMessage(att.why()));
                     }
-                    throw e;
+                    if (e instanceof WosError)
+                        throw e;
+                    throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
                 }
                 if (buf.byteLength === 0) {
                     throw new WosError(res.status, "empty image body — the service returned no bytes");
@@ -910,7 +950,14 @@ class Client {
                 }
                 if (e instanceof WosError)
                     throw e;
-                throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
+                if (!(IDEMPOTENT_METHODS.has(method.toUpperCase()) && attempt + 1 < attempts)) {
+                    throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
+                }
+                att.clear();
+                const delay = this.backoffMs(attempt);
+                logDebug(`${method} ${logPath} — body dropped mid-stream, retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
+                await this.backoffSleep(delay, deadlineAt);
+                continue;
             }
             finally {
                 att.clear();

package/dist/wontopos.d.ts

@@ -26,8 +26,8 @@
  * and searching call no LLM.
  *
  * Reliability: every call retries transient failures with exponential backoff +
- * jitter, honoring `Retry-After` — 429 always; 502/503 and connection errors only
- * when a retry can never double-process a write (idempotent calls, or a failure
+ * 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.
  *
@@ -74,10 +74,11 @@ 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). */
+/** 404 — the store or resource doesn't exist. */
 export declare class NotFoundError extends WosError {
 }
-/** 409 — a concurrent write to the same store. Retry. */
+/** 409 — another write to this store was in flight (nothing was stored; retry), or the
+ *  store id collides with an existing store's (permanent). */
 export declare class ConflictError extends WosError {
 }
 /** 429 — too many requests. Back off and retry (the client already retries these). */
@@ -86,8 +87,8 @@ export declare class RateLimitError extends WosError {
 /**
  * 5xx — the service failed.
  *
- * `502` / `503` are transient: the client already retries them for calls where a
- * retry cannot double-process a write, and retrying yourself is reasonable.
+ * `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`).
@@ -159,6 +160,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).
+ *
  * 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
@@ -291,8 +294,8 @@ export interface LineageResult {
 export interface SpeakerPage {
     speaker?: string;
     memories: Memory[];
-    /** How many underlying records a delete would actually remove, beyond what was returned. */
     chunks?: number;
+    /** The count to show before anyone confirms a delete of this speaker's memories. */
     points_to_delete?: number;
     returned?: number;
     has_more?: boolean;
@@ -307,20 +310,17 @@ export interface UpdateResult {
     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. */
+/** `searchFull` → everything one search answered with. `search` returns every memory
+ *  as one array; this keeps the fields apart and adds `verify_used`, the report on
+ *  the `verify` option. */
 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. */
+    /** 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. */
@@ -428,21 +428,27 @@ 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. */
+    /** The store id. `createStore` answers with the id as you sent it. */
     user_id?: string;
+    /** The normalized form the store is filed under, when it differs from `user_id`. */
+    canonical_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. */
+    /** Present when the API filed your id under a normalized form, explaining how. */
     note?: string;
     [key: string]: unknown;
 }
 export interface StoreInfo {
+    /** The id the store was created with — pass it back as `userId`. */
     user_id: string;
     created_at: string;
+    /** The normalized form the store is filed under, when it differs from `user_id`. */
+    canonical_id?: string;
     [key: string]: unknown;
 }
 /** `addSpeaker` / `removeSpeaker` → `{ user_id, speaker, status }`. */
@@ -532,11 +538,15 @@ export interface SearchOptions {
      * 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). */
+    form?: string;
+    /** Your UTC offset in hours, for rendering times in `form`. */
+    tz?: 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.
+     * request as written. Every other key is refused, so a typo cannot reach the wire.
+     * The store, the query and the count always win over a copy in here.
      */
     extra?: Record<string, unknown>;
 }
@@ -548,9 +558,9 @@ export interface SearchOptions {
  * 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 502 / 503 or a dropped body, where the
- * request may already have been stored and billed — without a key it cannot know
- * whether that first attempt landed.
+ * 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
@@ -582,8 +592,8 @@ export interface ClientOptions {
      * to the account's built-in `default` store. */
     userId?: string;
     /** How many times to retry transient failures before throwing — 429 always;
-     * 502/503 and connection errors only when a retry can never double-process a
-     * write. 0 disables retries (default 2). */
+     * 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
@@ -611,10 +621,8 @@ export interface ClientOptions {
      *
      *  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
-     *  this SDK could not connect at all — while the Python and Rust SDKs went
-     *  through, because `requests` and `reqwest` both read those variables. Pass a
-     *  proxy-aware fetch and the three behave the same again:
+     *  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!);
@@ -696,7 +704,7 @@ export declare class Client {
     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 re-ingest and re-bill the whole blob. */
+     *  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>;
@@ -707,18 +715,18 @@ export declare class Client {
      *  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. */
+     *  `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. */
     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. */
+     * that does not keep them apart, `self_memories` is `[]`. Image memories are not
+     * included; `search` and `searchFull` carry them. `userId` may be omitted. */
     searchSelf(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SelfSearchResult>;
     /**
      * Search, and keep every field the answer came with.
@@ -728,7 +736,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, which `search` drops
+     *     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
@@ -812,6 +820,11 @@ export declare class Client {
     }): 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.
      *
@@ -937,9 +950,8 @@ export declare class Client {
      * 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.
+     * `points_to_delete` is the count to show before anyone confirms a delete of this
+     * speaker's memories.
      */
     bySpeaker(speaker: string, userId?: string, opts?: {
         limit?: number;
@@ -969,7 +981,8 @@ export declare class Client {
      * 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). */
+    /** 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 }`. */
     deleteStore(userId: string): Promise<StoreOpResult>;

package/dist/wontopos.js

@@ -1,4 +1,4 @@
-const VERSION = "2.2.38";
+const VERSION = "2.2.40";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -13,7 +13,7 @@ function logDebug(msg) {
 const DEFAULT_BASE_URL = "https://api.wontopos.com";
 const DEFAULT_MODEL = "tablet-2";
 const RETRY_ALWAYS = new Set([429]);
-const RETRY_IF_IDEMPOTENT = new Set([502, 503]);
+const RETRY_IF_IDEMPOTENT = new Set([408, 502, 503, 504]);
 const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
 const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
@@ -35,8 +35,9 @@ const warnedStoreIds = new Set();
 function warnIfStoreIdCollapses(id) {
     if (!id || warnedStoreIds.has(id))
         return;
+    const valid = STORE_ID_FORMAT.test(id);
     const normalized = normalizeStoreId(id);
-    if (normalized === id)
+    if (valid && normalized === id)
         return;
     warnedStoreIds.add(id);
     while (warnedStoreIds.size > WARNED_STORE_IDS_MAX) {
@@ -45,10 +46,27 @@ function warnIfStoreIdCollapses(id) {
             break;
         warnedStoreIds.delete(oldest);
     }
-    console.warn(`wontopos: store id ${JSON.stringify(id)} is stored as ${JSON.stringify(normalized)} ` +
-        `(lowercased, and anything outside [a-z0-9_] becomes "_"). Ids that differ only by case or ` +
-        `punctuation share ONE store and therefore one set of memories — if these ids come from your ` +
-        `end users, normalize them yourself first so two people can never collide.`);
+    if (!valid) {
+        console.warn(`wontopos: store id ${JSON.stringify(id)} is not a valid store id: use 1-64 ASCII letters, ` +
+            `digits, ".", "_" and "-", starting with a letter or digit. Creating it is refused (400).`);
+        return;
+    }
+    console.warn(`wontopos: store id ${JSON.stringify(id)} normalizes to ${JSON.stringify(normalized)}. ` +
+        `Ids that differ only by case name this same store; one that differs only by punctuation ` +
+        `cannot be created beside it (409) and is not found when used (404). If these ids come from ` +
+        `your end users, normalize them yourself first so two people never compete for one name.`);
+}
+const STORE_ID_FORMAT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const NOT_METADATA = new Set(["userid", "storeid", "idempotencykey"]);
+function checkMetadataKeys(metadata) {
+    if (metadata == null || typeof metadata !== "object")
+        return;
+    for (const k of Object.keys(metadata)) {
+        if (NOT_METADATA.has(k.toLowerCase().replace(/[\s_.-]/g, ""))) {
+            throw new Error(`${JSON.stringify(k)} is not a metadata field: pass the store as userId and an ` +
+                `idempotency key as opts.idempotencyKey. Nothing was sent.`);
+        }
+    }
 }
 export function _resetStoreIdWarnings() {
     warnedStoreIds.clear();
@@ -136,13 +154,24 @@ function parseRateLimit(h) {
 const asList = (x) => (Array.isArray(x) ? x : []);
 const asObj = (x) => (x != null && typeof x === "object" && !Array.isArray(x) ? x : {});
 const asRecords = (x) => asList(x).filter((m) => m != null && typeof m === "object" && !Array.isArray(m));
+const memoryFromGet = (r) => {
+    const o = asObj(r);
+    if (o.memory != null && typeof o.memory === "object" && !Array.isArray(o.memory))
+        return o.memory;
+    return typeof o.id === "string" ? o : {};
+};
 function mergeResults(r) {
-    const main = asRecords(r?.memories);
-    const mine = asRecords(r?.self_memories);
-    if (mine.length === 0)
-        return main;
-    const seen = new Set(main.map((m) => m.id).filter((id) => typeof id === "string"));
-    return main.concat(mine.filter((m) => !(typeof m.id === "string" && seen.has(m.id))));
+    const out = asRecords(r?.memories);
+    const seen = new Set(out.map((m) => m.id).filter((id) => typeof id === "string"));
+    for (const m of [...asRecords(r?.self_memories), ...asRecords(r?.images)]) {
+        if (typeof m.id === "string") {
+            if (seen.has(m.id))
+                continue;
+            seen.add(m.id);
+        }
+        out.push(m);
+    }
+    return out;
 }
 function withForm(body, form, tz) {
     if (form !== undefined)
@@ -204,10 +233,11 @@ const KNOWN_FILTER_KEYS = new Set([
 ]);
 const warnedFilterKeys = new Set();
 const KNOWN_SEARCH_KEYS = new Set([
-    "cache_control", "speaker", "filters", "verify", "max_images", "extra",
+    "cache_control", "speaker", "filters", "verify", "max_images", "form", "tz", "extra",
 ]);
 const RESERVED_SEARCH_KEYS = new Set(["user_id", "query", "max_results"]);
 const KNOWN_RECALL_KEYS = new Set(["form", "tz", "limit", "context_limit"]);
+const KNOWN_ENGRAM_KEYS = new Set(["form", "tz"]);
 function checkSearchOpts(opts) {
     checkOpts(opts, KNOWN_SEARCH_KEYS, "search");
 }
@@ -222,8 +252,7 @@ function checkOpts(opts, known, what) {
         const near = [...known].find((n) => n !== "extra" && editWithin(k, n, 2));
         throw new Error(`unknown ${what} option ${JSON.stringify(k)}` +
             (near ? ` — did you mean ${JSON.stringify(near)}?` : "") +
-            `. The service drops keys it does not know and answers anyway, so this would ` +
-            `have looked like it worked.` +
+            `. It would have had no effect, and the call would have looked like it worked.` +
             (known.has("extra")
                 ? ` Pass it under \`extra\` if the service accepts it and this client does not know it yet.`
                 : ""));
@@ -392,25 +421,26 @@ export class Client {
     withRetries(maxRetries) {
         return this.clone({ maxRetries });
     }
-    add(content, userId, metadata = {}, opts = {}) {
+    async add(content, userId, metadata = {}, opts = {}) {
+        checkMetadataKeys(metadata);
         const body = { user_id: this.uid(userId), content, metadata };
         if (opts.image !== undefined)
             body.image = normalizeImage(opts.image);
         return this.post("/api/v1/memory/store", body, opts.idempotencyKey);
     }
-    store(content, userId, metadata = {}, opts = {}) {
+    async store(content, userId, metadata = {}, opts = {}) {
         return this.add(content, userId, metadata, opts);
     }
-    addTurn(userMsg, assistantMsg, userId, opts = {}) {
+    async addTurn(userMsg, assistantMsg, userId, opts = {}) {
         return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, opts.idempotencyKey);
     }
-    addBulk(content, userId, category = "general", timestamp, opts = {}) {
+    async addBulk(content, userId, category = "general", timestamp, opts = {}) {
         const body = { user_id: this.uid(userId), content, category };
         if (timestamp)
             body.timestamp = timestamp;
         return this.post("/api/v1/memory/bulk-store", body, opts.idempotencyKey);
     }
-    update(oldMemoryId, newContent, userId, opts = {}) {
+    async update(oldMemoryId, newContent, userId, opts = {}) {
         return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, opts.idempotencyKey);
     }
     async search(query, userId, limit = 10, opts = {}) {
@@ -455,14 +485,15 @@ export class Client {
         }
         return this.post("/api/v1/memory/recall", withForm(body, opts.form, opts.tz));
     }
-    engram(name, query, userId, opts = {}) {
+    async engram(name, query, userId, opts = {}) {
+        checkOpts(opts, KNOWN_ENGRAM_KEYS, "engram");
         return this.post("/api/v1/engram/run", withForm({ name, user_id: this.uid(userId), query }, opts.form, opts.tz));
     }
     async history(userId) {
         const r = await this.post("/api/v1/memory/history", { user_id: this.uid(userId) });
         return asRecords(r.turns);
     }
-    stats(userId) {
+    async stats(userId) {
         return this.post("/api/v1/memory/stats", { user_id: this.uid(userId) });
     }
     async usage(days = 7) {
@@ -471,13 +502,13 @@ export class Client {
         }
         return this.request("GET", `/api/v1/won/usage?days=${days}`);
     }
-    get(userId, memoryId) {
+    async get(userId, memoryId) {
         if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the id that add/store or listMemories returned.");
         }
-        return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId.trim() }).then((r) => asObj(r.memory));
+        return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId.trim() }).then(memoryFromGet);
     }
-    listMemories(userId, opts = {}) {
+    async listMemories(userId, opts = {}) {
         const body = { user_id: this.uid(userId), limit: opts.limit ?? 100 };
         if (opts.cursor)
             body.cursor = opts.cursor;
@@ -505,13 +536,19 @@ export class Client {
             out.push(m);
         return out;
     }
-    getImage(userId, memoryId) {
+    async exportImages(userId, opts = {}) {
+        const out = [];
+        for await (const m of this.iterImages(userId, opts))
+            out.push(m);
+        return out;
+    }
+    async getImage(userId, memoryId) {
         if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the id that add/store or listImages returned.");
         }
         return this.requestBytes("/api/v1/memory/image", { user_id: this.uid(userId), memory_id: memoryId.trim() });
     }
-    forgetImage(userId, memoryId, opts = {}) {
+    async forgetImage(userId, memoryId, opts = {}) {
         if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the id of the memory whose image you want removed.");
         }
@@ -520,7 +557,7 @@ export class Client {
             body.preview = true;
         return this.request("DELETE", "/api/v1/memory/image", body);
     }
-    listImages(userId, opts = {}) {
+    async listImages(userId, opts = {}) {
         const body = { user_id: this.uid(userId) };
         if (opts.limit !== undefined)
             body.limit = opts.limit;
@@ -550,7 +587,7 @@ export class Client {
         throw new Error(`stopped after ${MAX_PAGES} pages — the store did not end. This is a truncated ` +
             `answer, not the whole store.`);
     }
-    revisions(userId, opts = {}) {
+    async revisions(userId, opts = {}) {
         const body = {};
         if (opts.include !== undefined)
             body.include = opts.include;
@@ -563,13 +600,13 @@ export class Client {
         body.user_id = this.uid(userId);
         return this.post("/api/v1/won/revisions", body);
     }
-    lineage(userId, memoryId) {
+    async lineage(userId, memoryId) {
         if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the memory whose history you want.");
         }
         return this.post("/api/v1/memory/lineage", { user_id: this.uid(userId), memory_id: memoryId.trim() });
     }
-    bySpeaker(speaker, userId, opts = {}) {
+    async bySpeaker(speaker, userId, opts = {}) {
         if (!speaker || typeof speaker !== "string" || speaker.trim() === "") {
             throw new Error('speaker is required — "me" for the assistant, or a person\'s name.');
         }
@@ -593,41 +630,42 @@ export class Client {
     async listEngrams() {
         const data = await this.request("GET", "/api/v1/engram");
         return {
+            ...data,
             engrams: asRecords(data.engrams),
             forms: asRecords(data.forms),
             note: typeof data.note === "string" ? data.note : undefined,
         };
     }
-    createStore(userId) {
+    async createStore(userId) {
         return this.post("/api/v1/memory/collection", { user_id: this.uid(userId) });
     }
     async listStores() {
         const r = await this.request("GET", "/api/v1/memory/collections");
         return asRecords(r.collections);
     }
-    deleteStore(userId) {
+    async deleteStore(userId) {
         if (typeof userId !== "string" || !userId.trim())
             throw new Error("userId is required (a non-blank string) — deleteStore never falls back to the default store.");
         warnIfStoreIdCollapses(userId);
         return this.request("DELETE", "/api/v1/memory/collection", { user_id: userId });
     }
-    addSpeaker(speaker, userId) {
+    async addSpeaker(speaker, userId) {
         return this.post("/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
     }
     async listSpeakers(userId) {
         const r = await this.request("GET", `/api/v1/memory/speakers?user_id=${encodeURIComponent(this.uid(userId))}`);
         return { ...r, speakers: asRecords(r?.speakers) };
     }
-    removeSpeaker(speaker, userId) {
+    async removeSpeaker(speaker, userId) {
         return this.request("DELETE", "/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
     }
-    delete(userId, memoryId) {
+    async delete(userId, memoryId) {
         if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required (non-blank). To delete every memory in a store, call deleteAll(userId) explicitly.");
         }
         return this.post("/api/v1/memory/forget", { user_id: this.uid(userId), memory_id: memoryId.trim() });
     }
-    deleteAll(userId) {
+    async deleteAll(userId) {
         if (typeof userId !== "string" || !userId.trim())
             throw new Error("userId is required (a non-blank string) for deleteAll — anything else would wipe the default store.");
         warnIfStoreIdCollapses(userId);
@@ -762,7 +800,9 @@ export class Client {
                     if (e?.name === "AbortError" || att.signal.aborted) {
                         throw new APIConnectionError(0, this.abortMessage(att.why()));
                     }
-                    throw e;
+                    if (e instanceof WosError)
+                        throw e;
+                    throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
                 }
                 if (buf.byteLength === 0) {
                     throw new WosError(res.status, "empty image body — the service returned no bytes");
@@ -895,7 +935,14 @@ export class Client {
                 }
                 if (e instanceof WosError)
                     throw e;
-                throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
+                if (!(IDEMPOTENT_METHODS.has(method.toUpperCase()) && attempt + 1 < attempts)) {
+                    throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
+                }
+                att.clear();
+                const delay = this.backoffMs(attempt);
+                logDebug(`${method} ${logPath} — body dropped mid-stream, retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
+                await this.backoffSleep(delay, deadlineAt);
+                continue;
             }
             finally {
                 att.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.38",
+  "version": "2.2.40",
   "description": "Wontopos \u2014 long-term memory for AI agents. Identical recall in every language, ~100\u00d7 lower LLM bill.",
   "keywords": [
     "memory",