wontopos 2.2.12 → 2.2.14

package/dist/wontopos.d.ts

@@ -22,9 +22,10 @@
  * Pure semantic retrieval — no keyword/BM25 matching, so it works the SAME in every
  * language. Storing and searching call no LLM; you only pay for embeddings.
  *
- * Reliability: every call retries transient failures (429 / 502 / 503 and
- * connection errors) with exponential backoff + jitter, honoring `Retry-After`.
- * Tune with `maxRetries` (0 disables) and `timeoutMs`.
+ * Reliability: every call retries transient failures with exponential backoff +
+ * jitter, honoring `Retry-After` — 429 always; 502/503 and connection errors only
+ * when a retry can never double-process a write (idempotent calls, or a failure
+ * at connect time). Tune with `maxRetries` (0 disables) and `timeoutMs`.
  *
  * Security posture (not configurable off): redirects are refused so the API key
  * can never follow one to another host; responses over 64MB are refused; the key
@@ -226,8 +227,9 @@ export interface ClientOptions {
     /** Default store for every call. Override per call by passing `userId`. Defaults
      * to the account's built-in `default` store. */
     userId?: string;
-    /** How many times to retry transient failures (429/502/503 and connection
-     * errors) before throwing. 0 disables retries (default 2). */
+    /** How many times to retry transient failures before throwing — 429 always;
+     * 502/503 and connection errors only when a retry can never double-process a
+     * write. 0 disables retries (default 2). */
     maxRetries?: number;
 }
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */

package/dist/wontopos.js

@@ -22,9 +22,10 @@
  * Pure semantic retrieval — no keyword/BM25 matching, so it works the SAME in every
  * language. Storing and searching call no LLM; you only pay for embeddings.
  *
- * Reliability: every call retries transient failures (429 / 502 / 503 and
- * connection errors) with exponential backoff + jitter, honoring `Retry-After`.
- * Tune with `maxRetries` (0 disables) and `timeoutMs`.
+ * Reliability: every call retries transient failures with exponential backoff +
+ * jitter, honoring `Retry-After` — 429 always; 502/503 and connection errors only
+ * when a retry can never double-process a write (idempotent calls, or a failure
+ * at connect time). Tune with `maxRetries` (0 disables) and `timeoutMs`.
  *
  * Security posture (not configurable off): redirects are refused so the API key
  * can never follow one to another host; responses over 64MB are refused; the key
@@ -32,18 +33,54 @@
  * 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.14";
 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. */
 const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
 /** Model names travel in a header — only header-safe characters. */
 const MODEL_RE = /^[A-Za-z0-9._-]+$/;
+/** 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
+ * may already have processed (and billed) the request, so they're excluded. */
+const CONNECT_FAIL_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "EADDRNOTAVAIL",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+/** Walk an error's `cause` chain (and AggregateError members — happy-eyeballs
+ * connects) looking for a connect-level failure code. */
+function isConnectFailure(e) {
+    const stack = [e];
+    for (let steps = 0; stack.length && steps < 24; steps++) {
+        const cur = stack.pop();
+        if (!cur || typeof cur !== "object")
+            continue;
+        if (typeof cur.code === "string" && CONNECT_FAIL_CODES.has(cur.code))
+            return true;
+        if (cur.cause)
+            stack.push(cur.cause);
+        if (Array.isArray(cur.errors))
+            stack.push(...cur.errors.slice(0, 8));
+    }
+    return false;
+}
 /** `wos-abc...wxyz` — enough to tell keys apart, never enough to use. */
 function maskKey(key) {
     return key.length > 12 ? `${key.slice(0, 4)}...${key.slice(-4)}` : "***";
@@ -147,13 +184,21 @@ export class Client {
             throw new Error("apiKey contains whitespace - check for a stray newline or paste error");
         this.apiKey = key;
         this.base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        // Coerce a non-finite or non-positive timeout back to the default — NaN
+        // (e.g. Number() of an unset env var) would otherwise make the abort timer
+        // fire immediately and every request "time out after NaNms".
+        const tm = opts.timeoutMs;
+        this.timeoutMs = typeof tm === "number" && Number.isFinite(tm) && tm > 0 ? tm : 30_000;
         this.model = opts.model ?? DEFAULT_MODEL;
         if (this.model && !MODEL_RE.test(this.model)) {
             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 +210,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 +220,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 +293,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 +340,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 +388,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 +421,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 +435,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;
     }
@@ -435,24 +494,51 @@ export class Client {
                 clearTimeout(timer);
                 // Timeouts are ambiguous (the write may have landed) — don't retry those.
                 const timedOut = e?.name === "AbortError" || ctrl.signal.aborted;
-                if (!timedOut && attempt + 1 < attempts) {
+                // Other network errors retry only when a retry can't double-process a
+                // write: idempotent methods always; writes only for connect-level
+                // failures (the request never reached the server). A mid-stream drop on
+                // a POST may already have stored + billed server-side.
+                const safe = IDEMPOTENT_METHODS.has(method.toUpperCase()) || isConnectFailure(e);
+                if (!timedOut && safe && attempt + 1 < attempts) {
                     await new Promise((r) => setTimeout(r, this.backoffMs(attempt)));
                     continue;
                 }
                 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`);
+                }
+                if (e instanceof WosError)
+                    throw e; // the size cap — already the right error
+                // A drop while READING the body is a transport failure — surface it as
+                // APIConnectionError, not a raw fetch TypeError. Ambiguous, never retried.
+                throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
+            }
+            finally {
+                clearTimeout(timer);
+            }
             if (!res.ok) {
                 // Server returns either Anthropic-style envelope
                 //   {"type":"error","error":{"type":...,"message":...,"request_id":...}}
@@ -479,7 +565,16 @@ export class Client {
                 }
                 throw errorFor(res.status, msg, requestId);
             }
-            return text ? JSON.parse(text) : null;
+            if (!text)
+                return null;
+            try {
+                return JSON.parse(text);
+            }
+            catch (e) {
+                // A 2xx with a corrupt body is a real failure — surface it, don't leak
+                // a raw SyntaxError (parity with the Rust SDK).
+                throw new WosError(res.status, `invalid JSON in response: ${e?.message ?? e}`);
+            }
         }
         throw new WosError(0, "retries exhausted"); // unreachable; keeps the compiler happy
     }

package/package.json

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