/**
 * Client-Side Rate Limiter
 *
 * Implements client-side rate limiting to prevent overwhelming APIs
 * and respect rate limit headers from servers.
 *
 * @module api/advanced/rate-limiter
 */
/**
 * Rate limit configuration.
 */
export interface RateLimitConfig {
    /** Maximum requests per window */
    maxRequests: number;
    /** Time window in milliseconds */
    windowMs: number;
    /** Strategy for handling exceeded limits */
    strategy?: 'queue' | 'reject' | 'delay';
    /** Maximum queue size (for queue strategy) */
    maxQueueSize?: number;
    /** Maximum delay in milliseconds (for delay strategy) */
    maxDelay?: number;
    /** Key generator for per-endpoint limits */
    keyGenerator?: (endpoint: string) => string;
}
/**
 * Rate limit status.
 */
export interface RateLimitStatus {
    /** Number of requests remaining in current window */
    remaining: number;
    /** Total limit for the window */
    limit: number;
    /** Time until window resets (ms) */
    resetIn: number;
    /** Whether currently rate limited */
    isLimited: boolean;
    /** Current queue size */
    queueSize: number;
}
/**
 * Server rate limit headers.
 */
export interface RateLimitHeaders {
    /** Remaining requests */
    'x-ratelimit-remaining'?: string;
    /** Total limit */
    'x-ratelimit-limit'?: string;
    /** Reset timestamp */
    'x-ratelimit-reset'?: string;
    /** Retry after (seconds) */
    'retry-after'?: string;
}
/**
 * Client-Side Rate Limiter.
 *
 * Implements multiple rate limiting strategies to prevent API abuse
 * and handle server-imposed rate limits gracefully.
 *
 * @example
 * ```typescript
 * const limiter = new RateLimiter({
 *   maxRequests: 100,
 *   windowMs: 60000, // 1 minute
 *   strategy: 'queue',
 * });
 *
 * // Wrap API calls
 * const result = await limiter.execute('/users', () =>
 *   fetch('/api/users')
 * );
 *
 * // Check status
 * const status = limiter.getStatus('/users');
 * console.log(`${status.remaining} requests remaining`);
 * ```
 */
export declare class RateLimiter {
    private config;
    private windows;
    private readonly queue;
    private serverLimits;
    private processing;
    /**
     * Create a new rate limiter.
     *
     * @param config - Rate limit configuration
     */
    constructor(config: RateLimitConfig);
    /**
     * Execute a request with rate limiting.
     *
     * @param endpoint - Request endpoint
     * @param fn - Function to execute
     * @returns Promise resolving to function result
     */
    execute<T>(endpoint: string, fn: () => Promise<T>): Promise<T>;
    /**
     * Check if request would be rate limited.
     *
     * @param endpoint - Request endpoint
     * @returns Whether request would be limited
     */
    wouldBeLimited(endpoint: string): boolean;
    /**
     * Update rate limits from server response headers.
     *
     * @param endpoint - Request endpoint
     * @param headers - Response headers
     */
    updateFromHeaders(endpoint: string, headers: RateLimitHeaders): void;
    /**
     * Handle 429 Too Many Requests response.
     *
     * @param endpoint - Request endpoint
     * @param retryAfter - Retry-After header value
     */
    handle429(endpoint: string, retryAfter?: string): void;
    /**
     * Get rate limit status for an endpoint.
     *
     * @param endpoint - Request endpoint
     * @returns Rate limit status
     */
    getStatus(endpoint: string): RateLimitStatus;
    /**
     * Clear rate limit tracking for an endpoint.
     *
     * @param endpoint - Request endpoint
     */
    clear(endpoint: string): void;
    /**
     * Clear all rate limit tracking.
     */
    clearAll(): void;
    /**
     * Get all tracked endpoints.
     */
    getTrackedEndpoints(): string[];
    /**
     * Enqueue a request for later execution.
     */
    private enqueue;
    /**
     * Process queued requests.
     */
    private processQueue;
    /**
     * Get wait time until next request can be made.
     */
    private getWaitTime;
    /**
     * Check if server has imposed rate limit.
     */
    private isServerLimited;
    /**
     * Get or create window for key.
     */
    private getOrCreateWindow;
    /**
     * Delay execution.
     */
    private delay;
}
/**
 * Error thrown when rate limit is exceeded.
 */
export declare class RateLimitError extends Error {
    /** Time until rate limit resets (ms) */
    readonly retryAfter: number;
    /** Endpoint that was rate limited */
    readonly endpoint: string;
    constructor(message: string, retryAfter: number, endpoint: string);
}
/**
 * Create a new rate limiter.
 *
 * @param config - Rate limit configuration
 * @returns RateLimiter instance
 */
export declare function createRateLimiter(config: RateLimitConfig): RateLimiter;
/**
 * Common rate limit presets.
 */
export declare const RATE_LIMIT_PRESETS: {
    /** Conservative: 60 requests/minute */
    conservative: {
        maxRequests: number;
        windowMs: number;
        strategy: "queue";
    };
    /** Standard: 100 requests/minute */
    standard: {
        maxRequests: number;
        windowMs: number;
        strategy: "queue";
    };
    /** Aggressive: 300 requests/minute */
    aggressive: {
        maxRequests: number;
        windowMs: number;
        strategy: "delay";
    };
    /** Burst: 30 requests/second */
    burst: {
        maxRequests: number;
        windowMs: number;
        strategy: "queue";
        maxQueueSize: number;
    };
};