/**
 * Token bucket rate limiter configuration.
 */
export interface RateLimiterConfig {
    /** Maximum number of tokens in the bucket */
    maxTokens: number;
    /** Number of tokens refilled per interval */
    refillRate: number;
    /** Refill interval in milliseconds */
    refillIntervalMs: number;
}
/**
 * Pre-configured rate limit profiles for known external APIs.
 * These defaults are conservative estimates based on published API rate limits.
 * Consumers can override with custom configurations.
 */
export declare const RATE_LIMIT_PROFILES: Record<string, RateLimiterConfig>;
/**
 * Token bucket rate limiter.
 *
 * Implements the token bucket algorithm for client-side rate limiting.
 * Each API call consumes one token. Tokens are refilled at a configurable rate.
 * When the bucket is empty, callers must wait for tokens to become available.
 *
 * @example
 * const limiter = new TokenBucketRateLimiter(RATE_LIMIT_PROFILES.openai);
 * await limiter.acquire(); // Waits if necessary
 * const result = await callOpenAI();
 */
export declare class TokenBucketRateLimiter {
    private tokens;
    private readonly maxTokens;
    private readonly refillRate;
    private readonly refillIntervalMs;
    private lastRefillTime;
    private readonly name;
    constructor(config: RateLimiterConfig, name?: string);
    /**
     * Refills tokens based on elapsed time since last refill.
     * Tokens accumulate proportionally to elapsed time.
     */
    private refill;
    /**
     * Attempts to acquire a token without waiting.
     * @returns true if a token was acquired, false if the bucket is empty
     */
    tryAcquire(): boolean;
    /**
     * Acquires a token, waiting if necessary until one becomes available.
     * Logs a warning when rate limiting is active.
     *
     * @param maxWaitMs - Maximum time to wait in milliseconds (default: 30000)
     * @throws Error if the maximum wait time is exceeded
     */
    acquire(maxWaitMs?: number): Promise<void>;
    /** Returns the current number of available tokens */
    get availableTokens(): number;
    /** Resets the bucket to full capacity */
    reset(): void;
}
/**
 * Returns the rate limiter for a given service.
 * Creates one using the default profile if it doesn't exist.
 *
 * @param service - Service name (must match a key in RATE_LIMIT_PROFILES or custom config must be provided)
 * @param config - Optional custom configuration (overrides the default profile)
 * @returns The TokenBucketRateLimiter for the service
 */
export declare function getRateLimiter(service: string, config?: RateLimiterConfig): TokenBucketRateLimiter;
/**
 * Resets all rate limiters. Useful for testing.
 */
export declare function resetAllRateLimiters(): void;
/**
 * Wraps an async function with automatic rate limiting.
 *
 * @param service - Service name for rate limit lookup
 * @param fn - The async function to rate-limit
 * @param config - Optional custom rate limit configuration
 * @returns The result of the wrapped function
 *
 * @example
 * const result = await withRateLimit('openai', () => callOpenAI());
 */
export declare function withRateLimit<T>(service: string, fn: () => Promise<T>, config?: RateLimiterConfig): Promise<T>;