wontopos 2.2.7 → 2.2.9

package/README.md

@@ -55,9 +55,55 @@ 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)`.
+
+## Security
+
+Built in, none of it configurable off:
+
+- **Redirects refused** — a 3xx is an error, so the key never follows one to
+  another host.
+- **Response size cap** — anything over 64MB is refused instead of buffered.
+- **Key hygiene** — keys are trimmed (a stray newline from an env var otherwise
+  becomes a mystery 401) and inner whitespace is rejected; model names are
+  validated before they reach a header.
+- **`Client.fromEnv()`** reads `WONTOPOS_API_KEY` (or `WOS_API_KEY`) — keep
+  keys out of source code.
+- TLS certificate verification is never touched (runtime defaults; Node 18+
+  floors TLS at 1.2). Plain-HTTP base URLs on non-local hosts warn.
+  Zero runtime dependencies.
+
+## Typed responses
+
+Every method returns a documented shape — `StoreResult`, `UpdateResult`,
+`RecallResult`, `EngramResult`, `StatsResult`, `SpeakersList`, `Memory[]`, ... —
+each with an index signature, so new server fields flow through without an SDK
+update. `search` options are typed too (`SearchOptions`: `cache_control`,
+`speaker`, plus pass-through).
+
+```ts
+const hits: Memory[] = await mem.search("what did Bob say?", "alice", 10, { speaker: "Bob" });
+console.log(hits[0].speaker, hits[0].time_bucket);   // typed: string | undefined
+```
 
 ## 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 +112,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 +127,21 @@ 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.9** — typed responses for every method (index-signature friendly) +
+  typed `SearchOptions`; security round 2: 64MB response cap, key/model-name
+  hygiene, `Client.fromEnv()`.
+- **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,56 @@
  *
  * 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`.
+ *
+ * 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
+ * is masked in `toJSON`/inspect output. TLS certificate verification is the
+ * runtime's (never disabled by this SDK; Node 18+ floors TLS at 1.2). Prefer
+ * `Client.fromEnv()` over keys in source code.
  */
 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 Usage {
+    input_tokens?: number;
+    output_tokens?: number;
+    [key: string]: unknown;
 }
 export interface Memory {
     id?: string;
     content?: string;
     score?: number;
+    /** Month bucket the memory belongs to (e.g. "2026-07"). */
+    time_bucket?: string;
+    /** WHO said it: "me" (the assistant) or a registered person's name. Absent = untagged. */
+    speaker?: string;
+    [key: string]: unknown;
+}
+/** `add` / `store` → `{ id, status }` (`status: "stored" | "stored (async)" | "duplicate"`). */
+export interface StoreResult {
+    id?: string;
+    status?: string;
+    /** Present when the store was a duplicate and something (e.g. a speaker tag) was dropped. */
+    note?: string;
+    [key: string]: unknown;
+}
+/** `addTurn` / `addBulk` / `delete` / `deleteAll` → `{ status }`. */
+export interface StatusResult {
+    status?: string;
+    [key: string]: unknown;
+}
+/** `update` (supersede) → old and new memory ids. */
+export interface UpdateResult {
+    old_memory_id?: string;
+    new_memory_id?: string;
+    status?: string;
     [key: string]: unknown;
 }
 export interface RecallResult {
@@ -47,6 +88,28 @@ export interface RecallResult {
     };
     [key: string]: unknown;
 }
