import { RateLimitTokenBucket } from '@logosdx/utils';
import type { _InternalHttpMethods, RateLimitRule, RateLimitConfig, RequestSerializer, CacheAdapter, RequestKeyOptions } from '../types.ts';
import type { FetchPlugin } from '../engine/types.ts';
import { ResiliencePolicy } from './base.ts';
/**
 * Extended internal state for rate limit policy.
 * Includes rate limit-specific fields and token bucket management.
 */
export interface RateLimitPolicyState<S, H, P> {
    /** Whether the policy is globally enabled */
    enabled: boolean;
    /** Set of HTTP methods this policy applies to */
    methods: Set<string>;
    /** The serializer function for bucket key generation */
    serializer: RequestSerializer<S, H, P>;
    /** Memoized rule cache: method:path -> resolved rule or null */
    rulesCache: Map<string, RateLimitRule<S, H, P> | null>;
    /** Max calls per window */
    maxCalls: number;
    /** Window duration in milliseconds */
    windowMs: number;
    /** Whether to wait for token vs reject immediately */
    waitForToken: boolean;
    /** Token buckets by key */
    rateLimiters: Map<string, RateLimitTokenBucket>;
}
/**
 * Rate limit policy for controlling request rate.
 *
 * Uses token bucket algorithm to enforce rate limits. Each unique key
 * (generated by the serializer) gets its own bucket, allowing per-endpoint
 * or per-user rate limiting.
 *
 * Uses endpoint-scoped serialization by default (method + path),
 * meaning all requests to the same endpoint share a rate limit bucket
 * regardless of their parameters or payload.
 *
 * @template S - Instance state type
 * @template H - Headers type
 * @template P - Params type
 */
export declare class RateLimitPolicy<S = unknown, H = unknown, P = unknown> extends ResiliencePolicy<RateLimitConfig<S, H, P>, RateLimitRule<S, H, P>, S, H, P> {
    /**
     * Extended state with rate limit-specific fields.
     */
    protected state: RateLimitPolicyState<S, H, P> | null;
    /**
     * Get the adapter (if configured).
     */
    get adapter(): CacheAdapter<unknown> | undefined;
    /**
     * Get the default serializer for rate limiting.
     */
    protected getDefaultSerializer(): RequestSerializer<S, H, P>;
    /**
     * Get the default HTTP methods for rate limiting.
     */
    protected getDefaultMethods(): _InternalHttpMethods[];
    /**
     * Initialize the rate limit policy with configuration.
     */
    init(config?: boolean | RateLimitConfig<S, H, P>): void;
    /**
     * Merge a matched rule with policy defaults.
     */
    protected mergeRuleWithDefaults(rule: RateLimitRule<S, H, P> | null): RateLimitRule<S, H, P>;
    /**
     * Resolve rate limit configuration for a request.
     */
    resolveForRequest(method: string, path: string, ctx: RequestKeyOptions<S, H, P>): RateLimitRule<S, H, P> | null;
    /**
     * Get or create a rate limiter for the given key.
     */
    getRateLimiter(key: string, maxCalls: number, windowMs: number): RateLimitTokenBucket;
    /**
     * Get the onRateLimit callback from config.
     */
    get onRateLimit(): RateLimitConfig<S, H, P>['onRateLimit'];
}
/**
 * Factory function that creates a rate limit plugin for FetchEngine.
 *
 * The plugin installs a `beforeRequest` hook at priority `-30` that
 * enforces token bucket rate limiting before requests proceed.
 *
 * @param config - Rate limit configuration
 * @returns FetchPlugin that can be installed via `engine.use()` or `plugins` config
 *
 * @example
 *     const api = new FetchEngine({
 *         baseUrl: 'https://api.example.com',
 *         plugins: [
 *             rateLimitPlugin({ maxCalls: 60, windowMs: 60000 })
 *         ]
 *     });
 */
export declare function rateLimitPlugin<H = unknown, P = unknown, S = unknown>(config: boolean | RateLimitConfig<S, H, P>): FetchPlugin<H, P, S>;