/**
 * Retry Utilities
 *
 * Provides retry logic with exponential backoff for resilient async operations.
 */
import type { AsyncRetryOptions } from "../../types/index.js";
/**
 * Local alias: the canonical type was renamed to AsyncRetryOptions to avoid
 * collision with other RetryOptions types in the codebase.
 */
export type RetryOptions = AsyncRetryOptions;
/**
 * Default retry configuration.
 */
export declare const DEFAULT_RETRY_OPTIONS: RetryOptions;
/**
 * Calculate exponential backoff delay with optional jitter.
 *
 * Uses the formula: min(baseDelay * 2^(attempt-1) + jitter, maxDelay)
 *
 * @param attempt - Current attempt number (1-based)
 * @param baseDelayMs - Base delay in milliseconds
 * @param maxDelayMs - Maximum delay cap in milliseconds
 * @param addJitter - Whether to add random jitter (default: true)
 * @returns Calculated delay in milliseconds
 *
 * @example
 * ```typescript
 * // Without jitter
 * calculateBackoff(1, 1000, 30000, false); // 1000ms
 * calculateBackoff(2, 1000, 30000, false); // 2000ms
 * calculateBackoff(3, 1000, 30000, false); // 4000ms
 *
 * // With jitter (adds up to 10% random delay)
 * calculateBackoff(3, 1000, 30000, true); // ~4000-4400ms
 * ```
 */
export declare function calculateBackoff(attempt: number, baseDelayMs: number, maxDelayMs: number, addJitter?: boolean): number;
/**
 * Error thrown when all retry attempts are exhausted.
 */
export declare class RetryExhaustedError extends Error {
    readonly attempts: number;
    readonly lastError: Error;
    /**
     * Creates a new RetryExhaustedError.
     *
     * @param message - Error message
     * @param attempts - Total number of attempts made
     * @param lastError - The last error that caused the final failure
     */
    constructor(message: string, attempts: number, lastError: Error);
}
/**
 * Retry an async function with exponential backoff.
 *
 * Executes the provided function and retries on failure according to
 * the specified options. Uses exponential backoff between retries.
 *
 * @param fn - Async function to execute
 * @param options - Retry configuration (merged with defaults)
 * @returns Promise that resolves with the function result
 * @throws The last error if all retries are exhausted
 *
 * @example
 * ```typescript
 * // Basic usage with defaults
 * const data = await retry(() => fetchFromAPI());
 * ```
 *
 * @example
 * ```typescript
 * // With custom options
 * const data = await retry(
 *   () => fetchFromAPI(),
 *   {
 *     maxRetries: 5,
 *     baseDelayMs: 500,
 *     maxDelayMs: 10000,
 *     onRetry: (err, attempt, delay) => {
 *       console.log(`Retry ${attempt} after ${delay}ms: ${err.message}`);
 *     },
 *     shouldRetry: (err) => {
 *       // Only retry on network errors
 *       return err.name === 'NetworkError';
 *     }
 *   }
 * );
 * ```
 */
export declare function retry<T>(fn: () => Promise<T>, options?: Partial<RetryOptions>): Promise<T>;
/**
 * Create a retry wrapper with pre-configured options.
 *
 * Useful for creating reusable retry strategies.
 *
 * @param defaultOptions - Default retry options for the wrapper
 * @returns A retry function with the specified defaults
 *
 * @example
 * ```typescript
 * const apiRetry = createRetry({
 *   maxRetries: 5,
 *   baseDelayMs: 100,
 *   onRetry: (err, attempt) => logger.warn(`API retry ${attempt}`)
 * });
 *
 * // Use the configured retry
 * const data = await apiRetry(() => fetchFromAPI());
 * ```
 */
export declare function createRetry(defaultOptions: Partial<RetryOptions>): <T>(fn: () => Promise<T>, overrideOptions?: Partial<RetryOptions>) => Promise<T>;