+/** `engram` → the merged multi-hop result. */
+export interface EngramResult {
+    engram?: string;
+    form?: string;
+    user_id?: string;
+    hops?: number;
+    count?: number;
+    memories?: Memory[];
+    usage?: Usage;
+    [key: string]: unknown;
+}
+export interface HistoryTurn {
+    user_msg?: string;
+    assistant_msg?: string;
+    timestamp?: string;
+    [key: string]: unknown;
+}
+export interface StatsResult {
+    total_memories?: number;
+    short_term_turns?: number;
+    [key: string]: unknown;
+}
 export interface ModelInfo {
     id: string;
     name: string;
@@ -54,17 +117,62 @@ export interface ModelInfo {
     /** "shared" — reads the common memory pool; "isolated" — its own dedicated store. */
     memory: "shared" | "isolated";
 }
+/** `createStore` / `deleteStore` → `{ user_id, status }`. */
+export interface StoreOpResult {
+    user_id?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+export interface StoreInfo {
+    user_id: string;
+    created_at: string;
+    [key: string]: unknown;
+}
+/** `addSpeaker` / `removeSpeaker` → `{ user_id, speaker, status }`. */
+export interface SpeakerOpResult {
+    user_id?: string;
+    speaker?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+export interface SpeakerInfo {
+    speaker: string;
+    memories: number;
+    created_at?: string;
+    [key: string]: unknown;
+}
+/** `listSpeakers` → registered people with per-person memory counts. */
+export interface SpeakersList {
+    speakers: SpeakerInfo[];
+    count?: number;
+    /** The registration cap for this store (50 to start). */
+    limit?: number;
+    [key: string]: unknown;
+}
+/** Known `search` options; extra fields pass through to the API untouched. */
+export interface SearchOptions {
+    /** Recall caching: repeated/extended queries within the TTL bill at 0.1×. */
+    cache_control?: {
+        ttl: "5m" | "1h";
+    };
+    /** Recall only this person's words ("me" or a registered name). */
+    speaker?: string;
+    [key: string]: unknown;
+}
 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 +181,18 @@ 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);
+    /** A client whose key comes from `WONTOPOS_API_KEY` (or `WOS_API_KEY`) — keeps
+     * keys out of source code. Node/Bun/Deno-with-env only. */
+    static fromEnv(opts?: Omit<ClientOptions, "apiKey">): Client;
+    /** 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
@@ -88,53 +203,55 @@ export declare class Client {
     withUser(userId: string): 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<any>;
+    add(content: string, userId?: string, metadata?: Record<string, unknown>): Promise<StoreResult>;
     /** Alias of `add` — store one memory. Same surface as the Python SDK's `store`. */
-    store(content: string, userId?: string, metadata?: Record<string, unknown>): Promise<any>;
+    store(content: string, userId?: string, metadata?: Record<string, unknown>): Promise<StoreResult>;
     /** Store a conversation turn (user + assistant). Payload first, userId last — same shape as add/search. */
-    addTurn(userMsg: string, assistantMsg: string, userId?: string): Promise<any>;
+    addTurn(userMsg: string, assistantMsg: string, userId?: string): Promise<StatusResult>;
     /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling. */
-    addBulk(content: string, userId?: string, category?: string, timestamp?: string): Promise<any>;
+    addBulk(content: string, userId?: string, category?: string, timestamp?: string): Promise<StatusResult>;
     /** Supersede an old memory with new content. Payload first, userId last — same shape as add/search. */
-    update(oldMemoryId: string, newContent: string, userId?: string): Promise<any>;
+    update(oldMemoryId: string, newContent: string, userId?: string): Promise<UpdateResult>;
     /** Semantic search over a store's memories. Returns memories, most relevant first. */
-    search(query: string, userId?: string, limit?: number, opts?: Record<string, unknown>): Promise<Memory[]>;
+    search(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<Memory[]>;
     /** One-call LLM context: short-term turns + long-term matches + surrounding context. */
     recall(query: string, userId?: string): Promise<RecallResult>;
     /** Run a built-in engram ("deep_recall" | "timeline" | "gather"). Returns the merged result. */
-    engram(name: string, query: string, userId?: string): Promise<any>;
+    engram(name: string, query: string, userId?: string): Promise<EngramResult>;
     /** Recent conversation turns (short-term memory). */
-    history(userId?: string): Promise<unknown[]>;
+    history(userId?: string): Promise<HistoryTurn[]>;
     /** Memory counts for a store: { total_memories, short_term_turns }. */
-    stats(userId?: string): Promise<any>;
+    stats(userId?: string): Promise<StatsResult>;
     /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
     listModels(): Promise<ModelInfo[]>;
     /** Create a store — the `userId` you read and write under. Stores are explicit:
      * a store must exist before you `add` to or `search` it, otherwise those calls
      * return 404. Idempotent. Every account starts with a `default` store.
      * Returns `{ user_id, status }` (`status` is `"created"` or `"exists"`). */
-    createStore(userId?: string): Promise<any>;
+    createStore(userId?: string): Promise<StoreOpResult>;
     /** List your stores: `[{ user_id, created_at }, ...]` (`default` first). */
-    listStores(): Promise<Array<{
-        user_id: string;
-        created_at: string;
-    }>>;
+    listStores(): Promise<StoreInfo[]>;
     /** Delete a store and ALL its memories. Returns `{ user_id, status }`. */
-    deleteStore(userId: string): Promise<any>;
+    deleteStore(userId: string): Promise<StoreOpResult>;
     /** Register a person for this store. Speakers are explicit: register once, then
      * store with `{ speaker }`. `"me"` (the assistant itself) never needs
      * registration. A store registers up to 50 people to start. */
-    addSpeaker(speaker: string, userId?: string): Promise<any>;
+    addSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** The store's registered people, each with its memory count. */
-    listSpeakers(userId?: string): Promise<any>;
+    listSpeakers(userId?: string): Promise<SpeakersList>;
     /** Unregister a person. Their memories stay; the name tag goes. */
-    removeSpeaker(speaker: string, userId?: string): Promise<any>;
+    removeSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** Delete a single memory by id. `userId` optional (uses the default store). */
-    delete(userId: string | undefined, memoryId: string): Promise<any>;
+    delete(userId: string | undefined, memoryId: string): Promise<StatusResult>;
     /** 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: string): Promise<any>;
+    deleteAll(userId: string): Promise<StatusResult>;
     private post;
+    /** Seconds→ms to sleep before retry `attempt` (0-based). Honors Retry-After. */
+    private backoffMs;
+    /** Read the body with a hard size cap, so a broken/hostile endpoint can't
+     * make the process buffer gigabytes. */
+    private readCapped;
     private request;
 }
 /** Back-compat alias: older code used `WME`. */

package/dist/wontopos.js

@@ -21,15 +21,42 @@
  *
  * 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`.
+ *
+ * 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
+ * is masked in `toJSON`/inspect output. TLS certificate verification is the
+ * 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.9";
+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"]);
+/** 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._-]+$/;
+/** `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,35 +67,85 @@ export class Client {
     timeoutMs;
     apiKey;
     model;
+    maxRetries;
     /** The store every call uses unless one passes `userId`. */
     defaultUser;
     constructor(opts) {
-        if (!opts?.apiKey)
+        // Trim the key and reject inner whitespace — a stray newline from a file or
+        // env var otherwise turns into a mystery 401 (or a mangled header).
+        const key = (opts?.apiKey ?? "").trim();
+        if (!key)
             throw new Error("apiKey is required");
-        this.apiKey = opts.apiKey;
+        if (/\s/.test(key))
+            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;
         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.headers = { "X-API-Key": opts.apiKey, "Content-Type": "application/json" };
+        this.maxRetries = Math.max(0, opts.maxRetries ?? 2);
+        this.headers = {
+            "X-API-Key": this.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://.");
+        }
+    }
+    /** A client whose key comes from `WONTOPOS_API_KEY` (or `WOS_API_KEY`) — keeps
+     * 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())
+            throw new Error("set WONTOPOS_API_KEY (or WOS_API_KEY) in the environment");
+        return new Client({ apiKey: key, ...opts });
+    }
+    /** 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 +200,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 +218,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) -----
@@ -154,8 +230,9 @@ export class Client {
         return this.post("/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
     }
     /** The store's registered people, each with its memory count. */
-    listSpeakers(userId) {
-        return this.request("GET", `/api/v1/memory/speakers?user_id=${encodeURIComponent(this.uid(userId))}`);
+    async listSpeakers(userId) {
+        const r = await this.request("GET", `/api/v1/memory/speakers?user_id=${encodeURIComponent(this.uid(userId))}`);
+        return { speakers: [], ...r };
     }
     /** Unregister a person. Their memories stay; the name tag goes. */
     removeSpeaker(speaker, userId) {
@@ -164,58 +241,131 @@ 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}`);
+        return Math.min(8_000, 500 * 2 ** attempt) + Math.random() * 250;
+    }
+    /** Read the body with a hard size cap, so a broken/hostile endpoint can't
+     * make the process buffer gigabytes. */
+    async readCapped(res) {
+        const cl = res.headers.get("content-length");
+        if (cl && Number(cl) > MAX_RESPONSE_BYTES) {
+            throw new WosError(0, `response too large (${cl} bytes) — refusing to buffer it`);
         }
-        finally {
-            clearTimeout(timer);
+        if (!res.body)
+            return res.text();
+        const reader = res.body.getReader();
+        const parts = [];
+        let size = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_RESPONSE_BYTES) {
+                void reader.cancel();
+                throw new WosError(0, "response too large — refusing to buffer it");
+            }
+            parts.push(value);
+        }
+        const buf = new Uint8Array(size);
+        let off = 0;
+        for (const p of parts) {
+            buf.set(p, off);
+            off += p.byteLength;
         }
-        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 new TextDecoder().decode(buf);
+    }
+    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) {
+                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") {
+                throw new WosError(res.status, "unexpected redirect — refused (the API key never follows a redirect). Check baseUrl: exact host, https://.");
+            }
+            const text = await this.readCapped(res);
+            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 = text;
+                let requestId;
+                try {
+                    const data = JSON.parse(text);
+                    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 text ? JSON.parse(text) : null;
         }
-        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.9",
   "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": {