wontopos 2.2.44 → 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";
@@ -206,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

@@ -652,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

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 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.44";
+const VERSION = "2.2.45";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -508,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)) {
@@ -558,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. ` +
@@ -718,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);
@@ -741,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 = {}) {
@@ -750,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 = {}) {
@@ -759,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),
@@ -894,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;

package/dist/wontopos.d.ts

@@ -652,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.44";
+const VERSION = "2.2.45";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -492,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)) {
@@ -542,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. ` +
@@ -702,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);
@@ -725,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 = {}) {
@@ -734,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 = {}) {
@@ -743,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),
@@ -878,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.44",
+  "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",