wontopos 2.2.36 → 2.2.38

package/dist/wontopos.d.ts

@@ -359,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;
@@ -460,7 +490,10 @@ export interface SearchFilters {
 }
 /** Test hook — the warn-once set is process-global by design. */
 export declare function _resetFilterWarnings(): void;
-/** Known `search` options; extra fields pass through to the API untouched. */
+/** Known `search` options. An unknown key is refused before anything is sent — the
+ *  service drops keys it does not recognise and answers normally, so a misspelling
+ *  could not be told from an option that worked. Put a genuinely new one under
+ *  `extra`. */
 export interface SearchOptions {
     /** Recall caching. A hit inside the TTL bills at 0.1× — but the FIRST call
      *  writes the cache and bills the query tokens at 2× (`5m`) or 3× (`1h`), so
@@ -489,7 +522,9 @@ export interface SearchOptions {
      */
     verify?: number;
     /**
-     * How many image memories the answer may carry, 0–5. Default 1; 0 asks for none.
+     * How many image memories the answer may carry, 0–5. Omit it and the service uses
+     * 1; `0` asks for none. The MCP server defaults its own tool to 0 instead, so most
+     * searches through it carry no image rows.
      * Out of range is refused, not clamped — silently cutting 5 to 1 would leave you
      * believing you got five.
      *
@@ -497,7 +532,13 @@ export interface SearchOptions {
      * than answering with no images.
      */
     max_images?: number;
-    [key: string]: unknown;
+    /**
+     * Fields the service accepts that this version does not know about, merged into the
+     * request as written. Every other key is refused, so a typo cannot reach the wire —
+     * `verfy: 3` used to be sent, dropped by the service, and answered normally, leaving
+     * a caller billed for one pass believing they had bought three.
+     */
+    extra?: Record<string, unknown>;
 }
 /**
  * Per-call options for a write.
@@ -660,6 +701,11 @@ export declare class Client {
     /** Supersede an old memory with new content. Payload first, userId last — same shape as add/search. */
     update(oldMemoryId: string, newContent: string, userId?: string, opts?: WriteOptions): Promise<UpdateResult>;
     /** Search a store's memories. Returns them most relevant first.
+     *
+     *  `limit` is 5-20, and out of range is refused rather than clamped: asking for 50
+     *  and silently receiving 20 reads as "that is all there is". The default is 10, so
+     *  a call that passes no count is unaffected. Before 2.2.35 the count was sent on
+     *  unchecked.
      *
      *  `limit` bounds `memories`, not the returned array. On a model that keeps the
      *  assistant's own words separate (Scroll 1.2+) those come back as well, so the
@@ -720,6 +766,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