wontopos 2.2.13 → 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,7 +33,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.13";
+const VERSION = "2.2.14";
 const USER_AGENT = `wontopos-node/${VERSION}`;
 const DEFAULT_BASE_URL = "https://api.wontopos.com";
 const DEFAULT_MODEL = "tablet-1";
@@ -49,6 +50,37 @@ const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
 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)}` : "***";
@@ -152,7 +184,11 @@ 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)`);
@@ -458,7 +494,12 @@ 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;
                 }
@@ -489,7 +530,11 @@ export class Client {
                 if (e?.name === "AbortError" || ctrl.signal.aborted) {
                     throw new APIConnectionError(0, `request timed out after ${this.timeoutMs}ms`);
                 }
-                throw e;
+                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);
@@ -520,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.13",
+  "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",