wontopos 2.2.40 → 2.2.42

package/dist/cjs/wontopos.js

@@ -3,7 +3,7 @@ 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.40";
+const VERSION = "2.2.42";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -18,12 +18,29 @@ function logDebug(msg) {
 const DEFAULT_BASE_URL = "https://api.wontopos.com";
 const DEFAULT_MODEL = "tablet-2";
 const RETRY_ALWAYS = new Set([429]);
+const MAX_RETRY_WAIT_MS = 30_000;
+const MAX_TIMER_MS = 2_147_483_647;
 const RETRY_IF_IDEMPOTENT = new Set([408, 502, 503, 504]);
 const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+const READ_POSTS = new Set([
+    "/api/v1/memory/search",
+    "/api/v1/memory/recall",
+    "/api/v1/memory/get",
+    "/api/v1/memory/list",
+    "/api/v1/memory/stats",
+    "/api/v1/memory/history",
+    "/api/v1/memory/lineage",
+    "/api/v1/memory/by-speaker",
+    "/api/v1/memory/images",
+    "/api/v1/memory/image",
+    "/api/v1/engram/run",
+    "/api/v1/won/revisions",
+]);
 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 MAX_ERR_DETAILS = 8192;
 const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9._:\-]{1,128}$/;
 function normalizeStoreId(id) {
     return id.toLowerCase().replace(/[^a-z0-9_]/g, "_");
@@ -78,6 +95,9 @@ function _resetStoreIdWarnings() {
 }
 const NO_BODY_STATUS = new Set([204, 205, 304]);
 const MAX_PAGES = 20_000;
+function truncatedWalk(why) {
+    return new Error(`${why} This is a truncated answer, not the whole store.`);
+}
 exports.SEARCH_LIMIT_MIN = 5;
 exports.SEARCH_LIMIT_MAX = 20;
 exports.CONTEXT_LIMIT_MIN = 0;
@@ -94,6 +114,26 @@ function checkContextLimit(n) {
         throw new Error(`context_limit must be an integer between ${exports.CONTEXT_LIMIT_MIN} and ${exports.CONTEXT_LIMIT_MAX}, got ${n}.`);
     }
 }
