@providerprotocol/ai 0.0.39 → 0.0.40

package/dist/retry-C1eJbEMV.d.ts

@@ -1,531 +0,0 @@
-import { K as KeyStrategy, c as ProviderConfig, f as Modality, R as RetryStrategy, U as UPPError } from './llm-CZqlijjK.js';
-
-/**
- * API key management strategies for load balancing and dynamic key selection.
- * @module http/keys
- */
-
-/**
- * Distributes API requests across multiple keys using round-robin selection.
- *
- * Each call to {@link getKey} returns the next key in sequence, cycling back to
- * the first key after reaching the end. This provides even distribution of requests
- * across all available keys, which is useful for:
- * - Spreading rate limits across multiple API keys
- * - Load balancing between different accounts
- * - Maximizing throughput when multiple keys are available
- *
- * @implements {KeyStrategy}
- *
- * @example
- * ```typescript
- * const keys = new RoundRobinKeys([
- *   'sk-key-1',
- *   'sk-key-2',
- *   'sk-key-3'
- * ]);
- *
- * keys.getKey(); // Returns 'sk-key-1'
- * keys.getKey(); // Returns 'sk-key-2'
- * keys.getKey(); // Returns 'sk-key-3'
- * keys.getKey(); // Returns 'sk-key-1' (cycles back)
- * ```
- */
-declare class RoundRobinKeys implements KeyStrategy {
-    private keys;
-    private index;
-    /**
-     * Creates a new RoundRobinKeys instance.
-     *
-     * @param keys - Array of API keys to rotate through
-     * @throws {Error} When the keys array is empty
-     */
-    constructor(keys: string[]);
-    /**
-     * Returns the next key in the rotation sequence.
-     *
-     * @returns The next API key in round-robin order
-     */
-    getKey(): string;
-}
-/**
- * Selects API keys using weighted random probability.
- *
- * Each key is assigned a weight that determines its probability of being selected.
- * Higher weights mean higher selection probability. This is useful for:
- * - Preferring higher-tier API keys with better rate limits
- * - Gradually migrating traffic between old and new keys
- * - A/B testing different API accounts
- * - Directing more traffic to keys with higher quotas
- *
- * The selection probability for each key is: weight / totalWeight
- *
- * @implements {KeyStrategy}
- *
- * @example
- * ```typescript
- * const keys = new WeightedKeys([
- *   { key: 'sk-premium', weight: 70 },   // 70% of requests
- *   { key: 'sk-standard', weight: 20 },  // 20% of requests
- *   { key: 'sk-backup', weight: 10 }     // 10% of requests
- * ]);
- *
- * // Configure provider with weighted key selection
- * const provider = createOpenAI({
- *   apiKey: keys
- * });
- * ```
- */
-declare class WeightedKeys implements KeyStrategy {
-    private entries;
-    private totalWeight;
-    /**
-     * Creates a new WeightedKeys instance.
-     *
-     * @param keys - Array of key-weight pairs defining selection probabilities
-     * @throws {Error} When the keys array is empty
-     */
-    constructor(keys: Array<{
-        key: string;
-        weight: number;
-    }>);
-    /**
-     * Returns a randomly selected key based on configured weights.
-     *
-     * @returns An API key selected with probability proportional to its weight
-     */
-    getKey(): string;
-}
-/**
- * Provides dynamic key selection using custom logic.
- *
- * This strategy delegates key selection to a user-provided function, enabling
- * advanced scenarios such as:
- * - Fetching keys from a secrets manager (AWS Secrets Manager, HashiCorp Vault)
- * - Rotating keys based on external state or configuration
- * - Selecting keys based on request context or time of day
- * - Implementing custom load balancing algorithms
- *
- * The selector function can be synchronous or asynchronous.
- *
- * @implements {KeyStrategy}
- *
- * @example
- * ```typescript
- * // Fetch key from environment based on current mode
- * const dynamicKey = new DynamicKey(() => {
- *   return process.env.NODE_ENV === 'production'
- *     ? process.env.PROD_API_KEY!
- *     : process.env.DEV_API_KEY!;
- * });
- *
- * // Async key fetching from a secrets manager
- * const vaultKey = new DynamicKey(async () => {
- *   const secret = await vault.read('secret/openai');
- *   return secret.data.apiKey;
- * });
- *
- * // Time-based key rotation
- * const timedKey = new DynamicKey(() => {
- *   const hour = new Date().getHours();
- *   return hour < 12 ? morningKey : afternoonKey;
- * });
- * ```
- */
-declare class DynamicKey implements KeyStrategy {
-    private selector;
-    /**
-     * Creates a new DynamicKey instance.
-     *
-     * @param selector - Function that returns an API key (sync or async)
-     */
-    constructor(selector: () => string | Promise<string>);
-    /**
-     * Invokes the selector function to retrieve the current key.
-     *
-     * @returns Promise resolving to the selected API key
-     */
-    getKey(): Promise<string>;
-}
-/**
- * Masks an API key for safe logging.
- * Shows first 4 and last 4 characters with ellipsis, or '***' for short keys.
- *
- * @param key - The API key to mask
- * @returns Masked key like "sk-ab...yz12" or "***" for short keys
- *
- * @example
- * ```typescript
- * maskApiKey('sk-abc123def456xyz789'); // 'sk-a...z789'
- * maskApiKey('short'); // '***'
- * ```
- */
-declare function maskApiKey(key: string): string;
-/**
- * Resolves an API key from provider configuration with multiple fallback options.
- *
- * This function handles various key specification methods in priority order:
- * 1. Direct string key in config.apiKey
- * 2. Function returning a key (sync or async) in config.apiKey
- * 3. KeyStrategy instance in config.apiKey (RoundRobinKeys, WeightedKeys, DynamicKey)
- * 4. Environment variable fallback (if envVar parameter is provided)
- *
- * @param config - Provider configuration containing the apiKey option
- * @param envVar - Optional environment variable name to check as fallback
- * @param provider - Provider identifier for error context (default: 'unknown')
- * @param modality - Request modality for error context (default: 'llm')
- * @returns The resolved API key string
- *
- * @throws {UPPError} AUTHENTICATION_FAILED - When no valid key is found
- *
- * @example
- * ```typescript
- * // Direct key in config
- * const key1 = await resolveApiKey({ apiKey: 'sk-...' }, 'OPENAI_API_KEY', 'openai');
- *
- * // Function-based key
- * const key2 = await resolveApiKey({ apiKey: () => getKeyFromVault() }, undefined, 'anthropic');
- *
- * // KeyStrategy instance
- * const key3 = await resolveApiKey({
- *   apiKey: new RoundRobinKeys(['sk-1', 'sk-2', 'sk-3'])
- * }, 'OPENAI_API_KEY', 'openai');
- *
- * // Environment variable fallback
- * const key4 = await resolveApiKey({}, 'ANTHROPIC_API_KEY', 'anthropic');
- * ```
- */
-declare function resolveApiKey(config: ProviderConfig, envVar?: string, provider?: string, modality?: Modality): Promise<string>;
-
-/**
- * Retry strategies for handling transient failures in HTTP requests.
- * @module http/retry
- */
-
-/**
- * Implements exponential backoff with optional jitter for retry delays.
- *
- * The delay between retries doubles with each attempt, helping to:
- * - Avoid overwhelming servers during outages
- * - Reduce thundering herd effects when many clients retry simultaneously
- * - Give transient issues time to resolve
- *
- * Delay formula: min(baseDelay * 2^(attempt-1), maxDelay)
- * With jitter: delay * random(0.5, 1.0)
- *
- * Only retries on transient errors: RATE_LIMITED, NETWORK_ERROR, TIMEOUT, PROVIDER_ERROR
- *
- * @implements {RetryStrategy}
- *
- * @example
- * ```typescript
- * // Default configuration (3 retries, 1s base, 30s max, jitter enabled)
- * const retry = new ExponentialBackoff();
- *
- * // Custom configuration
- * const customRetry = new ExponentialBackoff({
- *   maxAttempts: 5,     // Up to 5 retry attempts
- *   baseDelay: 500,     // Start with 500ms delay
- *   maxDelay: 60000,    // Cap at 60 seconds
- *   jitter: false       // Disable random jitter
- * });
- *
- * // Use with provider
- * const provider = createOpenAI({
- *   retryStrategy: customRetry
- * });
- * ```
- */
-declare class ExponentialBackoff implements RetryStrategy {
-    private maxAttempts;
-    private baseDelay;
-    private maxDelay;
-    private jitter;
-    /**
-     * Creates a new ExponentialBackoff instance.
-     *
-     * @param options - Configuration options
-     * @param options.maxAttempts - Maximum number of retry attempts (default: 3)
-     * @param options.baseDelay - Initial delay in milliseconds (default: 1000)
-     * @param options.maxDelay - Maximum delay cap in milliseconds (default: 30000)
-     * @param options.jitter - Whether to add random jitter to delays (default: true)
-     */
-    constructor(options?: {
-        maxAttempts?: number;
-        baseDelay?: number;
-        maxDelay?: number;
-        jitter?: boolean;
-    });
-    /**
-     * Determines whether to retry and calculates the delay.
-     *
-     * @param error - The error that triggered the retry
-     * @param attempt - Current attempt number (1-indexed)
-     * @returns Delay in milliseconds before next retry, or null to stop retrying
-     */
-    onRetry(error: UPPError, attempt: number): number | null;
-    /**
-     * Checks if an error is eligible for retry.
-     *
-     * @param error - The error to evaluate
-     * @returns True if the error is transient and retryable
-     */
-    private isRetryable;
-}
-/**
- * Implements linear backoff where delays increase proportionally with each attempt.
- *
- * Unlike exponential backoff, linear backoff increases delays at a constant rate:
- * - Attempt 1: delay * 1 (e.g., 1000ms)
- * - Attempt 2: delay * 2 (e.g., 2000ms)
- * - Attempt 3: delay * 3 (e.g., 3000ms)
- *
- * This strategy is simpler and more predictable than exponential backoff,
- * suitable for scenarios where gradual delay increase is preferred over
- * aggressive backoff.
- *
- * Only retries on transient errors: RATE_LIMITED, NETWORK_ERROR, TIMEOUT, PROVIDER_ERROR
- *
- * @implements {RetryStrategy}
- *
- * @example
- * ```typescript
- * // Default configuration (3 retries, 1s delay increment)
- * const retry = new LinearBackoff();
- *
- * // Custom configuration
- * const customRetry = new LinearBackoff({
- *   maxAttempts: 4,  // Up to 4 retry attempts
- *   delay: 2000      // 2s, 4s, 6s, 8s delays
- * });
- *
- * // Use with provider
- * const provider = createAnthropic({
- *   retryStrategy: customRetry
- * });
- * ```
- */
-declare class LinearBackoff implements RetryStrategy {
-    private maxAttempts;
-    private delay;
-    /**
-     * Creates a new LinearBackoff instance.
-     *
-     * @param options - Configuration options
-     * @param options.maxAttempts - Maximum number of retry attempts (default: 3)
-     * @param options.delay - Base delay multiplier in milliseconds (default: 1000)
-     */
-    constructor(options?: {
-        maxAttempts?: number;
-        delay?: number;
-    });
-    /**
-     * Determines whether to retry and calculates the linear delay.
-     *
-     * @param error - The error that triggered the retry
-     * @param attempt - Current attempt number (1-indexed)
-     * @returns Delay in milliseconds (delay * attempt), or null to stop retrying
-     */
-    onRetry(error: UPPError, attempt: number): number | null;
-    /**
-     * Checks if an error is eligible for retry.
-     *
-     * @param error - The error to evaluate
-     * @returns True if the error is transient and retryable
-     */
-    private isRetryable;
-}
-/**
- * Disables all retry behavior, failing immediately on any error.
- *
- * Use this strategy when:
- * - Retries are handled at a higher level in your application
- * - You want immediate failure feedback
- * - The operation is not idempotent
- * - Time sensitivity requires fast failure
- *
- * @implements {RetryStrategy}
- *
- * @example
- * ```typescript
- * // Disable retries for time-sensitive operations
- * const provider = createOpenAI({
- *   retryStrategy: new NoRetry()
- * });
- * ```
- */
-declare class NoRetry implements RetryStrategy {
-    /**
-     * Always returns null to indicate no retry should be attempted.
-     *
-     * @returns Always returns null
-     */
-    onRetry(_error: UPPError, _attempt: number): null;
-}
-/**
- * Implements token bucket rate limiting with automatic refill.
- *
- * The token bucket algorithm provides smooth rate limiting by:
- * - Maintaining a bucket of tokens that replenish over time
- * - Consuming one token per request
- * - Delaying requests when the bucket is empty
- * - Allowing burst traffic up to the bucket capacity
- *
- * This is particularly useful for:
- * - Client-side rate limiting to avoid hitting API rate limits
- * - Smoothing request patterns to maintain consistent throughput
- * - Preventing accidental API abuse
- *
- * Unlike other retry strategies, TokenBucket implements {@link beforeRequest}
- * to proactively delay requests before they are made.
- *
- * @implements {RetryStrategy}
- *
- * @example
- * ```typescript
- * // Allow 10 requests burst, refill 1 token per second
- * const bucket = new TokenBucket({
- *   maxTokens: 10,    // Burst capacity
- *   refillRate: 1,    // Tokens per second
- *   maxAttempts: 3    // Retry attempts on rate limit
- * });
- *
- * // Aggressive rate limiting: 5 req/s sustained
- * const strictBucket = new TokenBucket({
- *   maxTokens: 5,
- *   refillRate: 5
- * });
- *
- * // Use with provider
- * const provider = createOpenAI({
- *   retryStrategy: bucket
- * });
- * ```
- */
-declare class TokenBucket implements RetryStrategy {
-    private tokens;
-    private maxTokens;
-    private refillRate;
-    private lastRefill;
-    private maxAttempts;
-    private lock;
-    /**
-     * Creates a new TokenBucket instance.
-     *
-     * @param options - Configuration options
-     * @param options.maxTokens - Maximum bucket capacity (default: 10)
-     * @param options.refillRate - Tokens added per second (default: 1)
-     * @param options.maxAttempts - Maximum retry attempts on rate limit (default: 3)
-     */
-    constructor(options?: {
-        maxTokens?: number;
-        refillRate?: number;
-        maxAttempts?: number;
-    });
-    /**
-     * Called before each request to consume a token or calculate wait time.
-     *
-     * Refills the bucket based on elapsed time, then either:
-     * - Returns 0 if a token is available (consumed immediately)
-     * - Returns the wait time in milliseconds until the next token
-     *
-     * This method may allow tokens to go negative to reserve future capacity
-     * and avoid concurrent callers oversubscribing the same refill.
-     *
-     * @returns Delay in milliseconds before the request can proceed
-     */
-    beforeRequest(): Promise<number>;
-    /**
-     * Handles retry logic for rate-limited requests.
-     *
-     * Only retries on RATE_LIMITED errors, waiting for bucket refill.
-     *
-     * @param error - The error that triggered the retry
-     * @param attempt - Current attempt number (1-indexed)
-     * @returns Delay in milliseconds (time for 2 tokens), or null to stop
-     */
-    onRetry(error: UPPError, attempt: number): number | null;
-    /**
-     * Resets the bucket to full capacity.
-     *
-     * Called automatically on successful requests to restore available tokens.
-     */
-    reset(): void;
-    /**
-     * Refills the bucket based on elapsed time since last refill.
-     */
-    private refill;
-    private withLock;
-}
-/**
- * Respects server-provided Retry-After headers for optimal retry timing.
- *
- * When servers return a 429 (Too Many Requests) response, they often include
- * a Retry-After header indicating when the client should retry. This strategy
- * uses that information for precise retry timing.
- *
- * Benefits over fixed backoff strategies:
- * - Follows server recommendations for optimal retry timing
- * - Avoids retrying too early and wasting requests
- * - Adapts to dynamic rate limit windows
- *
- * If no Retry-After header is provided, falls back to a configurable delay.
- * Only retries on RATE_LIMITED errors.
- *
- * @implements {RetryStrategy}
- *
- * @example
- * ```typescript
- * // Use server-recommended retry timing
- * const retryAfter = new RetryAfterStrategy({
- *   maxAttempts: 5,       // Retry up to 5 times
- *   fallbackDelay: 10000  // 10s fallback if no header
- * });
- *
- * // The doFetch function automatically calls setRetryAfter
- * // when a Retry-After header is present in the response
- *
- * const provider = createOpenAI({
- *   retryStrategy: retryAfter
- * });
- * ```
- */
-declare class RetryAfterStrategy implements RetryStrategy {
-    private maxAttempts;
-    private fallbackDelay;
-    private lastRetryAfter?;
-    /**
-     * Creates a new RetryAfterStrategy instance.
-     *
-     * @param options - Configuration options
-     * @param options.maxAttempts - Maximum number of retry attempts (default: 3)
-     * @param options.fallbackDelay - Delay in ms when no Retry-After header (default: 5000)
-     */
-    constructor(options?: {
-        maxAttempts?: number;
-        fallbackDelay?: number;
-    });
-    /**
-     * Creates a request-scoped copy of this strategy.
-     */
-    fork(): RetryAfterStrategy;
-    /**
-     * Sets the retry delay from a Retry-After header value.
-     *
-     * Called by doFetch when a Retry-After header is present in the response.
-     * The value is used for the next onRetry call and then cleared.
-     *
-     * @param seconds - The Retry-After value in seconds
-     */
-    setRetryAfter(seconds: number): void;
-    /**
-     * Determines retry delay using Retry-After header or fallback.
-     *
-     * @param error - The error that triggered the retry
-     * @param attempt - Current attempt number (1-indexed)
-     * @returns Delay from Retry-After header or fallback, null to stop
-     */
-    onRetry(error: UPPError, attempt: number): number | null;
-}
-
-export { DynamicKey as D, ExponentialBackoff as E, LinearBackoff as L, NoRetry as N, RoundRobinKeys as R, TokenBucket as T, WeightedKeys as W, RetryAfterStrategy as a, maskApiKey as m, resolveApiKey as r };