@routstr/sdk 0.3.7 → 0.3.8

package/dist/client/index.d.mts

@@ -0,0 +1,411 @@
+import { e as Model, S as SdkLogger, M as Message, n as TransactionHistory, m as StreamingResult } from '../types-_21yYFZG.mjs';
+import { P as ProviderRegistry, W as WalletAdapter, S as StorageAdapter, a as StreamingCallbacks } from '../interfaces-Csn8Uq04.mjs';
+import { S as SdkStore, U as UsageTrackingDriver } from '../store-C6dfj1cc.mjs';
+import { CashuSpender, BalanceManager } from '../wallet/index.mjs';
+import { Transform } from 'stream';
+import 'zustand/vanilla';
+import '../interfaces-Cv1k2EUK.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;
+    /** Track when each provider last failed (provider URL -> timestamp) */
+    private lastFailed;
+    /** Providers on cooldown: [provider_url, cooldown_started_timestamp][] */
+    private providersOnCoolDown;
+    /** Cooldown duration in milliseconds (42 seconds) */
+    private static readonly COOLDOWN_DURATION_MS;
+    /** Optional persistent store for failure tracking */
+    private store;
+    /** Instance ID for debugging */
+    private readonly instanceId;
+    private readonly logger;
+    constructor(providerRegistry: ProviderRegistry, store?: SdkStore, logger?: SdkLogger);
+    /**
+     * Hydrate in-memory state from persistent store
+     */
+    private hydrateFromStore;
+    /**
+     * Get instance ID for debugging
+     */
+    getInstanceId(): string;
+    /**
+     * Clean up expired cooldown entries
+     * Also removes the provider from failedProviders so it can be retried
+     */
+    private cleanupExpiredCooldowns;
+    /**
+     * Get the cooldown duration in milliseconds
+     */
+    getCooldownDurationMs(): number;
+    /**
+     * Check if a provider is currently on cooldown
+     */
+    isOnCooldown(baseUrl: string): boolean;
+    /**
+     * Get all providers currently on cooldown
+     */
+    getProvidersOnCooldown(): [string, number][];
+    /**
+     * Reset the failed providers list
+     */
+    resetFailedProviders(): void;
+    /**
+     * Get the last failed timestamp for a provider
+     */
+    getLastFailed(baseUrl: string): number | undefined;
+    /**
+     * Get all providers with their last failed timestamps
+     */
+    getAllLastFailed(): Map<string, number>;
+    /**
+     * Mark a provider as failed
+     * If a provider fails twice within 5 minutes, it's added to cooldown
+     */
+    markFailed(baseUrl: string): void;
+    /**
+     * Remove a provider from cooldown (e.g., after successful request)
+     */
+    removeFromCooldown(baseUrl: string): void;
+    /**
+     * Clear all cooldown tracking
+     */
+    clearCooldowns(): void;
+    /**
+     * Clear all failure tracking (lastFailed timestamps)
+     */
+    clearFailureHistory(): void;
+    /**
+     * Check if a provider has failed
+     */
+    hasFailed(baseUrl: string): boolean;
+    /**
+     * Get a copy of the failed providers set
+     */
+    getFailedProviders(): Set<string>;
+    /**
+     * 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" | "apikeys";
+type DebugLevel = "DEBUG" | "WARN" | "ERROR";
+interface RouteRequestParams {
+    path: string;
+    method: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    baseUrl: string;
+    mintUrl: string;
+    modelId?: string;
+    clientApiKey?: string;
+}
+interface RoutstrClientConfig {
+    usageTrackingDriver?: UsageTrackingDriver;
+    sdkStore?: SdkStore;
+    /** Optional: shared ProviderManager instance for consistent failure tracking across requests */
+    providerManager?: ProviderManager;
+    /** Optional: injectable logger (defaults to consoleLogger) */
+    logger?: SdkLogger;
+}
+declare class RoutstrClient {
+    private walletAdapter;
+    private storageAdapter;
+    private providerRegistry;
+    private cashuSpender;
+    private balanceManager;
+    private streamProcessor;
+    private providerManager;
+    private alertLevel;
+    private mode;
+    private debugLevel;
+    private usageTrackingDriver?;
+    private sdkStore?;
+    private logger;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, providerRegistry: ProviderRegistry, alertLevel: AlertLevel, mode?: RoutstrClientMode, options?: RoutstrClientConfig);
+    /**
+     * 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>;
+    private _prepareRoutedRequest;
+    /**
+     * Extract clientApiKey from Authorization Bearer token if present
+     */
+    private _extractClientApiKey;
+    /**
+     * 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;
+    private _trackResponseUsage;
+    /**
+     * Convert messages for API format
+     */
+    private _convertMessages;
+    /**
+     * Create assistant message from streaming result
+     */
+    private _createAssistantMessage;
+    /**
+     * Calculate estimated costs from usage
+     */
+    private _getEstimatedCosts;
+    /**
+     * Get pending API key amount
+     */
+    private _getPendingCashuTokenAmount;
+    /**
+     * 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;
+}
+
+interface UsageTrackingData {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cost: number;
+    satsCost: number;
+}
+
+/**
+ * Inspect a Web `ReadableStream<Uint8Array>` of SSE bytes for `usage` and
+ * response `id` fields without touching the bytes that are delivered to the
+ * real client. This is meant to be called on one branch of a `body.tee()`.
+ *
+ * The inspector reads the stream to completion (or errors out), decoding
+ * UTF-8 across chunk boundaries, splitting on SSE event terminators
+ * (`\r?\n\r?\n`), parsing each `data:` payload as JSON, and invoking the
+ * provided callbacks when usage / response id become known.
+ *
+ * The returned Promise resolves with the final captured values once the
+ * stream ends (or is cancelled / errors out).
+ */
+declare function inspectSSEWebStream(stream: ReadableStream<Uint8Array>, onUsage: (usage: UsageTrackingData) => void, onResponseId?: (responseId: string) => void): Promise<{
+    capturedUsage?: UsageTrackingData;
+    capturedResponseId?: string;
+}>;
+/**
+ * SSE parser transform that preserves the original byte stream.
+ *
+ * Incoming chunks are forwarded downstream unchanged so chunk boundaries and
+ * timing remain identical to the upstream source. In parallel, a streaming text
+ * decoder buffers just enough data to detect complete SSE event blocks for
+ * usage/responseId inspection.
+ *
+ * This means:
+ *   - The client sees the original stream bytes without parser-induced
+ *     re-chunking.
+ *   - Multi-line events (multiple `data:` lines, plus `event:`/`id:`/`retry:`
+ *     fields) are still parsed correctly for inspection.
+ *   - Chunks that contain multiple events, or events split across chunks, are
+ *     handled correctly without merging or losing packets.
+ *   - UTF-8 split across chunk boundaries is decoded safely.
+ */
+declare function createSSEParserTransform(onUsage: (usage: UsageTrackingData) => void, onResponseId?: (responseId: string) => void): Transform;
+
+export { type AlertLevel, type DebugLevel, type FetchOptions, type ModelProviderPrice, ProviderManager, type RouteRequestParams, RoutstrClient, type RoutstrClientConfig, type RoutstrClientMode, type StreamCallbacks, StreamProcessor, createSSEParserTransform, inspectSSEWebStream };