@routstr/sdk 0.2.4 → 0.2.6

package/README.md

@@ -25,10 +25,19 @@ This SDK lives under `sdk/` and exposes a framework-agnostic surface for Routstr
 - `sdk/storage/index.ts` exposes:
   - `getDefaultSdkDriver()` (localStorage -> sqlite -> memory)
   - `getDefaultSdkStore()`
+  - `getDefaultUsageTrackingDriver()`
   - `getDefaultDiscoveryAdapter()`
   - `getDefaultStorageAdapter()`
   - `getDefaultProviderRegistry()`
 
+Usage tracking is now stored separately from the Zustand-backed SDK state:
+
+- browser: IndexedDB usage-tracking object store
+- node: SQLite usage-tracking table
+- bun/ephemeral: in-memory usage-tracking driver
+
+The usage tracking driver also exposes `migrate()` so apps can proactively move legacy blob data into the new backend during startup instead of waiting for the first append/read operation.
+
 ## Minimal Usage
 
 ```ts
@@ -61,10 +70,9 @@ await client.fetchAIResponse(fetchOptions, streamingCallbacks);
 
 ## Client Modes
 
-The `RoutstrClient` supports three modes via the constructor `mode` parameter (defaults to `"xcashu"` if unspecified):
+The `RoutstrClient` supports two modes via the constructor `mode` parameter (defaults to `"xcashu"` if unspecified):
 
 - `"xcashu"` — Default mode. Uses standard Cashu token spending with refunds.
-- `"lazyrefund"` — Defers refund processing to reduce mint load; may retain tokens longer before refunding.
 - `"apikeys"` — Uses API key authentication instead of Cashu tokens; no token spending or refund flow.
 
 ```ts

package/dist/client/index.d.mts

@@ -1,6 +1,11 @@
-import { M as Model, a as Message, T as TransactionHistory, l as StreamingResult } from '../types-BlHjmWRK.mjs';
-import { P as ProviderRegistry, W as WalletAdapter, S as StorageAdapter, a as StreamingCallbacks } from '../interfaces-B85Wx7ni.mjs';
+import { M as Model, a as Message, T as TransactionHistory, l as StreamingResult } from '../types-BYj_8c5c.mjs';
+import { P as ProviderRegistry, W as WalletAdapter, S as StorageAdapter, a as StreamingCallbacks } from '../interfaces-C5fLD3jB.mjs';
+import { U as UsageTrackingDriver, S as SdkStore } from '../store-C5lnyX8k.mjs';
+import { ServerResponse } from 'http';
 import { CashuSpender, BalanceManager } from '../wallet/index.mjs';
+import { Transform } from 'stream';
+import 'zustand/vanilla';
+import '../interfaces-BWJJTCXO.mjs';
 
 /**
  * ProviderManager - Handles provider selection and failover logic
@@ -161,7 +166,7 @@ interface FetchOptions {
  * RoutstrClient is the main SDK entry point
  */
 type AlertLevel = "max" | "min";
