wontopos 2.2.24 → 2.2.25

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,6 +282,8 @@ 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×. */

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.25";
 /** 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 {
@@ -310,7 +383,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({
@@ -384,6 +459,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 +469,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) };
     }
@@ -753,6 +830,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.25",
   "description": "Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.",
   "keywords": [
     "memory",