wontopos 2.2.25 → 2.2.26

package/README.md

@@ -52,7 +52,13 @@ registration and never counts against it.
 ## Recall caching
 
 Opt in per search and repeated or extended queries reuse the previous result
-at 10% of the normal rate (Tablet and Scroll models):
+at 10% of the normal rate (Tablet and Scroll models).
+
+It is not free to turn on: the FIRST call writes the cache and bills the query
+tokens at 2x for a `5m` TTL, 3x for `1h`. Only hits inside the TTL bill at 0.1x.
+So it pays for a query you repeat or extend, and costs more for one you issue
+once — do not switch it on globally. Any write to the store invalidates its cache
+at once, so a hit can never predate a new memory.
 
 ```ts
 const hits = await mem.search("...the conversation so far...", "alice", 10,
@@ -74,6 +80,27 @@ Built in, no configuration needed:
   meaning "delete everything"; wiping a store is only ever the explicit
   `deleteAll(userId)` / `deleteStore(userId)`.
 
+### 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:
+
+```ts
+import { ProxyAgent } from "undici";
+
+const agent = new ProxyAgent(process.env.HTTPS_PROXY!);
+const mem = new Client({
+  apiKey: process.env.WONTOPOS_API_KEY!,
+  fetch: (url, init) => fetch(url, { ...init, dispatcher: agent } as any),
+});
+```
+
+The same option is how you add instrumentation or drive the client without a
+network in tests. It replaces the transport, not the client's rules — retries,
+timeouts, redirect refusal and the response cap all still apply.
+
 ## Security
 
 Built in, none of it configurable off:

package/dist/wontopos.d.ts

@@ -286,7 +286,9 @@ export interface SearchFilters {
 export declare function _resetFilterWarnings(): void;
 /** Known `search` options; extra fields pass through to the API untouched. */
 export interface SearchOptions {
-    /** Recall caching: repeated/extended queries within the TTL bill at 0.1×. */
+    /** Recall caching. A hit inside the TTL bills at 0.1× — but the FIRST call
+     *  writes the cache and bills the query tokens at 2× (`5m`) or 3× (`1h`), so
+     *  this only pays for a query you repeat or extend. Do not enable it globally. */
     cache_control?: {
         ttl: "5m" | "1h";
     };
@@ -336,6 +338,26 @@ export interface ClientOptions {
      *  key on an options object is not an error in TS at runtime). Both names work;
      *  `maxRetries` wins if somehow both are given. */
     retries?: number;
+    /** The `fetch` used for every request (default: the global `fetch`).
+     *
+     *  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:
+     *
+     *      import { ProxyAgent } from "undici";
+     *      const agent = new ProxyAgent(process.env.HTTPS_PROXY!);
+     *      const mem = new Client({
+     *        apiKey,
+     *        fetch: (url, init) => fetch(url, { ...init, dispatcher: agent } as any),
+     *      });
+     *
+     *  It is also how you add instrumentation or drive the client in a test without
+     *  a network. Retries, timeouts, redirect refusal and the size cap all still
+     *  apply — this replaces the transport, not the client's rules. */
+    fetch?: typeof fetch;
 }
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export declare class Client {
@@ -345,6 +367,9 @@ export declare class Client {
     private readonly apiKey;
     private readonly model;
     private readonly maxRetries;
+    /** Transport. Held as a field (not read off `globalThis` per call) so a caller
+     * who passes one gets it for every request, including from cloned clients. */
+    private readonly fetchImpl;
     /** The store every call uses unless one passes `userId`. */
     private readonly defaultUser;
     private _rateLimit;

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.25";
+const VERSION = "2.2.26";
 /** 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). */
@@ -310,6 +310,9 @@ export class Client {
     apiKey;
     model;
     maxRetries;
+    /** Transport. Held as a field (not read off `globalThis` per call) so a caller
+     * who passes one gets it for every request, including from cloned clients. */
+    fetchImpl;
     /** The store every call uses unless one passes `userId`. */
     defaultUser;
     _rateLimit = null;
@@ -344,6 +347,17 @@ export class Client {
         // "retries exhausted"; Infinity would retry forever.
         const mr = opts.maxRetries ?? opts.retries;
         this.maxRetries = typeof mr === "number" && Number.isFinite(mr) ? Math.max(0, Math.floor(mr)) : 2;
+        // Bind the global so `fetch` is not called as a method of `globalThis`, which
+        // throws "Illegal invocation" on some runtimes. A caller-supplied fetch is
+        // taken as given — it is already whatever they meant to hand us.
+        const f = opts.fetch;
+        if (f !== undefined && typeof f !== "function") {
+            throw new Error("fetch must be a function (a fetch-compatible transport)");
+        }
+        this.fetchImpl = f ?? (globalThis.fetch ? globalThis.fetch.bind(globalThis) : undefined);
+        if (typeof this.fetchImpl !== "function") {
+            throw new Error("no fetch available in this runtime — pass one as `fetch` (Node 18+ has it built in; older Node needs undici)");
+        }
         this.headers = {
             "X-API-Key": this.apiKey,
             "Content-Type": "application/json",
@@ -395,6 +409,10 @@ export class Client {
             model: this.model,
             userId: this.defaultUser,
             maxRetries: this.maxRetries,
+            // Carry the transport across clones. Without this, `withModel(...)` and
+            // friends would silently fall back to the global fetch and a proxy-bound
+            // client would stop connecting the moment it was cloned.
+            fetch: this.fetchImpl,
             ...overrides,
         });
     }
@@ -710,7 +728,7 @@ export class Client {
             const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
             let res;
             try {
-                res = await fetch(`${this.base}${path}`, {
+                res = await this.fetchImpl(`${this.base}${path}`, {
                     method,
                     headers: extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers,
                     body: body === undefined ? undefined : JSON.stringify(body),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.25",
+  "version": "2.2.26",
   "description": "Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.",
   "keywords": [
     "memory",