@juspay/neurolink 9.1.1 → 9.3.0

package/dist/processors/document/WordProcessor.js

@@ -0,0 +1,353 @@
+/**
+ * Word Document Processing Utility
+ *
+ * Handles downloading, validating, and processing Word (.docx, .doc) files.
+ * Uses mammoth library to extract text and HTML content from Word documents.
+ *
+ * Features:
+ * - DOCX format validation via ZIP/PK signature check
+ * - Text extraction using mammoth.extractRawText()
+ * - HTML conversion using mammoth.convertToHtml()
+ * - Warning collection from mammoth processing
+ * - Support for both URL downloads and direct buffer input
+ *
+ * @module processors/document/WordProcessor
+ *
+ * @example
+ * ```typescript
+ * import { wordProcessor, processWord, isWordFile } from "./WordProcessor.js";
+ *
+ * // Check if file is supported
+ * if (isWordFile(file.mimetype, file.name)) {
+ *   const result = await processWord(fileInfo, {
+ *     authHeaders: { Authorization: "Bearer token" },
+ *   });
+ *
+ *   if (result.success) {
+ *     console.log("Text:", result.data.textContent);
+ *     console.log("HTML:", result.data.htmlContent);
+ *     console.log("Warnings:", result.data.warnings);
+ *   }
+ * }
+ * ```
+ */
+import * as mammoth from "mammoth";
+import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
+import { SIZE_LIMITS } from "../config/index.js";
+import { FileErrorCode } from "../errors/index.js";
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/**
+ * Supported MIME types for Word documents
+ */
+const SUPPORTED_WORD_MIME_TYPES = [
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/msword",
+];
+/**
+ * Supported file extensions for Word documents
+ */
+const SUPPORTED_WORD_EXTENSIONS = [".docx", ".doc"];
+/**
+ * Default timeout for Word processing (60 seconds)
+ * Word documents can be larger due to embedded images and complex formatting
+ */
+const WORD_TIMEOUT_MS = 60000;
+// =============================================================================
+// WORD PROCESSOR CLASS
+// =============================================================================
+/**
+ * Word Processor - handles .docx and .doc files
+ *
+ * Uses mammoth library for both text and HTML extraction. The processor
+ * validates DOCX files by checking for the ZIP/PK signature (since DOCX
+ * files are actually ZIP archives).
+ *
+ * @example
+ * ```typescript
+ * const processor = new WordProcessor();
+ *
+ * // Check if file is supported
+ * if (processor.isFileSupported("application/msword", "report.doc")) {
+ *   const result = await processor.processFile(fileInfo);
+ *   if (result.success) {
+ *     console.log("Extracted text:", result.data.textContent);
+ *   }
+ * }
+ * ```
+ */
+export class WordProcessor extends BaseFileProcessor {
+    constructor() {
+        super({
+            maxSizeMB: SIZE_LIMITS.WORD_MAX_MB,
+            timeoutMs: WORD_TIMEOUT_MS,
+            supportedMimeTypes: SUPPORTED_WORD_MIME_TYPES,
+            supportedExtensions: SUPPORTED_WORD_EXTENSIONS,
+            fileTypeName: "Word",
+            defaultFilename: "document.docx",
+        });
+    }
+    /**
+     * Validate downloaded Word document has correct magic bytes.
+     * DOCX files are ZIP archives starting with PK signature (0x50 0x4B).
+     *
+     * @param buffer - Downloaded file content
+     * @param fileInfo - Original file information
+     * @returns null if valid, error message if invalid
+     */
+    async validateDownloadedFile(buffer, _fileInfo) {
+        // Minimum size check
+        if (buffer.length < 4) {
+            return "Invalid Word document - file too small";
+        }
+        // DOCX files are ZIP archives (PK signature: 0x50 0x4B)
+        const pkSignature = buffer.subarray(0, 2).toString("ascii");
+        if (pkSignature !== "PK") {
+            // Log what we actually received to help debug
+            const preview = buffer
+                .subarray(0, 100)
+                .toString("utf8")
+                .substring(0, 100);
+            const looksLikeHtml = preview.includes("<!DOCTYPE") || preview.includes("<html");
+            // Provide more specific error message
+            if (looksLikeHtml) {
+                return "Invalid Word document - received HTML response instead of file content (possibly an error page)";
+            }
+            return "Invalid Word document - not a valid DOCX format (expected ZIP/PK signature)";
+        }
+        return null;
+    }
+    /**
+     * Build processed Word result with extracted text and HTML content.
+     * This is a stub that returns an empty result - actual processing
+     * happens in the overridden processFile method since mammoth
+     * operations are asynchronous.
+     *
+     * @param buffer - Downloaded file content
+     * @param fileInfo - Original file information
+     * @returns Processed Word result (placeholder)
+     */
+    buildProcessedResult(buffer, fileInfo) {
+        // Note: This is a synchronous placeholder since buildProcessedResult is sync
+        // The actual mammoth extraction happens in the overridden processFile method
+        return {
+            textContent: "",
+            htmlContent: "",
+            warnings: [],
+            buffer,
+            mimetype: fileInfo.mimetype ||
+                "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            size: fileInfo.size,
+            filename: this.getFilename(fileInfo),
+        };
+    }
+    /**
+     * Override processFile for async mammoth extraction.
+     *
+     * The mammoth library's extractRawText and convertToHtml methods are
+     * asynchronous, so we need to override the entire processFile method
+     * rather than just buildProcessedResult.
+     *
+     * Processing steps:
+     * 1. Validate file type and size
+     * 2. Get buffer (download from URL or use provided buffer)
+     * 3. Validate downloaded file (check PK signature)
+     * 4. Extract text with mammoth.extractRawText()
+     * 5. Convert to HTML with mammoth.convertToHtml()
+     * 6. Collect any warnings from mammoth
+     * 7. Return structured result
+     *
+     * @param fileInfo - File information with URL or buffer
+     * @param options - Optional processing options
+     * @returns Processing result with text, HTML, and warnings
+     */
+    async processFile(fileInfo, options) {
+        try {
+            // Step 1: Validate file type and size
+            const validationResult = this.validateFileWithResult(fileInfo);
+            if (!validationResult.success) {
+                return {
+                    success: false,
+                    error: validationResult.error,
+                };
+            }
+            // Step 2: Get file buffer (from direct buffer or download from URL)
+            let buffer;
+            if (fileInfo.buffer) {
+                // Direct buffer provided - skip download
+                buffer = fileInfo.buffer;
+            }
+            else if (fileInfo.url) {
+                // Download from URL
+                const downloadResult = await this.downloadFileWithRetry(fileInfo, options);
+                if (!downloadResult.success) {
+                    return {
+                        success: false,
+                        error: downloadResult.error,
+                    };
+                }
+                if (!downloadResult.data) {
+                    return {
+                        success: false,
+                        error: this.createError(FileErrorCode.DOWNLOAD_FAILED, {
+                            reason: "Download succeeded but returned no data",
+                        }),
+                    };
+                }
+                buffer = downloadResult.data;
+            }
+            else {
+                // No buffer or URL provided
+                return {
+                    success: false,
+                    error: this.createError(FileErrorCode.DOWNLOAD_FAILED, {
+                        reason: "No buffer or URL provided for file",
+                    }),
+                };
+            }
+            // Step 3: Validate downloaded file (check magic bytes)
+            const postValidationError = await this.validateDownloadedFile(buffer, fileInfo);
+            if (postValidationError) {
+                return {
+                    success: false,
+                    error: this.createError(FileErrorCode.INVALID_FORMAT, {
+                        reason: postValidationError,
+                    }),
+                };
+            }
+            // Step 4 & 5: Extract text and HTML content using mammoth
+            let textContent = "";
+            let htmlContent = "";
+            const warnings = [];
+            try {
+                // Extract plain text
+                const textResult = await mammoth.extractRawText({ buffer });
+                textContent = textResult.value;
+                // Collect warnings from text extraction
+                if (textResult.messages && textResult.messages.length > 0) {
+                    warnings.push(...textResult.messages.map((m) => `[text] ${m.message}`));
+                }
+                // Convert to HTML for richer formatting
+                const htmlResult = await mammoth.convertToHtml({ buffer });
+                htmlContent = htmlResult.value;
+                // Collect warnings from HTML conversion
+                if (htmlResult.messages && htmlResult.messages.length > 0) {
+                    warnings.push(...htmlResult.messages.map((m) => `[html] ${m.message}`));
+                }
+            }
+            catch (extractError) {
+                return {
+                    success: false,
+                    error: this.createError(FileErrorCode.PROCESSING_FAILED, {
+                        reason: "Failed to extract Word document content",
+                        fileType: "Word",
+                    }, extractError instanceof Error ? extractError : undefined),
+                };
+            }
+            // Step 6: Return structured result
+            return {
+                success: true,
+                data: {
+                    buffer,
+                    mimetype: fileInfo.mimetype ||
+                        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+                    size: fileInfo.size,
+                    filename: this.getFilename(fileInfo),
+                    textContent,
+                    htmlContent,
+                    warnings,
+                },
+            };
+        }
+        catch (error) {
+            // Catch any unexpected errors
+            return {
+                success: false,
+                error: this.createError(FileErrorCode.UNKNOWN_ERROR, {
+                    error: error instanceof Error ? error.message : String(error),
+                }, error instanceof Error ? error : undefined),
+            };
+        }
+    }
+}
+// =============================================================================
+// SINGLETON INSTANCE
+// =============================================================================
+/**
+ * Singleton Word processor instance.
+ * Use this for most use cases to avoid creating multiple instances.
+ */
+export const wordProcessor = new WordProcessor();
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+/**
+ * Check if a file is a Word document (.docx or .doc).
+ *
+ * @param mimetype - MIME type of the file
+ * @param filename - Filename (for extension-based detection)
+ * @returns true if the file is a supported Word document
+ *
+ * @example
+ * ```typescript
+ * if (isWordFile(file.mimetype, file.name)) {
+ *   const result = await processWord(file);
+ * }
+ * ```
+ */
+export function isWordFile(mimetype, filename) {
+    return wordProcessor.isFileSupported(mimetype, filename);
+}
+/**
+ * Validate Word document size against configured limit.
+ *
+ * @param sizeBytes - File size in bytes
+ * @returns true if size is within the allowed limit
+ *
+ * @example
+ * ```typescript
+ * if (!validateWordSize(file.size)) {
+ *   throw new Error(`File exceeds ${SIZE_LIMITS.WORD_MAX_MB}MB limit`);
+ * }
+ * ```
+ */
+export function validateWordSize(sizeBytes) {
+    const maxBytes = SIZE_LIMITS.WORD_MAX_MB * 1024 * 1024;
+    return sizeBytes <= maxBytes;
+}
+/**
+ * Process a single Word document.
+ *
+ * Convenience function that uses the singleton wordProcessor instance.
+ *
+ * @param fileInfo - File information with URL or buffer
+ * @param options - Optional processing options (auth headers, timeout, retry config)
+ * @returns Processing result with extracted text, HTML, and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = await processWord({
+ *   id: "doc-123",
+ *   name: "report.docx",
+ *   mimetype: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+ *   size: 12345,
+ *   url: "https://example.com/files/report.docx",
+ * }, {
+ *   authHeaders: { Authorization: "Bearer token" },
+ * });
+ *
+ * if (result.success) {
+ *   console.log("Text content:", result.data.textContent);
+ *   console.log("HTML content:", result.data.htmlContent);
+ *   if (result.data.warnings.length > 0) {
+ *     console.warn("Warnings:", result.data.warnings);
+ *   }
+ * } else {
+ *   console.error("Failed:", result.error.userMessage);
+ * }
+ * ```
+ */
+export async function processWord(fileInfo, options) {
+    return wordProcessor.processFile(fileInfo, options);
+}

