@juspay/neurolink 9.32.0 → 9.33.0

package/dist/client/processors/document/WordProcessor.js

@@ -1,353 +0,0 @@
-/**
- * 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/client/processors/errors/FileErrorCode.js

@@ -1,255 +0,0 @@
-/**
- * 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 var FileErrorCode;
-(function (FileErrorCode) {
-    // ============================================================================
-    // DOWNLOAD ERRORS
-    // ============================================================================
-    /** File download failed due to network or server error */
-    FileErrorCode["DOWNLOAD_FAILED"] = "DOWNLOAD_FAILED";
-    /** Download operation exceeded timeout threshold */
-    FileErrorCode["DOWNLOAD_TIMEOUT"] = "DOWNLOAD_TIMEOUT";
-    /** Authentication failed when accessing the file */
-    FileErrorCode["DOWNLOAD_AUTH_FAILED"] = "DOWNLOAD_AUTH_FAILED";
-    /** Network error during download (connection reset, DNS failure, etc.) */
-    FileErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
-    /** File was not found at the specified location */
-    FileErrorCode["FILE_NOT_FOUND"] = "FILE_NOT_FOUND";
-    /** Request was rate limited by the server */
-    FileErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
-    // ============================================================================
-    // VALIDATION ERRORS
-    // ============================================================================
-    /** File exceeds maximum allowed size */
-    FileErrorCode["FILE_TOO_LARGE"] = "FILE_TOO_LARGE";
-    /** File type is not supported for processing */
-    FileErrorCode["UNSUPPORTED_TYPE"] = "UNSUPPORTED_TYPE";
-    /** File format is invalid or malformed */
-    FileErrorCode["INVALID_FORMAT"] = "INVALID_FORMAT";
-    /** File MIME type doesn't match expected format */
-    FileErrorCode["INVALID_MIME_TYPE"] = "INVALID_MIME_TYPE";
-    /** File magic bytes don't match expected file type */
-    FileErrorCode["INVALID_MAGIC_BYTES"] = "INVALID_MAGIC_BYTES";
-    /** File appears to be corrupted or damaged */
-    FileErrorCode["CORRUPTED_FILE"] = "CORRUPTED_FILE";
-    /** File internal structure is invalid */
-    FileErrorCode["INVALID_STRUCTURE"] = "INVALID_STRUCTURE";
-    // ============================================================================
-    // PROCESSING ERRORS
-    // ============================================================================
-    /** Generic processing failure */
-    FileErrorCode["PROCESSING_FAILED"] = "PROCESSING_FAILED";
-    /** Failed to parse file content */
-    FileErrorCode["PARSING_FAILED"] = "PARSING_FAILED";
-    /** Text encoding error (not UTF-8, BOM issues, etc.) */
-    FileErrorCode["ENCODING_ERROR"] = "ENCODING_ERROR";
-    /** Failed to extract content from file */
-    FileErrorCode["EXTRACTION_FAILED"] = "EXTRACTION_FAILED";
-    /** Failed to decompress file content */
-    FileErrorCode["DECOMPRESSION_FAILED"] = "DECOMPRESSION_FAILED";
-    // ============================================================================
-    // SECURITY ERRORS
-    // ============================================================================
-    /** Security validation failed */
-    FileErrorCode["SECURITY_VALIDATION_FAILED"] = "SECURITY_VALIDATION_FAILED";
-    /** XML External Entity (XXE) attack detected */
-    FileErrorCode["XXE_DETECTED"] = "XXE_DETECTED";
-    /** Cross-site scripting (XSS) attack detected */
-    FileErrorCode["XSS_DETECTED"] = "XSS_DETECTED";
-    /** Potentially malicious code execution detected */
-    FileErrorCode["CODE_EXECUTION_DETECTED"] = "CODE_EXECUTION_DETECTED";
-    /** Zip bomb or decompression bomb detected */
-    FileErrorCode["ZIP_BOMB_DETECTED"] = "ZIP_BOMB_DETECTED";
-    // ============================================================================
-    // SYSTEM ERRORS
-    // ============================================================================
-    /** Unknown or unexpected error */
-    FileErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
-})(FileErrorCode || (FileErrorCode = {}));
-/**
- * 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 const ERROR_MESSAGES = {
-    // Download errors
-    [FileErrorCode.DOWNLOAD_FAILED]: {
-        message: "Failed to download the file from the source.",
-        userMessage: "We couldn't download your file.",
-        suggestedAction: "Please try uploading the file again. If the problem persists, the file may have been deleted or access revoked.",
-        retryable: true,
-    },
-    [FileErrorCode.DOWNLOAD_TIMEOUT]: {
-        message: "File download timed out.",
-        userMessage: "The download took too long and was cancelled.",
-        suggestedAction: "This usually happens with very large files or slow connections. Try re-uploading a smaller version or check your network connection.",
-        retryable: true,
-    },
-    [FileErrorCode.DOWNLOAD_AUTH_FAILED]: {
-        message: "Authentication failed when accessing the file.",
-        userMessage: "We don't have permission to access this file.",
-        suggestedAction: "Please check the file permissions and ensure it's accessible, then try again.",
-        retryable: false,
-    },
-    [FileErrorCode.NETWORK_ERROR]: {
-        message: "Network error while downloading the file.",
-        userMessage: "A network error occurred while downloading.",
-        suggestedAction: "This is usually temporary. Please try uploading the file again.",
-        retryable: true,
-    },
-    [FileErrorCode.FILE_NOT_FOUND]: {
-        message: "The file could not be found at the specified location.",
-        userMessage: "The file could not be found.",
-        suggestedAction: "The file may have been moved or deleted. Please re-upload the file.",
-        retryable: false,
-    },
-    [FileErrorCode.RATE_LIMITED]: {
-        message: "Request was rate limited by the server.",
-        userMessage: "Too many requests in a short time.",
-        suggestedAction: "Please wait a few seconds and try again.",
-        retryable: true,
-    },
-    // Validation errors
-    [FileErrorCode.FILE_TOO_LARGE]: {
-        message: "File exceeds the maximum allowed size.",
-        userMessage: "This file is too large to process.",
-        suggestedAction: "Try compressing the file or splitting it into smaller parts. Consider reducing image quality or removing unnecessary content.",
-        retryable: false,
-    },
-    [FileErrorCode.UNSUPPORTED_TYPE]: {
-        message: "The file type is not supported for processing.",
-        userMessage: "This file type is not supported.",
-        suggestedAction: "Please convert your file to a supported format and try again.",
-        retryable: false,
-    },
-    [FileErrorCode.INVALID_FORMAT]: {
-        message: "The file format is invalid or malformed.",
-        userMessage: "This file appears to be in an invalid format.",
-        suggestedAction: "Please ensure the file is properly saved and not corrupted, then try again.",
-        retryable: false,
-    },
-    [FileErrorCode.INVALID_MIME_TYPE]: {
-        message: "File MIME type doesn't match the expected format.",
-        userMessage: "The file type doesn't match its extension.",
-        suggestedAction: "Please ensure the file extension matches its actual content type and try again.",
-        retryable: false,
-    },
-    [FileErrorCode.INVALID_MAGIC_BYTES]: {
-        message: "File magic bytes don't match the expected file type.",
-        userMessage: "This file doesn't appear to be a valid file of the expected type.",
-        suggestedAction: "The file may be corrupted or saved in the wrong format. Try re-saving the file in the correct format.",
-        retryable: true,
-    },
-    [FileErrorCode.CORRUPTED_FILE]: {
-        message: "File appears to be corrupted or damaged.",
-        userMessage: "This file appears to be corrupted or invalid.",
-        suggestedAction: "The file structure is invalid. Try re-downloading from the original source or re-creating the file.",
-        retryable: false,
-    },
-    [FileErrorCode.INVALID_STRUCTURE]: {
-        message: "File internal structure is invalid.",
-        userMessage: "The file has an invalid internal structure.",
-        suggestedAction: "The file format is correct but the content is malformed. Try validating the file with a format checker or re-exporting from the original application.",
-        retryable: false,
-    },
-    // Processing errors
-    [FileErrorCode.PROCESSING_FAILED]: {
-        message: "Failed to process the file content.",
-        userMessage: "We couldn't process this file.",
-        suggestedAction: "Please try again. If the problem persists, the file may be in an unsupported variant.",
-        retryable: true,
-    },
-    [FileErrorCode.PARSING_FAILED]: {
-        message: "Failed to parse the file content.",
-        userMessage: "We couldn't read the contents of this file.",
-        suggestedAction: "The file structure may be invalid. Try validating the file with a format checker or re-creating the file.",
-        retryable: false,
-    },
-    [FileErrorCode.ENCODING_ERROR]: {
-        message: "Text encoding error detected.",
-        userMessage: "We couldn't decode the text in this file.",
-        suggestedAction: "Try re-saving the file with UTF-8 encoding. Most modern text editors have this option in 'Save As' settings.",
-        retryable: false,
-    },
-    [FileErrorCode.EXTRACTION_FAILED]: {
-        message: "Failed to extract content from the file.",
-        userMessage: "We couldn't extract the content from this file.",
-        suggestedAction: "The file may be password-protected, corrupted, or use an unsupported variant. Try re-saving without protection.",
-        retryable: false,
-    },
-    [FileErrorCode.DECOMPRESSION_FAILED]: {
-        message: "Failed to decompress the file content.",
-        userMessage: "We couldn't decompress this file.",
-        suggestedAction: "The file may be corrupted or use an unsupported compression method. Try re-uploading or using a different file format.",
-        retryable: true,
-    },
-    // Security errors
-    [FileErrorCode.SECURITY_VALIDATION_FAILED]: {
-        message: "File failed security validation.",
-        userMessage: "This file contains content that is blocked for security reasons.",
-        suggestedAction: "Please remove the problematic content and try again. If you believe this is a legitimate file, please contact support.",
-        retryable: false,
-    },
-    [FileErrorCode.XXE_DETECTED]: {
-        message: "XML External Entity (XXE) attack pattern detected.",
-        userMessage: "This XML file contains DOCTYPE or ENTITY declarations that could pose security risks.",
-        suggestedAction: "Please remove DOCTYPE and ENTITY declarations from the XML file. Most XML files don't need these for basic data storage.",
-        retryable: false,
-    },
-    [FileErrorCode.XSS_DETECTED]: {
-        message: "Cross-site scripting (XSS) attack pattern detected.",
-        userMessage: "This file contains script tags or event handlers that could pose security risks.",
-        suggestedAction: "Please remove <script> tags and event handlers (onclick, onerror, etc.) from the file.",
-        retryable: false,
-    },
-    [FileErrorCode.CODE_EXECUTION_DETECTED]: {
-        message: "Potentially malicious code execution pattern detected.",
-        userMessage: "This file contains code execution tags that are not allowed.",
-        suggestedAction: "Please remove custom object/function tags and use standard data structures only.",
-        retryable: false,
-    },
-    [FileErrorCode.ZIP_BOMB_DETECTED]: {
-        message: "Zip bomb or decompression bomb pattern detected.",
-        userMessage: "This file has an unusually high compression ratio that could indicate a security threat.",
-        suggestedAction: "If this is a legitimate file, try re-saving it without extreme compression. Otherwise, please verify the file source.",
-        retryable: false,
-    },
-    // System errors
-    [FileErrorCode.UNKNOWN_ERROR]: {
-        message: "An unexpected error occurred.",
-        userMessage: "An unexpected error occurred while processing your file.",
-        suggestedAction: "Please try again. If the problem persists, contact support.",
-        retryable: true,
-    },
-};
-/**
- * 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 function getErrorTemplate(code) {
-    return ERROR_MESSAGES[code] ?? ERROR_MESSAGES[FileErrorCode.UNKNOWN_ERROR];
-}
-/**
- * Check if an error code represents a retryable error.
- *
- * @param code - The FileErrorCode to check
- * @returns true if the error is retryable
- */
-export function isRetryableErrorCode(code) {
-    return ERROR_MESSAGES[code]?.retryable ?? false;
-}