@routstr/sdk 0.1.0 → 0.1.2

package/dist/client/index.d.mts

@@ -0,0 +1,293 @@
+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 { CashuSpender, BalanceManager } from '../wallet/index.mjs';
+
+/**
+ * ProviderManager - Handles provider selection and failover logic
+ *
+ * Handles:
+ * - Finding the best provider for a model based on price
+ * - Provider failover when errors occur
+ * - Tracking failed providers to avoid retry loops
+ * - Provider version compatibility
+ *
+ * Extracted from utils/apiUtils.ts findNextBestProvider and related logic
+ */
+
+interface ModelProviderPrice {
+    baseUrl: string;
+    model: Model;
+    promptPerMillion: number;
+    completionPerMillion: number;
+    totalPerMillion: number;
+}
+declare class ProviderManager {
+    private providerRegistry;
+    private failedProviders;
+    constructor(providerRegistry: ProviderRegistry);
+    /**
+     * Reset the failed providers list
+     */
+    resetFailedProviders(): void;
+    /**
+     * Mark a provider as failed
+     */
+    markFailed(baseUrl: string): void;
+    /**
+     * Check if a provider has failed
+     */
+    hasFailed(baseUrl: string): boolean;
+    /**
+     * Find the next best provider for a model
+     * @param modelId The model ID to find a provider for
+     * @param currentBaseUrl The current provider to exclude
+     * @returns The best provider URL or null if none available
+     */
+    findNextBestProvider(modelId: string, currentBaseUrl: string): string | null;
+    /**
+     * Find the best model for a provider
+     * Useful when switching providers and need to find equivalent model
+     */
+    getModelForProvider(baseUrl: string, modelId: string): Promise<Model | null>;
+    /**
+     * Get all available providers for a model
+     * Returns sorted list by price
+     */
+    getAllProvidersForModel(modelId: string): Array<{
+        baseUrl: string;
+        model: Model;
+        cost: number;
+    }>;
+    /**
+     * Get providers for a model sorted by prompt+completion pricing
+     */
+    getProviderPriceRankingForModel(modelId: string, options?: {
+        torMode?: boolean;
+        includeDisabled?: boolean;
+    }): ModelProviderPrice[];
+    /**
+     * Get best-priced provider for a specific model
+     */
+    getBestProviderForModel(modelId: string, options?: {
+        torMode?: boolean;
+        includeDisabled?: boolean;
+    }): string | null;
+    private normalizeModelId;
+    /**
+     * Check if a provider accepts a specific mint
+     */
+    providerAcceptsMint(baseUrl: string, mintUrl: string): boolean;
+    /**
+     * Get required sats for a model based on message history
+     * Simple estimation based on typical usage
+     */
+    getRequiredSatsForModel(model: Model, apiMessages: any[], maxTokens?: number): number;
+}
+
+/**
+ * RoutstrClient - Main API client for Routstr
+ *
+ * Orchestrates:
+ * - Token spending via CashuSpender
+ * - API requests with authentication
+ * - Streaming response processing
+ * - Provider failover via ProviderManager
+ * - Error handling and refunds
+ *
+ * Extracted from utils/apiUtils.ts
+ */
+
+/**
+ * Options for fetching AI response
+ */
+interface FetchOptions {
+    messageHistory: Message[];
+    selectedModel: Model;
+    baseUrl: string;
+    mintUrl: string;
+    balance: number;
+    transactionHistory: TransactionHistory[];
+    maxTokens?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * RoutstrClient is the main SDK entry point
+ */
+type AlertLevel = "max" | "min";
+type RoutstrClientMode = "xcashu" | "lazyrefund" | "apikeys";
+type DebugLevel = "DEBUG" | "WARN" | "ERROR";
+interface RouteRequestParams {
+    path: string;
+    method: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    baseUrl: string;
+    mintUrl: string;
+    modelId?: string;
+}
+declare class RoutstrClient {
+    private walletAdapter;
+    private storageAdapter;
+    private providerRegistry;
+    private cashuSpender;
+    private balanceManager;
+    private streamProcessor;
+    private providerManager;
+    private alertLevel;
+    private mode;
+    private debugLevel;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, providerRegistry: ProviderRegistry, alertLevel: AlertLevel, mode?: RoutstrClientMode);
+    /**
+     * Get the current client mode
+     */
+    getMode(): RoutstrClientMode;
+    getDebugLevel(): DebugLevel;
+    setDebugLevel(level: DebugLevel): void;
+    private _log;
+    /**
+     * Get the CashuSpender instance
+     */
+    getCashuSpender(): CashuSpender;
+    /**
+     * Get the BalanceManager instance
+     */
+    getBalanceManager(): BalanceManager;
+    /**
+     * Get the ProviderManager instance
+     */
+    getProviderManager(): ProviderManager;
+    /**
+     * Check if the client is currently busy (in critical section)
+     */
+    get isBusy(): boolean;
+    /**
+     * Route an API request to the upstream provider
+     *
+     * This is a simpler alternative to fetchAIResponse that just proxies
+     * the request upstream without the streaming callback machinery.
+     * Useful for daemon-style routing where you just need to forward
+     * requests and get responses back.
+     */
+    routeRequest(params: RouteRequestParams): Promise<Response>;
+    /**
+     * Fetch AI response with streaming
+     */
+    fetchAIResponse(options: FetchOptions, callbacks: StreamingCallbacks): Promise<void>;
+    /**
+     * Make the API request with failover support
+     */
+    private _makeRequest;
+    /**
+     * Handle error responses with failover
+     */
+    private _handleErrorResponse;
+    /**
+     * Handle post-response balance update for all modes
+     */
+    private _handlePostResponseBalanceUpdate;
+    /**
+     * Convert messages for API format
+     */
+    private _convertMessages;
+    /**
+     * 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
+     */
+    private _getPendingCashuTokenAmount;
+    /**
+     * Check if error message indicates a network error
+     */
+    private _isNetworkError;
+    /**
+     * Handle errors and notify callbacks
+     */
+    private _handleError;
+    /**
+     * Check wallet balance and throw if insufficient
+     */
+    private _checkBalance;
+    /**
+     * Spend a token using CashuSpender with standardized error handling
+     */
+    private _spendToken;
+    /**
+     * Build request headers with common defaults and dev mock controls
+     */
+    private _buildBaseHeaders;
+    /**
+     * Attach auth headers using the active client mode
+     */
+    private _withAuthHeader;
+}
+
+/**
+ * StreamProcessor - Handles SSE streaming response parsing
+ *
+ * Handles:
+ * - Line buffering for large payloads
+ * - Content extraction from delta chunks
+ * - Thinking/reasoning block extraction
+ * - Image data merging and deduplication
+ * - Usage statistics extraction
+ * - Citations and annotations
+ *
+ * Extracted from utils/apiUtils.ts processStreamingResponse
+ */
+
+/**
+ * Callbacks for streaming updates
+ */
+interface StreamCallbacks {
+    /** Called when new content arrives */
+    onContent: (content: string) => void;
+    /** Called when thinking content arrives */
+    onThinking: (thinking: string) => void;
+}
+/**
+ * StreamProcessor parses SSE streaming responses
+ */
+declare class StreamProcessor {
+    private accumulatedContent;
+    private accumulatedThinking;
+    private accumulatedImages;
+    private isInThinking;
+    private isInContent;
+    /**
+     * Process a streaming response
+     */
+    process(response: Response, callbacks: StreamCallbacks, modelId?: string): Promise<StreamingResult>;
+    /**
+     * Parse a single SSE line
+     */
+    private _parseLine;
+    /**
+     * Handle content delta with thinking support
+     */
+    private _handleContent;
+    /**
+     * Handle thinking/reasoning content
+     */
+    private _handleThinking;
+    /**
+     * Extract thinking blocks from content (for models with inline thinking)
+     */
+    private _extractThinkingFromContent;
+    /**
+     * Merge images into accumulated array, avoiding duplicates
+     */
+    private _mergeImages;
+}
+
+export { type AlertLevel, type DebugLevel, type FetchOptions, type ModelProviderPrice, ProviderManager, type RouteRequestParams, RoutstrClient, type RoutstrClientMode, type StreamCallbacks, StreamProcessor };

