wontopos 2.2.36 → 2.2.37

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;
@@ -720,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