@juspay/neurolink 9.1.1 → 9.2.0

package/dist/lib/processors/document/RtfProcessor.js

@@ -0,0 +1,362 @@
+/**
+ * RTF Document Processor
+ *
+ * Processes Rich Text Format (.rtf) files by extracting plain text content
+ * from RTF control codes. Uses a lightweight text extraction approach
+ * without requiring external dependencies.
+ *
+ * Key features:
+ * - RTF control code stripping
+ * - Text content extraction
+ * - Raw content preservation for debugging
+ * - No external dependencies required
+ *
+ * Priority: ~110 (document format, processed after binary formats)
+ *
+ * @module processors/document/RtfProcessor
+ *
+ * @example
+ * ```typescript
+ * import { rtfProcessor, processRtf, isRtfFile } from "./document/index.js";
+ *
+ * // Check if a file is an RTF file
+ * if (isRtfFile("application/rtf", "document.rtf")) {
+ *   const result = await processRtf({
+ *     id: "file-123",
+ *     name: "document.rtf",
+ *     mimetype: "application/rtf",
+ *     size: 10240,
+ *     buffer: rtfBuffer,
+ *   });
+ *
+ *   if (result.success) {
+ *     console.log(`Text content: ${result.data.textContent}`);
+ *   }
+ * }
+ * ```
+ */
+import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
+import { SIZE_LIMITS } from "../config/index.js";
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/**
+ * Supported MIME types for RTF documents
+ */
+const SUPPORTED_RTF_MIME_TYPES = [
+    "application/rtf",
+    "text/rtf",
+    "text/richtext",
+];
+/**
+ * Supported file extensions for RTF documents
+ */
+const SUPPORTED_RTF_EXTENSIONS = [".rtf"];
+/**
+ * Default timeout for RTF processing (30 seconds)
+ */
+const RTF_TIMEOUT_MS = 30000;
+// =============================================================================
+// RTF PROCESSOR CLASS
+// =============================================================================
+/**
+ * RTF Processor - handles Rich Text Format files.
+ *
+ * Extracts plain text from RTF documents by stripping RTF control codes.
+ * This is a lightweight implementation that doesn't require external
+ * RTF parsing libraries.
+ *
+ * Priority: ~110 (document format)
+ *
+ * @example
+ * ```typescript
+ * const processor = new RtfProcessor();
+ *
+ * const result = await processor.processFile({
+ *   id: "file-123",
+ *   name: "report.rtf",
+ *   mimetype: "application/rtf",
+ *   size: 5120,
+ *   buffer: rtfBuffer,
+ * });
+ *
+ * if (result.success) {
+ *   console.log("Extracted text:", result.data.textContent);
+ * }
+ * ```
+ */
+export class RtfProcessor extends BaseFileProcessor {
+    constructor() {
+        super({
+            maxSizeMB: SIZE_LIMITS.DOCUMENT_MAX_MB,
+            timeoutMs: RTF_TIMEOUT_MS,
+            supportedMimeTypes: SUPPORTED_RTF_MIME_TYPES,
+            supportedExtensions: SUPPORTED_RTF_EXTENSIONS,
+            fileTypeName: "RTF",
+            defaultFilename: "document.rtf",
+        });
+    }
+    /**
+     * Validate downloaded RTF document.
+     * Checks for RTF header signature "{\\rtf".
+     *
+     * @param buffer - Downloaded file content
+     * @param fileInfo - Original file information
+     * @returns null if valid, error message if invalid
+     */
+    async validateDownloadedFile(buffer, _fileInfo) {
+        if (buffer.length < 5) {
+            return "Invalid RTF document - file too small";
+        }
+        // RTF files should start with "{\rtf"
+        const header = buffer.subarray(0, 10).toString("ascii");
+        if (!header.startsWith("{\\rtf")) {
+            // Check if it might be HTML error page
+            const preview = buffer
+                .subarray(0, 100)
+                .toString("utf8")
+                .substring(0, 100);
+            if (preview.includes("<!DOCTYPE") || preview.includes("<html")) {
+                return "Invalid RTF document - received HTML response instead of file content";
+            }
+            return "Invalid RTF document - missing RTF header signature";
+        }
+        return null;
+    }
+    /**
+     * Build the processed RTF result.
+     * Extracts plain text by stripping RTF control codes.
+     *
+     * @param buffer - Raw file content
+     * @param fileInfo - Original file information
+     * @returns Processed RTF with extracted text content
+     */
+    buildProcessedResult(buffer, fileInfo) {
+        const rawContent = buffer.toString("utf-8");
+        const textContent = this.extractText(rawContent);
+        return {
+            textContent,
+            rawContent,
+            buffer,
+            mimetype: fileInfo.mimetype || "application/rtf",
+            size: fileInfo.size,
+            filename: this.getFilename(fileInfo),
+        };
+    }
+    /**
+     * Extract plain text from RTF content.
+     * Strips RTF control codes, groups, and formatting commands.
+     *
+     * This is a basic RTF parser that handles common RTF constructs:
+     * - Control groups like {\fonttbl...}
+     * - Control words like \par, \b, \i
+     * - Special characters like \' hex escapes
+     * - Newlines from \par and \line commands
+     *
+     * @param rtf - Raw RTF content
+     * @returns Extracted plain text
+     */
+    extractText(rtf) {
+        const text = rtf;
+        let result = "";
+        let depth = 0;
+        let skipGroup = false;
+        let skipGroupDepth = 0;
+        let i = 0;
+        // Groups that should be skipped entirely (metadata, not content)
+        const skipGroupNames = [
+            "fonttbl",
+            "colortbl",
+            "stylesheet",
+            "info",
+            "pict",
+            "object",
+            "header",
+            "footer",
+        ];
+        while (i < text.length) {
+            const char = text[i];
+            if (char === "{") {
+                depth++;
+                // Check if this is a group we should skip
+                const nextChars = text.substring(i + 1, i + 20);
+                const groupMatch = nextChars.match(/^\\([a-z]+)/);
+                if (groupMatch &&
+                    skipGroupNames.includes(groupMatch[1]) &&
+                    !skipGroup) {
+                    skipGroup = true;
+                    skipGroupDepth = depth;
+                }
+                i++;
+                continue;
+            }
+            if (char === "}") {
+                depth--;
+                if (skipGroup && depth < skipGroupDepth) {
+                    skipGroup = false;
+                    skipGroupDepth = 0;
+                }
+                i++;
+                continue;
+            }
+            if (skipGroup) {
+                i++;
+                continue;
+            }
+            if (char === "\\") {
+                // Control word or symbol
+                const remaining = text.substring(i);
+                // Handle special escapes
+                if (remaining.startsWith("\\\\")) {
+                    result += "\\";
+                    i += 2;
+                    continue;
+                }
+                if (remaining.startsWith("\\{")) {
+                    result += "{";
+                    i += 2;
+                    continue;
+                }
+                if (remaining.startsWith("\\}")) {
+                    result += "}";
+                    i += 2;
+                    continue;
+                }
+                // Handle hex escapes like \'e9 (é)
+                const hexMatch = remaining.match(/^\\'([0-9a-f]{2})/i);
+                if (hexMatch) {
+                    const charCode = parseInt(hexMatch[1], 16);
+                    result += String.fromCharCode(charCode);
+                    i += 4;
+                    continue;
+                }
+                // Handle Unicode escapes like \u233? (é)
+                const unicodeMatch = remaining.match(/^\\u(-?\d+)\??/);
+                if (unicodeMatch) {
+                    let charCode = parseInt(unicodeMatch[1], 10);
+                    if (charCode < 0) {
+                        charCode += 65536; // Convert negative to positive
+                    }
+                    result += String.fromCharCode(charCode);
+                    i += unicodeMatch[0].length;
+                    continue;
+                }
+                // Handle control words
+                const controlMatch = remaining.match(/^\\([a-z]+)(-?\d*)[ ]?/i);
+                if (controlMatch) {
+                    const controlWord = controlMatch[1].toLowerCase();
+                    // Convert some control words to text
+                    if (controlWord === "par" || controlWord === "line") {
+                        result += "\n";
+                    }
+                    else if (controlWord === "tab") {
+                        result += "\t";
+                    }
+                    else if (controlWord === "emdash") {
+                        result += "—";
+                    }
+                    else if (controlWord === "endash") {
+                        result += "–";
+                    }
+                    else if (controlWord === "bullet") {
+                        result += "•";
+                    }
+                    else if (controlWord === "lquote") {
+                        result += "'";
+                    }
+                    else if (controlWord === "rquote") {
+                        result += "'";
+                    }
+                    else if (controlWord === "ldblquote") {
+                        result += '"';
+                    }
+                    else if (controlWord === "rdblquote") {
+                        result += '"';
+                    }
+                    i += controlMatch[0].length;
+                    continue;
+                }
+                // Unknown control sequence, skip the backslash and control word
+                i++;
+                continue;
+            }
+            // Regular character
+            if (char !== "\r" && char !== "\n") {
+                result += char;
+            }
+            i++;
+        }
+        // Clean up the result
+        result = result
+            .replace(/\s+/g, " ") // Normalize whitespace
+            .replace(/ +\n/g, "\n") // Remove trailing spaces before newlines
+            .replace(/\n +/g, "\n") // Remove leading spaces after newlines
+            .replace(/\n{3,}/g, "\n\n") // Collapse multiple newlines
+            .trim();
+        return result;
+    }
+}
+// =============================================================================
+// SINGLETON INSTANCE
+// =============================================================================
+/**
+ * Singleton instance of the RtfProcessor.
+ * Use this for all RTF document processing to share configuration.
+ */
+export const rtfProcessor = new RtfProcessor();
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+/**
+ * Check if a file is an RTF document.
+ *
+ * @param mimetype - MIME type of the file
+ * @param filename - Filename for detection
+ * @returns true if the file is a supported RTF document
+ *
+ * @example
+ * ```typescript
+ * if (isRtfFile("application/rtf", "document.rtf")) {
+ *   console.log("This is an RTF document");
+ * }
+ * ```
+ */
+export function isRtfFile(mimetype, filename) {
+    return rtfProcessor.isFileSupported(mimetype, filename);
+}
+/**
+ * Validate RTF document size against configured limit.
+ *
+ * @param sizeBytes - File size in bytes
+ * @returns true if size is within the allowed limit
+ */
+export function validateRtfSize(sizeBytes) {
+    const maxBytes = SIZE_LIMITS.DOCUMENT_MAX_MB * 1024 * 1024;
+    return sizeBytes <= maxBytes;
+}
+/**
+ * Process an RTF document.
+ *
+ * @param fileInfo - File information (can include URL or buffer)
+ * @param options - Optional processing options
+ * @returns Processing result with success flag and either data or error
+ *
+ * @example
+ * ```typescript
+ * const result = await processRtf({
+ *   id: "file-123",
+ *   name: "report.rtf",
+ *   mimetype: "application/rtf",
+ *   size: 10240,
+ *   buffer: rtfBuffer,
+ * });
+ *
+ * if (result.success) {
+ *   console.log("Extracted text:", result.data.textContent);
+ * }
+ * ```
+ */
+export async function processRtf(fileInfo, options) {
+    return rtfProcessor.processFile(fileInfo, options);
+}
+//# sourceMappingURL=RtfProcessor.js.map

package/dist/lib/processors/document/WordProcessor.d.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 { BaseFileProcessor } from "../base/BaseFileProcessor.js";
+import type { FileInfo, FileProcessingResult, ProcessOptions } from "../base/types.js";
+export type { ProcessedWord } from "../base/types.js";
+import type { ProcessedWord } from "../base/types.js";
+/**
+ * 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 declare class WordProcessor extends BaseFileProcessor<ProcessedWord> {
+    constructor();
+    /**
+     * 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
+     */
+    protected validateDownloadedFile(buffer: Buffer, _fileInfo: FileInfo): Promise<string | 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)
+     */
+    protected buildProcessedResult(buffer: Buffer, fileInfo: FileInfo): ProcessedWord;
+    /**
+     * 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
+     */
+    processFile(fileInfo: FileInfo, options?: ProcessOptions): Promise<FileProcessingResult<ProcessedWord>>;
+}
+/**
+ * Singleton Word processor instance.
+ * Use this for most use cases to avoid creating multiple instances.
+ */
+export declare const wordProcessor: WordProcessor;
+/**
+ * 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 declare function isWordFile(mimetype: string, filename: string): boolean;
+/**
+ * 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 declare function validateWordSize(sizeBytes: number): boolean;
+/**
+ * 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 declare function processWord(fileInfo: FileInfo, options?: ProcessOptions): Promise<FileProcessingResult<ProcessedWord>>;