@providerprotocol/ai 0.0.38 → 0.0.40

package/dist/retry-DVfdPLIB.d.ts

@@ -0,0 +1,322 @@
+import { K as KeyStrategy, c as ProviderConfig, f as Modality, R as RetryStrategyFactory } from './llm-BWLaTzzY.js';
+
+/**
+ * API key management strategies for load balancing and dynamic key selection.
+ * @module http/keys
+ */
+
+/**
+ * Creates a key strategy that distributes API requests across multiple keys
+ * using round-robin selection.
+ *
+ * Each call to `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
+ *
+ * @param keys - Array of API keys to rotate through
+ * @returns A {@link KeyStrategy} that cycles through the provided keys
+ * @throws {Error} When the keys array is empty
+ *
+ * @example
+ * ```typescript
+ * const keys = 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 function roundRobinKeys(keys: string[]): KeyStrategy;
+/**
+ * Creates a key strategy that 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
+ *
+ * @param keys - Array of key-weight pairs defining selection probabilities
+ * @returns A {@link KeyStrategy} that selects keys by weighted probability
+ * @throws {Error} When the keys array is empty
+ *
+ * @example
+ * ```typescript
+ * const keys = 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 function weightedKeys(keys: Array<{
+    key: string;
+    weight: number;
+}>): KeyStrategy;
+/**
+ * Creates a key strategy that 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.
+ *
+ * @param selector - Function that returns an API key (sync or async)
+ * @returns A {@link KeyStrategy} that delegates to the selector function
+ *
+ * @example
+ * ```typescript
+ * // Fetch key from environment based on current mode
+ * const envKey = 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 = dynamicKey(async () => {
+ *   const secret = await vault.read('secret/openai');
+ *   return secret.data.apiKey;
+ * });
+ *
+ * // Time-based key rotation
+ * const timedKey = dynamicKey(() => {
+ *   const hour = new Date().getHours();
+ *   return hour < 12 ? morningKey : afternoonKey;
+ * });
+ * ```
+ */
+declare function dynamicKey(selector: () => string | Promise<string>): KeyStrategy;
+/**
+ * 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: 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 strategy factories for handling transient failures in HTTP requests.
+ *
+ * All strategies use the factory pattern to ensure each request gets an
+ * isolated instance, preventing state sharing between concurrent requests.
+ *
+ * @module http/retry
+ */
+
+/**
+ * Options for exponential backoff retry strategy.
+ */
+interface ExponentialBackoffOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    baseDelay?: number;
+    /** Maximum delay cap in milliseconds (default: 30000) */
+    maxDelay?: number;
+    /** Whether to add random jitter to delays (default: true) */
+    jitter?: boolean;
+}
+/**
+ * Creates an exponential backoff retry strategy.
+ *
+ * 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
+ *
+ * @param options - Configuration options
+ * @returns A factory that creates fresh strategy instances per request
+ *
+ * @example
+ * ```typescript
+ * // Default configuration (3 retries, 1s base, 30s max, jitter enabled)
+ * const retry = exponentialBackoff();
+ *
+ * // Custom configuration
+ * const customRetry = 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 function exponentialBackoff(options?: ExponentialBackoffOptions): RetryStrategyFactory;
+/**
+ * Options for linear backoff retry strategy.
+ */
+interface LinearBackoffOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Base delay multiplier in milliseconds (default: 1000) */
+    delay?: number;
+}
+/**
+ * Creates a linear backoff retry strategy.
+ *
+ * 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
+ *
+ * @param options - Configuration options
+ * @returns A factory that creates fresh strategy instances per request
+ *
+ * @example
+ * ```typescript
+ * // Default configuration (3 retries, 1s delay increment)
+ * const retry = linearBackoff();
+ *
+ * // Custom configuration
+ * const customRetry = linearBackoff({
+ *   maxAttempts: 4,  // Up to 4 retry attempts
+ *   delay: 2000      // 2s, 4s, 6s, 8s delays
+ * });
+ *
+ * // Use with provider
+ * const provider = createAnthropic({
+ *   retryStrategy: customRetry
+ * });
+ * ```
+ */
+declare function linearBackoff(options?: LinearBackoffOptions): RetryStrategyFactory;
+/**
+ * Creates a no-retry strategy that fails 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
+ *
+ * @returns A factory that creates no-retry strategy instances
+ *
+ * @example
+ * ```typescript
+ * // Disable retries for time-sensitive operations
+ * const provider = createOpenAI({
+ *   retryStrategy: noRetry()
+ * });
+ * ```
+ */
+declare function noRetry(): RetryStrategyFactory;
+/**
+ * Options for retry-after strategy.
+ */
+interface RetryAfterStrategyOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Delay in ms when no Retry-After header is present (default: 5000) */
+    fallbackDelay?: number;
+}
+/**
+ * Creates a retry strategy that respects server-provided Retry-After headers.
+ *
+ * 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.
+ *
+ * @param options - Configuration options
+ * @returns A factory that creates fresh strategy instances per request
+ *
+ * @example
+ * ```typescript
+ * // Use server-recommended retry timing
+ * const retryAfter = retryAfterStrategy({
+ *   maxAttempts: 5,       // Retry up to 5 times
+ *   fallbackDelay: 10000  // 10s fallback if no header
+ * });
+ *
+ * const provider = createOpenAI({
+ *   retryStrategy: retryAfter
+ * });
+ * ```
+ */
+declare function retryAfterStrategy(options?: RetryAfterStrategyOptions): RetryStrategyFactory;
+
+export { type ExponentialBackoffOptions as E, type LinearBackoffOptions as L, type RetryAfterStrategyOptions as R, roundRobinKeys as a, retryAfterStrategy as b, dynamicKey as d, exponentialBackoff as e, linearBackoff as l, maskApiKey as m, noRetry as n, resolveApiKey as r, weightedKeys as w };