wontopos 2.2.35 → 2.2.37

package/dist/wontopos.d.ts

@@ -44,6 +44,9 @@
 export declare function _resetStoreIdWarnings(): void;
 export declare const SEARCH_LIMIT_MIN = 5;
 export declare const SEARCH_LIMIT_MAX = 20;
+/** `recall`'s surrounding-context count. 0 to 20 inclusive; 0 attaches none. */
+export declare const CONTEXT_LIMIT_MIN = 0;
+export declare const CONTEXT_LIMIT_MAX = 20;
 /** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
 export interface RateLimit {
     limit: number | null;
@@ -356,6 +359,36 @@ export interface HistoryTurn {
     timestamp?: string;
     [key: string]: unknown;
 }
+/** `usage` → what this key has spent, and what is left to spend. */
+export interface UsageResult {
+    window_days?: number;
+    /** This API key's LIFETIME spend. Never another key's. */
+    key?: {
+        requests?: number;
+        cost_cents?: number;
+        input_tokens?: number;
+        output_tokens?: number;
+        since?: string;
+    };
+    /** The workspace this key belongs to, over the window. */
+    workspace?: {
+        workspace_id?: string | null;
+        requests?: number;
+        cost_cents?: number;
+    };
+    /** Per-store spend over the window, busiest first, and at most 50 rows — a longer
+     *  list is cut, so these need not sum to `workspace`. `other`, when present, is an
+     *  overflow bucket rather than a store. */
+    stores?: {
+        store?: string;
+        requests?: number;
+        cost_cents?: number;
+    }[];
+    /** Prepaid balance left on the ACCOUNT. Negative means overdrawn. */
+    balance_cents?: number;
+    expiring_soon_cents?: number;
+    [key: string]: unknown;
+}
 export interface StatsResult {
     total_memories?: number;
     short_term_turns?: number;
@@ -547,6 +580,22 @@ export interface ClientOptions {
      *  key on an options object is not an error in TS at runtime). Both names work;
      *  `maxRetries` wins if somehow both are given. */
     retries?: number;
+    /** A total budget for one call, in ms, across every attempt.
+     *
+     *  `timeoutMs` bounds ONE attempt. At the defaults — 30s, two retries — a single
+     *  call can hold a connection for 30s + backoff + 30s + backoff + 30s, over a
+     *  minute, and a server handler awaiting it has no way to say "I only have five
+     *  seconds". This is that way. Unset means no overall budget. */
+    deadlineMs?: number;
+    /** The caller's `AbortSignal` — cancel work already in flight.
+     *
+     *  The SDK aborts on its own timeout; this is the seam for the caller's reason.
+     *  When someone closes the chat window, the recall that window asked for should
+     *  end, and the backoff sleep waiting to retry it should end too, instead of
+     *  running to completion and billing for an answer nobody will read.
+     *
+     *  Per call, clone: `mem.withSignal(ctrl.signal).recall(...)`. */
+    signal?: AbortSignal;
     /** The `fetch` used for every request (default: the global `fetch`).
      *
      *  This is the seam for anything the runtime cannot express through options.
@@ -576,6 +625,8 @@ export declare class Client {
     private readonly apiKey;
     private readonly model;
     private readonly maxRetries;
+    private readonly deadlineMs?;
+    private readonly signal?;
     /** Transport. Held as a field (not read off `globalThis` per call) so a caller
      * who passes one gets it for every request, including from cloned clients. */
     private readonly fetchImpl;
@@ -603,6 +654,18 @@ export declare class Client {
     withModel(model: string): Client;
     /** A client bound to `userId` as its default store (everything else kept). */
     withUser(userId: string): Client;
+    /** A client bound to a caller's `AbortSignal` (everything else kept).
+     *
+     *     const ctrl = new AbortController();
+     *     req.on("close", () => ctrl.abort());
+     *     const r = await mem.withSignal(ctrl.signal).recall(q, user);
+     *
+     * Aborting ends the request in flight AND any backoff sleep waiting to retry it. */
+    withSignal(signal: AbortSignal): Client;
+    /** A client with a total budget per call, across every retry (everything else
+     * kept). `mem.withDeadline(5_000).search(q)` inside a handler that has five
+     * seconds. */
+    withDeadline(deadlineMs: number): Client;
     /** A client with a different per-request timeout in ms (everything else kept).
      * `mem.withTimeout(120_000).addBulk(bigBlob)` — this slow call only. */
     withTimeout(timeoutMs: number): Client;
@@ -687,6 +750,20 @@ export declare class Client {
     history(userId?: string): Promise<HistoryTurn[]>;
     /** Memory counts for a store: { total_memories, short_term_turns }. */
     stats(userId?: string): Promise<StatsResult>;
+    /**
+     * What this key has spent, and what is left — the numbers behind "can I keep going?".
+     *
+     * Free: it carries no charge and skips the balance gate, because an account at zero
+     * still has to be able to find out why. Rate-limited instead.
+     *
+     * Scoped to THIS key: its own lifetime spend, its workspace and stores over the
+     * window. It never returns another key's spend. `balance_cents` is account-wide,
+     * because that is what gates the next call whichever key makes it.
+     *
+     *     const u = await mem.usage(7);
+     *     if (u.balance_cents! < 100) stop();
+     */
+    usage(days?: number): Promise<UsageResult>;
     /** Fetch ONE memory by id — the text you stored, and its metadata.
      * The id is what `add`/`store` or `listMemories` returned. Same visibility as
      * `listMemories`: an id from another store, an internal record id, or an
@@ -907,6 +984,31 @@ export declare class Client {
      * a non-2xx we re-read the body as text and reuse `errorFor`, which keeps 404
      * (`NotFoundError`) and 401 behaving the same as everywhere else.
      */
+    /** Where this call's budget runs out, or `undefined` when it has none. Computed
+     *  once per call, not per attempt — a budget recomputed each attempt is not a
+     *  budget. */
+    private deadlineAt;
+    /** The abort wiring for ONE attempt: this SDK's per-attempt timeout, the caller's
+     *  signal, and whatever is left of the overall deadline — whichever fires first.
+     *
+     *  One function, two callers (`request` and `requestBytes`), because a guard living
+     *  in one of two request paths is exactly how `getImage` ended up with no retry loop
+     *  while the module doc promised every call had one. */
+    private beginAttempt;
+    /** What to say when an attempt was cut short. The three reasons need different
+     *  words: a timeout may have landed server-side, a cancellation certainly did not
+     *  matter to the caller, and an exhausted budget is the caller's own setting. */
+    private abortMessage;
+    /** Sleep between attempts — but wake the moment the caller aborts, and give up
+     *  rather than wait out a backoff the budget cannot cover. A backoff that runs to
+     *  completion after the caller gave up wastes exactly as long as the request it was
+     *  waiting to repeat.
+     *
+     *  Clamping the wait to what is left and retrying anyway is the same answer as
+     *  having no deadline at all: the call still spends the whole allowance, and the one
+     *  attempt it buys has nothing left to finish in. If the wait does not fit, the
+     *  budget is already decided. */
+    private backoffSleep;
     private requestBytes;
     /** Validate an idempotency key BEFORE the network. The API answers a malformed
      *  key with a 400, which on a retry path reads as "my write failed" when in fact