wontopos 2.2.24 → 2.2.26

package/README.md

@@ -52,7 +52,13 @@ registration and never counts against it.
 ## Recall caching
 
 Opt in per search and repeated or extended queries reuse the previous result
-at 10% of the normal rate (Tablet and Scroll models):
+at 10% of the normal rate (Tablet and Scroll models).
+
+It is not free to turn on: the FIRST call writes the cache and bills the query
+tokens at 2x for a `5m` TTL, 3x for `1h`. Only hits inside the TTL bill at 0.1x.
+So it pays for a query you repeat or extend, and costs more for one you issue
+once — do not switch it on globally. Any write to the store invalidates its cache
+at once, so a hit can never predate a new memory.
 
 ```ts
 const hits = await mem.search("...the conversation so far...", "alice", 10,
@@ -74,6 +80,27 @@ Built in, no configuration needed:
   meaning "delete everything"; wiping a store is only ever the explicit
   `deleteAll(userId)` / `deleteStore(userId)`.
 
+### Behind a corporate proxy
+
+Node's global `fetch` (undici) ignores `HTTP_PROXY` / `HTTPS_PROXY`, so behind an
+egress proxy this SDK could not connect at all — while the Python and Rust SDKs went
+through, because `requests` and `reqwest` both read those variables. Pass a
+proxy-aware `fetch` and the three behave the same:
+
+```ts
+import { ProxyAgent } from "undici";
+
+const agent = new ProxyAgent(process.env.HTTPS_PROXY!);
+const mem = new Client({
+  apiKey: process.env.WONTOPOS_API_KEY!,
+  fetch: (url, init) => fetch(url, { ...init, dispatcher: agent } as any),
+});
+```
+
+The same option is how you add instrumentation or drive the client without a
+network in tests. It replaces the transport, not the client's rules — retries,
+timeouts, redirect refusal and the response cap all still apply.
+
 ## Security
 
 Built in, none of it configurable off:

package/dist/wontopos.d.ts

@@ -37,6 +37,8 @@
  * runtime's (never disabled by this SDK; Node 18+ floors TLS at 1.2). Prefer
  * `Client.fromEnv()` over keys in source code.
  */
+/** Test hook — the warn-once set is process-global by design. */
+export declare function _resetStoreIdWarnings(): void;
 /** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
 export interface RateLimit {
     limit: number | null;
@@ -73,7 +75,18 @@ 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. */
+/**
+ * 5xx — the service failed.
+ *
+ * `502` / `503` are transient: the client already retries them for calls where a
+ * retry cannot double-process a write, and retrying yourself is reasonable.
+ *
+ * `501` is NOT transient. It means the engine behind the model you selected does
+ * not implement that endpoint at all (the error carries `model` and `endpoint`).
+ * Retrying can never succeed — pick a model that supports it (`listModels`) or
+ * drop the call. This class used to say "safe to retry" for the whole 5xx range,
+ * which sent callers into a loop that could not end.
+ */
 export declare class ServerError extends WosError {
 }
 export interface Usage {
@@ -121,6 +134,10 @@ export interface StoreResult {
     duplicate_of?: string;
     /** Present when the store was a duplicate and something (e.g. a speaker tag) was dropped. */
     note?: string;
+    /** `true` when this response was REPLAYED from a previous request with the same
+     *  `idempotencyKey` — nothing new was stored. Absent on a fresh write. Read it to
+     *  tell "my retry landed" from "my retry was a no-op". */
+    replayed?: boolean;
     [key: string]: unknown;
 }
 /** `addTurn` / `addBulk` / `delete` / `deleteAll` → `{ status }`. */
@@ -209,8 +226,13 @@ export interface EngramCatalog {
 }
 /** `createStore` / `deleteStore` → `{ user_id, status }`. */
 export interface StoreOpResult {
+    /** The store id the API actually used — NOT necessarily the one you sent.
+     *  Ids are normalized (see the `note`), so compare this against your input. */
     user_id?: string;
     status?: string;
+    /** Present when the API changed your id, explaining how. Read it: two of your
+     *  end users can land in one store if their ids differ only by punctuation. */
+    note?: string;
     [key: string]: unknown;
 }
 export interface StoreInfo {
@@ -260,9 +282,13 @@ export interface SearchFilters {
     /** Drop matches the engine scored below this importance (0–1). */
     min_importance?: number;
 }
+/** Test hook — the warn-once set is process-global by design. */
+export declare function _resetFilterWarnings(): void;
 /** 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×. */
+    /** Recall caching. A hit inside the TTL bills at 0.1× — but the FIRST call
+     *  writes the cache and bills the query tokens at 2× (`5m`) or 3× (`1h`), so
+     *  this only pays for a query you repeat or extend. Do not enable it globally. */
     cache_control?: {
         ttl: "5m" | "1h";
     };
@@ -312,6 +338,26 @@ export interface ClientOptions {
      *  key on an options object is not an error in TS at runtime). Both names work;
      *  `maxRetries` wins if somehow both are given. */
     retries?: number;
+    /** The `fetch` used for every request (default: the global `fetch`).
+     *
+     *  This is the seam for anything the runtime cannot express through options.
+     *  The one that matters in practice is a corporate egress proxy: Node's global
+     *  fetch (undici) IGNORES `HTTP_PROXY` / `HTTPS_PROXY`, so behind such a proxy
+     *  this SDK could not connect at all — while the Python and Rust SDKs went
+     *  through, because `requests` and `reqwest` both read those variables. Pass a
+     *  proxy-aware fetch and the three behave the same again:
+     *
+     *      import { ProxyAgent } from "undici";
+     *      const agent = new ProxyAgent(process.env.HTTPS_PROXY!);
+     *      const mem = new Client({
+     *        apiKey,
+     *        fetch: (url, init) => fetch(url, { ...init, dispatcher: agent } as any),
+     *      });
+     *
+     *  It is also how you add instrumentation or drive the client in a test without
+     *  a network. Retries, timeouts, redirect refusal and the size cap all still
+     *  apply — this replaces the transport, not the client's rules. */
+    fetch?: typeof fetch;
 }
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export declare class Client {
@@ -321,6 +367,9 @@ export declare class Client {
     private readonly apiKey;
     private readonly model;
     private readonly maxRetries;
+    /** Transport. Held as a field (not read off `globalThis` per call) so a caller
+     * who passes one gets it for every request, including from cloned clients. */
+    private readonly fetchImpl;
     /** The store every call uses unless one passes `userId`. */
     private readonly defaultUser;
     private _rateLimit;

package/dist/wontopos.js

@@ -37,7 +37,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.24";
+const VERSION = "2.2.26";
 /** Runtime info helps support debug a report ("node 18 on Windows...") —
  * platform only, never anything identifying. Browsers have no `process` (and
  * silently drop the UA header anyway). */
@@ -74,6 +74,40 @@ const MAX_ERR_MSG = 4096;
 /** What the API accepts as an `Idempotency-Key`. Checked client-side so a bad key
  *  fails before the request instead of coming back as a 400 mid-retry. */
 const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9._:\-]{1,128}$/;
+/**
+ * The API normalizes a store id: lowercased, and every character outside
+ * `[a-z0-9_]` becomes `_`. So `Alice.Smith`, `alice-smith` and `alice_smith` are
+ * ALL the same store.
+ *
+ * That is a data-exposure hazard for the most common way this SDK is used — one
+ * store per end user. Two accounts whose ids differ only by punctuation or case
+ * (`bob.lee@x.com` / `bob-lee@x.com`) silently share every memory, and nothing in
+ * the response says so: the note only appears when `createStore` creates one, and
+ * an app that reuses an existing store never sees it.
+ *
+ * We cannot refuse the id — the API accepts it, and callers may have written it
+ * this way for a year. So we say it once, loudly, at the moment it happens.
+ */
+function normalizeStoreId(id) {
+    return id.toLowerCase().replace(/[^a-z0-9_]/g, "_");
+}
+const warnedStoreIds = new Set();
+function warnIfStoreIdCollapses(id) {
+    if (!id || warnedStoreIds.has(id))
+        return;
+    const normalized = normalizeStoreId(id);
+    if (normalized === id)
+        return;
+    warnedStoreIds.add(id);
+    console.warn(`wontopos: store id ${JSON.stringify(id)} is stored as ${JSON.stringify(normalized)} ` +
+        `(lowercased, and anything outside [a-z0-9_] becomes "_"). Ids that differ only by case or ` +
+        `punctuation share ONE store and therefore one set of memories — if these ids come from your ` +
+        `end users, normalize them yourself first so two people can never collide.`);
+}
+/** Test hook — the warn-once set is process-global by design. */
+export function _resetStoreIdWarnings() {
+    warnedStoreIds.clear();
+}
 /** Statuses that legitimately carry NO body (RFC 9110). Everything else must
  *  answer with a JSON object — see the empty-body check in `request`. */
 const NO_BODY_STATUS = new Set([204, 205, 304]);
@@ -208,7 +242,18 @@ 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. */
+/**
+ * 5xx — the service failed.
+ *
+ * `502` / `503` are transient: the client already retries them for calls where a
+ * retry cannot double-process a write, and retrying yourself is reasonable.
+ *
+ * `501` is NOT transient. It means the engine behind the model you selected does
+ * not implement that endpoint at all (the error carries `model` and `endpoint`).
+ * Retrying can never succeed — pick a model that supports it (`listModels`) or
+ * drop the call. This class used to say "safe to retry" for the whole 5xx range,
+ * which sent callers into a loop that could not end.
+ */
 export class ServerError extends WosError {
 }
 const STATUS_ERRORS = {
@@ -228,6 +273,34 @@ function errorFor(status, message, requestId) {
         : STATUS_ERRORS[status] ?? (status >= 500 && status < 600 ? ServerError : WosError);
     return new Cls(status, message, requestId);
 }
+/** The filter keys the API acts on. Anything else it DROPS silently, so a typo
+ *  widens the search instead of failing — we warn rather than reject, because the
+ *  API may grow a key before this package is updated. */
+const KNOWN_FILTER_KEYS = new Set([
+    "categories",
+    "event_from",
+    "event_to",
+    "time_from",
+    "time_to",
+    "min_importance",
+]);
+const warnedFilterKeys = new Set();
+function warnOnUnknownFilters(filters) {
+    if (!filters || typeof filters !== "object" || Array.isArray(filters))
+        return;
+    for (const k of Object.keys(filters)) {
+        if (KNOWN_FILTER_KEYS.has(k) || warnedFilterKeys.has(k))
+            continue;
+        warnedFilterKeys.add(k);
+        console.warn(`wontopos: unknown search filter ${JSON.stringify(k)} — the API drops keys it does not know, ` +
+            `so this filter has NO effect and the search is wider than you think. ` +
+            `Known keys: ${[...KNOWN_FILTER_KEYS].join(", ")}.`);
+    }
+}
+/** Test hook — the warn-once set is process-global by design. */
+export function _resetFilterWarnings() {
+    warnedFilterKeys.clear();
+}
 const DEFAULT_USER = "default";
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export class Client {
@@ -237,6 +310,9 @@ export class Client {
     apiKey;
     model;
     maxRetries;
+    /** Transport. Held as a field (not read off `globalThis` per call) so a caller
+     * who passes one gets it for every request, including from cloned clients. */
+    fetchImpl;
     /** The store every call uses unless one passes `userId`. */
     defaultUser;
     _rateLimit = null;
@@ -271,6 +347,17 @@ export class Client {
         // "retries exhausted"; Infinity would retry forever.
         const mr = opts.maxRetries ?? opts.retries;
         this.maxRetries = typeof mr === "number" && Number.isFinite(mr) ? Math.max(0, Math.floor(mr)) : 2;
+        // Bind the global so `fetch` is not called as a method of `globalThis`, which
+        // throws "Illegal invocation" on some runtimes. A caller-supplied fetch is
+        // taken as given — it is already whatever they meant to hand us.
+        const f = opts.fetch;
+        if (f !== undefined && typeof f !== "function") {
+            throw new Error("fetch must be a function (a fetch-compatible transport)");
+        }
+        this.fetchImpl = f ?? (globalThis.fetch ? globalThis.fetch.bind(globalThis) : undefined);
+        if (typeof this.fetchImpl !== "function") {
+            throw new Error("no fetch available in this runtime — pass one as `fetch` (Node 18+ has it built in; older Node needs undici)");
+        }
         this.headers = {
             "X-API-Key": this.apiKey,
             "Content-Type": "application/json",
@@ -310,7 +397,9 @@ export class Client {
     }
     /** Resolve a call's store: the explicit userId, else the client default. */
     uid(userId) {
-        return userId || this.defaultUser;
+        const id = userId || this.defaultUser;
+        warnIfStoreIdCollapses(id);
+        return id;
     }
     clone(overrides) {
         return new Client({
@@ -320,6 +409,10 @@ export class Client {
             model: this.model,
             userId: this.defaultUser,
             maxRetries: this.maxRetries,
+            // Carry the transport across clones. Without this, `withModel(...)` and
+            // friends would silently fall back to the global fetch and a proxy-bound
+            // client would stop connecting the moment it was cloned.
+            fetch: this.fetchImpl,
             ...overrides,
         });
     }
@@ -384,6 +477,7 @@ export class Client {
     async search(query, userId, limit = 10, 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.
+        warnOnUnknownFilters(opts.filters);
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
         return mergeLanes(r);
     }
@@ -393,6 +487,7 @@ export class Client {
      * speaker "me"), kept separate so the reader never confuses who said what. On a model
      * without a self lane, `self_memories` is `[]`. `userId` optional (default store). */
     async searchSelf(query, userId, limit = 10, opts = {}) {
+        warnOnUnknownFilters(opts.filters);
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
         return { memories: asRecords(r.memories), self_memories: asRecords(r.self_memories) };
     }
@@ -633,7 +728,7 @@ export class Client {
             const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
             let res;
             try {
-                res = await fetch(`${this.base}${path}`, {
+                res = await this.fetchImpl(`${this.base}${path}`, {
                     method,
                     headers: extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers,
                     body: body === undefined ? undefined : JSON.stringify(body),
@@ -753,6 +848,13 @@ export class Client {
                 const got = data === null ? "null" : Array.isArray(data) ? "array" : typeof data;
                 throw new WosError(res.status, `expected a JSON object in the response, got ${got}`);
             }
+            // 멱등키를 쓴 쓰기가 **저장된 것인지 재생된 것인지**를 호출자가 알아야 한다.
+            // 서버는 `Idempotent-Replayed: true` 로 말해주는데 지금까지 SDK 가 삼켰다 —
+            // 멱등키를 쓰는 사람이 가장 알고 싶은 사실이 그것이다(재시도가 실제로
+            // 저장을 일으켰나, 아니면 첫 응답이 되풀이된 것인가).
+            if (res.headers.get("Idempotent-Replayed") === "true") {
+                data.replayed = true;
+            }
             return data;
         }
         throw new WosError(0, "retries exhausted"); // unreachable; keeps the compiler happy

package/package.json

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