/**
 * @fileoverview Token Bucket Rate Limiter for NVD API
 * @module @nahisaho/musubix-security/cve/rate-limiter
 *
 * Implements Token Bucket algorithm for rate limiting.
 * - With API Key: 50 requests per 30 seconds
 * - Without API Key: 5 requests per 30 seconds
 *
 * @requirement REQ-CVE-001 - NVD API rate limiting compliance
 * @design DES-EPIC2-002 - Rate Limiter component
 */
/**
 * Rate limiter configuration options
 */
export interface RateLimiterOptions {
    /**
     * Maximum number of tokens in the bucket
     * @default 50 (with API key) or 5 (without)
     */
    maxTokens: number;
    /**
     * Time window in milliseconds for token refill
     * @default 30000 (30 seconds)
     */
    windowMs: number;
    /**
     * Number of tokens to refill per window
     * @default maxTokens
     */
    refillTokens?: number;
}
/**
 * Rate limit status information
 */
export interface RateLimitStatus {
    /** Available tokens */
    availableTokens: number;
    /** Maximum tokens */
    maxTokens: number;
    /** Milliseconds until next refill */
    msUntilRefill: number;
    /** Whether a request can be made now */
    canProceed: boolean;
    /** Estimated wait time if cannot proceed (ms) */
    waitTimeMs: number;
}
/**
 * Token Bucket Rate Limiter
 *
 * @example
 * ```typescript
 * // With API key (50 req/30s)
 * const limiter = new RateLimiter({ maxTokens: 50, windowMs: 30000 });
 *
 * // Check if request can proceed
 * if (limiter.canProceed()) {
 *   limiter.consume();
 *   // make request
 * }
 *
 * // Or wait for token
 * await limiter.waitForToken();
 * // make request
 * ```
 */
export declare class RateLimiter {
    private tokens;
    private readonly maxTokens;
    private readonly windowMs;
    private readonly refillTokens;
    private lastRefillTime;
    private refillInterval;
    constructor(options: RateLimiterOptions);
    /**
     * Create a rate limiter configured for NVD API with API key
     * @returns Rate limiter with 50 req/30s limit
     */
    static withApiKey(): RateLimiter;
    /**
     * Create a rate limiter configured for NVD API without API key
     * @returns Rate limiter with 5 req/30s limit
     */
    static withoutApiKey(): RateLimiter;
    /**
     * Create appropriate rate limiter based on whether API key is provided
     * @param hasApiKey - Whether an API key is available
     * @returns Configured rate limiter
     */
    static forNVD(hasApiKey: boolean): RateLimiter;
    /**
     * Refill tokens based on elapsed time
     */
    private refill;
    /**
     * Check if a request can proceed without waiting
     * @returns True if tokens are available
     */
    canProceed(): boolean;
    /**
     * Consume a token for a request
     * @returns True if token was consumed, false if no tokens available
     */
    consume(): boolean;
    /**
     * Try to acquire a token, consuming it if available
     * Alias for consume() for clearer semantics
     * @returns True if token was acquired
     */
    tryAcquire(): boolean;
    /**
     * Wait for a token to become available, then consume it
     * @param timeoutMs - Maximum time to wait (default: 2 * windowMs)
     * @returns Promise that resolves when token is acquired
     * @throws Error if timeout is exceeded
     */
    waitForToken(timeoutMs?: number): Promise<void>;
    /**
     * Get current rate limit status
     * @returns Current status including available tokens and wait time
     */
    getStatus(): RateLimitStatus;
    /**
     * Reset the rate limiter to initial state
     */
    reset(): void;
    /**
     * Start automatic token refill (for long-running processes)
     * @param callback - Optional callback when tokens are refilled
     */
    startAutoRefill(callback?: (tokens: number) => void): void;
    /**
     * Stop automatic token refill
     */
    stopAutoRefill(): void;
    /**
     * Dispose of the rate limiter
     */
    dispose(): void;
    /**
     * Sleep for specified milliseconds
     */
    private sleep;
}
/**
 * Decorator for rate-limited async functions
 *
 * @example
 * ```typescript
 * const limiter = RateLimiter.forNVD(true);
 *
 * const rateLimitedFetch = withRateLimit(limiter, async (url: string) => {
 *   return fetch(url);
 * });
 * ```
 */
export declare function withRateLimit<T extends (...args: unknown[]) => Promise<unknown>>(limiter: RateLimiter, fn: T): T;
/**
 * Rate limiter pool for managing multiple limiters
 *
 * @example
 * ```typescript
 * const pool = new RateLimiterPool();
 *
 * // Get or create a limiter for NVD API
 * const nvdLimiter = pool.get('nvd', () => RateLimiter.forNVD(true));
 * ```
 */
export declare class RateLimiterPool {
    private limiters;
    /**
     * Get or create a rate limiter by key
     * @param key - Unique identifier for the limiter
     * @param factory - Factory function to create limiter if not exists
     * @returns The rate limiter
     */
    get(key: string, factory: () => RateLimiter): RateLimiter;
    /**
     * Check if a limiter exists for the given key
     */
    has(key: string): boolean;
    /**
     * Remove a limiter by key
     */
    remove(key: string): boolean;
    /**
     * Get all limiter keys
     */
    keys(): string[];
    /**
     * Dispose all limiters
     */
    dispose(): void;
}
//# sourceMappingURL=rate-limiter.d.ts.map