wontopos 2.2.7 → 2.2.8

package/README.md

@@ -55,9 +55,26 @@ const hits = await mem.search("...the conversation so far...", "alice", 10,
                               { cache_control: { ttl: "5m" } });  // or "1h"
 ```
 
+## Reliability
+
+Built in, no configuration needed:
+
+- **Automatic retries** — 429 / 502 / 503 and connection errors retry twice with
+  exponential backoff + jitter, honoring the server's `Retry-After`. Tune with
+  `new Client({ maxRetries })`; `0` disables.
+- **Redirects refused** — the API key never follows a 3xx to another host.
+- **Timeouts** — 30s per attempt by default (`timeoutMs`).
+- **Key never in logs** — `JSON.stringify(client)` and Node's `console.log(client)`
+  print a masked key.
+- **Wipe guard** — `delete()` without a `memoryId` throws instead of silently
+  meaning "delete everything"; wiping a store is only ever the explicit
+  `deleteAll(userId)` / `deleteStore(userId)`.
 
 ## Errors
 
+Any non-2xx response throws `WosError` with `status`, `message`, and — when the
+server sent one — `requestId` (include it when contacting support).
+
 ```ts
 import { Client, WosError } from "wontopos";
 
@@ -66,8 +83,8 @@ try {
 } catch (e) {
   if (e instanceof WosError) {
     if (e.status === 401) console.error("API key invalid or revoked");
-    else if (e.status === 429) console.error("Rate limited");
-    else console.error(e.status, e.message);
+    else if (e.status === 429) console.error("Rate limited");   // already retried twice by then
+    else console.error(e.status, e.message, e.requestId);
   }
 }
 ```
@@ -81,7 +98,18 @@ const mem = new Client({ apiKey: "...", baseUrl: "https://wos.your-host.com" });
 ## Links
 
 - Homepage: <https://wontopos.com>
-- API reference: <https://wontopos.com/why> (Developers tab)
-- Repo: <https://github.com/Irina1920/Wos_API>
+- API reference: <https://wontopos.com/en/why> (Developers tab)
+
+## Changelog
+
+- **2.2.8** — reliability + hardening: automatic retries (429/502/503 + connection
+  errors, backoff + jitter, honors `Retry-After`), redirects refused, key masked in
+  `toJSON`/inspect, `WosError.requestId`, guard against `delete()` without
+  `memoryId`, plain-HTTP warning, `User-Agent`.
+- **2.2.7** — speakers: `addSpeaker` / `listSpeakers` / `removeSpeaker`.
+- **2.2.6** — docs: `userId` = store, clarified everywhere.
+- **2.2.5** — docs: speakers + recall caching sections.
+- **2.2.4** — Python/TypeScript/Rust converge on one version; all three now
+  release in lockstep (same version, same surface). Patch releases are additive.
 
 License: MIT.

package/dist/wontopos.d.ts

@@ -21,15 +21,24 @@
  *
  * 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`.
+ * Redirects are refused so the API key can never follow one to another host.
+ * Tune with `maxRetries` (0 disables) and `timeoutMs`.
  */
 export declare class WosError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    /** The server's id for the request when it sent one — include it when contacting support. */
