wontopos 2.2.10 → 2.2.12

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;
@@ -123,6 +158,14 @@ export interface StatsResult {
     short_term_turns?: number;
     [key: string]: unknown;
 }
+/** `listMemories` → one page of a store's raw memories (original text + metadata, no vector). */
+export interface MemoryPage {
+    memories: Memory[];
+    count: number;
+    /** Pass back as `cursor` for the next page; `null` on the last page. */
+    next_cursor: string | null;
+    [key: string]: unknown;
+}
 export interface ModelInfo {
     id: string;
     name: string;
@@ -197,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. */
@@ -235,6 +283,36 @@ export declare class Client {
     history(userId?: string): Promise<HistoryTurn[]>;
     /** Memory counts for a store: { total_memories, short_term_turns }. */
     stats(userId?: string): Promise<StatsResult>;
+    /** 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.
+     *
+     *     let cursor: string | null = null;
+     *     const all: Memory[] = [];
+     *     do {
+     *       const page = await mem.listMemories(undefined, { cursor: cursor ?? undefined });
+     *       all.push(...page.memories);
+     *       cursor = page.next_cursor;
+     *     } while (cursor);
+     */
+    listMemories(userId?: string, opts?: {
+        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,7 +32,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.10";
+const VERSION = "2.2.12";
 const USER_AGENT = `wontopos-node/${VERSION}`;
 const DEFAULT_BASE_URL = "https://api.wontopos.com";
 const DEFAULT_MODEL = "tablet-1";
@@ -48,17 +48,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 +130,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).
@@ -197,6 +264,54 @@ export class Client {
     stats(userId) {
         return this.post("/api/v1/memory/stats", { user_id: this.uid(userId) });
     }
+    /** 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.
+     *
+     *     let cursor: string | null = null;
+     *     const all: Memory[] = [];
+     *     do {
+     *       const page = await mem.listMemories(undefined, { cursor: cursor ?? undefined });
+     *       all.push(...page.memories);
+     *       cursor = page.next_cursor;
+     *     } while (cursor);
+     */
+    listMemories(userId, opts = {}) {
+        const body = { user_id: this.uid(userId), limit: opts.limit ?? 100 };
+        if (opts.cursor)
+            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;
+        for (;;) {
+            const page = await this.listMemories(userId, { limit: opts.pageSize ?? 100, cursor });
+            for (const m of page.memories ?? [])
+                yield m;
+            cursor = page.next_cursor ?? undefined;
+            if (!cursor)
+                break;
+        }
+    }
+    /** 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() {
@@ -324,7 +439,7 @@ 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) {
@@ -336,6 +451,7 @@ export class Client {
             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://.");
             }
+            this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
             const text = await this.readCapped(res);
             if (!res.ok) {
                 // Server returns either Anthropic-style envelope
@@ -361,7 +477,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.10",
+  "version": "2.2.12",
   "description": "Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.",
   "keywords": [
     "memory",