@juspay/neurolink
Version:
Universal AI Development Platform with working MCP integration, multi-provider support, voice (TTS/STT/realtime), and professional CLI. 58+ external MCP servers discoverable, multimodal file processing, RAG pipelines. Build, test, and deploy AI applicatio
274 lines (273 loc) • 10 kB
TypeScript
/**
* 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, ProcessorFileProcessingResult, FileProcessorConfig, ProcessorOperationResult, ProcessedFileBase, ProcessOptions } from "../../types/index.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<ProcessorFileProcessingResult<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<ProcessorOperationResult<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<ProcessorFileProcessingResult<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<ProcessorOperationResult<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): ProcessorOperationResult<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;