+const PAGE_LIMIT_MIN = 5;
+const PAGE_LIMIT_MAX = 20;
+const LIST_LIMIT_MAX = 500;
+const MAX_IMAGES_MAX = 5;
+function checkRange(n, name, min, max) {
+    if (typeof n !== "number" || !Number.isInteger(n) || n < min || n > max) {
+        throw new Error(`${name} must be an integer between ${min} and ${max}, got ${String(n)}.`);
+    }
+}
+function optRange(n, name, min, max) {
+    if (n === undefined || n === null)
+        return undefined;
+    checkRange(n, name, min, max);
+    return n;
+}
+function checkMs(v) {
+    if (typeof v !== "number" || Number.isNaN(v) || v <= 0)
+        return undefined;
+    return Math.min(v, MAX_TIMER_MS);
+}
 function normalizeImage(image) {
     if (!image || typeof image !== "object") {
         throw new Error("image must be an object — { data: '<base64>' }.");
@@ -123,14 +163,18 @@ const CONNECT_FAIL_CODES = new Set([
     "EADDRNOTAVAIL",
     "UND_ERR_CONNECT_TIMEOUT",
 ]);
+const CONNECT_SYSCALLS = new Set(["connect", "getaddrinfo"]);
+const CONNECT_ONLY_CODES = new Set(["ENOTFOUND", "EAI_AGAIN", "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))
+        if (typeof cur.code === "string" &&
+            (CONNECT_ONLY_CODES.has(cur.code) || (CONNECT_FAIL_CODES.has(cur.code) && CONNECT_SYSCALLS.has(cur.syscall)))) {
             return true;
+        }
         if (cur.cause)
             stack.push(cur.cause);
         if (Array.isArray(cur.errors))
@@ -138,6 +182,191 @@ function isConnectFailure(e) {
     }
     return false;
 }
+function causeCode(e) {
+    const queue = [e];
+    for (let steps = 0; queue.length && steps < 24; steps++) {
+        const cur = queue.shift();
+        if (!cur || typeof cur !== "object")
+            continue;
+        if (typeof cur.code === "string" && /^[A-Z0-9_]{1,64}$/.test(cur.code))
+            return cur.code;
+        if (cur.cause)
+            queue.push(cur.cause);
+        if (Array.isArray(cur.errors))
+            queue.push(...cur.errors.slice(0, 8));
+    }
+    return undefined;
+}
+function cleanServerText(s, max = MAX_ERR_MSG) {
+    const clean = s.replace(/[\u0000-\u001f\u007f]/g, "");
+    return clean.length > max ? clean.slice(0, max) + "…(truncated)" : clean;
+}
+function cleanDetails(d) {
+    if (!d)
+        return undefined;
+    const clean = (v) => {
+        if (typeof v === "string")
+            return cleanServerText(v);
+        if (Array.isArray(v))
+            return v.map(clean);
+        if (v && typeof v === "object") {
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [cleanServerText(k), clean(x)]));
+        }
+        return v;
+    };
+    let entries;
+    try {
+        JSON.stringify(d);
+        entries = Object.entries(clean(d)).map(([k, v]) => [
+            k,
+            v,
+            JSON.stringify(k).length + JSON.stringify(v).length + 2,
+        ]);
+    }
+    catch {
+        return undefined;
+    }
+    const keep = new Set();
+    let size = 2;
+    for (const [k, , n] of [...entries].sort((a, b) => a[2] - b[2])) {
+        if (size + n > MAX_ERR_DETAILS)
+            break;
+        keep.add(k);
+        size += n;
+    }
+    if (!keep.size)
+        return undefined;
+    return Object.fromEntries(entries.filter(([k]) => keep.has(k)).map(([k, v]) => [k, v]));
+}
+function parseErrorText(text) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return { message: text };
+    }
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return { message: text };
+    const err = data.error;
+    if (err && typeof err === "object" && !Array.isArray(err)) {
+        const { message, type, request_id, ...rest } = err;
+        return {
+            message: typeof message === "string" ? message : typeof type === "string" ? type : text,
+            requestId: typeof request_id === "string" ? request_id : undefined,
+            type: typeof type === "string" ? type : undefined,
+            details: Object.keys(rest).length ? rest : undefined,
+        };
+    }
+    if (typeof err === "string")
+        return { message: err };
+    if (typeof data.message === "string")
+        return { message: data.message };
+    return { message: text };
+}
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const IMF_FIXDATE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\d{2}) ([A-Z][a-z]{2}) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+const RFC850_DATE = /^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\d{2})-([A-Z][a-z]{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+const ASCTIME_DATE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) ([A-Z][a-z]{2}) ([ \d]\d) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/;
+function retryAfterMs(v, now = Date.now()) {
+    if (v == null)
+        return undefined;
+    const s = v.trim();
+    if (/^\d+$/.test(s))
+        return Math.min(Number(s), Number.MAX_SAFE_INTEGER / 1000) * 1000;
+    let parts;
+    let m;
+    if ((m = IMF_FIXDATE.exec(s)))
+        parts = [m[1], m[2], Number(m[3]), m[4], m[5], m[6]];
+    else if ((m = RFC850_DATE.exec(s))) {
+        let year = 2000 + Number(m[3]);
+        if (year > new Date(now).getUTCFullYear() + 50)
+            year -= 100;
+        parts = [m[1], m[2], year, m[4], m[5], m[6]];
+    }
+    else if ((m = ASCTIME_DATE.exec(s)))
+        parts = [m[2].trim(), m[1], Number(m[6]), m[3], m[4], m[5]];
+    if (!parts)
+        return undefined;
+    const [day, mon, year, hh, mm, ss] = parts;
+    const month = MONTHS.indexOf(mon);
+    const d = Number(day), h = Number(hh), mi = Number(mm), se = Number(ss);
+    if (month < 0 || d < 1 || d > 31 || h > 23 || mi > 59 || se > 60)
+        return undefined;
+    return Math.max(0, Date.UTC(year, month, d, h, mi, se) - now);
+}
+const BRIEF_BODY_MS = 1_000;
+class SlowBody extends Error {
+}
+const DEFAULT_TRANSPORTS = new WeakSet();
+function defaultTransport() {
+    const g = globalThis.fetch;
+    if (typeof g !== "function")
+        return undefined;
+    const bound = g.bind(globalThis);
+    DEFAULT_TRANSPORTS.add(bound);
+    return bound;
+}
+function discard(res) {
+    res.body?.cancel().catch(() => { });
+}
+function tryUrl(s, base) {
+    try {
+        return base === undefined ? new URL(s) : new URL(s, base);
+    }
+    catch {
+        return undefined;
+    }
+}
+function pageHref() {
+    try {
+        const href = globalThis.location?.href;
+        return typeof href === "string" ? href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseBase(base) {
+    let url = tryUrl(base);
+    if (!url) {
+        const page = pageHref();
+        if (page !== undefined)
+            url = tryUrl(base, page);
+    }
+    return url && (url.protocol === "http:" || url.protocol === "https:") ? url : undefined;
+}
+function asPageRelative(base) {
+    return tryUrl(base) ? undefined : tryUrl(base, "http://page.invalid/");
+}
+const BASE_URL_ENDS = /^\s+|\s+$/g;
+function notAUrl(base) {
+    return `baseUrl is not a URL: ${JSON.stringify(maskBase(base))} (expected e.g. ${DEFAULT_BASE_URL})`;
+}
+function maskBase(raw) {
+    const at = raw.lastIndexOf("@");
+    if (at === -1)
+        return raw;
+    const from = /^(?:[a-z][a-z0-9+.-]*:)?[\\/]*/i.exec(raw)[0].length;
+    return `${raw.slice(0, from)}***@${raw.slice(at + 1)}`;
+}
+function maskUserinfo(text) {
+    let out = "";
+    let done = 0;
+    for (let at = text.indexOf("@"); at !== -1; at = text.indexOf("@", at + 1)) {
+        let start = at;
+        while (start > 0 && !/[\s\\/@]/.test(text[start - 1]))
+            start--;
+        const run = text.slice(start, at);
+        const afterSlash = start > 0 && (text[start - 1] === "/" || text[start - 1] === "\\");
+        if (!afterSlash && !run.includes(":"))
+            continue;
+        const scheme = afterSlash ? "" : (/^[a-z][a-z0-9+.-]*:/i.exec(run)?.[0] ?? "");
+        out += `${text.slice(done, start + scheme.length)}***`;
+        done = at;
+    }
+    return out + text.slice(done);
+}
 function maskKey(key) {
     return key.length > 12 ? `${key.slice(0, 4)}...${key.slice(-4)}` : "***";
 }
@@ -188,11 +417,15 @@ function withForm(body, form, tz) {
 class WosError extends Error {
     status;
     requestId;
-    constructor(status, message, requestId) {
-        super(`[${status}] ${message}${requestId ? ` (request_id: ${requestId})` : ""}`);
+    type;
+    details;
+    constructor(status, message, requestId, init) {
+        super(`[${status}] ${message}${requestId ? ` (request_id: ${requestId})` : ""}`, init?.cause === undefined ? undefined : { cause: init.cause });
         this.name = new.target.name;
         this.status = status;
         this.requestId = requestId;
+        this.type = init?.type;
+        this.details = init?.details;
     }
 }
 exports.WosError = WosError;
@@ -215,9 +448,21 @@ class NotFoundError extends WosError {
 }
 exports.NotFoundError = NotFoundError;
 class ConflictError extends WosError {
+    conflictsWith;
+    constructor(status, message, requestId, init) {
+        super(status, message, requestId, init);
+        const c = init?.details?.conflicts_with;
+        this.conflictsWith = typeof c === "string" ? c : undefined;
+    }
 }
 exports.ConflictError = ConflictError;
 class RateLimitError extends WosError {
+    retryAfter;
+    constructor(status, message, requestId, init) {
+        super(status, message, requestId, init);
+        const r = init?.retryAfter;
+        this.retryAfter = typeof r === "number" && Number.isFinite(r) && r >= 0 ? r : undefined;
+    }
 }
 exports.RateLimitError = RateLimitError;
 class ServerError extends WosError {
@@ -230,13 +475,15 @@ const STATUS_ERRORS = {
     403: PermissionDeniedError,
     404: NotFoundError,
     409: ConflictError,
+    413: BadRequestError,
+    422: BadRequestError,
     429: RateLimitError,
 };
-function errorFor(status, message, requestId) {
+function errorFor(status, message, requestId, init) {
     const Cls = status === 0
         ? APIConnectionError
         : STATUS_ERRORS[status] ?? (status >= 500 && status < 600 ? ServerError : WosError);
-    return new Cls(status, message, requestId);
+    return new Cls(status, message, requestId, init);
 }
 const KNOWN_FILTER_KEYS = new Set([
     "categories",
@@ -255,6 +502,8 @@ const KNOWN_RECALL_KEYS = new Set(["form", "tz", "limit", "context_limit"]);
 const KNOWN_ENGRAM_KEYS = new Set(["form", "tz"]);
 function checkSearchOpts(opts) {
     checkOpts(opts, KNOWN_SEARCH_KEYS, "search");
+    const o = opts;
+    optRange(o.max_images !== undefined ? o.max_images : o.extra?.max_images, "max_images", 0, MAX_IMAGES_MAX);
 }
 function checkOpts(opts, known, what) {
     for (const k of Object.keys(opts)) {
@@ -288,24 +537,33 @@ function editWithin(a, b, max) {
     }
     return prev[b.length] <= max;
 }
-function warnOnUnknownFilters(filters) {
-    if (!filters || typeof filters !== "object" || Array.isArray(filters))
+function warnOnceUnknownKeys(obj, known, warned, message) {
+    if (!obj || typeof obj !== "object" || Array.isArray(obj))
         return;
-    for (const k of Object.keys(filters)) {
-        if (KNOWN_FILTER_KEYS.has(k) || warnedFilterKeys.has(k))
+    for (const k of Object.keys(obj)) {
+        if (known.has(k) || warned.has(k))
             continue;
-        warnedFilterKeys.add(k);
-        while (warnedFilterKeys.size > WARNED_FILTER_KEYS_MAX) {
-            const oldest = warnedFilterKeys.values().next().value;
+        warned.add(k);
+        while (warned.size > WARNED_FILTER_KEYS_MAX) {
+            const oldest = warned.values().next().value;
             if (oldest === undefined)
                 break;
-            warnedFilterKeys.delete(oldest);
+            warned.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(", ")}.`);
+        console.warn(message(k));
     }
 }
+function warnOnUnknownFilters(filters) {
+    warnOnceUnknownKeys(filters, KNOWN_FILTER_KEYS, warnedFilterKeys, (k) => `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(", ")}.`);
+}
+const KNOWN_METADATA_KEYS = new Set(["speaker", "event_date", "category", "conversation_id"]);
+const warnedMetadataKeys = new Set();
+function warnOnUnknownMetadata(metadata) {
+    warnOnceUnknownKeys(metadata, KNOWN_METADATA_KEYS, warnedMetadataKeys, (k) => `wontopos: metadata key ${JSON.stringify(k)} is not kept: the service keeps only ` +
+        `${[...KNOWN_METADATA_KEYS].join(", ")} and drops the rest, so this value is not stored.`);
+}
 function _resetFilterWarnings() {
     warnedFilterKeys.clear();
 }
@@ -320,6 +578,9 @@ class Client {
     deadlineMs;
     signal;
     fetchImpl;
+    userinfo;
+    pageRelative;
+    customFetch;
     defaultUser;
     _rateLimit = null;
     get rateLimit() {
@@ -339,25 +600,41 @@ class Client {
                 "en dash; copy the key from a plain-text field");
         }
         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;
+        const rawBase = opts.baseUrl ?? DEFAULT_BASE_URL;
+        if (typeof rawBase !== "string")
+            throw new Error("baseUrl must be a string");
+        const trimmed = rawBase.replace(BASE_URL_ENDS, "");
+        if (/[\s\\\u0000-\u001f\u007f]/.test(trimmed)) {
+            throw new Error(`baseUrl contains whitespace, a backslash or a control character: ${JSON.stringify(maskBase(trimmed))}`);
+        }
+        this.base = trimmed.replace(/\/+$/, "");
+        const url = parseBase(this.base);
+        const parsed = url ?? (pageHref() === undefined ? asPageRelative(this.base) : undefined);
+        if (!parsed)
+            throw new Error(notAUrl(trimmed));
+        this.pageRelative = !url;
+        this.userinfo = Boolean(parsed.username || parsed.password);
+        this.timeoutMs = checkMs(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)`);
         }
+        if (opts && "userId" in opts && opts.userId === undefined) {
+            throw new Error("new Client() needs a store id in userId, or no userId option at all. It was given " +
+                "undefined. That is usually a lookup that found nothing. Leave userId out to use the default store.");
+        }
         assertUsableStoreId(opts.userId);
         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.deadlineMs = checkMs(opts.deadlineMs);
         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);
+        this.customFetch = f !== undefined && !DEFAULT_TRANSPORTS.has(f);
+        this.fetchImpl = (f ?? defaultTransport());
         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)");
         }
@@ -368,14 +645,8 @@ class Client {
         };
         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)) {
+        const host = url?.hostname.toLowerCase().replace(/^\[|\]$/g, "") ?? "";
+        if (url?.protocol === "http:" && !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 });
@@ -389,10 +660,10 @@ class Client {
         return new Client({ ...opts, apiKey: key });
     }
     toJSON() {
-        return { baseUrl: this.base, model: this.model, userId: this.defaultUser, apiKey: maskKey(this.apiKey) };
+        return { baseUrl: maskBase(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)})`;
+        return `Client(${maskBase(this.base)}, model=${this.model}, userId=${this.defaultUser}, apiKey=${maskKey(this.apiKey)})`;
     }
     uid(userId) {
         assertUsableStoreId(userId);
@@ -441,6 +712,7 @@ class Client {
         const body = { user_id: this.uid(userId), content, metadata };
         if (opts.image !== undefined)
             body.image = normalizeImage(opts.image);
+        warnOnUnknownMetadata(metadata);
         return this.post("/api/v1/memory/store", body, opts.idempotencyKey);
     }
     async store(content, userId, metadata = {}, opts = {}) {
@@ -461,6 +733,7 @@ class Client {
     async search(query, userId, limit = 10, opts = {}) {
         checkSearchOpts(opts);
         warnOnUnknownFilters(opts.filters);
+        limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
         const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
@@ -469,6 +742,7 @@ class Client {
     async searchSelf(query, userId, limit = 10, opts = {}) {
         checkSearchOpts(opts);
         warnOnUnknownFilters(opts.filters);
+        limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
         const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
@@ -477,6 +751,7 @@ class Client {
     async searchFull(query, userId, limit = 10, opts = {}) {
         checkSearchOpts(opts);
         warnOnUnknownFilters(opts.filters);
+        limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
         const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
@@ -490,11 +765,11 @@ class Client {
     async recall(query, userId, opts = {}) {
         checkOpts(opts, KNOWN_RECALL_KEYS, "recall");
         const body = { user_id: this.uid(userId), query };
-        if (opts.limit !== undefined) {
+        if (opts.limit != null) {
             checkCount(opts.limit, "limit");
             body.limit = opts.limit;
         }
-        if (opts.context_limit !== undefined) {
+        if (opts.context_limit != null) {
             checkContextLimit(opts.context_limit);
             body.context_limit = opts.context_limit;
         }
@@ -524,7 +799,8 @@ class Client {
         return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId.trim() }).then(memoryFromGet);
     }
     async listMemories(userId, opts = {}) {
-        const body = { user_id: this.uid(userId), limit: opts.limit ?? 100 };
+        const limit = optRange(opts.limit, "limit", 1, LIST_LIMIT_MAX);
+        const body = { user_id: this.uid(userId), limit: limit ?? 100 };
         if (opts.cursor)
             body.cursor = opts.cursor;
         return this.post("/api/v1/memory/list", body);
@@ -534,16 +810,21 @@ class Client {
         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))
+            const rows = asRecords(p.memories);
+            for (const m of rows)
                 yield m;
             const next = p.next_cursor ?? undefined;
-            if (!next || seen.has(next))
+            if (!next)
+                return;
+            if (seen.has(next)) {
+                if (rows.length)
+                    throw truncatedWalk(`stopped at page ${page + 1}: the service repeated a cursor, so the store did not end.`);
                 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.`);
+        throw truncatedWalk(`stopped after ${MAX_PAGES} pages — the store did not end.`);
     }
     async exportMemories(userId) {
         const out = [];
@@ -568,14 +849,16 @@ class Client {
             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.trim() };
-        if (opts.preview)
-            body.preview = true;
+        if (!opts.preview)
+            return this.remove("/api/v1/memory/image", body);
+        body.preview = true;
         return this.request("DELETE", "/api/v1/memory/image", body);
     }
     async listImages(userId, opts = {}) {
+        const limit = optRange(opts.limit, "limit", PAGE_LIMIT_MIN, PAGE_LIMIT_MAX);
         const body = { user_id: this.uid(userId) };
-        if (opts.limit !== undefined)
-            body.limit = opts.limit;
+        if (limit !== undefined)
+            body.limit = limit;
         if (opts.before !== undefined)
             body.before = opts.before;
         if (opts.skipIds !== undefined)
@@ -588,26 +871,30 @@ class Client {
         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))
+            const rows = asRecords(p.images);
+            for (const m of rows)
                 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))
+            if (seen.has(key)) {
+                if (rows.length)
+                    throw truncatedWalk(`stopped at page ${page + 1}: the service repeated a cursor, so the store did not end.`);
                 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.`);
+        throw truncatedWalk(`stopped after ${MAX_PAGES} pages — the store did not end.`);
     }
     async revisions(userId, opts = {}) {
+        const limit = optRange(opts.limit, "limit", PAGE_LIMIT_MIN, PAGE_LIMIT_MAX);
         const body = {};
         if (opts.include !== undefined)
             body.include = opts.include;
-        if (opts.limit !== undefined)
-            body.limit = opts.limit;
+        if (limit !== undefined)
+            body.limit = limit;
         if (opts.before !== undefined)
             body.before = opts.before;
         if (opts.skipIds !== undefined)
@@ -625,9 +912,10 @@ class Client {
         if (!speaker || typeof speaker !== "string" || speaker.trim() === "") {
             throw new Error('speaker is required — "me" for the assistant, or a person\'s name.');
         }
+        const limit = optRange(opts.limit, "limit", PAGE_LIMIT_MIN, PAGE_LIMIT_MAX);
         const body = { user_id: this.uid(userId), speaker: speaker.trim() };
-        if (opts.limit !== undefined)
-            body.limit = opts.limit;
+        if (limit !== undefined)
+            body.limit = limit;
         if (opts.before !== undefined)
             body.before = opts.before;
         if (opts.skipIds !== undefined)
@@ -662,7 +950,7 @@ class Client {
         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 });
+        return this.remove("/api/v1/memory/collection", { user_id: userId });
     }
     async addSpeaker(speaker, userId) {
         return this.post("/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
@@ -672,7 +960,7 @@ class Client {
         return { ...r, speakers: asRecords(r?.speakers) };
     }
     async removeSpeaker(speaker, userId) {
-        return this.request("DELETE", "/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
+        return this.remove("/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
     }
     async delete(userId, memoryId) {
         if (typeof memoryId !== "string" || !memoryId.trim()) {
@@ -689,22 +977,26 @@ class Client {
     post(path, body, idempotencyKey) {
         return this.request("POST", path, body, idempotencyKey);
     }
+    remove(path, body) {
+        return this.request("DELETE", path, body, undefined, true);
+    }
     deadlineAt() {
         return this.deadlineMs === undefined ? undefined : Date.now() + this.deadlineMs;
     }
-    beginAttempt(deadlineAt) {
+    beginAttempt(deadlineAt, answer) {
         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"));
+                throw answer ?? new APIConnectionError(0, this.abortMessage("deadline"));
             if (left < budget) {
                 budget = left;
                 why = "deadline";
             }
         }
         const ctrl = new AbortController();
+        const endsAt = Date.now() + budget;
         const timer = setTimeout(() => ctrl.abort(), budget);
         const outer = this.signal;
         const onCaller = () => {
@@ -724,6 +1016,7 @@ class Client {
                 outer?.removeEventListener("abort", onCaller);
             },
             why: () => why,
+            endsAt,
         };
     }
     abortMessage(why) {
@@ -733,10 +1026,10 @@ class Client {
             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"));
-        }
+    fits(ms, deadlineAt) {
+        return deadlineAt === undefined || ms <= deadlineAt - Date.now();
+    }
+    async pause(ms) {
         const outer = this.signal;
         if (!outer) {
             await new Promise((r) => setTimeout(r, ms));
@@ -754,17 +1047,83 @@ class Client {
             outer.addEventListener("abort", done);
         });
     }
-    async requestBytes(path, body) {
+    networkError(e, path) {
+        let text = typeof e?.message === "string" && e.message ? e.message : String(e);
+        const q = path.indexOf("?");
+        if (q !== -1) {
+            const query = path.slice(q);
+            text = text.split(query).join("");
+            try {
+                text = text.split(decodeURIComponent(query)).join("");
+            }
+            catch {
+            }
+        }
+        text = cleanServerText(maskUserinfo(text), 512);
+        const code = causeCode(e);
+        if (code && !text.includes(code))
+            text += ` (${code})`;
+        const quotable = this.userinfo || q !== -1;
+        return new APIConnectionError(0, `network error: ${text}`, undefined, quotable ? undefined : { cause: e });
+    }
+    isRedirected(res) {
+        return (res.status >= 300 && res.status < 400) || res.type === "opaqueredirect" || res.redirected === true;
+    }
+    errorFromAnswer(res, body, retryAfter, mayBeDeleted = false, unread) {
+        const e = parseErrorText(new TextDecoder().decode(body));
+        let msg = cleanServerText(e.message) || `HTTP ${res.status}`;
+        if (unread)
+            msg += ` (the error body could not be read: ${cleanServerText(unread, 512)})`;
+        const requestId = e.requestId === undefined ? undefined : cleanServerText(e.requestId, 256) || undefined;
+        const err = errorFor(res.status, msg, requestId, {
+            type: e.type === undefined ? undefined : cleanServerText(e.type, 256) || undefined,
+            details: cleanDetails(e.details),
+            retryAfter: retryAfter === undefined ? undefined : Math.ceil(retryAfter / 1000),
+        });
+        if (mayBeDeleted && err instanceof NotFoundError) {
+            err.message += " (an earlier attempt may already have deleted it)";
+        }
+        return err;
+    }
+    async send(method, path, payload, extraHeaders, removes = false, reads = false) {
+        if (this.pageRelative && !this.customFetch && !parseBase(this.base)) {
+            throw new Error(`${notAUrl(this.base)}. A relative baseUrl needs a page to resolve against, and this runtime has none.`);
+        }
         const attempts = this.maxRetries + 1;
+        const upper = method.toUpperCase();
+        const idempotent = IDEMPOTENT_METHODS.has(upper);
+        const logPath = path.split("?")[0];
         const deadlineAt = this.deadlineAt();
+        const headers = extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers;
+        let ambiguous = false;
+        let refused;
         for (let attempt = 0;; attempt++) {
-            const att = this.beginAttempt(deadlineAt);
+            const last = attempt + 1 >= attempts;
+            const tag = `(attempt ${attempt + 1}/${attempts})`;
+            const start = Date.now();
+            const previous = refused;
+            refused = undefined;
+            const att = this.beginAttempt(deadlineAt, previous);
+            const pauseWithoutAnswer = async (why) => {
+                const delay = this.backoffMs(attempt);
+                if (!this.fits(delay, deadlineAt))
+                    throw previous ?? new APIConnectionError(0, this.abortMessage("deadline"));
+                logDebug(`${method} ${logPath}: ${why}. Retrying in ${Math.round(delay)}ms ${tag}`);
+                await this.pause(delay);
+            };
+            const cutShort = () => {
+                const why = att.why();
+                if (why === "deadline" && (idempotent || reads || (upper === "POST" && READ_POSTS.has(logPath))) && previous) {
+                    return previous;
+                }
+                return new APIConnectionError(0, this.abortMessage(why));
+            };
             let res;
             try {
                 res = await this.fetchImpl(`${this.base}${path}`, {
-                    method: "POST",
-                    headers: this.headers,
-                    body: JSON.stringify(body),
+                    method,
+                    headers,
+                    body: payload,
                     signal: att.signal,
                     redirect: "manual",
                 });
@@ -772,63 +1131,109 @@ class Client {
             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);
+                if (timedOut)
+                    throw cutShort();
+                const connect = isConnectFailure(e);
+                if ((idempotent || connect) && !last) {
+                    if (!connect)
+                        ambiguous = true;
+                    await pauseWithoutAnswer(e?.code ?? e?.name ?? "network error");
                     continue;
                 }
-                throw new APIConnectionError(0, timedOut ? this.abortMessage(att.why()) : `network error: ${e?.message ?? e}`);
+                throw this.networkError(e, path);
             }
-            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");
+            const readBody = async () => {
+                try {
+                    return await this.readCappedBytes(res);
                 }
-                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}`);
+                catch (e) {
+                    if (e?.name === "AbortError" || att.signal.aborted)
+                        throw cutShort();
+                    if (e instanceof WosError)
+                        throw e;
+                    if (idempotent && !last)
+                        return null;
+                    throw this.networkError(e, path);
                 }
-                let buf;
+            };
+            const readErrorBody = async (withinMs) => {
                 try {
-                    buf = await this.readCappedBytes(res);
+                    return { body: await this.readCappedBytes(res, withinMs) };
                 }
                 catch (e) {
-                    if (e?.name === "AbortError" || att.signal.aborted) {
-                        throw new APIConnectionError(0, this.abortMessage(att.why()));
+                    const aborted = e?.name === "AbortError" || att.signal.aborted;
+                    if (aborted && att.why() === "caller")
+                        throw new APIConnectionError(0, this.abortMessage("caller"));
+                    const unread = aborted
+                        ? this.abortMessage(att.why())
+                        : e instanceof SlowBody
+                            ? e.message
+                            : (e instanceof WosError ? e : this.networkError(e, path)).message.replace(/^\[\d+\] /, "");
+                    return { body: new Uint8Array(0), unread };
+                }
+            };
+            try {
+                if (this.isRedirected(res)) {
+                    discard(res);
+                    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;
+                if (!res.ok) {
+                    const ra = retryAfterMs(res.headers.get("Retry-After"));
+                    let wait = RETRY_ALWAYS.has(res.status) || (RETRY_IF_IDEMPOTENT.has(res.status) && idempotent)
+                        ? ra ?? this.backoffMs(attempt)
+                        : undefined;
+                    const retrying = wait !== undefined && !last && wait <= MAX_RETRY_WAIT_MS && this.fits(wait, deadlineAt);
+                    const { body, unread } = await readErrorBody(retrying ? Math.max(0, Math.min(BRIEF_BODY_MS, att.endsAt - Date.now())) : undefined);
+                    if (res.status === 409) {
+                        const d = parseErrorText(new TextDecoder().decode(body)).details;
+                        const ms = d?.retry_after_ms;
+                        if (typeof ms === "number" && Number.isFinite(ms) && ms >= 0 && d?.conflicts_with === undefined) {
+                            wait = Math.max(ms, this.backoffMs(attempt));
+                        }
                     }
-                    if (e instanceof WosError)
-                        throw e;
-                    throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
+                    if (wait !== undefined && !last) {
+                        if (wait > MAX_RETRY_WAIT_MS) {
+                            logDebug(`${method} ${logPath} -> ${res.status}: asked to wait ${Math.round(wait)}ms, over the cap. Not retrying ${tag}`);
+                        }
+                        else if (!this.fits(wait, deadlineAt)) {
+                            logDebug(`${method} ${logPath} -> ${res.status}: a ${Math.round(wait)}ms wait does not fit the deadline. Not retrying ${tag}`);
+                        }
+                        else {
+                            if (RETRY_IF_IDEMPOTENT.has(res.status))
+                                ambiguous = true;
+                            refused = this.errorFromAnswer(res, body, ra, ambiguous && removes, unread);
+                            att.clear();
+                            logDebug(`${method} ${logPath} -> ${res.status}. Retrying in ${Math.round(wait)}ms ${tag}`);
+                            await this.pause(wait);
+                            continue;
+                        }
+                    }
+                    logDebug(`${method} ${logPath} -> ${res.status} in ${Date.now() - start}ms ${tag}`);
+                    throw this.errorFromAnswer(res, body, ra, ambiguous && removes, unread);
                 }
-                if (buf.byteLength === 0) {
-                    throw new WosError(res.status, "empty image body — the service returned no bytes");
+                const body = await readBody();
+                if (body === null) {
+                    ambiguous = true;
+                    att.clear();
+                    await pauseWithoutAnswer("body dropped mid-stream");
+                    continue;
                 }
-                return { bytes: buf, contentType: res.headers.get("content-type") ?? "application/octet-stream" };
+                logDebug(`${method} ${logPath} -> ${res.status} in ${Date.now() - start}ms ${tag}`);
+                return { res, body };
             }
             finally {
                 att.clear();
             }
         }
     }
+    async requestBytes(path, body) {
+        const { res, body: buf } = await this.send("POST", path, JSON.stringify(body), undefined, false, true);
+        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" };
+    }
     idemHeader(key) {
         if (key === undefined || key === null)
             return undefined;
@@ -838,58 +1243,72 @@ class Client {
         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()));
-        }
+        const ra = retryAfterMs(retryAfter ?? null);
+        if (ra !== undefined)
+            return ra;
         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) {
+    async readCappedBytes(res, withinMs) {
         const cl = res.headers.get("content-length");
         if (cl && Number(cl) > MAX_RESPONSE_BYTES) {
+            discard(res);
             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`);
+        const slow = () => new SlowBody(`not received within ${withinMs}ms`);
+        let late = false;
+        let reader;
+        let stop = () => { };
+        const stopped = new Promise((_, reject) => (stop = () => reject(slow())));
+        stopped.catch(() => { });
+        const timer = withinMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                late = true;
+                stop();
+                reader?.cancel().catch(() => { });
+            }, withinMs);
+        const within = (p) => (timer === undefined ? p : Promise.race([p, stopped]));
+        try {
+            if (!res.body) {
+                const buf = new Uint8Array(await within(res.arrayBuffer()));
+                if (buf.byteLength > MAX_RESPONSE_BYTES) {
+                    throw new WosError(res.status, `response too large (${buf.byteLength} bytes) — refusing it`);
+                }
+                return buf;
+            }
+            reader = res.body.getReader();
+            const parts = [];
+            let size = 0;
+            for (;;) {
+                const { done, value } = await within(reader.read());
+                if (late)
+                    throw slow();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > MAX_RESPONSE_BYTES) {
+                    reader.cancel().catch(() => { });
+                    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;
         }
-        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);
+        catch (e) {
+            throw late && !(e instanceof SlowBody) ? slow() : e;
         }
-        const buf = new Uint8Array(size);
-        let off = 0;
-        for (const p of parts) {
-            buf.set(p, off);
-            off += p.byteLength;
+        finally {
+            clearTimeout(timer);
         }
-        return buf;
     }
-    async request(method, path, body, idempotencyKey) {
+    async request(method, path, body, idempotencyKey, removes = false) {
         const extraHeaders = this.idemHeader(idempotencyKey);
-        const attempts = this.maxRetries + 1;
-        const logPath = path.split("?")[0];
-        const deadlineAt = this.deadlineAt();
         let payload;
         try {
             payload = body === undefined ? undefined : JSON.stringify(body);
@@ -898,117 +1317,28 @@ class Client {
             throw new Error(`request body could not be serialized: ${e instanceof Error ? e.message : String(e)}. ` +
                 "Pass plain JSON values — an ORM entity, a BigInt or a circular reference cannot be sent.");
         }
-        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: payload,
-                    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;
-                if (!(IDEMPOTENT_METHODS.has(method.toUpperCase()) && attempt + 1 < attempts)) {
-                    throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
-                }
-                att.clear();
-                const delay = this.backoffMs(attempt);
-                logDebug(`${method} ${logPath} — body dropped mid-stream, retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
-                await this.backoffSleep(delay, deadlineAt);
-                continue;
-            }
-            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;
+        const { res, body: buf } = await this.send(method, path, payload, extraHeaders, removes);
+        const text = new TextDecoder().decode(buf);
+        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: ${cleanServerText(String(e?.message ?? e), 512)}`);
+        }
+        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;
         }
-        throw new Error("retries exhausted");
+        return data;
     }
 }
 exports.Client = Client;