package/dist/client/index.d.ts

@@ -0,0 +1,293 @@
+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 { CashuSpender, BalanceManager } from '../wallet/index.js';
+
+/**
+ * ProviderManager - Handles provider selection and failover logic
+ *
+ * Handles:
+ * - Finding the best provider for a model based on price
+ * - Provider failover when errors occur
+ * - Tracking failed providers to avoid retry loops
+ * - Provider version compatibility
+ *
+ * Extracted from utils/apiUtils.ts findNextBestProvider and related logic
+ */
+
+interface ModelProviderPrice {
+    baseUrl: string;
+    model: Model;
+    promptPerMillion: number;
+    completionPerMillion: number;
+    totalPerMillion: number;
+}
+declare class ProviderManager {
+    private providerRegistry;
+    private failedProviders;
+    constructor(providerRegistry: ProviderRegistry);
+    /**
+     * Reset the failed providers list
+     */
+    resetFailedProviders(): void;
+    /**
+     * Mark a provider as failed
+     */
+    markFailed(baseUrl: string): void;
+    /**
+     * Check if a provider has failed
+     */
+    hasFailed(baseUrl: string): boolean;
+    /**
+     * Find the next best provider for a model
+     * @param modelId The model ID to find a provider for
+     * @param currentBaseUrl The current provider to exclude
+     * @returns The best provider URL or null if none available
+     */
+    findNextBestProvider(modelId: string, currentBaseUrl: string): string | null;
+    /**
+     * Find the best model for a provider
+     * Useful when switching providers and need to find equivalent model
+     */
+    getModelForProvider(baseUrl: string, modelId: string): Promise<Model | null>;
+    /**
+     * Get all available providers for a model
+     * Returns sorted list by price
+     */
+    getAllProvidersForModel(modelId: string): Array<{
+        baseUrl: string;
+        model: Model;
+        cost: number;
+    }>;
+    /**
+     * Get providers for a model sorted by prompt+completion pricing
+     */
+    getProviderPriceRankingForModel(modelId: string, options?: {
+        torMode?: boolean;
+        includeDisabled?: boolean;
+    }): ModelProviderPrice[];
+    /**
+     * Get best-priced provider for a specific model
+     */
+    getBestProviderForModel(modelId: string, options?: {
+        torMode?: boolean;
+        includeDisabled?: boolean;
+    }): string | null;
+    private normalizeModelId;
+    /**
+     * Check if a provider accepts a specific mint
+     */
+    providerAcceptsMint(baseUrl: string, mintUrl: string): boolean;
+    /**
+     * Get required sats for a model based on message history
+     * Simple estimation based on typical usage
+     */
+    getRequiredSatsForModel(model: Model, apiMessages: any[], maxTokens?: number): number;
+}
+
+/**
+ * RoutstrClient - Main API client for Routstr
+ *
+ * Orchestrates:
+ * - Token spending via CashuSpender
+ * - API requests with authentication
+ * - Streaming response processing
+ * - Provider failover via ProviderManager
+ * - Error handling and refunds
+ *
+ * Extracted from utils/apiUtils.ts
+ */
+
+/**
+ * Options for fetching AI response
+ */
+interface FetchOptions {
+    messageHistory: Message[];
+    selectedModel: Model;
+    baseUrl: string;
+    mintUrl: string;
+    balance: number;
+    transactionHistory: TransactionHistory[];
+    maxTokens?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * RoutstrClient is the main SDK entry point
+ */
+type AlertLevel = "max" | "min";
+type RoutstrClientMode = "xcashu" | "lazyrefund" | "apikeys";
+type DebugLevel = "DEBUG" | "WARN" | "ERROR";
+interface RouteRequestParams {
+    path: string;
+    method: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    baseUrl: string;
+    mintUrl: string;
+    modelId?: string;
+}
+declare class RoutstrClient {
+    private walletAdapter;
+    private storageAdapter;
+    private providerRegistry;
+    private cashuSpender;
+    private balanceManager;
+    private streamProcessor;
+    private providerManager;
+    private alertLevel;
+    private mode;
+    private debugLevel;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, providerRegistry: ProviderRegistry, alertLevel: AlertLevel, mode?: RoutstrClientMode);
+    /**
+     * Get the current client mode
+     */
+    getMode(): RoutstrClientMode;
+    getDebugLevel(): DebugLevel;
+    setDebugLevel(level: DebugLevel): void;
+    private _log;
+    /**
+     * Get the CashuSpender instance
+     */
+    getCashuSpender(): CashuSpender;
+    /**
+     * Get the BalanceManager instance
+     */
+    getBalanceManager(): BalanceManager;
+    /**
+     * Get the ProviderManager instance
+     */
+    getProviderManager(): ProviderManager;
+    /**
+     * Check if the client is currently busy (in critical section)
+     */
+    get isBusy(): boolean;
+    /**
+     * Route an API request to the upstream provider
+     *
+     * This is a simpler alternative to fetchAIResponse that just proxies
+     * the request upstream without the streaming callback machinery.
+     * Useful for daemon-style routing where you just need to forward
+     * requests and get responses back.
+     */
+    routeRequest(params: RouteRequestParams): Promise<Response>;
+    /**
+     * Fetch AI response with streaming
+     */
+    fetchAIResponse(options: FetchOptions, callbacks: StreamingCallbacks): Promise<void>;
+    /**
+     * Make the API request with failover support
+     */
+    private _makeRequest;
+    /**
+     * Handle error responses with failover
+     */
+    private _handleErrorResponse;
+    /**
+     * Handle post-response balance update for all modes
+     */
+    private _handlePostResponseBalanceUpdate;
+    /**
+     * Convert messages for API format
+     */
+    private _convertMessages;
+    /**
+     * 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
+     */
+    private _getPendingCashuTokenAmount;
+    /**
+     * Check if error message indicates a network error
+     */
+    private _isNetworkError;
+    /**
+     * Handle errors and notify callbacks
+     */
+    private _handleError;
+    /**
+     * Check wallet balance and throw if insufficient
+     */
+    private _checkBalance;
+    /**
+     * Spend a token using CashuSpender with standardized error handling
+     */
+    private _spendToken;
+    /**
+     * Build request headers with common defaults and dev mock controls
+     */
+    private _buildBaseHeaders;
+    /**
+     * Attach auth headers using the active client mode
+     */
+    private _withAuthHeader;
+}
+
+/**
+ * StreamProcessor - Handles SSE streaming response parsing
+ *
+ * Handles:
+ * - Line buffering for large payloads
+ * - Content extraction from delta chunks
+ * - Thinking/reasoning block extraction
+ * - Image data merging and deduplication
+ * - Usage statistics extraction
+ * - Citations and annotations
+ *
+ * Extracted from utils/apiUtils.ts processStreamingResponse
+ */
+
+/**
+ * Callbacks for streaming updates
+ */
+interface StreamCallbacks {
+    /** Called when new content arrives */
+    onContent: (content: string) => void;
+    /** Called when thinking content arrives */
+    onThinking: (thinking: string) => void;
+}
+/**
+ * StreamProcessor parses SSE streaming responses
+ */
+declare class StreamProcessor {
+    private accumulatedContent;
+    private accumulatedThinking;
+    private accumulatedImages;
+    private isInThinking;
+    private isInContent;
+    /**
+     * Process a streaming response
+     */
+    process(response: Response, callbacks: StreamCallbacks, modelId?: string): Promise<StreamingResult>;
+    /**
+     * Parse a single SSE line
+     */
+    private _parseLine;
+    /**
+     * Handle content delta with thinking support
+     */
+    private _handleContent;
+    /**
+     * Handle thinking/reasoning content
+     */
+    private _handleThinking;
+    /**
+     * Extract thinking blocks from content (for models with inline thinking)
+     */
+    private _extractThinkingFromContent;
+    /**
+     * Merge images into accumulated array, avoiding duplicates
+     */
+    private _mergeImages;
+}
+
+export { type AlertLevel, type DebugLevel, type FetchOptions, type ModelProviderPrice, ProviderManager, type RouteRequestParams, RoutstrClient, type RoutstrClientMode, type StreamCallbacks, StreamProcessor };