@mayank3238/keymux 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,859 @@
+export { NvidiaStreamTranslator, OpenRouterStreamTranslator, startProxyServer, stopProxyServer, translateAnthropicToOpenAI, translateOpenAIToAnthropic } from './proxy/index.js';
+import 'http';
+
+/**
+ * Core type definitions for keymux
+ * Public API types exported for consumers
+ */
+/**
+ * Configuration for a single API key in the pool
+ */
+interface KeyConfig {
+    /** Unique identifier - each key has its own ID */
+    id: string;
+    /** Actual API key string */
+    key: string;
+    /** RPM limit - how many requests can run in one minute (default: 40) */
+    rpmLimit?: number;
+    /** Weight - increase weight for more important keys (default: 1) */
+    weight?: number;
+    /** Base URL - custom URL if you don't want to use the provider's default URL */
+    baseURL?: string;
+    /** Custom metadata - for storing extra info */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Internal state tracking for a key
+ */
+interface KeyState {
+    config: KeyConfig;
+    /** Current RPM - how many requests have been made in the current minute */
+    rpm: number;
+    /** Last request timestamp */
+    lastUsed: number;
+    /** Circuit breaker state - HEALTHY, DEGRADED or OPEN */
+    circuitState: CircuitState;
+    /** Continuous failures - circuit opens if this gets too high */
+    failures: number;
+    /** Cooldown until - how long to wait before retrying */
+    cooldownUntil: number;
+    /** Average latency - calculated from last 25 requests */
+    avgLatencyMs: number;
+    /** Raw TTFT history - sliding window of last 25 readings for true average calculation */
+    latencyHistory: number[];
+    /** Total requests - how many requests processed so far */
+    totalRequests: number;
+    /** Total errors - how many errors encountered so far */
+    totalErrors: number;
+    /** Timestamps of requests in the current window */
+    requestTimestamps: number[];
+}
+/**
+ * Circuit breaker states
+ * HEALTHY -> DEGRADED -> OPEN (recovers after cooldown)
+ */
+declare enum CircuitState {
+    HEALTHY = "healthy",// Everything is fine, can be used
+    DEGRADED = "degraded",// Some issues, use carefully
+    OPEN = "open"
+}
+/**
+ * Configuration for the key router
+ */
+interface KeyRouterConfig {
+    /** All API keys to manage */
+    keys: KeyConfig[];
+    /** Default RPM limit - used if key-specific limit is not provided (default: 40) */
+    defaultRpmLimit?: number;
+    /** Default weight - equal importance for all keys? Or some more important? (default: 1) */
+    defaultWeight?: number;
+    /** Circuit breaker - block key after this many failures (default: 3) */
+    failureThreshold?: number;
+    /** Circuit breaker - recovery time in milliseconds after being blocked (default: 30000 = 30sec) */
+    cooldownMs?: number;
+    /** Sliding window - RPM is counted within a 1 minute (60000ms) window */
+    windowMs?: number;
+    /** Latency tracking - track how fast requests complete? (default: true) */
+    trackLatency?: boolean;
+    /** Callback - called when a key's state changes (e.g. healthy to degraded) */
+    onStateChange?: (keyId: string, state: CircuitState) => void;
+    /** Debug callback - for understanding what is happening in development */
+    onDebug?: (event: DebugEvent) => void;
+}
+/**
+ * Debug events - for logging and monitoring
+ * What event occurred (selected, failed, recovered), which key, when, and extra details
+ */
+interface DebugEvent {
+    type: 'key_selected' | 'key_failed' | 'key_recovered' | 'circuit_opened' | 'all_exhausted';
+    keyId?: string;
+    keyIndex?: number;
+    timestamp: number;
+    details?: Record<string, unknown>;
+}
+/**
+ * Result of key selection
+ */
+interface KeySelectionResult {
+    /** The selected API key */
+    key: string;
+    /** Key configuration */
+    config: KeyConfig;
+    /** Internal key ID */
+    keyId: string;
+    /** Current utilization (0-1) */
+    utilization: number;
+}
+/**
+ * Statistics for a single key
+ */
+interface KeyStats {
+    id: string;
+    key: string;
+    rpm: number;
+    rpmLimit: number;
+    utilization: number;
+    circuitState: CircuitState;
+    failures: number;
+    avgLatencyMs: number;
+    totalRequests: number;
+    totalErrors: number;
+    isHealthy: boolean;
+    cooldownRemainingMs?: number;
+}
+/**
+ * Overall router statistics
+ */
+interface RouterStats {
+    totalKeys: number;
+    healthyKeys: number;
+    totalRpm: number;
+    totalRpmLimit: number;
+    overallUtilization: number;
+    keys: KeyStats[];
+}
+/**
+ * Options for key selection
+ */
+interface SelectionOptions {
+    /** Preferred key IDs (will try these first if healthy) */
+    preferredKeys?: string[];
+    /** Minimum utilization threshold (0-1) - skip keys above this */
+    maxUtilization?: number;
+    /** Custom selection strategy name */
+    strategy?: string;
+}
+/**
+ * Error types for better error handling
+ */
+declare class KeyRouterError extends Error {
+    readonly code: 'ALL_KEYS_EXHAUSTED' | 'NO_KEYS_CONFIGURED' | 'KEY_NOT_FOUND' | 'CIRCUIT_OPEN' | 'INVALID_CONFIG';
+    readonly keyId?: string | undefined;
+    constructor(message: string, code: 'ALL_KEYS_EXHAUSTED' | 'NO_KEYS_CONFIGURED' | 'KEY_NOT_FOUND' | 'CIRCUIT_OPEN' | 'INVALID_CONFIG', keyId?: string | undefined);
+}
+declare class RateLimitError extends KeyRouterError {
+    constructor(keyId: string);
+}
+/**
+ * Provider preset configurations
+ */
+interface ProviderPreset {
+    name: string;
+    baseURL: string;
+    defaultRpmLimit: number;
+    models: string[];
+}
+declare const PROVIDER_PRESETS: Record<string, ProviderPreset>;
+/**
+ * Configuration for one provider in a multi-provider pool
+ * Each provider can have multiple API keys
+ */
+interface ProviderPoolEntry {
+    /** Provider name - use preset name ('nvidia', 'gemini', etc.) or any custom string */
+    provider: string;
+    /** API keys for this provider (multiple keys = more RPM capacity) */
+    keys: string[];
+    /** Base URL - auto-filled from PROVIDER_PRESETS for known providers */
+    baseURL?: string;
+    /** Models this provider serves - first model is the default */
+    models?: string[];
+    /** Per-key RPM limit - auto-filled from PROVIDER_PRESETS for known providers */
+    rpmLimit?: number;
+    /** Provider priority weight - higher weight = more requests routed here (default: 1) */
+    weight?: number;
+    /** Custom metadata - for storing extra info per provider */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of getEndpoint() — everything needed to make an API call
+ * Unlike getKey() which returns just a string, this returns the full endpoint info
+ */
+interface EndpointResult {
+    /** The API key to use */
+    key: string;
+    /** Provider's base URL for API calls */
+    baseURL: string;
+    /** Model to use for this request */
+    model: string;
+    /** Provider name (e.g. 'nvidia', 'gemini', 'openrouter') */
+    provider: string;
+    /** Unique endpoint ID for reporting success/failure */
+    endpointId: string;
+    /** Current utilization of this endpoint (0-1) */
+    utilization: number;
+}
+/**
+ * Options for getEndpoint() - filter and control which endpoint is selected
+ */
+interface EndpointOptions {
+    /** Try these providers first if healthy (e.g. ['gemini', 'nvidia']) */
+    preferProviders?: string[];
+    /** Never use these providers for this request */
+    excludeProviders?: string[];
+    /** Request a specific model - router picks the provider that has it */
+    model?: string;
+    /** Skip endpoints above this utilization (0-1) */
+    maxUtilization?: number;
+    /** Override selection strategy for this request */
+    strategy?: string;
+}
+/**
+ * Configuration options for MultiProviderRouter
+ */
+interface MultiProviderConfig {
+    /** Circuit breaker - block key after this many failures (default: 3) */
+    failureThreshold?: number;
+    /** Circuit breaker - recovery time in ms after being blocked (default: 30000) */
+    cooldownMs?: number;
+    /** Sliding window for RPM counting in ms (default: 60000) */
+    windowMs?: number;
+    /** Track latency per endpoint? (default: true) */
+    trackLatency?: boolean;
+    /** Default selection strategy (default: 'weighted-least-utilization') */
+    strategy?: string;
+    /** Callback when an endpoint's state changes */
+    onStateChange?: (endpointId: string, state: CircuitState) => void;
+    /** Debug callback for monitoring */
+    onDebug?: (event: DebugEvent) => void;
+}
+
+/**
+ * Key Selection Strategies
+ * Pure functions that select the best key from the available keys
+ */
+
+/**
+ * Strategy interface
+ */
+interface SelectionStrategy {
+    name: string;
+    select(keys: KeyState[], options?: SelectionOptions): KeyState | null;
+}
+/**
+ * Weighted Least Utilization Strategy (RECOMMENDED)
+ * Picks key with lowest (rpm / rpmLimit) ratio, weighted by key weight
+ * Handles different RPM limits per key fairly
+ */
+declare class WeightedLeastUtilizationStrategy implements SelectionStrategy {
+    name: string;
+    select(keys: KeyState[], options?: SelectionOptions): KeyState | null;
+}
+/**
+ * Least Requests Strategy
+ * Picks key with absolute lowest RPM count
+ * Good when all keys have same limits
+ */
+declare class LeastRequestsStrategy implements SelectionStrategy {
+    name: string;
+    select(keys: KeyState[], options?: SelectionOptions): KeyState | null;
+}
+/**
+ * Smart Routing Strategy
+ * 1. Filters out keys exceeding max utilization.
+ * 2. Forms a "fast pool" of keys within 100ms of the fastest key. Always includes keys with no latency data (e.g., avgLatencyMs === 0) so they don't get starved.
+ * 3. Sorts the pool by RPM (ascending) and then totalRequests (ascending) to balance load (Least Used).
+ */
+declare class SmartRoutingStrategy implements SelectionStrategy {
+    name: string;
+    select(keys: KeyState[], options?: SelectionOptions): KeyState | null;
+}
+/**
+ * Least Latency Strategy
+ * Picks key with lowest average latency
+ * Requires latency tracking to be enabled
+ * Falls back to LeastRequestsStrategy if no latency data is available
+ */
+declare class LeastLatencyStrategy implements SelectionStrategy {
+    name: string;
+    select(keys: KeyState[], options?: SelectionOptions): KeyState | null;
+}
+/**
+ * Preferred Keys Strategy
+ * Tries preferred keys first, falls back to another strategy
+ */
+declare class PreferredKeysStrategy implements SelectionStrategy {
+    private fallbackStrategy;
+    name: string;
+    constructor(fallbackStrategy: SelectionStrategy);
+    select(keys: KeyState[], options?: SelectionOptions): KeyState | null;
+}
+/**
+ * Random Strategy
+ * Selects a key randomly - good for distributing load evenly over time
+ * Applies utilization filter so overloaded keys are not selected
+ */
+declare class RandomStrategy implements SelectionStrategy {
+    name: string;
+    select(keys: KeyState[], options?: SelectionOptions): KeyState | null;
+}
+/**
+ * Strategy Factory - creates strategy by name
+ */
+declare function createStrategy(name: string, fallback?: SelectionStrategy): SelectionStrategy;
+/**
+ * Default strategy instance (singleton)
+ */
+declare const defaultStrategy: WeightedLeastUtilizationStrategy;
+
+/**
+ * KeyRouter - Main entry point of the keymux library
+ * Manages keys, tracks state, and distributes requests
+ * Uses a selection strategy to pick the best key
+ */
+
+declare class KeyRouter {
+    private tracker;
+    private strategy;
+    private config;
+    private initialized;
+    constructor(config: KeyRouterConfig);
+    /**
+     * Initialize the router with keys
+     * Must be called before using getKey()
+     */
+    initialize(): void;
+    /**
+     * Get the next available API key
+     * Returns key string ready to use with OpenAI/LangChain SDKs
+     */
+    getKey(options?: SelectionOptions): Promise<string>;
+    /**
+     * Get key with full metadata (for debugging/logging)
+     */
+    getKeyWithMeta(options?: SelectionOptions): Promise<KeySelectionResult>;
+    /**
+     * Report a failed request for a specific key or key ID
+     * Call this when you catch a 429/5xx error from the API
+     */
+    reportFailure(keyOrId: string, isRateLimit?: boolean): void;
+    /**
+     * Report a successful request for a specific key or key ID
+     * Optional: call this if you want to track latency manually
+     */
+    reportSuccess(keyOrId: string, latencyMs?: number): void;
+    /**
+     * Manually mark a key as recovered
+     */
+    reportRecovery(keyOrId: string): void;
+    /**
+     * Get statistics for all keys
+     */
+    getStats(): KeyStats[];
+    /**
+     * Get overall router statistics
+     */
+    getOverallStats(): {
+        totalKeys: number;
+        healthyKeys: number;
+        totalRpm: number;
+        totalRpmLimit: number;
+        overallUtilization: number;
+        keys: KeyStats[];
+    };
+    /**
+     * Get a specific key's stats by ID
+     */
+    getKeyStats(keyId: string): KeyStats | undefined;
+    /**
+     * Check if a specific key is healthy
+     */
+    isKeyHealthy(keyId: string): boolean;
+    /**
+     * Get all available (healthy + under limit) key IDs
+     */
+    getAvailableKeyIds(): string[];
+    /**
+     * Set custom selection strategy
+     */
+    setStrategy(strategy: SelectionStrategy | string): void;
+    /**
+     * Add a new key at runtime
+     */
+    addKey(keyConfig: KeyConfig): void;
+    /**
+     * Remove a key at runtime
+     */
+    removeKey(keyId: string): boolean;
+    /**
+     * Update key configuration at runtime
+     */
+    updateKey(keyId: string, updates: Partial<KeyConfig>): boolean;
+    /**
+     * Reset all tracking (useful for testing)
+     */
+    reset(): void;
+    /**
+     * Shutdown and cleanup
+     */
+    destroy(): void;
+    /**
+     * Create a router from a provider preset
+     */
+    static fromProvider(provider: keyof typeof PROVIDER_PRESETS, keys: string[], options?: Partial<KeyRouterConfig>): KeyRouter;
+    /**
+     * Create a router for NVIDIA specifically (most common use case)
+     */
+    static forNvidia(keys: string[], options?: Partial<KeyRouterConfig>): KeyRouter;
+    /**
+     * Create router from environment variable (comma-separated keys)
+     */
+    static fromEnv(envVar: string, options?: Partial<KeyRouterConfig>): KeyRouter;
+    private ensureInitialized;
+    private findKeyOrId;
+}
+
+/**
+ * KeyTracker - Tracks per-key state: RPM, circuit breaker, latency
+ * Single responsibility: tracks and updates key metrics
+ */
+
+interface KeyTrackerOptions {
+    defaultRpmLimit: number;
+    defaultWeight: number;
+    failureThreshold: number;
+    cooldownMs: number;
+    windowMs: number;
+    trackLatency: boolean;
+    onStateChange?: (keyId: string, state: CircuitState) => void;
+    onDebug?: (event: DebugEvent) => void;
+}
+declare class KeyTracker {
+    private keys;
+    private options;
+    private cleanupInterval?;
+    constructor(options: KeyTrackerOptions);
+    initialize(keyConfigs: KeyConfig[]): void;
+    /**
+     * Get all key states - for debugging or stats
+     */
+    getAllStates(): KeyState[];
+    /**
+     * Get state of a specific key
+     */
+    getState(keyId: string): KeyState | undefined;
+    /**
+     * Get only healthy and available keys
+     * Checks circuit breaker state and RPM limits
+     */
+    getAvailableKeys(): KeyState[];
+    /**
+     * Record a request attempt (reservation)
+     * Increments RPM count without touching failures or circuit state.
+     */
+    recordAttempt(keyId: string): void;
+    /**
+     * Record a successful request completion
+     * Updates latency and resets failures (RPM already incremented by recordAttempt).
+     */
+    recordSuccess(keyId: string, latencyMs?: number): void;
+    /**
+     * Record a failed request (rate limit, server error, etc.)
+     * Triggers circuit breaker logic (RPM already incremented by recordAttempt).
+     */
+    recordFailure(keyId: string, isRateLimit?: boolean): void;
+    /**
+     * Manually report a key as recovered (for external health checks)
+     */
+    reportRecovery(keyId: string): void;
+    /**
+     * Get statistics for all keys
+     */
+    getStats(): KeyStats[];
+    /**
+     * Get overall router statistics
+     */
+    getOverallStats(): {
+        totalKeys: number;
+        healthyKeys: number;
+        totalRpm: number;
+        totalRpmLimit: number;
+        overallUtilization: number;
+        keys: KeyStats[];
+    };
+    /**
+     * Reset all tracking (useful for testing)
+     */
+    reset(): void;
+    /**
+     * Shutdown cleanup
+     */
+    destroy(): void;
+    private transitionToHealthy;
+    private openCircuit;
+    private toStats;
+    private maskKey;
+    private emitDebug;
+    private startCleanupLoop;
+    private cleanupExpiredWindows;
+    private checkCircuitRecovery;
+}
+
+/**
+ * Utility helpers for keymux
+ */
+/**
+ * Check if an error is a rate limit error (429)
+ */
+declare function isRateLimitError(error: unknown, seen?: WeakSet<object>): boolean;
+/**
+ * Check if an error is a server error (5xx)
+ */
+declare function isServerError(error: unknown, seen?: WeakSet<object>): boolean;
+/**
+ * Check if an error is retryable (rate limit or server error)
+ */
+declare function isRetryableError(error: unknown): boolean;
+/**
+ * Calculate exponential backoff delay with jitter
+ */
+declare function calculateBackoff(attempt: number, baseMs?: number, maxMs?: number): number;
+/**
+ * Mask API key for logging (show only first 4 and last 4 chars)
+ * Example: sk-abcdef1234567890 -> sk-ab****7890
+ */
+declare function maskKey(key: string): string;
+/**
+ * Parse comma-separated keys from string
+ * Reads keys from environment variables - splits by comma to create an array
+ * Filters out empty strings
+ */
+declare function parseKeys(keysString: string): string[];
+/**
+ * Create a simple async key getter for OpenAI SDK / LangChain
+ * Usage: new ChatOpenAI({ apiKey: createKeyGetter(router) })
+ * This function returns an async getter that calls router.getKey()
+ */
+declare function createKeyGetter(router: {
+    getKey(): Promise<string>;
+}): () => Promise<string>;
+/**
+ * Create a key getter with automatic failover
+ * Usage: new ChatOpenAI({ apiKey: createFailoverKeyGetter(router, 3) })
+ */
+declare function createFailoverKeyGetter(router: {
+    getKey(): Promise<string>;
+    reportFailure(key: string, isRateLimit?: boolean): void;
+    reportSuccess(key: string): void;
+}, maxRetries?: number): () => Promise<string>;
+/**
+ * Sleep utility
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Format router stats for pretty logging
+ */
+declare function formatStats(stats: ReturnType<KeyRouter['getOverallStats']>): string;
+/**
+ * Create a periodic stats logger
+ */
+declare function createStatsLogger(router: {
+    getOverallStats(): ReturnType<KeyRouter['getOverallStats']>;
+}, intervalMs?: number): NodeJS.Timeout;
+
+/**
+ * MultiProviderRouter - Routes requests across multiple AI providers
+ *
+ * Internally uses KeyTracker + SelectionStrategy directly (same engine as KeyRouter)
+ * but adds provider-awareness: baseURL, model, and provider-level filtering.
+ *
+ * Architecture:
+ *   - Flattens all providers' keys into a single pool of KeyConfig entries
+ *   - Each entry gets a unique ID: `${provider}-${keyIndex}` (e.g. 'nvidia-0', 'gemini-1')
+ *   - An endpointMap stores the metadata (baseURL, model, provider) for each key ID
+ *   - A providerGroups map tracks which key IDs belong to which provider
+ *   - Selection uses existing KeyTracker (circuit breakers, RPM) + SelectionStrategy
+ */
+
+/**
+ * Per-provider statistics
+ */
+interface ProviderStats {
+    provider: string;
+    totalKeys: number;
+    healthyKeys: number;
+    totalRpm: number;
+    totalRpmLimit: number;
+    utilization: number;
+    keys: KeyStats[];
+}
+declare class MultiProviderRouter {
+    private tracker;
+    private strategy;
+    private endpointMap;
+    private providerGroups;
+    lastRoute: {
+        provider: string;
+        model: string;
+        key: string;
+        time: number;
+    } | null;
+    private keyConfigs;
+    private providers;
+    private config;
+    constructor(providers: ProviderPoolEntry[], config?: MultiProviderConfig);
+    /**
+     * Get the next best endpoint for making an API call
+     * Returns key + baseURL + model + provider — everything needed for a request
+     *
+     * Supports filtering:
+     * - preferProviders: try these first
+     * - excludeProviders: skip these entirely
+     * - model: pick a provider that has this model
+     * - maxUtilization: skip overloaded endpoints
+     */
+    getEndpoint(options?: EndpointOptions): Promise<EndpointResult>;
+    /**
+     * Report a successful request for an endpoint
+     * Resets failure count, updates latency (EMA), recovers degraded state
+     */
+    reportSuccess(endpointId: string, latencyMs?: number): void;
+    /**
+     * Report a failed request for an endpoint
+     * Increments failure count, may open circuit breaker
+     * Next getEndpoint() call will automatically route to a different provider
+     */
+    reportFailure(endpointId: string, isRateLimit?: boolean): void;
+    /**
+     * Manually recover an endpoint (e.g. after external health check)
+     */
+    reportRecovery(endpointId: string): void;
+    /**
+     * Get overall stats across all providers (same familiar format as KeyRouter)
+     */
+    getOverallStats(): {
+        totalKeys: number;
+        healthyKeys: number;
+        totalRpm: number;
+        totalRpmLimit: number;
+        overallUtilization: number;
+        keys: KeyStats[];
+    };
+    /**
+     * Get stats for all endpoints
+     */
+    getStats(): KeyStats[];
+    /**
+     * Get stats for a specific provider
+     */
+    getProviderStats(provider: string): ProviderStats;
+    /**
+     * Get list of all configured provider names
+     */
+    getProviderNames(): string[];
+    /**
+     * Get all available (healthy + under limit) endpoint IDs
+     */
+    getLastRoute(): {
+        provider: string;
+        model: string;
+        key: string;
+        time: number;
+    } | null;
+    getAvailableEndpointIds(): string[];
+    /**
+     * Check if a specific endpoint is healthy
+     */
+    isEndpointHealthy(endpointId: string): boolean;
+    /**
+     * Check if a provider has any healthy endpoints
+     */
+    isProviderHealthy(provider: string): boolean;
+    /**
+     * Add a new provider at runtime
+     */
+    addProvider(entry: ProviderPoolEntry): void;
+    /**
+     * Add a key to an existing provider at runtime
+     */
+    addKeyToProvider(provider: string, key: string): void;
+    /**
+     * Remove a provider entirely at runtime
+     */
+    removeProvider(provider: string): boolean;
+    /**
+     * Remove a specific key from a provider at runtime
+     */
+    removeKey(provider: string, key: string): boolean;
+    /**
+     * Set the selection strategy
+     */
+    setStrategy(strategy: SelectionStrategy | string): void;
+    /**
+     * Reset all tracking data (useful for testing)
+     */
+    reset(): void;
+    /**
+     * Shutdown and cleanup (stops background cleanup timer)
+     */
+    destroy(): void;
+    /**
+     * Flatten all providers into a single key pool
+     * Each key gets a unique ID: `${provider}-${keyIndex}`
+     * Provider metadata (baseURL, model) is stored in endpointMap
+     */
+    private buildPool;
+    /**
+     * Rebuild the pool from current providers (used after dynamic changes)
+     */
+    private rebuildPool;
+}
+
+interface FetchConfig {
+    router: MultiProviderRouter;
+    maxRetries?: number;
+    preferProviders?: string[];
+    excludeProviders?: string[];
+    model?: string;
+}
+declare function fetchWithFailover(urlBuilder: (ep: EndpointResult) => string | URL, fetchOptionsBuilder: (ep: EndpointResult) => RequestInit, config: FetchConfig): Promise<Response>;
+
+interface DailyUsage {
+    date: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheTokens: number;
+    requests: number;
+    providerUsage?: Record<string, ProviderUsage>;
+}
+interface ProviderUsage {
+    requests: number;
+    tokens: number;
+}
+interface UsageData {
+    totalRequests: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheTokens: number;
+    providerUsage: Record<string, number | ProviderUsage>;
+    daily: Record<string, DailyUsage>;
+    sessions: number;
+    firstUsed: number;
+}
+declare class UsageTracker {
+    private data;
+    private filePath;
+    private saveTimeout;
+    private sessionProviderUsage;
+    private initialized;
+    constructor();
+    private ensureInitialized;
+    private loadData;
+    private saveData;
+    private scheduleSave;
+    recordRequest(provider: string, inputTokens: number, outputTokens: number, cacheTokens?: number): void;
+    getSessionUsage(): Record<string, ProviderUsage>;
+    getTodayUsage(): Record<string, ProviderUsage>;
+    getData(): UsageData;
+}
+declare const globalUsageTracker: UsageTracker;
+
+/**
+ * Create a KeyRouter for NVIDIA keys - the most common use case
+ * NVIDIA preset settings will be automatically applied
+ *
+ * @example
+ * ```typescript
+ * import { createNvidiaRouter } from 'keymux';
+ *
+ * const router = createNvidiaRouter([
+ *   'nvapi-key-1',
+ *   'nvapi-key-2',
+ *   'nvapi-key-3'
+ * ]);
+ *
+ * // Use with OpenAI SDK
+ * import OpenAI from 'openai';
+ * const client = new OpenAI({
+ *   apiKey: async () => await router.getKey(),
+ *   baseURL: 'https://integrate.api.nvidia.com/v1'
+ * });
+ * ```
+ */
+declare function createNvidiaRouter(keys: string[], options?: Partial<KeyRouterConfig>): KeyRouter;
+/**
+ * Create a KeyRouter from a provider preset
+ * Examples: mistral, openai, nvidia, etc.
+ *
+ * @example
+ * ```typescript
+ * import { createRouter } from 'keymux';
+ *
+ * const router = createRouter('mistral', [
+ *   'mistral-key-1',
+ *   'mistral-key-2'
+ * ]);
+ * ```
+ */
+declare function createRouter(provider: keyof typeof PROVIDER_PRESETS, keys: string[], options?: Partial<KeyRouterConfig>): KeyRouter;
+/**
+ * Create a KeyRouter from an environment variable
+ * Read keys from .env file or system env - comma separated
+ *
+ * @example
+ * ```typescript
+ * import { createRouterFromEnv } from 'keymux';
+ *
+ * // Set NVIDIA_KEYS="key1,key2,key3" in .env
+ * const router = createRouterFromEnv('NVIDIA_KEYS');
+ * ```
+ */
+declare function createRouterFromEnv(envVar: string, options?: Partial<KeyRouterConfig>): KeyRouter;
+
+/**
+ * Create a MultiProviderRouter from provider configs
+ * Routes requests across multiple AI providers with automatic failover
+ *
+ * @example
+ * ```typescript
+ * import { createMultiProviderRouter } from 'keymux';
+ *
+ * const router = createMultiProviderRouter([
+ *   { provider: 'gemini', keys: ['AIza-key1'] },
+ *   { provider: 'nvidia', keys: ['nvapi-key1', 'nvapi-key2'] },
+ *   { provider: 'openrouter', keys: ['sk-or-key1'] }
+ * ]);
+ *
+ * const ep = await router.getEndpoint();
+ * // ep = { key, baseURL, model, provider, endpointId, utilization }
+ * ```
+ */
+declare function createMultiProviderRouter(providers: ProviderPoolEntry[], config?: MultiProviderConfig): MultiProviderRouter;
+/**
+ * Create a MultiProviderRouter from environment variables
+ * Each provider's keys are read from a comma-separated env var
+ *
+ * @example
+ * ```typescript
+ * import { createMultiProviderRouterFromEnv } from 'keymux';
+ *
+ * // process.env.NVIDIA_KEYS = "nvapi-key1,nvapi-key2"
+ * // process.env.GEMINI_KEYS = "AIza-key1"
+ * const router = createMultiProviderRouterFromEnv({
+ *   nvidia: 'NVIDIA_KEYS',
+ *   gemini: 'GEMINI_KEYS',
+ * });
+ * ```
+ */
+declare function createMultiProviderRouterFromEnv(envMap: Record<string, string>, overrides?: Record<string, Partial<ProviderPoolEntry>>, config?: MultiProviderConfig): MultiProviderRouter;
+
+export { CircuitState, type DailyUsage, type DebugEvent, type EndpointOptions, type EndpointResult, type KeyConfig, KeyRouter, type KeyRouterConfig, KeyRouterError, type KeySelectionResult, type KeyState, type KeyStats, KeyTracker, LeastLatencyStrategy, LeastRequestsStrategy, type MultiProviderConfig, MultiProviderRouter, PROVIDER_PRESETS, PreferredKeysStrategy, type ProviderPoolEntry, type ProviderPreset, type ProviderStats, type ProviderUsage, RandomStrategy, RateLimitError, type RouterStats, type SelectionOptions, type SelectionStrategy, SmartRoutingStrategy, type UsageData, UsageTracker, WeightedLeastUtilizationStrategy, calculateBackoff, createFailoverKeyGetter, createKeyGetter, createMultiProviderRouter, createMultiProviderRouterFromEnv, createNvidiaRouter, createRouter, createRouterFromEnv, createStatsLogger, createStrategy, defaultStrategy, fetchWithFailover, formatStats, globalUsageTracker, isRateLimitError, isRetryableError, isServerError, maskKey, parseKeys, sleep };