wontopos 2.2.12 → 2.2.13

package/dist/wontopos.js

@@ -32,12 +32,17 @@
  * 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.12";
+const VERSION = "2.2.13";
 const USER_AGENT = `wontopos-node/${VERSION}`;
 const DEFAULT_BASE_URL = "https://api.wontopos.com";
 const DEFAULT_MODEL = "tablet-1";
-/** Statuses where the request was NOT processed, so retrying is always safe. */
-const RETRY_STATUSES = new Set([429, 502, 503]);
+/** 429 = rate-limited BEFORE processing → always safe to retry (no write, no bill). */
+const RETRY_ALWAYS = new Set([429]);
+/** 502/503 are ambiguous for a write (gateway may return them AFTER the backend
+ *  processed + billed the request), so retry them only for idempotent methods —
+ *  a retried POST could double-store / double-bill. */
+const RETRY_IF_IDEMPOTENT = new Set([502, 503]);
+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"]);
 /** Refuse to buffer absurd responses (real ones are a few KB) — protects the
  * process if a self-hosted baseUrl points somewhere broken or hostile. */
@@ -153,7 +158,11 @@ export class Client {
             throw new Error(`invalid model name: ${JSON.stringify(this.model)} (letters, digits, '.', '_', '-' only)`);
         }
         this.defaultUser = opts.userId || DEFAULT_USER;
