/**
 * File Processing Error Helpers
 *
 * Utilities for creating consistent, user-friendly file processing errors.
 * Provides factory functions for structured errors, retry determination logic,
 * and HTTP status extraction.
 *
 * @module processors/errors
 */
import type { FileProcessingError, FileProcessingSummary } from "../../types/index.js";
import { FileErrorCode } from "./FileErrorCode.js";
/**
 * Create a structured file processing error with user-friendly messaging.
 *
 * @param code - The error code from FileErrorCode enum
 * @param details - Additional context for the error (e.g., file size, format)
 * @param originalError - The original error that caused this failure
 * @returns A structured FileProcessingError with user-friendly messaging
 *
 * @example
 * ```typescript
 * const error = createFileError(FileErrorCode.FILE_TOO_LARGE, {
 *   sizeMB: "15.5",
 *   maxMB: "10",
 *   filename: "large-document.pdf",
 * });
 * ```
 */
export declare function createFileError(code: FileErrorCode, details?: Record<string, unknown>, originalError?: Error): FileProcessingError;
/**
 * Create a file processing error with custom messages.
 * Useful when you need to override the default messages with context-specific ones.
 *
 * @param code - The error code from FileErrorCode enum
 * @param customMessage - Custom technical message
 * @param customUserMessage - Custom user-friendly message
 * @param details - Additional context
 * @returns A structured FileProcessingError
 */
export declare function createCustomFileError(code: FileErrorCode, customMessage: string, customUserMessage: string, details?: Record<string, unknown>): FileProcessingError;
/**
 * Extract HTTP status code from various error types.
 *
 * @param error - The error to extract status from
 * @returns The HTTP status code if found, null otherwise
 *
 * @example
 * ```typescript
 * const status = extractHttpStatus(error);
 * if (status === 404) {
 *   // Handle not found
 * }
 * ```
 */
export declare function extractHttpStatus(error: unknown): number | null;
/**
 * Determine if an error is retryable based on error type and characteristics.
 * Checks for transient errors like 5xx, network errors, and timeouts.
 *
 * @param error - The error to check
 * @returns true if the error is transient and potentially retryable
 *
 * @example
 * ```typescript
 * if (isRetryableError(error) && retryCount < maxRetries) {
 *   await delay(backoffMs);
 *   return retry();
 * }
 * ```
 */
export declare function isRetryableError(error: unknown): boolean;
/**
 * Type guard to check if an error is a FileProcessingError.
 *
 * @param error - The value to check
 * @returns true if error is a FileProcessingError
 */
export declare function isFileProcessingError(error: unknown): error is FileProcessingError;
/**
 * Map an error to the appropriate FileErrorCode based on its characteristics.
 *
 * @param error - The error to analyze
 * @returns The most appropriate FileErrorCode
 */
export declare function mapErrorToCode(error: unknown): FileErrorCode;
/**
 * Format a file processing error for display to users.
 *
 * @param error - The FileProcessingError to format
 * @returns A formatted string suitable for display
 */
export declare function formatFileError(error: FileProcessingError): string;
/**
 * Create a processing summary from arrays of results.
 *
 * @param totalFiles - Total number of files attempted
 * @param processedFiles - Successfully processed files
 * @param failedFiles - Files that failed to process
 * @param skippedFiles - Files that were skipped
 * @param warnings - Non-fatal warnings
 * @returns A FileProcessingSummary object
 */
export declare function createProcessingSummary(totalFiles: number, processedFiles?: FileProcessingSummary["processedFiles"], failedFiles?: FileProcessingSummary["failedFiles"], skippedFiles?: FileProcessingSummary["skippedFiles"], warnings?: FileProcessingSummary["warnings"]): FileProcessingSummary;
/**
 * Combine multiple processing summaries into one.
 * Useful when processing different file types separately.
 *
 * @param summaries - Array of summaries to combine
 * @returns A combined FileProcessingSummary
 */
export declare function combineSummaries(summaries: FileProcessingSummary[]): FileProcessingSummary;
/**
 * Get retry delay based on error type and attempt number.
 * Implements exponential backoff with jitter.
 *
 * @param error - The error that occurred
 * @param attempt - Current attempt number (1-based)
 * @param baseDelayMs - Base delay in milliseconds (default: 1000)
 * @returns Delay in milliseconds before next retry
 */
export declare function getRetryDelay(error: unknown, attempt: number, baseDelayMs?: number): number;