wontopos 2.2.8 → 2.2.9

package/README.md

@@ -70,6 +70,35 @@ Built in, no configuration needed:
   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
@@ -102,6 +131,9 @@ const mem = new Client({ apiKey: "...", baseUrl: "https://wos.your-host.com" });
 
 ## 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

package/dist/wontopos.d.ts

@@ -24,8 +24,13 @@
  *
  * 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`.
+ *
+ * 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;
@@ -33,14 +38,41 @@ export declare class WosError extends Error {
     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 {
     short_term: {
         turns: unknown[];
@@ -56,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;
@@ -63,6 +117,48 @@ 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). */
@@ -89,6 +185,9 @@ export declare class Client {
     /** 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. */
@@ -104,55 +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

@@ -24,16 +24,26 @@
  *
  * 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`.
+ *
+ * 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.8";
+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)}` : "***";
@@ -61,16 +71,24 @@ export class Client {
     /** 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.maxRetries = Math.max(0, opts.maxRetries ?? 2);
         this.headers = {
-            "X-API-Key": opts.apiKey,
+            "X-API-Key": this.apiKey,
             "Content-Type": "application/json",
             // Browsers silently drop User-Agent (forbidden header) — harmless.
             "User-Agent": USER_AGENT,
@@ -85,6 +103,15 @@ export class Client {
             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) };
@@ -203,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) {
@@ -240,6 +268,37 @@ export class Client {
         }
         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`);
+        }
+        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;
+        }
+        return new TextDecoder().decode(buf);
+    }
     async request(method, path, body) {
         const attempts = this.maxRetries + 1;
         for (let attempt = 0; attempt < attempts; attempt++) {
@@ -269,20 +328,23 @@ export class Client {
             }
             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"))));
+                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 = await res.text();
+                let msg = text;
                 let requestId;
                 try {
-                    const data = JSON.parse(msg);
+                    const data = JSON.parse(text);
                     if (data && typeof data === "object") {
                         const err = data.error;
                         if (err && typeof err === "object") {
@@ -301,7 +363,7 @@ export class Client {
                 }
                 throw new WosError(res.status, msg, requestId);
             }
-            return res.json();
+            return text ? JSON.parse(text) : null;
         }
         throw new WosError(0, "retries exhausted"); // unreachable; keeps the compiler happy
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.8",
+  "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",