wontopos 2.2.35 → 2.2.37

package/dist/cjs/wontopos.js

@@ -0,0 +1,900 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WME = exports.Client = exports.ServerError = exports.RateLimitError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.PaymentRequiredError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionError = exports.WosError = exports.CONTEXT_LIMIT_MAX = exports.CONTEXT_LIMIT_MIN = exports.SEARCH_LIMIT_MAX = exports.SEARCH_LIMIT_MIN = void 0;
+exports._resetStoreIdWarnings = _resetStoreIdWarnings;
+exports._resetFilterWarnings = _resetFilterWarnings;
+const VERSION = "2.2.37";
+const RUNTIME = (() => {
+    const p = globalThis?.process;
+    return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
+})();
+const USER_AGENT = `wontopos-node/${VERSION}${RUNTIME}`;
+function logDebug(msg) {
+    const env = globalThis?.process?.env;
+    if (typeof env?.WONTOPOS_LOG === "string" && env.WONTOPOS_LOG.toLowerCase() === "debug") {
+        console.error(`wontopos: ${msg}`);
+    }
+}
+const DEFAULT_BASE_URL = "https://api.wontopos.com";
+const DEFAULT_MODEL = "tablet-2";
+const RETRY_ALWAYS = new Set([429]);
+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"]);
+const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
+const MODEL_RE = /^[A-Za-z0-9._-]+$/;
+const MAX_ERR_MSG = 4096;
+const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9._:\-]{1,128}$/;
+function normalizeStoreId(id) {
+    return id.toLowerCase().replace(/[^a-z0-9_]/g, "_");
+}
+const WARNED_STORE_IDS_MAX = 1024;
+const WARNED_FILTER_KEYS_MAX = 1024;
+const warnedStoreIds = new Set();
+function warnIfStoreIdCollapses(id) {
+    if (!id || warnedStoreIds.has(id))
+        return;
+    const normalized = normalizeStoreId(id);
+    if (normalized === id)
+        return;
+    warnedStoreIds.add(id);
+    while (warnedStoreIds.size > WARNED_STORE_IDS_MAX) {
+        const oldest = warnedStoreIds.values().next().value;
+        if (oldest === undefined)
+            break;
+        warnedStoreIds.delete(oldest);
+    }
+    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.`);
+}
+function _resetStoreIdWarnings() {
+    warnedStoreIds.clear();
+}
+const NO_BODY_STATUS = new Set([204, 205, 304]);
+const MAX_PAGES = 20_000;
+exports.SEARCH_LIMIT_MIN = 5;
+exports.SEARCH_LIMIT_MAX = 20;
+exports.CONTEXT_LIMIT_MIN = 0;
+exports.CONTEXT_LIMIT_MAX = 20;
+function checkCount(limit, name) {
+    if (!Number.isInteger(limit) || limit < exports.SEARCH_LIMIT_MIN || limit > exports.SEARCH_LIMIT_MAX) {
+        throw new Error(`${name} must be an integer between ${exports.SEARCH_LIMIT_MIN} and ${exports.SEARCH_LIMIT_MAX}, got ${limit}. ` +
+            `Out of range is refused rather than adjusted, so a short answer always means ` +
+            `the store was short.`);
+    }
+}
+function checkContextLimit(n) {
+    if (!Number.isInteger(n) || n < exports.CONTEXT_LIMIT_MIN || n > exports.CONTEXT_LIMIT_MAX) {
+        throw new Error(`context_limit must be an integer between ${exports.CONTEXT_LIMIT_MIN} and ${exports.CONTEXT_LIMIT_MAX}, got ${n}.`);
+    }
+}
+function normalizeImage(image) {
+    if (!image || typeof image !== "object") {
+        throw new Error("image must be an object — { data: '<base64>' }.");
+    }
+    if (typeof image.data !== "string" || image.data.trim() === "") {
+        throw new Error("image.data is required — base64 of the image (a data: URL is fine).");
+    }
+    const raw = image.data.trim();
+    const comma = raw.startsWith("data:") ? raw.indexOf(",") : -1;
+    const data = (comma === -1 ? raw : raw.slice(comma + 1)).replace(/\s+/g, "");
+    if (data === "")
+        throw new Error("image.data is empty after stripping its data: prefix.");
+    const out = { data };
+    if (image.reference !== undefined)
+        out.reference = image.reference;
+    if (image.taken_at !== undefined)
+        out.taken_at = image.taken_at;
+    return out;
+}
+const CONNECT_FAIL_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "EADDRNOTAVAIL",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+function isConnectFailure(e) {
+    const stack = [e];
+    for (let steps = 0; stack.length && steps < 24; steps++) {
+        const cur = stack.pop();
+        if (!cur || typeof cur !== "object")
+            continue;
+        if (typeof cur.code === "string" && CONNECT_FAIL_CODES.has(cur.code))
+            return true;
+        if (cur.cause)
+            stack.push(cur.cause);
+        if (Array.isArray(cur.errors))
+            stack.push(...cur.errors.slice(0, 8));
+    }
+    return false;
+}
+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;
+        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 };
+}
+const asList = (x) => (Array.isArray(x) ? x : []);
+const asObj = (x) => (x != null && typeof x === "object" && !Array.isArray(x) ? x : {});
+const asRecords = (x) => asList(x).filter((m) => m != null && typeof m === "object" && !Array.isArray(m));
+function mergeResults(r) {
+    const main = asRecords(r?.memories);
+    const mine = asRecords(r?.self_memories);
+    if (mine.length === 0)
+        return main;
+    const seen = new Set(main.map((m) => m.id).filter((id) => typeof id === "string"));
+    return main.concat(mine.filter((m) => !(typeof m.id === "string" && seen.has(m.id))));
+}
+function withForm(body, form, tz) {
+    if (form !== undefined)
+        body.form = form;
+    if (tz !== undefined)
+        body.tz = tz;
+    return body;
+}
+class WosError extends Error {
+    status;
+    requestId;
+    constructor(status, message, requestId) {
+        super(`[${status}] ${message}${requestId ? ` (request_id: ${requestId})` : ""}`);
+        this.name = new.target.name;
+        this.status = status;
+        this.requestId = requestId;
+    }
+}
+exports.WosError = WosError;
+class APIConnectionError extends WosError {
+}
+exports.APIConnectionError = APIConnectionError;
+class BadRequestError extends WosError {
+}
+exports.BadRequestError = BadRequestError;
+class AuthenticationError extends WosError {
+}
+exports.AuthenticationError = AuthenticationError;
+class PaymentRequiredError extends WosError {
+}
+exports.PaymentRequiredError = PaymentRequiredError;
+class PermissionDeniedError extends WosError {
+}
+exports.PermissionDeniedError = PermissionDeniedError;
+class NotFoundError extends WosError {
+}
+exports.NotFoundError = NotFoundError;
+class ConflictError extends WosError {
+}
+exports.ConflictError = ConflictError;
+class RateLimitError extends WosError {
+}
+exports.RateLimitError = RateLimitError;
+class ServerError extends WosError {
+}
+exports.ServerError = ServerError;
+const STATUS_ERRORS = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitError,
+};
+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 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);
+        while (warnedFilterKeys.size > WARNED_FILTER_KEYS_MAX) {
+            const oldest = warnedFilterKeys.values().next().value;
+            if (oldest === undefined)
+                break;
+            warnedFilterKeys.delete(oldest);
+        }
+        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(", ")}.`);
+    }
+}
+function _resetFilterWarnings() {
+    warnedFilterKeys.clear();
+}
+const DEFAULT_USER = "default";
+class Client {
+    base;
+    headers;
+    timeoutMs;
+    apiKey;
+    model;
+    maxRetries;
+    deadlineMs;
+    signal;
+    fetchImpl;
+    defaultUser;
+    _rateLimit = null;
+    get rateLimit() {
+        return this._rateLimit;
+    }
+    constructor(opts) {
+        const key = (opts?.apiKey ?? "").trim();
+        if (!key)
+            throw new Error("apiKey is required");
+        if (/\s/.test(key))
+            throw new Error("apiKey contains whitespace - check for a stray newline or paste error");
+        if (/[\x00-\x1f\x7f]/.test(key))
+            throw new Error("apiKey contains a control character - check for a stray byte or paste error");
+        this.apiKey = key;
+        this.base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        const tm = opts.timeoutMs;
+        this.timeoutMs = typeof tm === "number" && Number.isFinite(tm) && tm > 0 ? tm : 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;
+        const mr = opts.maxRetries ?? opts.retries;
+        this.maxRetries = typeof mr === "number" && Number.isFinite(mr) ? Math.max(0, Math.floor(mr)) : 2;
+        const dl = opts.deadlineMs;
+        this.deadlineMs = typeof dl === "number" && Number.isFinite(dl) && dl > 0 ? dl : undefined;
+        this.signal = opts.signal;
+        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",
+            "User-Agent": USER_AGENT,
+        };
+        if (this.model)
+            this.headers["X-WOS-Model"] = this.model;
+        let host;
+        try {
+            host = new URL(this.base).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+        }
+        catch {
+            host = "";
+        }
+        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://.");
+        }
+        Object.defineProperty(this, "apiKey", { enumerable: false });
+        Object.defineProperty(this, "headers", { enumerable: false });
+    }
+    static fromEnv(opts = {}) {
+        const env = globalThis?.process?.env;
+        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({ ...opts, apiKey: key });
+    }
+    toJSON() {
+        return { baseUrl: this.base, model: this.model, userId: this.defaultUser, apiKey: maskKey(this.apiKey) };
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return `Client(${this.base}, model=${this.model}, userId=${this.defaultUser}, apiKey=${maskKey(this.apiKey)})`;
+    }
+    uid(userId) {
+        if (userId !== undefined && (typeof userId !== "string" || !userId.trim())) {
+            throw new Error(`userId must be a non-blank string; got ${JSON.stringify(userId)}. Omit it to use the client's ` +
+                "default store, or pass a real store id — anything else would silently write into the default store.");
+        }
+        const id = userId || this.defaultUser;
+        warnIfStoreIdCollapses(id);
+        return id;
+    }
+    clone(overrides) {
+        return new Client({
+            apiKey: this.apiKey,
+            baseUrl: this.base,
+            timeoutMs: this.timeoutMs,
+            model: this.model,
+            userId: this.defaultUser,
+            maxRetries: this.maxRetries,
+            fetch: this.fetchImpl,
+            deadlineMs: this.deadlineMs,
+            signal: this.signal,
+            ...overrides,
+        });
+    }
+    withModel(model) {
+        return this.clone({ model });
+    }
+    withUser(userId) {
+        return this.clone({ userId });
+    }
+    withSignal(signal) {
+        return this.clone({ signal });
+    }
+    withDeadline(deadlineMs) {
+        return this.clone({ deadlineMs });
+    }
+    withTimeout(timeoutMs) {
+        return this.clone({ timeoutMs });
+    }
+    withRetries(maxRetries) {
+        return this.clone({ maxRetries });
+    }
+    add(content, userId, metadata = {}, opts = {}) {
+        const body = { user_id: this.uid(userId), content, metadata };
+        if (opts.image !== undefined)
+            body.image = normalizeImage(opts.image);
+        return this.post("/api/v1/memory/store", body, opts.idempotencyKey);
+    }
+    store(content, userId, metadata = {}, opts = {}) {
+        return this.add(content, userId, metadata, opts);
+    }
+    addTurn(userMsg, assistantMsg, userId, opts = {}) {
+        return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, opts.idempotencyKey);
+    }
+    addBulk(content, userId, category = "general", timestamp, opts = {}) {
+        const body = { user_id: this.uid(userId), content, category };
+        if (timestamp)
+            body.timestamp = timestamp;
+        return this.post("/api/v1/memory/bulk-store", body, opts.idempotencyKey);
+    }
+    update(oldMemoryId, newContent, userId, opts = {}) {
+        return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, opts.idempotencyKey);
+    }
+    async search(query, userId, limit = 10, opts = {}) {
+        warnOnUnknownFilters(opts.filters);
+        checkCount(limit, "limit");
+        const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
+        return mergeResults(r);
+    }
+    async searchSelf(query, userId, limit = 10, opts = {}) {
+        warnOnUnknownFilters(opts.filters);
+        checkCount(limit, "limit");
+        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) };
+    }
+    async searchFull(query, userId, limit = 10, opts = {}) {
+        warnOnUnknownFilters(opts.filters);
+        checkCount(limit, "limit");
+        const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
+        return {
+            ...r,
+            memories: asRecords(r.memories),
+            self_memories: asRecords(r.self_memories),
+            images: asRecords(r.images),
+        };
+    }
+    async recall(query, userId, opts = {}) {
+        const body = { user_id: this.uid(userId), query };
+        if (opts.limit !== undefined) {
+            checkCount(opts.limit, "limit");
+            body.limit = opts.limit;
+        }
+        if (opts.context_limit !== undefined) {
+            checkContextLimit(opts.context_limit);
+            body.context_limit = opts.context_limit;
+        }
+        return this.post("/api/v1/memory/recall", withForm(body, opts.form, opts.tz));
+    }
+    engram(name, query, userId, opts = {}) {
+        return this.post("/api/v1/engram/run", withForm({ name, user_id: this.uid(userId), query }, opts.form, opts.tz));
+    }
+    async history(userId) {
+        const r = await this.post("/api/v1/memory/history", { user_id: this.uid(userId) });
+        return asRecords(r.turns);
+    }
+    stats(userId) {
+        return this.post("/api/v1/memory/stats", { user_id: this.uid(userId) });
+    }
+    async usage(days = 7) {
+        if (!Number.isInteger(days) || days < 1 || days > 365) {
+            throw new Error(`days must be an integer between 1 and 365, got ${days}.`);
+        }
+        return this.request("GET", `/api/v1/won/usage?days=${days}`);
+    }
+    get(userId, memoryId) {
+        if (!memoryId || typeof memoryId !== "string") {
+            throw new Error("memoryId is required — the id that add/store or listMemories returned.");
+        }
+        return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId }).then((r) => asObj(r.memory));
+    }
+    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 *iterMemories(userId, opts = {}) {
+        let cursor;
+        const seen = new Set();
+        for (let page = 0; page < MAX_PAGES; page++) {
+            const p = await this.listMemories(userId, { limit: opts.pageSize ?? 100, cursor });
+            for (const m of asRecords(p.memories))
+                yield m;
+            const next = p.next_cursor ?? undefined;
+            if (!next || seen.has(next))
+                return;
+            seen.add(next);
+            cursor = next;
+        }
+        throw new Error(`stopped after ${MAX_PAGES} pages — the store did not end. This is a truncated ` +
+            `answer, not the whole store.`);
+    }
+    async exportMemories(userId) {
+        const out = [];
+        for await (const m of this.iterMemories(userId))
+            out.push(m);
+        return out;
+    }
+    getImage(userId, memoryId) {
+        if (!memoryId || typeof memoryId !== "string") {
+            throw new Error("memoryId is required — the id that add/store or listImages returned.");
+        }
+        return this.requestBytes("/api/v1/memory/image", { user_id: this.uid(userId), memory_id: memoryId });
+    }
+    forgetImage(userId, memoryId, opts = {}) {
+        if (!memoryId || typeof memoryId !== "string") {
+            throw new Error("memoryId is required — the id of the memory whose image you want removed.");
+        }
+        const body = { user_id: this.uid(userId), memory_id: memoryId };
+        if (opts.preview)
+            body.preview = true;
+        return this.request("DELETE", "/api/v1/memory/image", body);
+    }
+    listImages(userId, opts = {}) {
+        const body = { user_id: this.uid(userId) };
+        if (opts.limit !== undefined)
+            body.limit = opts.limit;
+        if (opts.before !== undefined)
+            body.before = opts.before;
+        if (opts.skipIds !== undefined)
+            body.skip_ids = opts.skipIds;
+        return this.post("/api/v1/memory/images", body);
+    }
+    async *iterImages(userId, opts = {}) {
+        let before;
+        let skipIds;
+        const seen = new Set();
+        for (let page = 0; page < MAX_PAGES; page++) {
+            const p = await this.listImages(userId, { limit: opts.pageSize, before, skipIds });
+            for (const m of asRecords(p.images))
+                yield m;
+            if (!p.has_more || !p.next_before)
+                return;
+            const key = `${p.next_before}|${(Array.isArray(p.next_skip_ids) ? p.next_skip_ids : []).join(",")}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            before = p.next_before;
+            skipIds = Array.isArray(p.next_skip_ids) ? p.next_skip_ids : undefined;
+        }
+        throw new Error(`stopped after ${MAX_PAGES} pages — the store did not end. This is a truncated ` +
+            `answer, not the whole store.`);
+    }
+    revisions(userId, opts = {}) {
+        const body = {};
+        if (opts.include !== undefined)
+            body.include = opts.include;
+        if (opts.limit !== undefined)
+            body.limit = opts.limit;
+        if (opts.before !== undefined)
+            body.before = opts.before;
+        if (opts.skipIds !== undefined)
+            body.skip_ids = opts.skipIds;
+        body.user_id = this.uid(userId);
+        return this.post("/api/v1/won/revisions", body);
+    }
+    lineage(userId, memoryId) {
+        if (!memoryId || typeof memoryId !== "string") {
+            throw new Error("memoryId is required — the memory whose history you want.");
+        }
+        return this.post("/api/v1/memory/lineage", { user_id: this.uid(userId), memory_id: memoryId });
+    }
+    bySpeaker(speaker, userId, opts = {}) {
+        if (!speaker || typeof speaker !== "string" || speaker.trim() === "") {
+            throw new Error('speaker is required — "me" for the assistant, or a person\'s name.');
+        }
+        const body = { user_id: this.uid(userId), speaker: speaker.trim() };
+        if (opts.limit !== undefined)
+            body.limit = opts.limit;
+        if (opts.before !== undefined)
+            body.before = opts.before;
+        if (opts.skipIds !== undefined)
+            body.skip_ids = opts.skipIds;
+        return this.post("/api/v1/memory/by-speaker", body);
+    }
+    async ping() {
+        await this.request("GET", "/api/v1/memory/collections");
+        return true;
+    }
+    async listModels() {
+        const data = await this.request("GET", "/api/v1/models");
+        return asRecords(data.models);
+    }
+    async listEngrams() {
+        const data = await this.request("GET", "/api/v1/engram");
+        return {
+            engrams: asRecords(data.engrams),
+            forms: asRecords(data.forms),
+            note: typeof data.note === "string" ? data.note : undefined,
+        };
+    }
+    createStore(userId) {
+        return this.post("/api/v1/memory/collection", { user_id: this.uid(userId) });
+    }
+    async listStores() {
+        const r = await this.request("GET", "/api/v1/memory/collections");
+        return asRecords(r.collections);
+    }
+    deleteStore(userId) {
+        if (typeof userId !== "string" || !userId.trim())
+            throw new Error("userId is required (a non-blank string) — deleteStore never falls back to the default store.");
+        warnIfStoreIdCollapses(userId);
+        return this.request("DELETE", "/api/v1/memory/collection", { user_id: userId });
+    }
+    addSpeaker(speaker, userId) {
+        return this.post("/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
+    }
+    async listSpeakers(userId) {
+        const r = await this.request("GET", `/api/v1/memory/speakers?user_id=${encodeURIComponent(this.uid(userId))}`);
+        return { ...r, speakers: asRecords(r?.speakers) };
+    }
+    removeSpeaker(speaker, userId) {
+        return this.request("DELETE", "/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
+    }
+    delete(userId, memoryId) {
+        if (typeof memoryId !== "string" || !memoryId.trim()) {
+            throw new Error("memoryId is required (non-blank). To delete every memory in a store, call deleteAll(userId) explicitly.");
+        }
+        return this.post("/api/v1/memory/forget", { user_id: this.uid(userId), memory_id: memoryId.trim() });
+    }
+    deleteAll(userId) {
+        if (typeof userId !== "string" || !userId.trim())
+            throw new Error("userId is required (a non-blank string) for deleteAll — anything else would wipe the default store.");
+        warnIfStoreIdCollapses(userId);
+        return this.post("/api/v1/memory/forget", { user_id: userId });
+    }
+    post(path, body, idempotencyKey) {
+        return this.request("POST", path, body, idempotencyKey);
+    }
+    deadlineAt() {
+        return this.deadlineMs === undefined ? undefined : Date.now() + this.deadlineMs;
+    }
+    beginAttempt(deadlineAt) {
+        let why = "timeout";
+        let budget = this.timeoutMs;
+        if (deadlineAt !== undefined) {
+            const left = deadlineAt - Date.now();
+            if (left <= 0)
+                throw new APIConnectionError(0, this.abortMessage("deadline"));
+            if (left < budget) {
+                budget = left;
+                why = "deadline";
+            }
+        }
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), budget);
+        const outer = this.signal;
+        const onCaller = () => {
+            why = "caller";
+            ctrl.abort();
+        };
+        if (outer) {
+            if (outer.aborted)
+                onCaller();
+            else
+                outer.addEventListener("abort", onCaller);
+        }
+        return {
+            signal: ctrl.signal,
+            clear: () => {
+                clearTimeout(timer);
+                outer?.removeEventListener("abort", onCaller);
+            },
+            why: () => why,
+        };
+    }
+    abortMessage(why) {
+        if (why === "caller")
+            return "cancelled — the caller's AbortSignal fired";
+        if (why === "deadline")
+            return `deadline of ${this.deadlineMs}ms exhausted`;
+        return `request timed out after ${this.timeoutMs}ms`;
+    }
+    async backoffSleep(ms, deadlineAt) {
+        if (deadlineAt !== undefined && ms > deadlineAt - Date.now()) {
+            throw new APIConnectionError(0, this.abortMessage("deadline"));
+        }
+        const outer = this.signal;
+        if (!outer) {
+            await new Promise((r) => setTimeout(r, ms));
+            return;
+        }
+        if (outer.aborted)
+            return;
+        await new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                outer.removeEventListener("abort", done);
+                resolve();
+            };
+            const timer = setTimeout(done, ms);
+            outer.addEventListener("abort", done);
+        });
+    }
+    async requestBytes(path, body) {
+        const attempts = this.maxRetries + 1;
+        const deadlineAt = this.deadlineAt();
+        for (let attempt = 0;; attempt++) {
+            const att = this.beginAttempt(deadlineAt);
+            let res;
+            try {
+                res = await this.fetchImpl(`${this.base}${path}`, {
+                    method: "POST",
+                    headers: this.headers,
+                    body: JSON.stringify(body),
+                    signal: att.signal,
+                    redirect: "manual",
+                });
+            }
+            catch (e) {
+                att.clear();
+                const timedOut = e?.name === "AbortError" || att.signal.aborted;
+                if (!timedOut && isConnectFailure(e) && attempt + 1 < attempts) {
+                    await this.backoffSleep(this.backoffMs(attempt), deadlineAt);
+                    continue;
+                }
+                throw new APIConnectionError(0, timedOut ? this.abortMessage(att.why()) : `network error: ${e?.message ?? e}`);
+            }
+            try {
+                this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
+                if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
+                    void res.body?.cancel();
+                    throw errorFor(res.status, "the API answered with a redirect; refusing to follow it");
+                }
+                if (!res.ok) {
+                    if (RETRY_ALWAYS.has(res.status) && attempt + 1 < attempts) {
+                        const retryAfter = res.headers.get("Retry-After");
+                        void res.body?.cancel();
+                        att.clear();
+                        await this.backoffSleep(this.backoffMs(attempt, retryAfter), deadlineAt);
+                        continue;
+                    }
+                    let msg = await this.readCapped(res).catch(() => "");
+                    try {
+                        const data = JSON.parse(msg);
+                        const err = data?.error;
+                        if (err && typeof err === "object")
+                            msg = err.message ?? err.type ?? msg;
+                        else if (typeof err === "string")
+                            msg = err;
+                    }
+                    catch {
+                    }
+                    if (msg.length > MAX_ERR_MSG)
+                        msg = msg.slice(0, MAX_ERR_MSG) + "…(truncated)";
+                    throw errorFor(res.status, msg || `HTTP ${res.status}`);
+                }
+                let buf;
+                try {
+                    buf = await this.readCappedBytes(res);
+                }
+                catch (e) {
+                    if (e?.name === "AbortError" || att.signal.aborted) {
+                        throw new APIConnectionError(0, this.abortMessage(att.why()));
+                    }
+                    throw e;
+                }
+                if (buf.byteLength === 0) {
+                    throw new WosError(res.status, "empty image body — the service returned no bytes");
+                }
+                return { bytes: buf, contentType: res.headers.get("content-type") ?? "application/octet-stream" };
+            }
+            finally {
+                att.clear();
+            }
+        }
+    }
+    idemHeader(key) {
+        if (key === undefined || key === null)
+            return undefined;
+        if (!IDEMPOTENCY_KEY_RE.test(key)) {
+            throw new Error(`invalid idempotencyKey: ${JSON.stringify(key)} — 1-128 chars of [A-Za-z0-9._:-]`);
+        }
+        return { "Idempotency-Key": key };
+    }
+    backoffMs(attempt, retryAfter) {
+        if (retryAfter) {
+            const s = Number(retryAfter);
+            if (Number.isFinite(s) && s >= 0)
+                return Math.min(30_000, s * 1000);
+            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;
+    }
+    async readCapped(res) {
+        return new TextDecoder().decode(await this.readCappedBytes(res));
+    }
+    async readCappedBytes(res) {
+        const cl = res.headers.get("content-length");
+        if (cl && Number(cl) > MAX_RESPONSE_BYTES) {
+            throw new WosError(res.status, `response too large (${cl} bytes) — refusing to buffer it`);
+        }
+        if (!res.body) {
+            const buf = new Uint8Array(await res.arrayBuffer());
+            if (buf.byteLength > MAX_RESPONSE_BYTES) {
+                throw new WosError(res.status, `response too large (${buf.byteLength} bytes) — refusing it`);
+            }
+            return buf;
+        }
+        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(res.status, "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 buf;
+    }
+    async request(method, path, body, idempotencyKey) {
+        const extraHeaders = this.idemHeader(idempotencyKey);
+        const attempts = this.maxRetries + 1;
+        const logPath = path.split("?")[0];
+        const deadlineAt = this.deadlineAt();
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            const start = Date.now();
+            const att = this.beginAttempt(deadlineAt);
+            let res;
+            try {
+                res = await this.fetchImpl(`${this.base}${path}`, {
+                    method,
+                    headers: extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers,
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal: att.signal,
+                    redirect: "manual",
+                });
+            }
+            catch (e) {
+                att.clear();
+                const timedOut = e?.name === "AbortError" || att.signal.aborted;
+                const safe = IDEMPOTENT_METHODS.has(method.toUpperCase()) || isConnectFailure(e);
+                if (!timedOut && safe && attempt + 1 < attempts) {
+                    const delay = this.backoffMs(attempt);
+                    logDebug(`${method} ${logPath}: ${e?.code ?? e?.name ?? "network error"} — retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
+                    await this.backoffSleep(delay, deadlineAt);
+                    continue;
+                }
+                throw new APIConnectionError(0, timedOut ? this.abortMessage(att.why()) : `network error: ${e?.message ?? e}`);
+            }
+            const retryable = RETRY_ALWAYS.has(res.status) ||
+                (RETRY_IF_IDEMPOTENT.has(res.status) && IDEMPOTENT_METHODS.has(method.toUpperCase()));
+            if (retryable && attempt + 1 < attempts) {
+                att.clear();
+                const retryAfter = res.headers.get("Retry-After");
+                void res.body?.cancel();
+                const delay = this.backoffMs(attempt, retryAfter);
+                logDebug(`${method} ${logPath} -> ${res.status} — retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
+                await this.backoffSleep(delay, deadlineAt);
+                continue;
+            }
+            if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
+                att.clear();
+                void res.body?.cancel();
+                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;
+            let text;
+            try {
+                text = await this.readCapped(res);
+            }
+            catch (e) {
+                if (e?.name === "AbortError" || att.signal.aborted) {
+                    throw new APIConnectionError(0, this.abortMessage(att.why()));
+                }
+                if (e instanceof WosError)
+                    throw e;
+                throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
+            }
+            finally {
+                att.clear();
+            }
+            logDebug(`${method} ${logPath} -> ${res.status} in ${Date.now() - start}ms (attempt ${attempt + 1}/${attempts})`);
+            if (!res.ok) {
+                let msg = text;
+                let requestId;
+                try {
+                    const data = JSON.parse(text);
+                    if (data && typeof data === "object") {
+                        const err = data.error;
+                        if (err && typeof err === "object") {
+                            msg = err.message ?? err.type ?? msg;
+                            if (typeof err.request_id === "string")
+                                requestId = err.request_id;
+                        }
+                        else if (typeof err === "string")
+                            msg = err;
+                        else if (typeof data.message === "string")
+                            msg = data.message;
+                    }
+                }
+                catch {
+                }
+                if (typeof msg === "string" && msg.length > MAX_ERR_MSG)
+                    msg = msg.slice(0, MAX_ERR_MSG) + "…(truncated)";
+                throw errorFor(res.status, msg, requestId);
+            }
+            if (!text) {
+                if (NO_BODY_STATUS.has(res.status))
+                    return {};
+                throw new WosError(res.status, "empty response body — expected a JSON object");
+            }
+            let data;
+            try {
+                data = JSON.parse(text);
+            }
+            catch (e) {
+                throw new WosError(res.status, `invalid JSON in response: ${e?.message ?? e}`);
+            }
+            if (data === null || typeof data !== "object" || Array.isArray(data)) {
+                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}`);
+            }
+            if (res.headers.get("Idempotent-Replayed") === "true" && !("replayed" in data)) {
+                data.replayed = true;
+            }
+            return data;
+        }
+        throw new Error("retries exhausted");
+    }
+}
+exports.Client = Client;
+exports.WME = Client;
+exports.default = Client;