-        this.maxRetries = Math.max(0, opts.maxRetries ?? 2);
+        // Coerce a non-finite maxRetries (NaN/Infinity) back to the default — otherwise
+        // NaN makes `attempts = NaN + 1` and the loop runs zero requests then throws
+        // "retries exhausted"; Infinity would retry forever.
+        const mr = opts.maxRetries;
+        this.maxRetries = typeof mr === "number" && Number.isFinite(mr) ? Math.max(0, Math.floor(mr)) : 2;
         this.headers = {
             "X-API-Key": this.apiKey,
             "Content-Type": "application/json",
@@ -165,8 +174,9 @@ export class Client {
         // An API key on plain HTTP travels readable by anyone on the path. Loopback
         // is fine (local dev / self-hosted on the same box); anything else gets a
         // warning, not an error, so private-network gateways keep working.
-        const host = this.base.replace(/^https?:\/\//, "").split(/[/:]/)[0].toLowerCase();
-        if (this.base.startsWith("http://") && !LOOPBACK_HOSTS.has(host)) {
+        const host = this.base.replace(/^https?:\/\//i, "").split(/[/:]/)[0].toLowerCase();
+        // Scheme compare is case-insensitive — `HTTP://` connects in plaintext too.
+        if (/^http:\/\//i.test(this.base) && !LOOPBACK_HOSTS.has(host)) {
             console.warn("wontopos: baseUrl uses plain HTTP on a non-local host, so the API key travels unencrypted. Use https://.");
         }
     }
@@ -174,10 +184,13 @@ export class Client {
      * keys out of source code. Node/Bun/Deno-with-env only. */
     static fromEnv(opts = {}) {
         const env = globalThis?.process?.env;
-        const key = env?.WONTOPOS_API_KEY ?? env?.WOS_API_KEY;
-        if (!key || !key.trim())
+        // First env var with a NON-EMPTY value wins — an empty WONTOPOS_API_KEY must
+        // not shadow a valid WOS_API_KEY (`??` only skips null/undefined, not "").
+        const key = [env?.WONTOPOS_API_KEY, env?.WOS_API_KEY].find((v) => v && v.trim());
+        if (!key)
             throw new Error("set WONTOPOS_API_KEY (or WOS_API_KEY) in the environment");
-        return new Client({ apiKey: key, ...opts });
+        // apiKey LAST so a stray apiKey in opts can't override the env key.
+        return new Client({ ...opts, apiKey: key });
     }
     /** Never expose the key: `JSON.stringify(client)` gets the redacted view. */
     toJSON() {
@@ -244,7 +257,9 @@ export class Client {
     // ----- read -----
     /** Semantic search over a store's memories. Returns memories, most relevant first. */
     async search(query, userId, limit = 10, opts = {}) {
-        const r = await this.post("/api/v1/memory/search", { user_id: this.uid(userId), query, max_results: limit, ...opts });
+        // Reserved fields win over ...opts: an app that forwards untrusted input as
+        // opts must not be able to override the store (user_id), query, or limit.
+        const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
         return (r.memories ?? []);
     }
     /** One-call LLM context: short-term turns + long-term matches + surrounding context. */
@@ -289,13 +304,17 @@ export class Client {
      */
     async *iterMemories(userId, opts = {}) {
         let cursor;
+        const seen = new Set();
         for (;;) {
             const page = await this.listMemories(userId, { limit: opts.pageSize ?? 100, cursor });
             for (const m of page.memories ?? [])
                 yield m;
-            cursor = page.next_cursor ?? undefined;
-            if (!cursor)
+            const next = page.next_cursor ?? undefined;
+            // Stop on last page OR a server that repeats a cursor (would loop forever).
+            if (!next || seen.has(next))
                 break;
+            seen.add(next);
+            cursor = next;
         }
     }
     /** Collect ALL of a store's memories into an array (original text + metadata, no vectors). */
@@ -333,8 +352,8 @@ export class Client {
     }
     /** Delete a store and ALL its memories. Returns `{ user_id, status }`. */
     deleteStore(userId) {
-        if (!userId)
-            throw new Error("userId is required — deleteStore never falls back to the default store.");
+        if (!userId || !userId.trim())
+            throw new Error("userId is required (non-blank) — deleteStore never falls back to the default store.");
         return this.request("DELETE", "/api/v1/memory/collection", { user_id: userId });
     }
     // ----- speakers (who said it) -----
@@ -366,8 +385,8 @@ export class Client {
     /** Delete ALL memories for a store (GDPR erase). `userId` is required on purpose -
      * this is destructive, so it never falls back to the default store. */
     deleteAll(userId) {
-        if (!userId)
-            throw new Error("userId is required for deleteAll — it never falls back to the default store.");
+        if (!userId || !userId.trim())
+            throw new Error("userId is required (non-blank) for deleteAll — a blank/whitespace id would wipe the default store.");
         return this.post("/api/v1/memory/forget", { user_id: userId });
     }
     // ----- internal -----
@@ -380,6 +399,10 @@ export class Client {
             const s = Number(retryAfter);
             if (Number.isFinite(s) && s >= 0)
                 return Math.min(30_000, s * 1000);
+            // HTTP-date form (RFC 9110), e.g. "Wed, 21 Oct 2015 07:28:00 GMT".
+            const t = Date.parse(retryAfter);
+            if (Number.isFinite(t))
+                return Math.min(30_000, Math.max(0, t - Date.now()));
         }
         return Math.min(8_000, 500 * 2 ** attempt) + Math.random() * 250;
     }
@@ -441,18 +464,36 @@ export class Client {
                 }
                 throw new APIConnectionError(0, timedOut ? `request timed out after ${this.timeoutMs}ms` : `network error: ${e?.message ?? e}`);
             }
-            clearTimeout(timer);
-            if (RETRY_STATUSES.has(res.status) && attempt + 1 < attempts) {
+            const retryable = RETRY_ALWAYS.has(res.status) ||
+                (RETRY_IF_IDEMPOTENT.has(res.status) && IDEMPOTENT_METHODS.has(method.toUpperCase()));
+            if (retryable && attempt + 1 < attempts) {
+                clearTimeout(timer);
                 const retryAfter = res.headers.get("Retry-After");
                 void res.body?.cancel();
                 await new Promise((r) => setTimeout(r, this.backoffMs(attempt, retryAfter)));
                 continue;
             }
             if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
+                clearTimeout(timer);
                 throw new WosError(res.status, "unexpected redirect — refused (the API key never follows a redirect). Check baseUrl: exact host, https://.");
             }
             this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
-            const text = await this.readCapped(res);
+            // Keep the abort timer alive THROUGH the body read: fetch resolves on
+            // headers, so a server that sends headers then trickles/hangs the body
+            // would otherwise stall forever. An abort mid-body surfaces as a timeout.
+            let text;
+            try {
+                text = await this.readCapped(res);
+            }
+            catch (e) {
+                if (e?.name === "AbortError" || ctrl.signal.aborted) {
+                    throw new APIConnectionError(0, `request timed out after ${this.timeoutMs}ms`);
+                }
+                throw e;
+            }
+            finally {
+                clearTimeout(timer);
+            }
             if (!res.ok) {
                 // Server returns either Anthropic-style envelope
                 //   {"type":"error","error":{"type":...,"message":...,"request_id":...}}

package/package.json

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