import { type Maybe, type PromiseOrValue, type PromiseRateLimiter } from '@dereekb/util';
import { type FetchHandler } from './fetch';
import { type FetchResponseError } from './error';
/**
 * A FetchRequestFactory with PromiseRateLimiter
 */
export type RateLimitedFetchHandler<T extends PromiseRateLimiter = PromiseRateLimiter> = FetchHandler & {
    /**
     * Internal limiter used by the RateLimitedFetchRequestFactory.
     */
    readonly _rateLimiter: T;
};
export interface RateLimitedFetchHandlerConfig<T extends PromiseRateLimiter> {
    /**
     * Rate limiter configuration. Should be based on the target API.
     */
    readonly rateLimiter: T;
    /**
     * The maximum number of retries to try.
     *
     * Defaults to 1.
     */
    readonly maxRetries?: number;
    /**
     * Update the fetch handler with the response, ideally setting/updating the time at which the rate limiter can be reset.
     *
     * Return true if the response should be retried. Should typically also only return true if the response is a throttle error by the remote server.
     *
     * The response is only allowed to be retried once not guranteed to be retried if it returns true on a second retry.
     */
    updateWithResponse(response: Response, fetchResponseError?: Maybe<FetchResponseError>): PromiseOrValue<boolean>;
}
/**
 * Creates a FetchHandler that enforces rate limiting via the provided PromiseRateLimiter and supports
 * automatic retry when the server signals throttling.
 *
 * @param config - configuration containing the rate limiter, retry settings, and response handler
 * @returns a RateLimitedFetchHandler that rate-limits outgoing requests and retries on throttle responses
 */
export declare function rateLimitedFetchHandler<T extends PromiseRateLimiter>(config: RateLimitedFetchHandlerConfig<T>): RateLimitedFetchHandler<T>;