-type RoutstrClientMode = "xcashu" | "lazyrefund" | "apikeys";
+type RoutstrClientMode = "xcashu" | "apikeys";
 type DebugLevel = "DEBUG" | "WARN" | "ERROR";
 interface RouteRequestParams {
     path: string;
@@ -171,6 +176,14 @@ interface RouteRequestParams {
     baseUrl: string;
     mintUrl: string;
     modelId?: string;
+    clientApiKey?: string;
+}
+interface RouteRequestToNodeResponseParams extends RouteRequestParams {
+    res: ServerResponse;
+}
+interface RoutstrClientConfig {
+    usageTrackingDriver?: UsageTrackingDriver;
+    sdkStore?: SdkStore;
 }
 declare class RoutstrClient {
     private walletAdapter;
@@ -183,7 +196,9 @@ declare class RoutstrClient {
     private alertLevel;
     private mode;
     private debugLevel;
-    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, providerRegistry: ProviderRegistry, alertLevel: AlertLevel, mode?: RoutstrClientMode);
+    private usageTrackingDriver?;
+    private sdkStore?;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, providerRegistry: ProviderRegistry, alertLevel: AlertLevel, mode?: RoutstrClientMode, options?: RoutstrClientConfig);
     /**
      * Get the current client mode
      */
@@ -216,6 +231,12 @@ declare class RoutstrClient {
      * requests and get responses back.
      */
     routeRequest(params: RouteRequestParams): Promise<Response>;
+    routeRequestToNodeResponse(params: RouteRequestToNodeResponseParams): Promise<void>;
+    private _prepareRoutedRequest;
+    /**
+     * Extract clientApiKey from Authorization Bearer token if present
+     */
+    private _extractClientApiKey;
     /**
      * Fetch AI response with streaming
      */
@@ -232,6 +253,7 @@ declare class RoutstrClient {
      * Handle post-response balance update for all modes
      */
     private _handlePostResponseBalanceUpdate;
+    private _trackResponseUsage;
     /**
      * Convert messages for API format
      */
@@ -240,17 +262,12 @@ declare class RoutstrClient {
      * Create assistant message from streaming result
      */
     private _createAssistantMessage;
-    /**
-     * Create a child key for a parent API key via the provider's API
-     * POST /v1/balance/child-key
-     */
-    private _createChildKey;
     /**
      * Calculate estimated costs from usage
      */
     private _getEstimatedCosts;
     /**
-     * Get pending cashu token amount
+     * Get pending API key amount
      */
     private _getPendingCashuTokenAmount;
     /**
@@ -333,4 +350,14 @@ declare class StreamProcessor {
     private _mergeImages;
 }
 
-export { type AlertLevel, type DebugLevel, type FetchOptions, type ModelProviderPrice, ProviderManager, type RouteRequestParams, RoutstrClient, type RoutstrClientMode, type StreamCallbacks, StreamProcessor };
+interface UsageTrackingData {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cost: number;
+    satsCost: number;
+}
+
+declare function createSSEParserTransform(onUsage: (usage: UsageTrackingData) => void, onResponseId?: (responseId: string) => void): Transform;
+
+export { type AlertLevel, type DebugLevel, type FetchOptions, type ModelProviderPrice, ProviderManager, type RouteRequestParams, type RouteRequestToNodeResponseParams, RoutstrClient, type RoutstrClientConfig, type RoutstrClientMode, type StreamCallbacks, StreamProcessor, createSSEParserTransform };

package/dist/client/index.d.ts

@@ -1,6 +1,11 @@
-import { M as Model, a as Message, T as TransactionHistory, l as StreamingResult } from '../types-BlHjmWRK.js';
-import { P as ProviderRegistry, W as WalletAdapter, S as StorageAdapter, a as StreamingCallbacks } from '../interfaces-BVNyAmKu.js';
+import { M as Model, a as Message, T as TransactionHistory, l as StreamingResult } from '../types-BYj_8c5c.js';
+import { P as ProviderRegistry, W as WalletAdapter, S as StorageAdapter, a as StreamingCallbacks } from '../interfaces-B62Rw-dd.js';
+import { U as UsageTrackingDriver, S as SdkStore } from '../store-BJlwiDX5.js';
+import { ServerResponse } from 'http';
 import { CashuSpender, BalanceManager } from '../wallet/index.js';
+import { Transform } from 'stream';
+import 'zustand/vanilla';
+import '../interfaces-BxDEka72.js';
 
 /**
  * ProviderManager - Handles provider selection and failover logic
@@ -161,7 +166,7 @@ interface FetchOptions {
  * RoutstrClient is the main SDK entry point
  */
 type AlertLevel = "max" | "min";
-type RoutstrClientMode = "xcashu" | "lazyrefund" | "apikeys";
+type RoutstrClientMode = "xcashu" | "apikeys";
 type DebugLevel = "DEBUG" | "WARN" | "ERROR";
 interface RouteRequestParams {
     path: string;
@@ -171,6 +176,14 @@ interface RouteRequestParams {
     baseUrl: string;
     mintUrl: string;
     modelId?: string;
+    clientApiKey?: string;
+}
+interface RouteRequestToNodeResponseParams extends RouteRequestParams {
+    res: ServerResponse;
+}
+interface RoutstrClientConfig {
+    usageTrackingDriver?: UsageTrackingDriver;
+    sdkStore?: SdkStore;
 }
 declare class RoutstrClient {
     private walletAdapter;
@@ -183,7 +196,9 @@ declare class RoutstrClient {
     private alertLevel;
     private mode;
     private debugLevel;
-    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, providerRegistry: ProviderRegistry, alertLevel: AlertLevel, mode?: RoutstrClientMode);
+    private usageTrackingDriver?;
+    private sdkStore?;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, providerRegistry: ProviderRegistry, alertLevel: AlertLevel, mode?: RoutstrClientMode, options?: RoutstrClientConfig);
     /**
      * Get the current client mode
      */
@@ -216,6 +231,12 @@ declare class RoutstrClient {
      * requests and get responses back.
      */
     routeRequest(params: RouteRequestParams): Promise<Response>;
+    routeRequestToNodeResponse(params: RouteRequestToNodeResponseParams): Promise<void>;
+    private _prepareRoutedRequest;
+    /**
+     * Extract clientApiKey from Authorization Bearer token if present
+     */
+    private _extractClientApiKey;
     /**
      * Fetch AI response with streaming
      */
@@ -232,6 +253,7 @@ declare class RoutstrClient {
      * Handle post-response balance update for all modes
      */
     private _handlePostResponseBalanceUpdate;
+    private _trackResponseUsage;
     /**
      * Convert messages for API format
      */
@@ -240,17 +262,12 @@ declare class RoutstrClient {
      * Create assistant message from streaming result
      */
     private _createAssistantMessage;
-    /**
-     * Create a child key for a parent API key via the provider's API
-     * POST /v1/balance/child-key
-     */
-    private _createChildKey;
     /**
      * Calculate estimated costs from usage
      */
     private _getEstimatedCosts;
     /**
-     * Get pending cashu token amount
+     * Get pending API key amount
      */
     private _getPendingCashuTokenAmount;
     /**
@@ -333,4 +350,14 @@ declare class StreamProcessor {
     private _mergeImages;
 }
 
-export { type AlertLevel, type DebugLevel, type FetchOptions, type ModelProviderPrice, ProviderManager, type RouteRequestParams, RoutstrClient, type RoutstrClientMode, type StreamCallbacks, StreamProcessor };
+interface UsageTrackingData {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cost: number;
+    satsCost: number;
+}
+
+declare function createSSEParserTransform(onUsage: (usage: UsageTrackingData) => void, onResponseId?: (responseId: string) => void): Transform;
+
+export { type AlertLevel, type DebugLevel, type FetchOptions, type ModelProviderPrice, ProviderManager, type RouteRequestParams, type RouteRequestToNodeResponseParams, RoutstrClient, type RoutstrClientConfig, type RoutstrClientMode, type StreamCallbacks, StreamProcessor, createSSEParserTransform };