wontopos 2.2.11 → 2.2.13

package/dist/wontopos.d.ts

@@ -32,12 +32,47 @@
  * runtime's (never disabled by this SDK; Node 18+ floors TLS at 1.2). Prefer
  * `Client.fromEnv()` over keys in source code.
  */
+/** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
+export interface RateLimit {
+    limit: number | null;
+    remaining: number | null;
+    reset: number | null;
+}
 export declare class WosError extends Error {
     readonly status: number;
     /** 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);
 }
+/** The request never got a response (DNS/TLS/timeout/connection). `status` is 0. */
+export declare class APIConnectionError extends WosError {
+}
+/** 400 — the request was malformed (bad arguments). */
+export declare class BadRequestError extends WosError {
+}
+/** 401 — the API key is missing, wrong, or revoked. */
+export declare class AuthenticationError extends WosError {
+}
+/** 402 — no card on file or the balance is depleted. Top up to continue. */
+export declare class PaymentRequiredError extends WosError {
+}
+/** 403 — the key/model isn't allowed to do this. */
+export declare class PermissionDeniedError extends WosError {
+}
+/** 404 — the store or resource doesn't exist (create the store first). */
+export declare class NotFoundError extends WosError {
+}
+/** 409 — a concurrent write to the same store. Retry. */
+export declare class ConflictError extends WosError {
+}
+/** 429 — too many requests. Back off and retry (the client already retries these). */
+export declare class RateLimitError extends WosError {
+}
+/** 5xx — the service failed. Safe to retry. */
+export declare class ServerError extends WosError {
+}
+/** Build the most specific WosError subclass for an HTTP status. */
+export declare function errorFor(status: number, message: string, requestId?: string): WosError;
 export interface Usage {
     input_tokens?: number;
     output_tokens?: number;
@@ -205,6 +240,11 @@ export declare class Client {
     private readonly maxRetries;
     /** The store every call uses unless one passes `userId`. */
     private readonly defaultUser;
+    private _rateLimit;
+    /** Quota from the MOST RECENT call: `{ limit, remaining, reset }` (or `null` before
+     * the first call). Read it to self-throttle — the client already retries 429s, but
+     * this lets you slow down before hitting the wall. */
+    get rateLimit(): RateLimit | null;
     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. */
@@ -259,6 +299,20 @@ export declare class Client {
         limit?: number;
         cursor?: string;
     }): Promise<MemoryPage>;
+    /** Async-iterate every stored memory in a store, paging under the hood — no cursor
+     * bookkeeping. Original text + metadata only, never vectors.
+     *
+     *     for await (const m of mem.iterMemories()) console.log(m.id, m.content);
+     */
+    iterMemories(userId?: string, opts?: {
+        pageSize?: number;
+    }): AsyncGenerator<Memory>;
+    /** Collect ALL of a store's memories into an array (original text + metadata, no vectors). */
+    exportMemories(userId?: string): Promise<Memory[]>;
+    /** Check connectivity AND that the API key works. Resolves `true`, or rejects — an
+     * `AuthenticationError` (bad key), `PaymentRequiredError` (valid key but no card /
+     * depleted balance), or `APIConnectionError` (unreachable). Makes one metered request. */
+    ping(): Promise<boolean>;
     /** 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:

package/dist/wontopos.js

@@ -32,12 +32,17 @@
  * 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.11";
+const VERSION = "2.2.13";
 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. */
@@ -48,17 +53,77 @@ const MODEL_RE = /^[A-Za-z0-9._-]+$/;
 function maskKey(key) {
     return key.length > 12 ? `${key.slice(0, 4)}...${key.slice(-4)}` : "***";
 }
+function parseRateLimit(h) {
+    const num = (name) => {
+        const v = h.get(name);
+        if (v == null || v.trim() === "")
+            return null; // Number("") is 0 — treat blank as absent
+        const n = Number(v);
+        return Number.isFinite(n) ? n : null;
+    };
+    const limit = num("X-RateLimit-Limit");
+    const remaining = num("X-RateLimit-Remaining");
+    const reset = num("X-RateLimit-Reset");
+    if (limit === null && remaining === null && reset === null)
+        return null;
+    return { limit, remaining, reset };
+}
 export class WosError extends Error {
     status;
     /** 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.name = new.target.name; // the concrete subclass name (RateLimitError, …)
         this.status = status;
         this.requestId = requestId;
     }
 }
+// Typed subclasses so callers can branch on the failure — `catch (e) { if (e instanceof
+// RateLimitError) … }`. Each is a WosError, so a broad `instanceof WosError` still works.
+/** The request never got a response (DNS/TLS/timeout/connection). `status` is 0. */
+export class APIConnectionError extends WosError {
+}
+/** 400 — the request was malformed (bad arguments). */
+export class BadRequestError extends WosError {
+}
+/** 401 — the API key is missing, wrong, or revoked. */
+export class AuthenticationError extends WosError {
+}
+/** 402 — no card on file or the balance is depleted. Top up to continue. */
+export class PaymentRequiredError extends WosError {
+}
+/** 403 — the key/model isn't allowed to do this. */
+export class PermissionDeniedError extends WosError {
+}
+/** 404 — the store or resource doesn't exist (create the store first). */
+export class NotFoundError extends WosError {
+}
+/** 409 — a concurrent write to the same store. Retry. */
+export class ConflictError extends WosError {
+}
+/** 429 — too many requests. Back off and retry (the client already retries these). */
+export class RateLimitError extends WosError {
+}
+/** 5xx — the service failed. Safe to retry. */
+export class ServerError extends WosError {
+}
+const STATUS_ERRORS = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitError,
+};
+/** Build the most specific WosError subclass for an HTTP status. */
+export function errorFor(status, message, requestId) {
+    const Cls = status === 0
+        ? APIConnectionError
+        : STATUS_ERRORS[status] ?? (status >= 500 && status < 600 ? ServerError : WosError);
+    return new Cls(status, message, requestId);
+}
 const DEFAULT_USER = "default";
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export class Client {
@@ -70,6 +135,13 @@ export class Client {
     maxRetries;
     /** The store every call uses unless one passes `userId`. */
     defaultUser;
+    _rateLimit = null;
+    /** Quota from the MOST RECENT call: `{ limit, remaining, reset }` (or `null` before
+     * the first call). Read it to self-throttle — the client already retries 429s, but
+     * this lets you slow down before hitting the wall. */
+    get rateLimit() {
+        return this._rateLimit;
+    }
     constructor(opts) {
         // 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).
@@ -86,7 +158,11 @@ export class Client {
             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",
@@ -98,8 +174,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://.");
         }
     }
@@ -107,10 +184,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() {
@@ -177,7 +257,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. */
@@ -215,6 +297,40 @@ export class Client {
             body.cursor = opts.cursor;
         return this.post("/api/v1/memory/list", body);
     }
+    /** Async-iterate every stored memory in a store, paging under the hood — no cursor
+     * bookkeeping. Original text + metadata only, never vectors.
+     *
+     *     for await (const m of mem.iterMemories()) console.log(m.id, m.content);
+     */
+    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;
+            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). */
+    async exportMemories(userId) {
+        const out = [];
+        for await (const m of this.iterMemories(userId))
+            out.push(m);
+        return out;
+    }
+    /** Check connectivity AND that the API key works. Resolves `true`, or rejects — an
+     * `AuthenticationError` (bad key), `PaymentRequiredError` (valid key but no card /
+     * depleted balance), or `APIConnectionError` (unreachable). Makes one metered request. */
+    async ping() {
+        await this.request("GET", "/api/v1/memory/collections");
+        return true;
+    }
     // ----- models -----
     /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
     async listModels() {
@@ -236,8 +352,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) -----
@@ -269,8 +385,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 -----
@@ -283,6 +399,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;
     }
@@ -342,19 +462,38 @@ export class Client {
                     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}`);
+                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://.");
             }
-            const text = await this.readCapped(res);
+            this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
+            // 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`);
+                }
+                throw e;
+            }
+            finally {
+                clearTimeout(timer);
+            }
             if (!res.ok) {
                 // Server returns either Anthropic-style envelope
                 //   {"type":"error","error":{"type":...,"message":...,"request_id":...}}
@@ -379,7 +518,7 @@ export class Client {
                 catch {
                     /* keep raw text */
                 }
-                throw new WosError(res.status, msg, requestId);
+                throw errorFor(res.status, msg, requestId);
             }
             return text ? JSON.parse(text) : null;
         }

package/package.json

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