/**
 * Configuration options for rate limiter
 */
export interface IRateLimitConfig {
    /** Maximum tokens per period */
    maxPerPeriod: number;
    /** Time period in milliseconds */
    periodMs: number;
    /** Whether to apply per domain/key (vs globally) */
    perKey: boolean;
    /** Initial token count (defaults to max) */
    initialTokens?: number;
    /** Grace tokens to allow occasional bursts */
    burstTokens?: number;
    /** Apply global limit in addition to per-key limits */
    useGlobalLimit?: boolean;
}
/**
 * Rate limiter using token bucket algorithm
 * Provides more sophisticated rate limiting with burst handling
 */
export declare class RateLimiter {
    /** Rate limit configuration */
    private config;
    /** Token buckets per key */
    private buckets;
    /** Global bucket for non-keyed rate limiting */
    private globalBucket;
    /**
     * Create a new rate limiter
     * @param config Rate limiter configuration
     */
    constructor(config: IRateLimitConfig);
    /**
     * Check if a request is allowed under rate limits
     * @param key Key to check rate limit for (e.g. domain, user, IP)
     * @param cost Token cost (defaults to 1)
     * @returns Whether the request is allowed
     */
    isAllowed(key?: string, cost?: number): boolean;
    /**
     * Check if a bucket has enough tokens and consume them
     * @param bucket The token bucket to check
     * @param cost Token cost
     * @returns Whether tokens were consumed
     */
    private checkBucket;
    /**
     * Consume tokens for a request (if available)
     * @param key Key to consume tokens for
     * @param cost Token cost (defaults to 1)
     * @returns Whether tokens were consumed
     */
    consume(key?: string, cost?: number): boolean;
    /**
     * Get the remaining tokens for a key
     * @param key Key to check
     * @returns Number of remaining tokens
     */
    getRemainingTokens(key?: string): number;
    /**
     * Get stats for a specific key
     * @param key Key to get stats for
     * @returns Rate limit statistics
     */
    getStats(key?: string): {
        remaining: number;
        limit: number;
        resetIn: number;
        allowed: number;
        denied: number;
    };
    /**
     * Get or create a token bucket for a key
     * @param key The rate limit key
     * @returns Token bucket
     */
    private getBucket;
    /**
     * Refill tokens in a bucket based on elapsed time
     * @param bucket Token bucket to refill
     */
    private refillBucket;
    /**
     * Reset rate limits for a specific key
     * @param key Key to reset
     */
    reset(key?: string): void;
    /**
     * Reset all rate limiters
     */
    resetAll(): void;
    /**
     * Cleanup old buckets to prevent memory leaks
     * @param maxAge Maximum age in milliseconds
     */
    cleanup(maxAge?: number): void;
    /**
     * Record an error for a key (e.g., IP address) and determine if blocking is needed
     * RFC 5321 Section 4.5.4.1 suggests limiting errors to prevent abuse
     *
     * @param key Key to record error for (typically an IP address)
     * @param errorWindow Time window for error tracking in ms (default: 5 minutes)
     * @param errorThreshold Maximum errors before blocking (default: 10)
     * @returns true if the key should be blocked due to excessive errors
     */
    recordError(key: string, errorWindow?: number, errorThreshold?: number): boolean;
}