@juspay/neurolink 9.1.1 → 9.2.0

package/dist/lib/processors/base/BaseFileProcessor.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Base File Processor Abstract Class
+ *
+ * Provides common functionality for downloading, validating, and processing files
+ * from any source (URLs, buffers, cloud storage, etc.)
+ *
+ * This class uses the Template Method pattern to provide a consistent processing
+ * pipeline while allowing subclasses to customize specific steps.
+ *
+ * Key features:
+ * - Support for both URL downloads and direct buffer input
+ * - Configurable retry with exponential backoff
+ * - Gzip decompression support
+ * - Structured error handling with user-friendly messages
+ * - File type validation by MIME type and extension
+ * - Size limit enforcement
+ *
+ * @module processors/base/BaseFileProcessor
+ *
+ * @example
+ * ```typescript
+ * class ImageProcessor extends BaseFileProcessor<ProcessedImage> {
+ *   constructor() {
+ *     super({
+ *       maxSizeMB: 10,
+ *       timeoutMs: 30000,
+ *       supportedMimeTypes: ['image/jpeg', 'image/png'],
+ *       supportedExtensions: ['.jpg', '.jpeg', '.png'],
+ *       fileTypeName: 'image',
+ *       defaultFilename: 'image.jpg',
+ *     });
+ *   }
+ *
+ *   protected buildProcessedResult(buffer: Buffer, fileInfo: FileInfo): ProcessedImage {
+ *     return {
+ *       buffer,
+ *       mimetype: fileInfo.mimetype,
+ *       size: buffer.length,
+ *       filename: this.getFilename(fileInfo),
+ *       // ... additional image-specific fields
+ *     };
+ *   }
+ * }
+ * ```
+ */
+import { FileErrorCode } from "../errors/index.js";
+import type { BatchProcessingSummary, FileInfo, FileProcessingError, FileProcessingResult, FileProcessorConfig, OperationResult, ProcessedFileBase, ProcessOptions } from "./types.js";
+/**
+ * Abstract base class for file processors.
+ * Provides common download, validation, and error handling functionality.
+ *
+ * @typeParam T - The type of processed result, must extend ProcessedFileBase
+ */
+export declare abstract class BaseFileProcessor<T extends ProcessedFileBase> {
+    /** Processor configuration */
+    protected readonly config: FileProcessorConfig;
+    /**
+     * Creates a new file processor with the given configuration.
+     *
+     * @param config - Processor configuration
+     */
+    constructor(config: FileProcessorConfig);
+    /**
+     * Get the processor configuration.
+     * Provides read-only access to processor config for external consumers
+     * (e.g., ProcessorRegistry, FileProcessorIntegration) without requiring
+     * unsafe casts to access the protected field.
+     *
+     * @returns Readonly processor configuration
+     */
+    getConfig(): Readonly<FileProcessorConfig>;
+    /**
+     * Process a single file.
+     * Main entry point - implements the Template Method pattern.
+     *
+     * @param fileInfo - File information (can include URL or buffer)
+     * @param options - Optional processing options (auth headers, timeout, retry config)
+     * @returns Processing result with success flag and either data or error
+     *
+     * @example
+     * ```typescript
+     * const result = await processor.processFile(fileInfo, {
+     *   authHeaders: { 'Authorization': 'Bearer token' },
+     *   timeout: 60000,
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Processed:', result.data.filename);
+     * } else {
+     *   console.error('Failed:', result.error.userMessage);
+     * }
+     * ```
+     */
+    processFile(fileInfo: FileInfo, options?: ProcessOptions): Promise<FileProcessingResult<T>>;
+    /**
+     * Process multiple files with detailed summary.
+     *
+     * @param fileIds - Array of file IDs to process
+     * @param getFileInfo - Function to retrieve file info by ID
+     * @param options - Optional processing options
+     * @returns Summary with processed, failed, and skipped files
+     *
+     * @example
+     * ```typescript
+     * const summary = await processor.processFiles(
+     *   ['file1', 'file2', 'file3'],
+     *   async (id) => await fetchFileInfo(id),
+     *   { authHeaders: { 'Authorization': 'Bearer token' } }
+     * );
+     *
+     * console.log(`Success: ${summary.processedFiles.length}`);
+     * console.log(`Failed: ${summary.failedFiles.length}`);
+     * ```
+     */
+    processFiles(fileIds: string[], getFileInfo: (id: string) => Promise<FileInfo | null>, options?: ProcessOptions): Promise<BatchProcessingSummary<T>>;
+    /**
+     * Check if a file is supported by this processor.
+     *
+     * @param mimetype - MIME type of the file
+     * @param filename - Filename (for extension-based detection)
+     * @returns true if the file type is supported
+     *
+     * @example
+     * ```typescript
+     * if (processor.isFileSupported('image/jpeg', 'photo.jpg')) {
+     *   // Process the file
+     * }
+     * ```
+     */
+    isFileSupported(mimetype: string, filename: string): boolean;
+    /**
+     * Build the processed result object.
+     * Subclasses must implement this to create their specific result type.
+     *
+     * @param buffer - Downloaded/provided file content
+     * @param fileInfo - Original file information
+     * @returns Processed result object
+     */
+    protected abstract buildProcessedResult(buffer: Buffer, fileInfo: FileInfo): T | Promise<T>;
+    /**
+     * Validate downloaded file buffer.
+     * Override for custom post-download validation (e.g., magic bytes).
+     *
+     * @param _buffer - Downloaded file content
+     * @param _fileInfo - Original file information
+     * @returns null if valid, error message if invalid
+     */
+    protected validateDownloadedFile(_buffer: Buffer, _fileInfo: FileInfo): Promise<string | null>;
+    /**
+     * Validate downloaded file buffer with structured error result.
+     * Override for custom post-download validation with detailed errors.
+     *
+     * @param buffer - Downloaded file content
+     * @param fileInfo - Original file information
+     * @returns Success result or error result
+     */
+    protected validateDownloadedFileWithResult(buffer: Buffer, fileInfo: FileInfo): Promise<OperationResult<void>>;
+    /**
+     * Build processed result with structured error handling.
+     * Override for custom result building that can fail with errors.
+     *
+     * @param buffer - Downloaded file content
+     * @param fileInfo - Original file information
+     * @returns Success result with data or error result
+     */
+    protected buildProcessedResultWithResult(buffer: Buffer, fileInfo: FileInfo): Promise<FileProcessingResult<T>>;
+    /**
+     * Get filename with default fallback.
+     *
+     * @param fileInfo - File information
+     * @returns Filename or default if not available
+     */
+    protected getFilename(fileInfo: FileInfo): string;
+    /**
+     * Download file from URL with authentication.
+     *
+     * @param url - URL to download from
+     * @param authHeaders - Optional authentication headers
+     * @param timeout - Optional timeout override
+     * @returns Downloaded file content as Buffer
+     * @throws Error if download fails
+     */
+    protected downloadFile(url: string, authHeaders?: Record<string, string>, timeout?: number): Promise<Buffer>;
+    /**
+     * Download file with retry logic for transient failures.
+     *
+     * @param fileInfo - File information with URL
+     * @param options - Processing options including auth headers and retry config
+     * @returns Success result with buffer or error result
+     */
+    protected downloadFileWithRetry(fileInfo: FileInfo, options?: ProcessOptions): Promise<OperationResult<Buffer>>;
+    /**
+     * Validate file type and size with structured error result.
+     *
+     * @param fileInfo - File information to validate
+     * @returns Success result or error result
+     */
+    protected validateFileWithResult(fileInfo: FileInfo): OperationResult<void>;
+    /**
+     * Validate file size against configured maximum.
+     *
+     * @param sizeBytes - File size in bytes
+     * @returns true if size is within limits
+     */
+    protected validateFileSize(sizeBytes: number): boolean;
+    /**
+     * Check if file matches supported MIME types.
+     *
+     * @param mimetype - MIME type to check
+     * @returns true if MIME type is supported
+     */
+    protected isSupportedMimeType(mimetype: string): boolean;
+    /**
+     * Check if file matches supported extensions.
+     *
+     * @param filename - Filename to check
+     * @returns true if extension is supported
+     */
+    protected isSupportedExtension(filename: string): boolean;
+    /**
+     * Format file size in MB with 2 decimal places.
+     *
+     * @param sizeBytes - Size in bytes
+     * @returns Formatted size string
+     */
+    protected formatSizeMB(sizeBytes: number): string;
+    /**
+     * Create a structured file processing error.
+     *
+     * @param code - Error code
+     * @param details - Additional error details
+     * @param originalError - Original error that caused this
+     * @returns Structured error object
+     */
+    protected createError(code: FileErrorCode, details?: Record<string, unknown>, originalError?: Error): FileProcessingError;
+    /**
+     * Classify a download error into appropriate error code.
+     *
+     * @param error - The error to classify
+     * @returns Structured file processing error
+     */
+    protected classifyDownloadError(error: Error): FileProcessingError;
+    /**
+     * Sleep for specified milliseconds.
+     *
+     * @param ms - Milliseconds to sleep
+     */
+    protected sleep(ms: number): Promise<void>;
+}
+/**
+ * Get the default text file download timeout.
+ *
+ * @returns Timeout in milliseconds
+ */
+export declare function getDefaultTextTimeout(): number;
+/**
+ * Get the default image download timeout.
+ *
+ * @returns Timeout in milliseconds
+ */
+export declare function getDefaultImageTimeout(): number;
+/**
+ * Get the default text file max size in MB.
+ *
+ * @returns Max size in megabytes
+ */
+export declare function getDefaultTextMaxSizeMB(): number;
+/**
+ * Get the default image max size in MB.
+ *
+ * @returns Max size in megabytes
+ */
+export declare function getDefaultImageMaxSizeMB(): number;