/**
 * Custom fetch function factory with download progress tracking.
 *
 * This module provides a factory function that creates a custom fetch wrapper
 * which monitors the complete request lifecycle and provides event-based
 * progress tracking for UI updates and logging.
 *
 * @module
 */
import type { Logger } from '../../logger/index.js';
import type { FetchProgressEvent } from '../types/progress-event.types.js';
/**
 * Check if the logger should output progress logs based on its current level.
 *
 * This function is used to control direct stderr output (process.stderr.write)
 * which bypasses the logger's internal level filtering. For logger.info() calls,
 * the logger itself handles level filtering.
 *
 * @param logger - Logger instance to check
 * @returns true if progress logs should be output, false otherwise
 *
 * @remarks
 * - Used only for process.stderr.write() calls, not for logger.info()
 * - If the logger has a 'level' property, checks if it's 'debug' or 'info'
 * - If no 'level' property exists, assumes logging should be enabled
 *
 * @example
 * ```typescript
 * const logger = new ConsoleLogger('warn');
 * shouldProgressLog(logger); // false (warn > info)
 *
 * const debugLogger = new ConsoleLogger('debug');
 * shouldProgressLog(debugLogger); // true (debug <= info)
 * ```
 */
export declare function shouldProgressLog(logger: Logger): boolean;
/**
 * Configuration for creating a fetch function with progress tracking.
 *
 * @remarks
 * This interface defines all options needed to create a custom fetch wrapper
 * that monitors the complete request lifecycle through event callbacks.
 *
 * @example Basic usage with logging
 * ```typescript
 * const customFetch = createFetchWithProgress({
 *   logger: myLogger,
 *   enableProgressLog: true,
 * });
 * ```
 *
 * @example With event callback for UI updates
 * ```typescript
 * const customFetch = createFetchWithProgress({
 *   logger: myLogger,
 *   enableProgressLog: false,
 *   onProgressEvent: (event) => {
 *     if (event.type === 'download-progress') {
 *       updateProgressBar(event.percentage);
 *     }
 *   },
 * });
 * ```
 */
export type FetchWithProgressConfig = {
    /**
     * Logger instance for progress output.
     */
    readonly logger: Logger;
    /**
     * Whether to log progress to the logger.
     */
    readonly enableProgressLog: boolean;
    /**
     * Base fetch function to wrap with progress tracking.
     * If not provided, uses global fetch.
     */
    readonly baseFetch?: typeof fetch;
    /**
     * Optional callback for progress events.
     *
     * Receives all lifecycle events:
     * - request-start
     * - response-received
     * - download-progress (throttled to 500ms)
     * - complete
     *
     * @param event - Progress event with type-specific data
     */
    readonly onProgressEvent?: (event: FetchProgressEvent) => void;
};
/**
 * Create a custom fetch function with complete lifecycle progress tracking.
 *
 * This factory function creates a fetch wrapper that monitors the entire request
 * lifecycle and provides real-time feedback through event callbacks and/or logging.
 * The returned function is compatible with the standard fetch API signature.
 *
 * @param config - Configuration object containing logger and callback options
 * @returns A fetch-compatible function with progress tracking capabilities
 *
 * @remarks
 * The returned fetch function:
 * - Maintains the same signature as standard fetch
 * - Fires events for all lifecycle phases: request-start, response-received, download-progress, complete
 * - Wraps response body with a ReadableStream that tracks bytes received
 * - Throttles progress updates to 500ms intervals to avoid overhead
 * - Automatically estimates download size based on URL parameters (limit × 2670 bytes)
 * - Works in both Node.js (using process.stderr for live updates) and browser environments
 *
 * Progress tracking behavior:
 * - If `enableProgressLog` is true and logger level is 'debug' or 'info', logs progress messages
 * - If `onProgressEvent` callback is provided, fires events regardless of log level
 * - If neither logging nor callback are enabled, returns response without tracking overhead
 *
 * @example With progress logging
 * ```typescript
 * const customFetch = createFetchWithProgress({
 *   logger: myLogger,
 *   enableProgressLog: true,
 * });
 *
 * // Use like standard fetch
 * const response = await customFetch('https://api.example.com/data?limit=1000');
 * const data = await response.json();
 * ```
 *
 * @example With custom event handler
 * ```typescript
 * let progressBar: ProgressBar | null = null;
 *
 * const customFetch = createFetchWithProgress({
 *   logger: myLogger,
 *   enableProgressLog: false,
 *   onProgressEvent: (event) => {
 *     switch (event.type) {
 *       case 'request-start':
 *         console.log('Starting request...');
 *         break;
 *       case 'response-received':
 *         progressBar = new ProgressBar({ total: event.estimatedTotal });
 *         break;
 *       case 'download-progress':
 *         progressBar?.update(event.percentage);
 *         break;
 *       case 'complete':
 *         progressBar?.complete();
 *         if (event.status >= 200 && event.status < 300) {
 *           console.log(`Downloaded ${event.received} bytes in ${event.totalTimeMs}ms`);
 *         }
 *         break;
 *     }
 *   },
 * });
 * ```
 */
export declare function createFetchWithProgress(config: FetchWithProgressConfig): typeof fetch;
//# sourceMappingURL=fetch-with-progress.d.ts.map