+    readonly requestId?: string;
+    constructor(status: number, message: string, requestId?: string);
 }
 export interface Memory {
     id?: string;
     content?: string;
     score?: number;
+    /** WHO said it: "me" (the assistant) or a registered person's name. Absent = untagged. */
+    speaker?: string;
     [key: string]: unknown;
 }
 export interface RecallResult {
@@ -58,13 +67,16 @@ export interface ClientOptions {
     apiKey: string;
     /** API base URL (defaults to the hosted service). */
     baseUrl?: string;
-    /** Per-request timeout in ms (default 30000). */
+    /** Per-request timeout in ms, applied to each retry attempt (default 30000). */
     timeoutMs?: number;
     /** Default model for every call (sent as `X-WOS-Model`). See `listModels()`. */
     model?: string;
     /** 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). */
+    maxRetries?: number;
 }
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export declare class Client {
@@ -73,11 +85,15 @@ export declare class Client {
     private readonly timeoutMs;
     private readonly apiKey;
     private readonly model;
+    private readonly maxRetries;
     /** The store every call uses unless one passes `userId`. */
     private readonly defaultUser;
     constructor(opts: ClientOptions);
+    /** Never expose the key: `JSON.stringify(client)` gets the redacted view. */
+    toJSON(): Record<string, string>;
     /** Resolve a call's store: the explicit userId, else the client default. */
     private uid;
+    private clone;
     /**
      * A client that uses `model` (sent as `X-WOS-Model`). Use it to set the default
      * (`new Client({ apiKey, model })`) or to override one call
@@ -135,6 +151,8 @@ export declare class Client {
      * this is destructive, so it never falls back to the default store. */
     deleteAll(userId: string): Promise<any>;
     private post;
+    /** Seconds→ms to sleep before retry `attempt` (0-based). Honors Retry-After. */
+    private backoffMs;
     private request;
 }
 /** Back-compat alias: older code used `WME`. */

package/dist/wontopos.js

@@ -21,15 +21,32 @@
  *
  * 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`.
+ * Redirects are refused so the API key can never follow one to another host.
+ * Tune with `maxRetries` (0 disables) and `timeoutMs`.
  */
+const VERSION = "2.2.8";
+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]);
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
+/** `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)}` : "***";
+}
 export class WosError extends Error {
     status;
-    constructor(status, message) {
-        super(`[${status}] ${message}`);
+    /** The server's id for the request when it sent one — include it when contacting support. */
+    requestId;
+    constructor(status, message, requestId) {
+        super(`[${status}] ${message}${requestId ? ` (request_id: ${requestId})` : ""}`);
         this.name = "WosError";
         this.status = status;
+        this.requestId = requestId;
     }
 }
 const DEFAULT_USER = "default";
@@ -40,6 +57,7 @@ export class Client {
     timeoutMs;
     apiKey;
     model;
+    maxRetries;
     /** The store every call uses unless one passes `userId`. */
     defaultUser;
     constructor(opts) {
@@ -50,25 +68,57 @@ export class Client {
         this.timeoutMs = opts.timeoutMs ?? 30_000;
         this.model = opts.model ?? DEFAULT_MODEL;
         this.defaultUser = opts.userId || DEFAULT_USER;
-        this.headers = { "X-API-Key": opts.apiKey, "Content-Type": "application/json" };
+        this.maxRetries = Math.max(0, opts.maxRetries ?? 2);
+        this.headers = {
+            "X-API-Key": opts.apiKey,
+            "Content-Type": "application/json",
+            // Browsers silently drop User-Agent (forbidden header) — harmless.
+            "User-Agent": USER_AGENT,
+        };
         if (this.model)
             this.headers["X-WOS-Model"] = this.model;
+        // 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)) {
+            console.warn("wontopos: baseUrl uses plain HTTP on a non-local host, so the API key travels unencrypted. Use https://.");
+        }
+    }
+    /** Never expose the key: `JSON.stringify(client)` gets the redacted view. */
+    toJSON() {
+        return { baseUrl: this.base, model: this.model, userId: this.defaultUser, apiKey: maskKey(this.apiKey) };
+    }
+    /** Never expose the key: Node's `console.log(client)` gets the redacted view. */
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return `Client(${this.base}, model=${this.model}, userId=${this.defaultUser}, apiKey=${maskKey(this.apiKey)})`;
     }
     /** Resolve a call's store: the explicit userId, else the client default. */
     uid(userId) {
         return userId || this.defaultUser;
     }
+    clone(overrides) {
+        return new Client({
+            apiKey: this.apiKey,
+            baseUrl: this.base,
+            timeoutMs: this.timeoutMs,
+            model: this.model,
+            userId: this.defaultUser,
+            maxRetries: this.maxRetries,
+            ...overrides,
+        });
+    }
     /**
      * A client that uses `model` (sent as `X-WOS-Model`). Use it to set the default
      * (`new Client({ apiKey, model })`) or to override one call
      * (`client.withModel("tablet-1").recall(...)`).
      */
     withModel(model) {
-        return new Client({ apiKey: this.apiKey, baseUrl: this.base, timeoutMs: this.timeoutMs, model, userId: this.defaultUser });
+        return this.clone({ model });
     }
     /** A client bound to `userId` as its default store (everything else kept). */
     withUser(userId) {
-        return new Client({ apiKey: this.apiKey, baseUrl: this.base, timeoutMs: this.timeoutMs, model: this.model, userId });
+        return this.clone({ userId });
     }
     // ----- write -----
     // `userId` is optional in every call below - omit it to use the client's default
@@ -123,10 +173,7 @@ export class Client {
     // ----- models -----
     /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
     async listModels() {
-        const res = await fetch(`${this.base}/api/v1/models`);
-        if (!res.ok)
-            throw new WosError(res.status, await res.text());
-        const data = await res.json();
+        const data = await this.request("GET", "/api/v1/models");
         return (data.models ?? []);
     }
     // ----- stores -----
@@ -144,6 +191,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.");
         return this.request("DELETE", "/api/v1/memory/collection", { user_id: userId });
     }
     // ----- speakers (who said it) -----
@@ -164,58 +213,97 @@ export class Client {
     // ----- delete -----
     /** Delete a single memory by id. `userId` optional (uses the default store). */
     delete(userId, memoryId) {
+        // Guard: without a memory_id the API's forget endpoint means "delete the
+        // whole store". An undefined/"" slipping in here must never become a wipe.
+        if (!memoryId || typeof memoryId !== "string") {
+            throw new Error("memoryId is required. To delete every memory in a store, call deleteAll(userId) explicitly.");
+        }
         return this.post("/api/v1/memory/forget", { user_id: this.uid(userId), memory_id: memoryId });
     }
     /** 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.");
         return this.post("/api/v1/memory/forget", { user_id: userId });
     }
     // ----- internal -----
     post(path, body) {
         return this.request("POST", path, body);
     }
-    async request(method, path, body) {
-        const ctrl = new AbortController();
-        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
-        let res;
-        try {
-            res = await fetch(`${this.base}${path}`, {
-                method,
-                headers: this.headers,
-                body: body === undefined ? undefined : JSON.stringify(body),
-                signal: ctrl.signal,
-            });
+    /** Seconds→ms to sleep before retry `attempt` (0-based). Honors Retry-After. */
+    backoffMs(attempt, retryAfter) {
+        if (retryAfter) {
+            const s = Number(retryAfter);
+            if (Number.isFinite(s) && s >= 0)
+                return Math.min(30_000, s * 1000);
         }
-        catch (e) {
-            throw new WosError(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":...}}
-            // or simple {"error":"reason"}. Fall back to raw text.
-            let msg = await res.text();
+        return Math.min(8_000, 500 * 2 ** attempt) + Math.random() * 250;
+    }
+    async request(method, path, body) {
+        const attempts = this.maxRetries + 1;
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            const ctrl = new AbortController();
+            const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+            let res;
             try {
-                const data = JSON.parse(msg);
-                if (data && typeof data === "object") {
-                    const err = data.error;
-                    if (err && typeof err === "object")
-                        msg = err.message ?? err.type ?? msg;
-                    else if (typeof err === "string")
-                        msg = err;
-                    else if (typeof data.message === "string")
-                        msg = data.message;
+                res = await fetch(`${this.base}${path}`, {
+                    method,
+                    headers: this.headers,
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal: ctrl.signal,
+                    // Never follow a redirect: fetch would forward the API key to
+                    // wherever a 3xx points. The API never legitimately redirects.
+                    redirect: "manual",
+                });
+            }
+            catch (e) {
+                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)));
+                    continue;
                 }
+                throw new WosError(0, timedOut ? `request timed out after ${this.timeoutMs}ms` : `network error: ${e?.message ?? e}`);
             }
-            catch {
-                /* keep raw text */
+            clearTimeout(timer);
+            if (RETRY_STATUSES.has(res.status) && attempt + 1 < attempts) {
+                await new Promise((r) => setTimeout(r, this.backoffMs(attempt, res.headers.get("Retry-After"))));
+                continue;
+            }
+            if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
+                throw new WosError(res.status, "unexpected redirect — refused (the API key never follows a redirect). Check baseUrl: exact host, https://.");
+            }
+            if (!res.ok) {
+                // Server returns either Anthropic-style envelope
+                //   {"type":"error","error":{"type":...,"message":...,"request_id":...}}
+                // or simple {"error":"reason"}. Fall back to raw text.
+                let msg = await res.text();
+                let requestId;
+                try {
+                    const data = JSON.parse(msg);
+                    if (data && typeof data === "object") {
+                        const err = data.error;
+                        if (err && typeof err === "object") {
+                            msg = err.message ?? err.type ?? msg;
+                            if (typeof err.request_id === "string")
+                                requestId = err.request_id;
+                        }
+                        else if (typeof err === "string")
+                            msg = err;
+                        else if (typeof data.message === "string")
+                            msg = data.message;
+                    }
+                }
+                catch {
+                    /* keep raw text */
+                }
+                throw new WosError(res.status, msg, requestId);
             }
-            throw new WosError(res.status, msg);
+            return res.json();
         }
-        return res.json();
+        throw new WosError(0, "retries exhausted"); // unreachable; keeps the compiler happy
     }
 }
 /** Back-compat alias: older code used `WME`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.7",
+  "version": "2.2.8",
   "description": "Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.",
   "keywords": [
     "memory",
@@ -14,14 +14,6 @@
     "context"
   ],
   "homepage": "https://wontopos.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Irina1920/Wos_API.git",
-    "directory": "sdk/typescript"
-  },
-  "bugs": {
-    "url": "https://github.com/Irina1920/Wos_API/issues"
-  },
   "license": "MIT",
   "author": "Wontopos",
   "type": "module",
@@ -45,6 +37,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "test": "npm run build && node --test test/client.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {