wontopos 2.2.43 → 2.2.45

package/README.md

@@ -5,7 +5,7 @@ npm install wontopos
 ```
 
 Get an API key in the [console](https://wontopos.com). Keys look like `wos-live-...`;
-the client also reads `WONTOPOS_API_KEY` from the environment.
+`Client.fromEnv()` reads `WONTOPOS_API_KEY` from the environment instead.
 
 ```ts
 import { Client } from "wontopos";
@@ -35,10 +35,10 @@ Where the store id goes depends on whether the method takes a payload. A method
 writes or searches puts the payload first and the store second — `mem.add("...", "alice")`,
 `mem.search("...", "alice")`. A method that only addresses a store takes it first —
 `mem.listMemories("alice")`, `mem.stats("alice")`, `mem.delete("alice", memoryId)`.
-Most of them let you leave it out for the client's default store. Four take it
-positionally and cannot — `get`, `delete`, `lineage` and `forgetImage` want an explicit
-`undefined` there, because a second required argument follows it. Python omits it in
-all four; this is the one place the three clients differ in shape rather than meaning.
+Most of them let you leave it out for the client's default store. Five take it
+positionally and cannot — `get`, `getImage`, `delete`, `lineage` and `forgetImage` want
+an explicit `undefined` there, because a second required argument follows it. Python
+omits it in all five; this is the one place the three clients differ in shape rather than meaning.
 Let your editor confirm the order: every signature is typed. A store is one isolated memory space per end-user, agent, or topic. WHO said each memory inside a store is the `speaker` tag below — storing the assistant's own words never needs a separate id.
 
 ## Who said it (speakers)
@@ -112,6 +112,7 @@ This one needs `npm i undici` — Node's global `fetch` is built on undici, but
 package itself is not installed for you.
 
 ```ts
+import { Client } from "wontopos";
 import { ProxyAgent } from "undici";
 
 const agent = new ProxyAgent(process.env.HTTPS_PROXY!);
@@ -147,7 +148,7 @@ Every method returns a documented shape — `StoreResult`, `UpdateResult`,
 `RecallResult`, `EngramResult`, `StatsResult`, `SpeakersList`, `Memory[]`, ... —
 each with an index signature, so new server fields flow through without an SDK
 update. `search` options are typed too (`SearchOptions`: `cache_control`,
-`speaker`, plus pass-through).
+`speaker`, plus `extra` for pass-through).
 
 ```ts
 import { type Memory } from "wontopos";
@@ -180,6 +181,10 @@ try {
 }
 ```
 
+A retired model answers `410`, thrown as `GoneError`: retrying cannot succeed, so name a
+live model (`listModels()` lists them, with `retires_at` on one that is scheduled to
+retire). `deleteStore` still works under a retired model.
+
 ## A different API host
 
 Point the client somewhere other than the default endpoint - a dedicated region,
@@ -202,14 +207,14 @@ Found something wrong, or something that looks unsafe? Tell us — every report
 - 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
+Include the SDK version (the one 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
 
 The three clients release in lockstep — same version, same surface, same day. Patch
-releases are additive. Eight inside 2.2 were not, deliberately and each with its
+releases are additive. Nine 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

@@ -106,6 +106,11 @@ export declare class ConflictError extends WosError {
     readonly conflictsWith?: string;
     constructor(status: number, message: string, requestId?: string, init?: WosErrorInit);
 }
+/** 410 — the model this call named is retired. Retrying cannot succeed: name a live
+ *  model instead (`listModels()` lists them). `deleteStore` still works under a
+ *  retired model. */
+export declare class GoneError extends WosError {
+}
 /** 429 — too many requests. Back off and retry (the client already retries these,
  *  unless `Retry-After` asks for more than 30 seconds). */
 export declare class RateLimitError extends WosError {
@@ -647,9 +652,10 @@ export interface SearchOptions {
 export interface WriteOptions {
     idempotencyKey?: string;
     /**
-     * An image to store alongside the text. Needs a model that lists `images` in its
-     * `listModels()` capabilities; any other refuses the write rather than store the
-     * caption and quietly drop the image.
+     * An image to store alongside the text, read by `add` (and `store`) only: `addTurn`,
+     * `addBulk` and `update` warn about it and do not send it. Needs a model that lists
+     * `images` in its `listModels()` capabilities; any other refuses the write rather than
+     * store the caption and quietly drop the image.
      *
      * A caption is required: the service refuses empty `content` (400) even with an
      * image attached.

package/dist/cjs/wontopos.js

@@ -1,9 +1,9 @@
 "use strict";
 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.WME = exports.Client = exports.ServerError = exports.RateLimitError = exports.GoneError = 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.43";
+const VERSION = "2.2.45";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -456,6 +456,9 @@ class ConflictError extends WosError {
     }
 }
 exports.ConflictError = ConflictError;
+class GoneError extends WosError {
+}
+exports.GoneError = GoneError;
 class RateLimitError extends WosError {
     retryAfter;
     constructor(status, message, requestId, init) {
@@ -468,6 +471,7 @@ exports.RateLimitError = RateLimitError;
 class ServerError extends WosError {
 }
 exports.ServerError = ServerError;
+const GONE_HINT = "This model is retired; listModels() lists the ones you can use.";
 const STATUS_ERRORS = {
     400: BadRequestError,
     401: AuthenticationError,
@@ -475,6 +479,7 @@ const STATUS_ERRORS = {
     403: PermissionDeniedError,
     404: NotFoundError,
     409: ConflictError,
+    410: GoneError,
     413: BadRequestError,
     422: BadRequestError,
     429: RateLimitError,
@@ -503,7 +508,7 @@ const KNOWN_ENGRAM_KEYS = new Set(["form", "tz"]);
 function checkSearchOpts(opts) {
     checkOpts(opts, KNOWN_SEARCH_KEYS, "search");
     const o = opts;
-    optRange(o.max_images !== undefined ? o.max_images : o.extra?.max_images, "max_images", 0, MAX_IMAGES_MAX);
+    optRange(o.max_images != null ? o.max_images : o.extra?.max_images, "max_images", 0, MAX_IMAGES_MAX);
 }
 function checkOpts(opts, known, what) {
     for (const k of Object.keys(opts)) {
@@ -553,6 +558,17 @@ function warnOnceUnknownKeys(obj, known, warned, message) {
         console.warn(message(k));
     }
 }
+function givenOpts(known) {
+    return Object.fromEntries(Object.entries(known).filter(([, v]) => v !== null));
+}
+const ADD_KEYS = new Set(["idempotencyKey", "image"]);
+const WRITE_KEYS = new Set(["idempotencyKey"]);
+const warnedWriteKeys = new Set();
+function writeKey(opts, takesImage = false) {
+    warnOnceUnknownKeys(opts, takesImage ? ADD_KEYS : WRITE_KEYS, warnedWriteKeys, (k) => `wontopos: write option ${JSON.stringify(k)} is not sent. ` +
+        (takesImage ? "add takes idempotencyKey and image." : "This call takes idempotencyKey only."));
+    return opts.idempotencyKey;
+}
 function warnOnUnknownFilters(filters) {
     warnOnceUnknownKeys(filters, KNOWN_FILTER_KEYS, warnedFilterKeys, (k) => `wontopos: unknown search filter ${JSON.stringify(k)} — the API drops keys it does not know, ` +
         `so this filter has NO effect and the search is wider than you think. ` +
@@ -713,22 +729,22 @@ class Client {
         if (opts.image !== undefined)
             body.image = normalizeImage(opts.image);
         warnOnUnknownMetadata(metadata);
-        return this.post("/api/v1/memory/store", body, opts.idempotencyKey);
+        return this.post("/api/v1/memory/store", body, writeKey(opts, true));
     }
     async store(content, userId, metadata = {}, opts = {}) {
         return this.add(content, userId, metadata, 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);
+        return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, writeKey(opts));
     }
     async addBulk(content, userId, category = "general", timestamp, opts = {}) {
-        const body = { user_id: this.uid(userId), content, category };
+        const body = { user_id: this.uid(userId), content, category: category ?? "general" };
         if (timestamp)
             body.timestamp = timestamp;
-        return this.post("/api/v1/memory/bulk-store", body, opts.idempotencyKey);
+        return this.post("/api/v1/memory/bulk-store", body, writeKey(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);
+        return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, writeKey(opts));
     }
     async search(query, userId, limit = 10, opts = {}) {
         checkSearchOpts(opts);
@@ -736,7 +752,7 @@ class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return mergeResults(r);
     }
     async searchSelf(query, userId, limit = 10, opts = {}) {
@@ -745,7 +761,7 @@ class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return { memories: asRecords(r.memories), self_memories: asRecords(r.self_memories) };
     }
     async searchFull(query, userId, limit = 10, opts = {}) {
@@ -754,7 +770,7 @@ class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return {
             ...r,
             memories: asRecords(r.memories),
@@ -889,9 +905,13 @@ class Client {
         throw truncatedWalk(`stopped after ${MAX_PAGES} pages — the store did not end.`);
     }
     async revisions(userId, opts = {}) {
+        const inc = opts.include;
+        if (inc !== undefined && inc !== null && inc !== "revised" && inc !== "unrevised") {
+            throw new Error(`include must be "revised" or "unrevised", got ${JSON.stringify(inc)}.`);
+        }
         const limit = optRange(opts.limit, "limit", PAGE_LIMIT_MIN, PAGE_LIMIT_MAX);
         const body = {};
-        if (opts.include !== undefined)
+        if (opts.include != null)
             body.include = opts.include;
         if (limit !== undefined)
             body.limit = limit;
@@ -1072,6 +1092,8 @@ class Client {
     errorFromAnswer(res, body, retryAfter, mayBeDeleted = false, unread) {
         const e = parseErrorText(new TextDecoder().decode(body));
         let msg = cleanServerText(e.message) || `HTTP ${res.status}`;
+        if (res.status === 410)
+            msg += ` ${GONE_HINT}`;
         if (unread)
             msg += ` (the error body could not be read: ${cleanServerText(unread, 512)})`;
         const requestId = e.requestId === undefined ? undefined : cleanServerText(e.requestId, 256) || undefined;

package/dist/wontopos.d.ts

@@ -106,6 +106,11 @@ export declare class ConflictError extends WosError {
     readonly conflictsWith?: string;
     constructor(status: number, message: string, requestId?: string, init?: WosErrorInit);
 }
+/** 410 — the model this call named is retired. Retrying cannot succeed: name a live
+ *  model instead (`listModels()` lists them). `deleteStore` still works under a
+ *  retired model. */
+export declare class GoneError extends WosError {
+}
 /** 429 — too many requests. Back off and retry (the client already retries these,
  *  unless `Retry-After` asks for more than 30 seconds). */
 export declare class RateLimitError extends WosError {
@@ -647,9 +652,10 @@ export interface SearchOptions {
 export interface WriteOptions {
     idempotencyKey?: string;
     /**
-     * An image to store alongside the text. Needs a model that lists `images` in its
-     * `listModels()` capabilities; any other refuses the write rather than store the
-     * caption and quietly drop the image.
+     * An image to store alongside the text, read by `add` (and `store`) only: `addTurn`,
+     * `addBulk` and `update` warn about it and do not send it. Needs a model that lists
+     * `images` in its `listModels()` capabilities; any other refuses the write rather than
+     * store the caption and quietly drop the image.
      *
      * A caption is required: the service refuses empty `content` (400) even with an
      * image attached.

package/dist/wontopos.js

@@ -1,4 +1,4 @@
-const VERSION = "2.2.43";
+const VERSION = "2.2.45";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -443,6 +443,8 @@ export class ConflictError extends WosError {
         this.conflictsWith = typeof c === "string" ? c : undefined;
     }
 }
+export class GoneError extends WosError {
+}
 export class RateLimitError extends WosError {
     retryAfter;
     constructor(status, message, requestId, init) {
@@ -453,6 +455,7 @@ export class RateLimitError extends WosError {
 }
 export class ServerError extends WosError {
 }
+const GONE_HINT = "This model is retired; listModels() lists the ones you can use.";
 const STATUS_ERRORS = {
     400: BadRequestError,
     401: AuthenticationError,
@@ -460,6 +463,7 @@ const STATUS_ERRORS = {
     403: PermissionDeniedError,
     404: NotFoundError,
     409: ConflictError,
+    410: GoneError,
     413: BadRequestError,
     422: BadRequestError,
     429: RateLimitError,
@@ -488,7 +492,7 @@ const KNOWN_ENGRAM_KEYS = new Set(["form", "tz"]);
 function checkSearchOpts(opts) {
     checkOpts(opts, KNOWN_SEARCH_KEYS, "search");
     const o = opts;
-    optRange(o.max_images !== undefined ? o.max_images : o.extra?.max_images, "max_images", 0, MAX_IMAGES_MAX);
+    optRange(o.max_images != null ? o.max_images : o.extra?.max_images, "max_images", 0, MAX_IMAGES_MAX);
 }
 function checkOpts(opts, known, what) {
     for (const k of Object.keys(opts)) {
@@ -538,6 +542,17 @@ function warnOnceUnknownKeys(obj, known, warned, message) {
         console.warn(message(k));
     }
 }
+function givenOpts(known) {
+    return Object.fromEntries(Object.entries(known).filter(([, v]) => v !== null));
+}
+const ADD_KEYS = new Set(["idempotencyKey", "image"]);
+const WRITE_KEYS = new Set(["idempotencyKey"]);
+const warnedWriteKeys = new Set();
+function writeKey(opts, takesImage = false) {
+    warnOnceUnknownKeys(opts, takesImage ? ADD_KEYS : WRITE_KEYS, warnedWriteKeys, (k) => `wontopos: write option ${JSON.stringify(k)} is not sent. ` +
+        (takesImage ? "add takes idempotencyKey and image." : "This call takes idempotencyKey only."));
+    return opts.idempotencyKey;
+}
 function warnOnUnknownFilters(filters) {
     warnOnceUnknownKeys(filters, KNOWN_FILTER_KEYS, warnedFilterKeys, (k) => `wontopos: unknown search filter ${JSON.stringify(k)} — the API drops keys it does not know, ` +
         `so this filter has NO effect and the search is wider than you think. ` +
@@ -698,22 +713,22 @@ export class Client {
         if (opts.image !== undefined)
             body.image = normalizeImage(opts.image);
         warnOnUnknownMetadata(metadata);
-        return this.post("/api/v1/memory/store", body, opts.idempotencyKey);
+        return this.post("/api/v1/memory/store", body, writeKey(opts, true));
     }
     async store(content, userId, metadata = {}, opts = {}) {
         return this.add(content, userId, metadata, 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);
+        return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, writeKey(opts));
     }
     async addBulk(content, userId, category = "general", timestamp, opts = {}) {
-        const body = { user_id: this.uid(userId), content, category };
+        const body = { user_id: this.uid(userId), content, category: category ?? "general" };
         if (timestamp)
             body.timestamp = timestamp;
-        return this.post("/api/v1/memory/bulk-store", body, opts.idempotencyKey);
+        return this.post("/api/v1/memory/bulk-store", body, writeKey(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);
+        return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, writeKey(opts));
     }
     async search(query, userId, limit = 10, opts = {}) {
         checkSearchOpts(opts);
@@ -721,7 +736,7 @@ export class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return mergeResults(r);
     }
     async searchSelf(query, userId, limit = 10, opts = {}) {
@@ -730,7 +745,7 @@ export class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return { memories: asRecords(r.memories), self_memories: asRecords(r.self_memories) };
     }
     async searchFull(query, userId, limit = 10, opts = {}) {
@@ -739,7 +754,7 @@ export class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return {
             ...r,
             memories: asRecords(r.memories),
@@ -874,9 +889,13 @@ export class Client {
         throw truncatedWalk(`stopped after ${MAX_PAGES} pages — the store did not end.`);
     }
     async revisions(userId, opts = {}) {
+        const inc = opts.include;
+        if (inc !== undefined && inc !== null && inc !== "revised" && inc !== "unrevised") {
+            throw new Error(`include must be "revised" or "unrevised", got ${JSON.stringify(inc)}.`);
+        }
         const limit = optRange(opts.limit, "limit", PAGE_LIMIT_MIN, PAGE_LIMIT_MAX);
         const body = {};
-        if (opts.include !== undefined)
+        if (opts.include != null)
             body.include = opts.include;
         if (limit !== undefined)
             body.limit = limit;
@@ -1057,6 +1076,8 @@ export class Client {
     errorFromAnswer(res, body, retryAfter, mayBeDeleted = false, unread) {
         const e = parseErrorText(new TextDecoder().decode(body));
         let msg = cleanServerText(e.message) || `HTTP ${res.status}`;
+        if (res.status === 410)
+            msg += ` ${GONE_HINT}`;
         if (unread)
             msg += ` (the error body could not be read: ${cleanServerText(unread, 512)})`;
         const requestId = e.requestId === undefined ? undefined : cleanServerText(e.requestId, 256) || undefined;

package/package.json

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