/**
 * Rate Limiting & Retry Types
 *
 * Provides types for rate limiting and automatic retry functionality.
 */
/**
 * Configuration for rate limiter
 */
export interface RateLimiterConfig {
    /**
     * Maximum requests per minute
     * @default 60
     */
    requestsPerMinute?: number;
    /**
     * Maximum tokens per minute (for token-based limiting)
     * Set to 0 to disable token-based limiting
     * @default 0
     */
    tokensPerMinute?: number;
    /**
     * Maximum concurrent requests
     * Set to 0 for unlimited
     * @default 0
     */
    maxConcurrent?: number;
    /**
     * Whether to throw immediately when rate limited instead of waiting
     * @default false
     */
    throwOnLimit?: boolean;
}
/**
 * Rate limiter statistics
 */
export interface RateLimiterStats {
    /**
     * Current number of available request tokens
     */
    availableRequests: number;
    /**
     * Current number of available LLM tokens
     */
    availableTokens: number;
    /**
     * Current number of concurrent requests
     */
    currentConcurrent: number;
    /**
     * Total requests made
     */
    totalRequests: number;
    /**
     * Total tokens consumed
     */
    totalTokens: number;
    /**
     * Number of times rate limit was hit
     */
    rateLimitHits: number;
    /**
     * Total time spent waiting due to rate limits (ms)
     */
    totalWaitTimeMs: number;
}
/**
 * Configuration for automatic retry
 */
export interface RetryConfig {
    /**
     * Maximum number of retry attempts
     * @default 3
     */
    maxRetries?: number;
    /**
     * Base delay between retries in milliseconds
     * @default 1000
     */
    baseDelayMs?: number;
    /**
     * Maximum delay between retries in milliseconds
     * @default 60000
     */
    maxDelayMs?: number;
    /**
     * Multiplier for exponential backoff
     * @default 2
     */
    backoffMultiplier?: number;
    /**
     * Whether to add random jitter to delays
     * @default true
     */
    jitter?: boolean;
    /**
     * Custom function to determine if an error is retryable
     * If not provided, uses default logic (429, 5xx, connection errors)
     */
    isRetryable?: (error: Error) => boolean;
    /**
     * Callback invoked before each retry attempt
     */
    onRetry?: (attempt: number, error: Error, delayMs: number) => void;
}
/**
 * Combined rate limit and retry configuration
 */
export interface RateLimitRetryConfig {
    /**
     * Rate limiter configuration
     */
    rateLimit?: RateLimiterConfig;
    /**
     * Retry configuration
     */
    retry?: RetryConfig;
}
/**
 * Result of acquiring a rate limit token
 */
export interface AcquireResult {
    /**
     * Whether the acquisition was successful
     */
    acquired: boolean;
    /**
     * Time waited to acquire the token (ms)
     */
    waitedMs: number;
    /**
     * If not acquired, the estimated wait time (ms)
     */
    estimatedWaitMs?: number;
}
/**
 * Rate limiter interface
 */
export interface RateLimiter {
    /**
     * Acquire permission to make a request
     * Waits if necessary (unless throwOnLimit is true)
     *
     * @param estimatedTokens - Estimated tokens for the request (optional)
     * @returns Acquire result
     */
    acquire(estimatedTokens?: number): Promise<AcquireResult>;
    /**
     * Release a concurrent request slot
     */
    release(): void;
    /**
     * Report actual token usage after request completes
     * Used to update token bucket
     *
     * @param tokens - Actual tokens used
     */
    reportUsage(tokens: number): void;
    /**
     * Get current rate limiter statistics
     */
    getStats(): RateLimiterStats;
    /**
     * Reset the rate limiter
     */
    reset(): void;
    /**
     * Check if a request can be made immediately
     */
    canAcquire(estimatedTokens?: number): boolean;
}
/**
 * Error thrown when rate limit is exceeded and throwOnLimit is true
 */
export declare class RateLimitExceededError extends Error {
    readonly estimatedWaitMs: number;
    constructor(message: string, estimatedWaitMs: number);
}
/**
 * Check if an error is a RateLimitExceededError
 */
export declare function isRateLimitExceededError(error: unknown): error is RateLimitExceededError;