wontopos 2.2.29 → 2.2.31

package/README.md

@@ -160,22 +160,43 @@ const mem = new Client({ apiKey: "...", baseUrl: "https://wos.your-host.com" });
 - Homepage: <https://wontopos.com>
 - API reference: <https://wontopos.com/en/why> (Developers tab)
 
+## Reporting a bug
+
+Found something wrong, or something that looks unsafe? Tell us — one person reads
+every report.
+
+- Bugs: <https://wontopos.com/contact?topic=bug>
+- Security: <https://wontopos.com/contact?topic=security> (also published at
+  [`/.well-known/security.txt`](https://wontopos.com/.well-known/security.txt))
+
+Include the SDK version (`the version in package.json`) and the language. If it involves a store id or a
+memory, describe the shape rather than pasting the contents — we do not need your
+data to fix it.
+
 ## Changelog
 
-- **2.2.10** — `Memory` fix: the relevance field is `similarity` (not `score`,
-  which was never in the response); added typed `importance`, `category`,
-  `is_superseded`, `superseded_by`, `created_at`, `event_date`.
-- **2.2.9** — typed responses for every method (index-signature friendly) +
-  typed `SearchOptions`; security round 2: 64MB response cap, key/model-name
-  hygiene, `Client.fromEnv()`.
-- **2.2.8** — reliability + hardening: automatic retries (429/502/503 + connection
-  errors, backoff + jitter, honors `Retry-After`), redirects refused, key masked in
-  `toJSON`/inspect, `WosError.requestId`, guard against `delete()` without
-  `memoryId`, plain-HTTP warning, `User-Agent`.
-- **2.2.7** — speakers: `addSpeaker` / `listSpeakers` / `removeSpeaker`.
-- **2.2.6** — docs: `userId` = store, clarified everywhere.
-- **2.2.5** — docs: speakers + recall caching sections.
-- **2.2.4** — Python/TypeScript/Rust converge on one version; all three now
-  release in lockstep (same version, same surface). Patch releases are additive.
+The three clients release in lockstep — same version, same surface, same day.
+Patch releases are additive: nothing is removed or reordered within a minor line.
+
+- **2.2.30** — documentation only: this changelog, which had not been updated
+  in the shipped package since 2.2.10.
+- **2.2.29** — a store id that was PASSED but unusable no longer becomes the
+  default store. 2.2.28 caught a blank string; the value a failed tenant lookup
+  actually produces in JavaScript is `null` — and `String(null)` is the truthy
+  `"null"`, so it walked past the check and `null || default` sent the write to
+  the client's default store. `0` did the same. Anything but a non-blank string
+  now throws, on `deleteStore` / `deleteAll` too. Omitting the argument still
+  means "use the default". Also: `deleteStore` validates before it warns, so a
+  non-string no longer surfaces as a `TypeError` from inside the SDK.
+- **2.2.28** — audit: the API key no longer survives an object spread (`private`
+  is erased at runtime, so `{...client}` copied it), a whitespace `memoryId` can
+  no longer read as a whole-store delete, and a blank store id throws instead of
+  silently using the default.
+- **2.2.11–2.2.27** — additive fixes and hardening across all three clients.
+- **2.2.10** — `Memory` fix: the relevance field is `similarity` (not `score`);
+  added typed `importance`, `category`, `is_superseded`, `superseded_by`,
+  `created_at`, `event_date`.
+- **2.2.4–2.2.9** — one version across Python, TypeScript and Rust, released in
+  lockstep; retries, redirect refusal, response cap, key masking, speakers.
 
 License: MIT.

package/dist/wontopos.d.ts

@@ -145,6 +145,129 @@ export interface StatusResult {
     status?: string;
     [key: string]: unknown;
 }
+/**
+ * An image attached to a memory, passed to `add`/`store` via `opts.image`.
+ *
+ * The bytes are used ONCE, to embed the image, and are not kept. If you want the
+ * original back later, either let the service keep it (then `getImage` returns it) or
+ * put your own URL in `reference` — we store that string and never open it.
+ */
+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 original bytes plus what they actually are. */
+export interface ImageBytes {
+    /** The raw image. Write it to a file, or wrap it in a Blob to show it. */
+    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. Atoms — the fragments search uses internally — 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[];
+    /** Sentence-level fragments behind these memories — what a delete would actually remove. */
+    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;
@@ -296,6 +419,31 @@ export interface SearchOptions {
     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. Retrieval stays purely semantic — no LLM 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. Default 1; 0 asks for none.
+     * 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;
     [key: string]: unknown;
 }
 /**
@@ -316,6 +464,14 @@ export interface SearchOptions {
  */
 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;
@@ -439,6 +595,18 @@ export declare class Client {
     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;
+        /** Chunks of surrounding context 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"). Returns the merged result.
      * `form`/`tz` render memory times (memoir/archive) on Scroll 1.2+, same as search/recall. */
@@ -481,6 +649,130 @@ export declare class Client {
     }): AsyncGenerator<Memory>;
     /** Collect ALL of a store's memories into an array (original text + metadata, no vectors). */
     exportMemories(userId?: string): Promise<Memory[]>;
+    /**
+     * Fetch the ORIGINAL bytes of an image memory.
+     *
+     * Returns what was uploaded, with the type sniffed from the bytes themselves rather
+     * than from whatever the file was called. Rejects with `NotFoundError` when this
+     * memory has no image, or when the service was not configured to keep originals —
+     * 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);
+     *     await fs.writeFile("image.jpg", 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
+     * atoms, the sentence fragments search uses internally — nobody stored one, 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 the sentence-level fragments behind these
+     * memories, which is what a delete would actually remove — usually larger than
+     * `returned`, and worth showing before anyone confirms 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. */
@@ -523,6 +815,19 @@ export declare class Client {
      * 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.
+     */
+    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. */
@@ -532,6 +837,13 @@ export declare class Client {
     /** 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.
+     *
+     * `getImage` used to call `arrayBuffer()` here, which buffers whatever arrives. The
+     * cap exists for a hostile or broken `baseUrl`, and a photo endpoint is exactly where
+     * that shows up — the JSON paths were guarded while the one path that returns
+     * megabytes was not. One implementation, two callers, so they cannot drift. */
+    private readCappedBytes;
     private request;
 }
 /** Back-compat alias: older code used `WME`. */

package/dist/wontopos.js

@@ -37,7 +37,7 @@
  * runtime's (never disabled by this SDK; Node 18+ floors TLS at 1.2). Prefer
  * `Client.fromEnv()` over keys in source code.
  */
-const VERSION = "2.2.29";
+const VERSION = "2.2.31";
 /** Runtime info helps support debug a report ("node 18 on Windows...") —
  * platform only, never anything identifying. Browsers have no `process` (and
  * silently drop the UA header anyway). */
@@ -132,6 +132,45 @@ export function _resetStoreIdWarnings() {
 const NO_BODY_STATUS = new Set([204, 205, 304]);
 /** Paging backstop: bound the walk so a fresh-cursor-forever server can't loop us. */
 const MAX_PAGES = 1_000_000;
+/**
+ * Put an image into the shape the API expects, and fail loudly on the parts we can
+ * check from here.
+ *
+ * Deliberately NOT checked: the byte ceiling. It is a server setting (`/health`
+ * reports it as `memory.images.max_bytes`), so a number baked in here would drift the
+ * first time that config changes and would reject an image the service would have
+ * taken. What we do check is what cannot change: an empty payload, and a `data:` URL
+ * prefix — browsers and file pickers hand you `data:image/jpeg;base64,…`, the API
+ * wants the part after the comma, and the difference is invisible until the write
+ * fails with "not a readable image".
+ */
+function normalizeImage(image) {
+    if (!image || typeof image !== "object") {
+        throw new Error("image must be an object — { data: '<base64>' }.");
+    }
+    if (typeof image.data !== "string" || image.data.trim() === "") {
+        throw new Error("image.data is required — base64 of the image (a data: URL is fine).");
+    }
+    // 🔴**다듬고 나서 접두어를 본다.** 예전엔 원본에 바로 `startsWith("data:")` 를
+    //   걸어서, 앞에 공백이 하나만 있어도(` data:image/png;base64,…`) 접두어를 못 떼고
+    //   **`data:image/png;base64,` 문자열까지 통째로 base64 로** 보냈다. 엔진은
+    //   "이미지를 읽을 수 없다"며 400 을 내고, 부르는 쪽은 왜인지 모른다.
+    const raw = image.data.trim();
+    const comma = raw.startsWith("data:") ? raw.indexOf(",") : -1;
+    // 🔴그리고 **가운데 공백까지** 없앤다. `base64` 명령과 `openssl base64` 는 76자마다
+    //   줄을 바꾼다 — 파일을 그렇게 만들어 붙여넣는 건 흔한 길인데, 양끝만 다듬으면
+    //   그 줄바꿈이 그대로 payload 에 남는다. base64 알파벳에 공백은 없으므로
+    //   전부 빼는 게 안전하다.
+    const data = (comma === -1 ? raw : raw.slice(comma + 1)).replace(/\s+/g, "");
+    if (data === "")
+        throw new Error("image.data is empty after stripping its data: prefix.");
+    const out = { data };
+    if (image.reference !== undefined)
+        out.reference = image.reference;
+    if (image.taken_at !== undefined)
+        out.taken_at = image.taken_at;
+    return out;
+}
 /** Error codes that only occur while ESTABLISHING a connection — the request
  * never reached the server, so a retry can't double-process a write. Mid-stream
  * codes (ECONNRESET, EPIPE, UND_ERR_SOCKET, ETIMEDOUT) are ambiguous: the server
@@ -513,7 +552,10 @@ export class Client {
      * `opts.idempotencyKey`: see {@link WriteOptions} — pass one to make YOUR retry
      * of this exact write safe to repeat. */
     add(content, userId, metadata = {}, opts = {}) {
-        return this.post("/api/v1/memory/store", { user_id: this.uid(userId), content, metadata }, opts.idempotencyKey);
+        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);
     }
     /** Alias of `add` — store one memory. Same surface as the Python SDK's `store`. */
     store(content, userId, metadata = {}, opts = {}) {
@@ -566,7 +608,12 @@ export class Client {
      * `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, userId, opts = {}) {
-        return this.post("/api/v1/memory/recall", withForm({ user_id: this.uid(userId), query }, opts.form, opts.tz));
+        const body = { user_id: this.uid(userId), query };
+        if (opts.limit !== undefined)
+            body.limit = opts.limit;
+        if (opts.context_limit !== undefined)
+            body.context_limit = opts.context_limit;
+        return this.post("/api/v1/memory/recall", withForm(body, opts.form, opts.tz));
     }
     /** Run a built-in engram ("deep_recall" | "timeline" | "gather"). Returns the merged result.
      * `form`/`tz` render memory times (memoir/archive) on Scroll 1.2+, same as search/recall. */
@@ -640,6 +687,173 @@ export class Client {
             out.push(m);
         return out;
     }
+    // ----- images (Tablet 2 and newer) -----
+    /**
+     * Fetch the ORIGINAL bytes of an image memory.
+     *
+     * Returns what was uploaded, with the type sniffed from the bytes themselves rather
+     * than from whatever the file was called. Rejects with `NotFoundError` when this
+     * memory has no image, or when the service was not configured to keep originals —
+     * 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);
+     *     await fs.writeFile("image.jpg", bytes);
+     */
+    getImage(userId, memoryId) {
+        if (!memoryId || typeof memoryId !== "string") {
+            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 });
+    }
+    /**
+     * 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, memoryId, opts = {}) {
+        if (!memoryId || typeof memoryId !== "string") {
+            throw new Error("memoryId is required — the id of the memory whose image you want removed.");
+        }
+        const body = { user_id: this.uid(userId), memory_id: memoryId };
+        if (opts.preview)
+            body.preview = true;
+        return this.request("DELETE", "/api/v1/memory/image", body);
+    }
+    /**
+     * 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, opts = {}) {
+        const body = { user_id: this.uid(userId) };
+        if (opts.limit !== undefined)
+            body.limit = opts.limit;
+        if (opts.before !== undefined)
+            body.before = opts.before;
+        if (opts.skipIds !== undefined)
+            body.skip_ids = opts.skipIds;
+        return this.post("/api/v1/memory/images", body);
+    }
+    /** Async-iterate every image memory, paging under the hood. */
+    async *iterImages(userId, opts = {}) {
+        let before;
+        let skipIds;
+        for (let page = 0; page < MAX_PAGES; page++) {
+            const p = await this.listImages(userId, { limit: opts.pageSize, before, skipIds });
+            for (const m of asRecords(p.images))
+                yield m;
+            if (!p.has_more || !p.next_before)
+                break;
+            before = p.next_before;
+            skipIds = Array.isArray(p.next_skip_ids) ? p.next_skip_ids : undefined;
+        }
+    }
+    // ----- how much has this memory been edited -----
+    /**
+     * 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
+     * atoms, the sentence fragments search uses internally — nobody stored one, 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, opts = {}) {
+        const body = {};
+        if (opts.include !== undefined)
+            body.include = opts.include;
+        if (opts.limit !== undefined)
+            body.limit = opts.limit;
+        if (opts.before !== undefined)
+            body.before = opts.before;
+        if (opts.skipIds !== undefined)
+            body.skip_ids = opts.skipIds;
+        // `user_id` LAST, after the caller's fields — an `opts` spread that can land on top
+        // of it is how a client ends up reading another store. Same order as `search`.
+        body.user_id = this.uid(userId);
+        return this.post("/api/v1/won/revisions", body);
+    }
+    /**
+     * 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, memoryId) {
+        if (!memoryId || typeof memoryId !== "string") {
+            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 });
+    }
+    /**
+     * 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 the sentence-level fragments behind these
+     * memories, which is what a delete would actually remove — usually larger than
+     * `returned`, and worth showing before anyone confirms one.
+     */
+    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.');
+        }
+        const body = { user_id: this.uid(userId), speaker: speaker.trim() };
+        if (opts.limit !== undefined)
+            body.limit = opts.limit;
+        if (opts.before !== undefined)
+            body.before = opts.before;
+        if (opts.skipIds !== undefined)
+            body.skip_ids = opts.skipIds;
+        return this.post("/api/v1/memory/by-speaker", body);
+    }
     /** 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. */
@@ -747,6 +961,73 @@ export class Client {
     post(path, body, idempotencyKey) {
         return this.request("POST", path, body, idempotencyKey);
     }
+    /**
+     * 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.
+     */
+    async requestBytes(path, body) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.base}${path}`, {
+                method: "POST",
+                headers: this.headers,
+                body: JSON.stringify(body),
+                signal: ctrl.signal,
+                redirect: "manual",
+            });
+        }
+        catch (e) {
+            clearTimeout(timer);
+            if (e?.name === "AbortError" || ctrl.signal.aborted) {
+                throw new APIConnectionError(0, `request timed out after ${this.timeoutMs}ms`);
+            }
+            throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
+        }
+        try {
+            this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
+            if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
+                void res.body?.cancel();
+                throw errorFor(res.status, "the API answered with a redirect; refusing to follow it");
+            }
+            if (!res.ok) {
+                let msg = await this.readCapped(res).catch(() => "");
+                try {
+                    const data = JSON.parse(msg);
+                    const err = data?.error;
+                    if (err && typeof err === "object")
+                        msg = err.message ?? err.type ?? msg;
+                    else if (typeof err === "string")
+                        msg = err;
+                }
+                catch {
+                    /* keep raw text */
+                }
+                if (msg.length > MAX_ERR_MSG)
+                    msg = msg.slice(0, MAX_ERR_MSG) + "…(truncated)";
+                throw errorFor(res.status, msg || `HTTP ${res.status}`);
+            }
+            const buf = await this.readCappedBytes(res);
+            if (buf.byteLength === 0) {
+                // An empty 200 would otherwise read as "here is your image" and write a
+                // zero-byte file — indistinguishable from an image we lost.
+                throw new WosError(res.status, "empty image body — the service returned no bytes");
+            }
+            return { bytes: buf, contentType: res.headers.get("content-type") ?? "application/octet-stream" };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     /** 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. */
@@ -774,12 +1055,21 @@ export class Client {
     /** Read the body with a hard size cap, so a broken/hostile endpoint can't
      * make the process buffer gigabytes. */
     async readCapped(res) {
+        return new TextDecoder().decode(await this.readCappedBytes(res));
+    }
+    /** The same cap, for a body that is not text.
+     *
+     * `getImage` used to call `arrayBuffer()` here, which buffers whatever arrives. The
+     * cap exists for a hostile or broken `baseUrl`, and a photo endpoint is exactly where
+     * that shows up — the JSON paths were guarded while the one path that returns
+     * megabytes was not. One implementation, two callers, so they cannot drift. */
+    async readCappedBytes(res) {
         const cl = res.headers.get("content-length");
         if (cl && Number(cl) > MAX_RESPONSE_BYTES) {
             throw new WosError(0, `response too large (${cl} bytes) — refusing to buffer it`);
         }
         if (!res.body)
-            return res.text();
+            return new Uint8Array(await res.arrayBuffer());
         const reader = res.body.getReader();
         const parts = [];
         let size = 0;
@@ -800,7 +1090,7 @@ export class Client {
             buf.set(p, off);
             off += p.byteLength;
         }
-        return new TextDecoder().decode(buf);
+        return buf;
     }
     async request(method, path, body, idempotencyKey) {
         const extraHeaders = this.idemHeader(idempotencyKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.29",
+  "version": "2.2.31",
   "description": "Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.",
   "keywords": [
     "memory",
@@ -42,5 +42,8 @@
   },
   "devDependencies": {
     "typescript": "^5.4.0"
+  },
+  "bugs": {
+    "url": "https://wontopos.com/contact?topic=bug"
   }
 }