package/dist/processors/document/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Document Processors Module
+ *
+ * Exports document file processors for Word, Excel, and other document formats.
+ * Each processor handles downloading, validating, and extracting content from
+ * their respective file types.
+ *
+ * @module processors/document
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   // Word documents
+ *   WordProcessor,
+ *   wordProcessor,
+ *   isWordFile,
+ *   processWord,
+ *   type ProcessedWord,
+ *
+ *   // Excel spreadsheets
+ *   ExcelProcessor,
+ *   excelProcessor,
+ *   isExcelFile,
+ *   processExcel,
+ *   type ProcessedExcel,
+ *   type ExcelWorksheet,
+ * } from "./document/index.js";
+ *
+ * // Process a Word document
+ * if (isWordFile(file.mimetype, file.name)) {
+ *   const result = await processWord(fileInfo);
+ *   if (result.success) {
+ *     console.log("Text:", result.data.textContent);
+ *     console.log("HTML:", result.data.htmlContent);
+ *   }
+ * }
+ *
+ * // Process an Excel spreadsheet
+ * if (isExcelFile(file.mimetype, file.name)) {
+ *   const result = await processExcel(fileInfo);
+ *   if (result.success) {
+ *     console.log(`Sheets: ${result.data.sheetCount}`);
+ *     console.log(`Total rows: ${result.data.totalRows}`);
+ *     for (const sheet of result.data.worksheets) {
+ *       console.log(`  ${sheet.name}: ${sheet.rowCount} rows`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export { isWordFile, type ProcessedWord, processWord, validateWordSize, WordProcessor, wordProcessor, } from "./WordProcessor.js";
+export { ExcelProcessor, type ExcelWorksheet, excelProcessor, getExcelMaxRows, getExcelMaxSheets, getExcelMaxSizeMB, isExcelFile, type ProcessedExcel, processExcel, validateExcelSize, } from "./ExcelProcessor.js";
+export { isRtfFile, type ProcessedRtf, processRtf, RtfProcessor, rtfProcessor, validateRtfSize, } from "./RtfProcessor.js";
+export { getOpenDocumentMaxSizeMB, isOpenDocumentFile, OpenDocumentProcessor, openDocumentProcessor, type ProcessedOpenDocument, processOpenDocument, validateOpenDocumentSize, } from "./OpenDocumentProcessor.js";

package/dist/processors/document/index.js

@@ -0,0 +1,90 @@
+/**
+ * Document Processors Module
+ *
+ * Exports document file processors for Word, Excel, and other document formats.
+ * Each processor handles downloading, validating, and extracting content from
+ * their respective file types.
+ *
+ * @module processors/document
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   // Word documents
+ *   WordProcessor,
+ *   wordProcessor,
+ *   isWordFile,
+ *   processWord,
+ *   type ProcessedWord,
+ *
+ *   // Excel spreadsheets
+ *   ExcelProcessor,
+ *   excelProcessor,
+ *   isExcelFile,
+ *   processExcel,
+ *   type ProcessedExcel,
+ *   type ExcelWorksheet,
+ * } from "./document/index.js";
+ *
+ * // Process a Word document
+ * if (isWordFile(file.mimetype, file.name)) {
+ *   const result = await processWord(fileInfo);
+ *   if (result.success) {
+ *     console.log("Text:", result.data.textContent);
+ *     console.log("HTML:", result.data.htmlContent);
+ *   }
+ * }
+ *
+ * // Process an Excel spreadsheet
+ * if (isExcelFile(file.mimetype, file.name)) {
+ *   const result = await processExcel(fileInfo);
+ *   if (result.success) {
+ *     console.log(`Sheets: ${result.data.sheetCount}`);
+ *     console.log(`Total rows: ${result.data.totalRows}`);
+ *     for (const sheet of result.data.worksheets) {
+ *       console.log(`  ${sheet.name}: ${sheet.rowCount} rows`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+// =============================================================================
+// WORD PROCESSOR
+// =============================================================================
+export { 
+// Helper functions
+isWordFile, processWord, validateWordSize, 
+// Class
+WordProcessor, 
+// Singleton instance
+wordProcessor, } from "./WordProcessor.js";
+// =============================================================================
+// EXCEL PROCESSOR
+// =============================================================================
+export { 
+// Class
+ExcelProcessor, 
+// Singleton instance
+excelProcessor, 
+// Helper functions
+getExcelMaxRows, getExcelMaxSheets, getExcelMaxSizeMB, isExcelFile, processExcel, validateExcelSize, } from "./ExcelProcessor.js";
+// =============================================================================
+// RTF PROCESSOR
+// =============================================================================
+export { 
+// Helper functions
+isRtfFile, processRtf, 
+// Class
+RtfProcessor, 
+// Singleton instance
+rtfProcessor, validateRtfSize, } from "./RtfProcessor.js";
+// =============================================================================
+// OPENDOCUMENT PROCESSOR
+// =============================================================================
+export { getOpenDocumentMaxSizeMB, 
+// Helper functions
+isOpenDocumentFile, 
+// Class
+OpenDocumentProcessor, 
+// Singleton instance
+openDocumentProcessor, processOpenDocument, validateOpenDocumentSize, } from "./OpenDocumentProcessor.js";

package/dist/processors/errors/FileErrorCode.d.ts

@@ -0,0 +1,98 @@
+/**
+ * File Processing Error Codes
+ *
+ * Comprehensive error codes for file processing operations including:
+ * - Download operations (timeout, auth, network)
+ * - File validation (size, type, format)
+ * - Content processing (parsing, encoding, extraction)
+ * - Security validation (XXE, XSS, zip bombs)
+ * - System errors
+ *
+ * @module processors/errors
+ */
+/**
+ * Enumeration of all file processing error codes.
+ * Each code represents a specific failure scenario with associated messaging.
+ */
+export declare enum FileErrorCode {
+    /** File download failed due to network or server error */
+    DOWNLOAD_FAILED = "DOWNLOAD_FAILED",
+    /** Download operation exceeded timeout threshold */
+    DOWNLOAD_TIMEOUT = "DOWNLOAD_TIMEOUT",
+    /** Authentication failed when accessing the file */
+    DOWNLOAD_AUTH_FAILED = "DOWNLOAD_AUTH_FAILED",
+    /** Network error during download (connection reset, DNS failure, etc.) */
+    NETWORK_ERROR = "NETWORK_ERROR",
+    /** File was not found at the specified location */
+    FILE_NOT_FOUND = "FILE_NOT_FOUND",
+    /** Request was rate limited by the server */
+    RATE_LIMITED = "RATE_LIMITED",
+    /** File exceeds maximum allowed size */
+    FILE_TOO_LARGE = "FILE_TOO_LARGE",
+    /** File type is not supported for processing */
+    UNSUPPORTED_TYPE = "UNSUPPORTED_TYPE",
+    /** File format is invalid or malformed */
+    INVALID_FORMAT = "INVALID_FORMAT",
+    /** File MIME type doesn't match expected format */
+    INVALID_MIME_TYPE = "INVALID_MIME_TYPE",
+    /** File magic bytes don't match expected file type */
+    INVALID_MAGIC_BYTES = "INVALID_MAGIC_BYTES",
+    /** File appears to be corrupted or damaged */
+    CORRUPTED_FILE = "CORRUPTED_FILE",
+    /** File internal structure is invalid */
+    INVALID_STRUCTURE = "INVALID_STRUCTURE",
+    /** Generic processing failure */
+    PROCESSING_FAILED = "PROCESSING_FAILED",
+    /** Failed to parse file content */
+    PARSING_FAILED = "PARSING_FAILED",
+    /** Text encoding error (not UTF-8, BOM issues, etc.) */
+    ENCODING_ERROR = "ENCODING_ERROR",
+    /** Failed to extract content from file */
+    EXTRACTION_FAILED = "EXTRACTION_FAILED",
+    /** Failed to decompress file content */
+    DECOMPRESSION_FAILED = "DECOMPRESSION_FAILED",
+    /** Security validation failed */
+    SECURITY_VALIDATION_FAILED = "SECURITY_VALIDATION_FAILED",
+    /** XML External Entity (XXE) attack detected */
+    XXE_DETECTED = "XXE_DETECTED",
+    /** Cross-site scripting (XSS) attack detected */
+    XSS_DETECTED = "XSS_DETECTED",
+    /** Potentially malicious code execution detected */
+    CODE_EXECUTION_DETECTED = "CODE_EXECUTION_DETECTED",
+    /** Zip bomb or decompression bomb detected */
+    ZIP_BOMB_DETECTED = "ZIP_BOMB_DETECTED",
+    /** Unknown or unexpected error */
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Error message template with user-friendly messaging and retry information.
+ */
+export interface ErrorMessageTemplate {
+    /** Technical error message */
+    message: string;
+    /** User-friendly error message */
+    userMessage: string;
+    /** Suggested action to resolve the error */
+    suggestedAction: string;
+    /** Whether this error is potentially retryable */
+    retryable: boolean;
+}
+/**
+ * Error messages map with technical and user-friendly messaging for each error code.
+ * All messages are designed to be clear, actionable, and free of technical jargon.
+ */
+export declare const ERROR_MESSAGES: Record<FileErrorCode, ErrorMessageTemplate>;
+/**
+ * Get the error message template for a specific error code.
+ *
+ * @param code - The FileErrorCode to get the template for
+ * @returns The ErrorMessageTemplate for the given code
+ */
+export declare function getErrorTemplate(code: FileErrorCode): ErrorMessageTemplate;
+/**
+ * Check if an error code represents a retryable error.
+ *
+ * @param code - The FileErrorCode to check
+ * @returns true if the error is retryable
+ */
+export declare function isRetryableErrorCode(code: FileErrorCode): boolean;