wontopos 2.2.13 → 2.2.15

package/README.md

@@ -22,7 +22,7 @@ const ctx = await mem.recall("what does alice drink?", "alice");
 
 ## Methods
 
-`add` · `addTurn` · `addBulk` · `update` · `search` · `recall` · `history` · `stats` · `delete` · `deleteAll`
+`add` · `addTurn` · `addBulk` · `update` · `search` · `recall` · `history` · `stats` · `get` · `listMemories` · `delete` · `deleteAll`
 
 All methods take `{ userId }` — it names the **store**: one isolated memory space per end-user, agent, or topic, then per account. WHO said each memory inside a store is the `speaker` tag below — storing the assistant's own words never needs a separate id.
 

package/dist/wontopos.d.ts

@@ -22,9 +22,14 @@
  * 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`, or per
+ * call site via the `withTimeout()` / `withRetries()` clones.
+ *
+ * Debugging: set `WONTOPOS_LOG=debug` to log method/path/status/timing/retries
+ * to stderr — never memory content, request bodies, or the API key.
  *
  * 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 +231,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`. */
@@ -262,6 +268,11 @@ export declare class Client {
     withModel(model: string): Client;
     /** A client bound to `userId` as its default store (everything else kept). */
     withUser(userId: string): Client;
+    /** A client with a different per-request timeout in ms (everything else kept).
+     * `mem.withTimeout(120_000).addBulk(bigBlob)` — this slow call only. */
+    withTimeout(timeoutMs: number): Client;
+    /** A client with a different retry budget (everything else kept). 0 disables retries. */
+    withRetries(maxRetries: number): Client;
     /** Store one memory. `metadata` optional (e.g. { event_date: "2026-03-01" }).
      * `metadata.speaker`: "me" = the assistant's own words, or a person's name (up to 50 per store). */
     add(content: string, userId?: string, metadata?: Record<string, unknown>): Promise<StoreResult>;
@@ -283,6 +294,11 @@ export declare class Client {
     history(userId?: string): Promise<HistoryTurn[]>;
     /** Memory counts for a store: { total_memories, short_term_turns }. */
     stats(userId?: string): Promise<StatsResult>;
+    /** Fetch ONE memory by id — the original text + metadata, never the vector.
+     * The id is what `add`/`store` or `listMemories` returned. Same visibility as
+     * `listMemories`: an id from another store, a decomposed atom sentence, or an
+     * invalidated memory rejects with `NotFoundError`. `userId` optional (default store). */
+    get(userId: string | undefined, memoryId: string): Promise<Memory>;
     /** List a store's stored memories — the original text plus metadata, never the
      * vector. Paginated: pass the returned `next_cursor` back as `cursor` for the next
      * page; a `null` cursor means the last page. Use it to browse or export a store.

package/dist/wontopos.js

@@ -22,9 +22,14 @@
  * 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`, or per
+ * call site via the `withTimeout()` / `withRetries()` clones.
+ *
+ * Debugging: set `WONTOPOS_LOG=debug` to log method/path/status/timing/retries
+ * to stderr — never memory content, request bodies, or the API key.
  *
  * 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,8 +37,23 @@
  * 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 USER_AGENT = `wontopos-node/${VERSION}`;
+const VERSION = "2.2.15";
+/** 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). */
+const RUNTIME = (() => {
+    const p = globalThis?.process;
+    return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
+})();
+const USER_AGENT = `wontopos-node/${VERSION}${RUNTIME}`;
+/** Wire-level debug logging: set WONTOPOS_LOG=debug. Logs method/path/status/
+ * timing/retries to stderr — NEVER memory content, request bodies, or the key. */
+function logDebug(msg) {
+    const env = globalThis?.process?.env;
+    if (typeof env?.WONTOPOS_LOG === "string" && env.WONTOPOS_LOG.toLowerCase() === "debug") {
+        console.error(`wontopos: ${msg}`);
+    }
+}
 const DEFAULT_BASE_URL = "https://api.wontopos.com";
 const DEFAULT_MODEL = "tablet-1";
 /** 429 = rate-limited BEFORE processing → always safe to retry (no write, no bill). */
@@ -49,6 +69,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 +203,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)`);
@@ -227,6 +282,15 @@ export class Client {
     withUser(userId) {
         return this.clone({ userId });
     }
+    /** A client with a different per-request timeout in ms (everything else kept).
+     * `mem.withTimeout(120_000).addBulk(bigBlob)` — this slow call only. */
+    withTimeout(timeoutMs) {
+        return this.clone({ timeoutMs });
+    }
+    /** A client with a different retry budget (everything else kept). 0 disables retries. */
+    withRetries(maxRetries) {
+        return this.clone({ maxRetries });
+    }
     // ----- write -----
     // `userId` is optional in every call below - omit it to use the client's default
     // store (set via `new Client({ apiKey, userId })` or `withUser`).
@@ -279,6 +343,18 @@ export class Client {
     stats(userId) {
         return this.post("/api/v1/memory/stats", { user_id: this.uid(userId) });
     }
+    /** Fetch ONE memory by id — the original text + metadata, never the vector.
+     * The id is what `add`/`store` or `listMemories` returned. Same visibility as
+     * `listMemories`: an id from another store, a decomposed atom sentence, or an
+     * invalidated memory rejects with `NotFoundError`. `userId` optional (default store). */
+    get(userId, memoryId) {
+        // Sync throw (same shape as `delete`), so a missing id fails loudly even
+        // when the caller forgets to await.
+        if (!memoryId || typeof memoryId !== "string") {
+            throw new Error("memoryId is required — the id that add/store or listMemories returned.");
+        }
+        return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId }).then((r) => (r.memory ?? {}));
+    }
     /** List a store's stored memories — the original text plus metadata, never the
      * vector. Paginated: pass the returned `next_cursor` back as `cursor` for the next
      * page; a `null` cursor means the last page. Use it to browse or export a store.
@@ -439,7 +515,11 @@ export class Client {
     }
     async request(method, path, body) {
         const attempts = this.maxRetries + 1;
+        // Debug logging shows the path WITHOUT its query string — a query can carry
+        // a store id (listSpeakers), and logs must never carry data.
+        const logPath = path.split("?")[0];
         for (let attempt = 0; attempt < attempts; attempt++) {
+            const start = Date.now();
             const ctrl = new AbortController();
             const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
             let res;
@@ -458,8 +538,15 @@ 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) {
-                    await new Promise((r) => setTimeout(r, this.backoffMs(attempt)));
+                // 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) {
+                    const delay = this.backoffMs(attempt);
+                    logDebug(`${method} ${logPath}: ${e?.code ?? e?.name ?? "network error"} — retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
+                    await new Promise((r) => setTimeout(r, delay));
                     continue;
                 }
                 throw new APIConnectionError(0, timedOut ? `request timed out after ${this.timeoutMs}ms` : `network error: ${e?.message ?? e}`);
@@ -470,7 +557,9 @@ export class Client {
                 clearTimeout(timer);
                 const retryAfter = res.headers.get("Retry-After");
                 void res.body?.cancel();
-                await new Promise((r) => setTimeout(r, this.backoffMs(attempt, retryAfter)));
+                const delay = this.backoffMs(attempt, retryAfter);
+                logDebug(`${method} ${logPath} -> ${res.status} — retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
+                await new Promise((r) => setTimeout(r, delay));
                 continue;
             }
             if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
@@ -489,11 +578,16 @@ 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);
             }
+            logDebug(`${method} ${logPath} -> ${res.status} in ${Date.now() - start}ms (attempt ${attempt + 1}/${attempts})`);
             if (!res.ok) {
                 // Server returns either Anthropic-style envelope
                 //   {"type":"error","error":{"type":...,"message":...,"request_id":...}}
@@ -520,7 +614,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.15",
   "description": "Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.",
   "keywords": [
     "memory",