officeparser 5.2.1 → 6.0.1

package/dist/utils/chartUtils.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractChartData = void 0;
+const xmlUtils_1 = require("./xmlUtils");
+/**
+ * Extracts a single text element located at:
+ * c:title -> c:tx -> c:rich -> a:p -> a:r -> a:t
+ * OR c:tx -> c:strRef -> c:strCache -> c:pt -> c:v
+ * @param el Chart element
+ * @param tagName The tag to search for (e.g., "c:title", "c:tx")
+ */
+const extractOpenXmlRichText = (el, tagName) => {
+    const target = (el.localName === tagName || el.tagName === tagName) ? el : el.getElementsByTagName(tagName)[0];
+    if (!target)
+        return undefined;
+    // 1. Try c:rich or a:p (standard rich text)
+    const richNodes = target.getElementsByTagName("c:rich");
+    const pNodes = target.getElementsByTagName("a:p");
+    const textContainers = richNodes.length > 0 ? Array.from(richNodes) : Array.from(pNodes);
+    if (textContainers.length > 0) {
+        let acc = "";
+        for (const container of textContainers) {
+            const tNodes = container.getElementsByTagName("a:t");
+            for (let i = 0; i < tNodes.length; i++) {
+                acc += (tNodes[i].textContent || "") + " ";
+            }
+        }
+        if (acc.trim())
+            return acc.trim();
+    }
+    // 2. Try c:v (cached values/strings)
+    const vNode = target.getElementsByTagName("c:v")[0];
+    if (vNode && vNode.textContent) {
+        return vNode.textContent.trim() || undefined;
+    }
+    return undefined;
+};
+/**
+ * Extracts fully structured chart data from OpenXML (PPTX, XLSX) chart XML.
+ * @param xmlBuffer Chart XML buffer
+ */
+const extractOpenXmlChartData = (xmlBuffer) => {
+    const xml = xmlBuffer.toString("utf8");
+    const dom = (0, xmlUtils_1.parseXmlString)(xml);
+    const root = dom.documentElement;
+    const title = extractOpenXmlRichText(root, "c:title");
+    // Axis titles
+    let xAxisTitle = undefined;
+    let yAxisTitle = undefined;
+    const catAxes = root.getElementsByTagName("c:catAx");
+    if (catAxes.length > 0)
+        xAxisTitle = extractOpenXmlRichText(catAxes[0], "c:title");
+    const valAxes = root.getElementsByTagName("c:valAx");
+    if (valAxes.length > 0)
+        yAxisTitle = extractOpenXmlRichText(valAxes[0], "c:title");
+    // Extract Series (dataSets)
+    const seriesNodes = root.getElementsByTagName("c:ser");
+    const dataSets = [];
+    const sharedLabels = [];
+    for (let i = 0; i < seriesNodes.length; i++) {
+        const ser = seriesNodes[i];
+        // DataSet Name (c:tx)
+        const name = extractOpenXmlRichText(ser, "c:tx");
+        // Values (c:val)
+        const values = [];
+        const valNode = ser.getElementsByTagName("c:val")[0] || ser.getElementsByTagName("c:yVal")[0];
+        if (valNode) {
+            const vNodes = valNode.getElementsByTagName("c:v");
+            for (let j = 0; j < vNodes.length; j++) {
+                const v = vNodes[j].textContent?.trim();
+                if (v)
+                    values.push(v);
+            }
+        }
+        // Point Labels (data labels)
+        const pointLabels = [];
+        const dLbls = ser.getElementsByTagName("c:dLbl");
+        for (let j = 0; j < dLbls.length; j++) {
+            const lbl = extractOpenXmlRichText(dLbls[j], "c:tx");
+            if (lbl)
+                pointLabels.push(lbl);
+        }
+        // Categories (labels) - c:cat or c:xVal
+        const catNode = ser.getElementsByTagName("c:cat")[0] || ser.getElementsByTagName("c:xVal")[0];
+        if (catNode) {
+            const vNodes = catNode.getElementsByTagName("c:v");
+            const localLabels = [];
+            for (let j = 0; j < vNodes.length; j++) {
+                const v = vNodes[j].textContent?.trim();
+                if (v)
+                    localLabels.push(v);
+            }
+            if (localLabels.length > 0 && sharedLabels.length === 0) {
+                sharedLabels.push(...localLabels);
+            }
+        }
+        dataSets.push({ name, values, pointLabels });
+    }
+    // Structured rawTexts: for each dataset: Name -> Labels -> Values
+    const rawTexts = [];
+    for (const ds of dataSets) {
+        if (ds.name)
+            rawTexts.push(ds.name);
+        rawTexts.push(...sharedLabels);
+        rawTexts.push(...ds.values);
+    }
+    return {
+        title,
+        xAxisTitle,
+        yAxisTitle,
+        dataSets,
+        labels: sharedLabels,
+        rawTexts
+    };
+};
+/**
+ * Extracts structured chart data from ODF (ODP, ODS) chart content.xml.
+ * @param xmlBuffer Chart XML buffer
+ */
+const extractOdfChartData = (xmlBuffer) => {
+    const xml = xmlBuffer.toString("utf8");
+    const dom = (0, xmlUtils_1.parseXmlString)(xml);
+    const chart = (0, xmlUtils_1.getElementsByTagName)(dom, "chart:chart")[0] || dom.documentElement;
+    const titleNode = (0, xmlUtils_1.getElementsByTagName)(chart, "chart:title")[0];
+    const title = titleNode ? (0, xmlUtils_1.getElementsByTagName)(titleNode, "text:p")[0]?.textContent || undefined : undefined;
+    const table = (0, xmlUtils_1.getElementsByTagName)(chart, "table:table")[0];
+    const dataSets = [];
+    const labels = [];
+    const rawTexts = [];
+    if (table) {
+        // Chart with embedded data table (common in ODP presentations)
+        let rows = [];
+        const headerRowsNode = (0, xmlUtils_1.getDirectChildren)(table, "table:table-header-rows")[0];
+        if (headerRowsNode) {
+            rows.push(...(0, xmlUtils_1.getDirectChildren)(headerRowsNode, "table:table-row"));
+        }
+        rows.push(...(0, xmlUtils_1.getDirectChildren)(table, "table:table-row"));
+        if (rows.length > 0) {
+            // Header row for series names
+            const headerCells = (0, xmlUtils_1.getDirectChildren)(rows[0], "table:table-cell");
+            for (let j = 1; j < headerCells.length; j++) {
+                const colsRepeated = parseInt(headerCells[j].getAttribute("table:number-columns-repeated") || "1");
+                const name = (0, xmlUtils_1.getDirectChildren)(headerCells[j], "text:p")[0]?.textContent || undefined;
+                for (let k = 0; k < colsRepeated; k++) {
+                    dataSets.push({ name, values: [], pointLabels: [] });
+                }
+            }
+            // Data rows
+            for (let i = 1; i < rows.length; i++) {
+                const dataCells = (0, xmlUtils_1.getDirectChildren)(rows[i], "table:table-cell");
+                if (dataCells.length > 0) {
+                    const label = (0, xmlUtils_1.getDirectChildren)(dataCells[0], "text:p")[0]?.textContent || undefined;
+                    if (label)
+                        labels.push(label);
+                    let dsIdx = 0;
+                    for (let j = 1; j < dataCells.length; j++) {
+                        const colsRepeated = parseInt(dataCells[j].getAttribute("table:number-columns-repeated") || "1");
+                        const val = dataCells[j].getAttribute("office:value") || (0, xmlUtils_1.getDirectChildren)(dataCells[j], "text:p")[0]?.textContent || "";
+                        for (let k = 0; k < colsRepeated; k++) {
+                            if (dataSets[dsIdx]) {
+                                dataSets[dsIdx].values.push(val);
+                            }
+                            dsIdx++;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    else {
+        // Chart with cell references (common in ODS spreadsheets)
+        // Extract series info from chart:series elements
+        const seriesNodes = (0, xmlUtils_1.getElementsByTagName)(chart, "chart:series");
+        for (const series of seriesNodes) {
+            // Series label is in chart:label-cell-address attribute
+            const labelAddr = series.getAttribute("chart:label-cell-address");
+            const valuesAddr = series.getAttribute("chart:values-cell-range-address");
+            // Try to get series name from any text:p in a title
+            let name = undefined;
+            const seriesLabels = (0, xmlUtils_1.getElementsByTagName)(series, "text:p");
+            if (seriesLabels.length > 0) {
+                name = seriesLabels[0].textContent || undefined;
+            }
+            // If no embedded name, use cell address as identifier
+            if (!name && labelAddr) {
+                // Extract just the cell reference part, e.g., "Sheet1.$D$2" -> "D2"
+                const cellRef = labelAddr.split('.').pop()?.replace(/\$/g, '') || labelAddr;
+                name = `Series ${cellRef}`;
+            }
+            // Values cell range can give us some info
+            const dataSet = {
+                name,
+                values: [],
+                pointLabels: []
+            };
+            // Add values address as a hint in rawTexts
+            if (valuesAddr) {
+                dataSet.values.push(`[${valuesAddr}]`);
+            }
+            dataSets.push(dataSet);
+        }
+        // Extract category labels from chart:categories
+        const categories = (0, xmlUtils_1.getElementsByTagName)(chart, "chart:categories")[0];
+        if (categories) {
+            const catRange = categories.getAttribute("table:cell-range-address");
+            if (catRange) {
+                labels.push(`[${catRange}]`);
+            }
+        }
+    }
+    // Axis titles
+    const axes = (0, xmlUtils_1.getElementsByTagName)(dom, "chart:axis");
+    let xAxisTitle = undefined;
+    let yAxisTitle = undefined;
+    for (const axis of axes) {
+        const dimension = axis.getAttribute("chart:dimension");
+        const axisTitleNode = (0, xmlUtils_1.getElementsByTagName)(axis, "chart:title")[0];
+        const axisTitle = axisTitleNode ? (0, xmlUtils_1.getElementsByTagName)(axisTitleNode, "text:p")[0]?.textContent || undefined : undefined;
+        if (dimension === 'x')
+            xAxisTitle = axisTitle;
+        else if (dimension === 'y')
+            yAxisTitle = axisTitle;
+    }
+    // Structured rawTexts: title + series info
+    if (title)
+        rawTexts.push(title);
+    for (const ds of dataSets) {
+        if (ds.name)
+            rawTexts.push(ds.name);
+        rawTexts.push(...labels);
+        rawTexts.push(...ds.values);
+    }
+    return {
+        title,
+        xAxisTitle,
+        yAxisTitle,
+        dataSets,
+        labels,
+        rawTexts
+    };
+};
+/**
+ * Universal chart data extractor that selects logic based on XML content.
+ * @param xmlBuffer Chart XML buffer
+ */
+const extractChartData = (xmlBuffer) => {
+    const head = xmlBuffer.toString("utf8", 0, 500);
+    if (head.includes("urn:oasis:names:tc:opendocument:xmlns:chart:1.0")) {
+        return extractOdfChartData(xmlBuffer);
+    }
+    else {
+        return extractOpenXmlChartData(xmlBuffer);
+    }
+};
+exports.extractChartData = extractChartData;

package/dist/utils/errorUtils.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Error Handling Utilities
+ *
+ * This module provides centralized error management for the OfficeParser library.
+ * It defines standard error types, messages, and handling logic to ensure
+ * consistent error reporting across all parsers and the main entry point.
+ */
+import { OfficeParserConfig } from '../types';
+/**
+ * Standard error types for OfficeParser.
+ * Use these to identify the kind of error being reported.
+ */
+export declare enum OfficeErrorType {
+    /** Unsupported file extension */
+    EXTENSION_UNSUPPORTED = "EXTENSION_UNSUPPORTED",
+    /** File appears to be corrupted or malformed */
+    FILE_CORRUPTED = "FILE_CORRUPTED",
+    /** File could not be found at the specified path */
+    FILE_DOES_NOT_EXIST = "FILE_DOES_NOT_EXIST",
+    /** Specified location/directory is not reachable or is a directory */
+    LOCATION_NOT_FOUND = "LOCATION_NOT_FOUND",
+    /** Arguments passed to the function are missing or invalid */
+    IMPROPER_ARGUMENTS = "IMPROPER_ARGUMENTS",
+    /** Error occurred while reading or processing file buffers */
+    IMPROPER_BUFFERS = "IMPROPER_BUFFERS",
+    /** Input type is not a supported type (string, Buffer, ArrayBuffer) */
+    INVALID_INPUT = "INVALID_INPUT",
+    /** PDF worker source is missing (required in browser) */
+    PDF_WORKER_MISSING = "PDF_WORKER_MISSING"
+}
+/**
+ * Creates, optionally logs to console, and returns a formatted OfficeParser error.
+ *
+ * @param type - The type of error
+ * @param config - Parser configuration (checks outputErrorToConsole)
+ * @param info - Optional additional information
+ * @returns The Error object to be thrown
+ */
+export declare const getOfficeError: (type: OfficeErrorType, config: OfficeParserConfig, info?: any) => Error;
+/**
+ * Wraps an existing error with OfficeParser context and performs corruption detection.
+ * Optionally logs the error to console.
+ *
+ * @param error - The original error object
+ * @param config - Parser configuration
+ * @param filePath - Optional file path for context
+ * @returns The wrapped Error object to be thrown
+ */
+export declare const getWrappedError: (error: any, config: OfficeParserConfig, filePath?: string) => Error;
+/**
+ * Conditionally logs a warning message to the console.
+ * Used for non-fatal errors that shouldn't stop the parsing process.
+ *
+ * @param message - The warning message
+ * @param config - Parser configuration
+ * @param error - Optional original error object for more context
+ */
+export declare const logWarning: (message: string, config: OfficeParserConfig, error?: any) => void;

package/dist/utils/errorUtils.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Error Handling Utilities
+ *
+ * This module provides centralized error management for the OfficeParser library.
+ * It defines standard error types, messages, and handling logic to ensure
+ * consistent error reporting across all parsers and the main entry point.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logWarning = exports.getWrappedError = exports.getOfficeError = exports.OfficeErrorType = void 0;
+/** Error header prefix for all error messages */
+const ERRORHEADER = "[OfficeParser]: ";
+/**
+ * Standard error types for OfficeParser.
+ * Use these to identify the kind of error being reported.
+ */
+var OfficeErrorType;
+(function (OfficeErrorType) {
+    /** Unsupported file extension */
+    OfficeErrorType["EXTENSION_UNSUPPORTED"] = "EXTENSION_UNSUPPORTED";
+    /** File appears to be corrupted or malformed */
+    OfficeErrorType["FILE_CORRUPTED"] = "FILE_CORRUPTED";
+    /** File could not be found at the specified path */
+    OfficeErrorType["FILE_DOES_NOT_EXIST"] = "FILE_DOES_NOT_EXIST";
+    /** Specified location/directory is not reachable or is a directory */
+    OfficeErrorType["LOCATION_NOT_FOUND"] = "LOCATION_NOT_FOUND";
+    /** Arguments passed to the function are missing or invalid */
+    OfficeErrorType["IMPROPER_ARGUMENTS"] = "IMPROPER_ARGUMENTS";
+    /** Error occurred while reading or processing file buffers */
+    OfficeErrorType["IMPROPER_BUFFERS"] = "IMPROPER_BUFFERS";
+    /** Input type is not a supported type (string, Buffer, ArrayBuffer) */
+    OfficeErrorType["INVALID_INPUT"] = "INVALID_INPUT";
+    /** PDF worker source is missing (required in browser) */
+    OfficeErrorType["PDF_WORKER_MISSING"] = "PDF_WORKER_MISSING";
+})(OfficeErrorType = exports.OfficeErrorType || (exports.OfficeErrorType = {}));
+/**
+ * Lookup table for error messages.
+ * Some entries are functions that take parameters to build dynamic messages.
+ */
+const ERROR_MESSAGES = {
+    [OfficeErrorType.EXTENSION_UNSUPPORTED]: (ext) => `Sorry, OfficeParser currently supports docx, pptx, xlsx, odt, odp, ods, pdf, rtf files only. Create a ticket in Issues on github to add support for ${ext} files. Stay tuned for further updates.`,
+    [OfficeErrorType.FILE_CORRUPTED]: (filepath) => `Your file ${filepath} seems to be corrupted. If you are sure it is fine, please create a ticket in Issues on github with the file to reproduce error.`,
+    [OfficeErrorType.FILE_DOES_NOT_EXIST]: (filepath) => `File ${filepath} could not be found! Check if the file exists or verify if the relative path to the file is correct from your terminal's location.`,
+    [OfficeErrorType.LOCATION_NOT_FOUND]: (location) => `Entered location ${location} is not reachable! Please make sure that the entered directory location exists. Check relative paths and reenter.`,
+    [OfficeErrorType.IMPROPER_ARGUMENTS]: `Improper arguments`,
+    [OfficeErrorType.IMPROPER_BUFFERS]: `Error occured while reading the file buffers`,
+    [OfficeErrorType.INVALID_INPUT]: `Invalid input type: Expected a Buffer or a valid file path`,
+    [OfficeErrorType.PDF_WORKER_MISSING]: `Missing PDF worker configuration. PDF parsing in browser environments requires a worker source. Please provide "pdfWorkerSrc" in your configuration.`
+};
+/**
+ * Creates a formatted error message for a specific error type.
+ *
+ * @param type - The type of error
+ * @param info - Optional additional information (e.g., filepath, extension)
+ * @returns The formatted error message string
+ */
+const createOfficeError = (type, info) => {
+    const msg = ERROR_MESSAGES[type];
+    const message = typeof msg === 'function' ? msg(info) : msg;
+    return message;
+};
+/**
+ * Creates, optionally logs to console, and returns a formatted OfficeParser error.
+ *
+ * @param type - The type of error
+ * @param config - Parser configuration (checks outputErrorToConsole)
+ * @param info - Optional additional information
+ * @returns The Error object to be thrown
+ */
+const getOfficeError = (type, config, info) => {
+    const message = createOfficeError(type, info);
+    if (config.outputErrorToConsole) {
+        console.error(ERRORHEADER + message);
+    }
+    return new Error(ERRORHEADER + message);
+};
+exports.getOfficeError = getOfficeError;
+/**
+ * Wraps an existing error with OfficeParser context and performs corruption detection.
+ * Optionally logs the error to console.
+ *
+ * @param error - The original error object
+ * @param config - Parser configuration
+ * @param filePath - Optional file path for context
+ * @returns The wrapped Error object to be thrown
+ */
+const getWrappedError = (error, config, filePath) => {
+    let message = error.message || error;
+    // Detect file corruption from common library error messages
+    if (filePath && (message.includes('end of central directory record') ||
+        message.includes('invalid XML') ||
+        message.includes('Failed to open zip file') ||
+        message.includes('invalid distance too far back'))) {
+        message = createOfficeError(OfficeErrorType.FILE_CORRUPTED, filePath);
+    }
+    if (config.outputErrorToConsole) {
+        console.error(ERRORHEADER + message);
+    }
+    return new Error(ERRORHEADER + message);
+};
+exports.getWrappedError = getWrappedError;
+/**
+ * Conditionally logs a warning message to the console.
+ * Used for non-fatal errors that shouldn't stop the parsing process.
+ *
+ * @param message - The warning message
+ * @param config - Parser configuration
+ * @param error - Optional original error object for more context
+ */
+const logWarning = (message, config, error) => {
+    if (config.outputErrorToConsole) {
+        if (error) {
+            console.warn(ERRORHEADER + message, error);
+        }
+        else {
+            console.warn(ERRORHEADER + message);
+        }
+    }
+};
+exports.logWarning = logWarning;

package/dist/utils/imageUtils.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Image Processing Utilities
+ *
+ * Provides helper functions for working with image attachments extracted from office documents.
+ * Handles MIME type conversions, file extension mapping, and attachment object creation.
+ *
+ * @module imageUtils
+ */
+/// <reference types="node" />
+import { OfficeAttachment } from '../types';
+/**
+ * Converts a file extension to its corresponding MIME type.
+ *
+ * Used when creating attachments to determine the MIME type from a filename.
+ * The extension check is case-insensitive.
+ *
+ * @param ext - The file extension (with or without a dot, e.g., 'png', '.png')
+ * @returns The corresponding MIME type string
+ * @example
+ * ```typescript
+ * getMimeFromExtension('png'); // Returns 'image/png'
+ * getMimeFromExtension('JPG'); // Returns 'image/jpeg' (case-insensitive)
+ * getMimeFromExtension('unknown'); // Returns 'application/octet-stream'
+ * ```
+ */
+export declare const getMimeFromExtension: (ext: string) => string;
+/**
+ * Detects the MIME type from file magic bytes (file signature).
+ *
+ * This is useful for files with incorrect or missing extensions (like .tmp files).
+ * Inspects the first few bytes of the file to determine the actual format.
+ *
+ * @param buffer - The file content as a Buffer
+ * @returns The detected MIME type, or undefined if not recognized
+ * @example
+ * ```typescript
+ * const pngBuffer = fs.readFileSync('image.tmp');
+ * getMimeFromBytes(pngBuffer); // Returns 'image/png' if it's a PNG file
+ * ```
+ */
+export declare const getMimeFromBytes: (buffer: Buffer) => string | undefined;
+/**
+ * Creates an OfficeAttachment object from image data.
+ *
+ * This is a convenience function that:
+ * 1. Extracts the file extension from the filename
+ * 2. Determines the MIME type from the extension
+ * 3. Encodes the image buffer as Base64
+ * 4. Constructs a properly formatted OfficeAttachment object
+ *
+ * @param name - The filename of the image (e.g., 'image1.png', 'chart.jpg')
+ * @param content - The image data as a Node.js Buffer
+ * @returns An OfficeAttachment object ready to be added to the attachments array
+ *
+ * @example
+ * ```typescript
+ * const imageBuffer = fs.readFileSync('photo.png');
+ * const attachment = createAttachment('photo.png', imageBuffer);
+ *
+ * console.log(attachment.type); // 'image'
+ * console.log(attachment.mimeType); // 'image/png'
+ * console.log(attachment.name); // 'photo.png'
+ * console.log(attachment.extension); // 'png'
+ * console.log(attachment.data); // 'iVBORw0KGgoAAAANSUhEUgAA...' (Base64)
+ * ```
+ */
+export declare const createAttachment: (name: string, content: Buffer) => OfficeAttachment;

package/dist/utils/imageUtils.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * Image Processing Utilities
+ *
+ * Provides helper functions for working with image attachments extracted from office documents.
+ * Handles MIME type conversions, file extension mapping, and attachment object creation.
+ *
+ * @module imageUtils
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAttachment = exports.getMimeFromBytes = exports.getMimeFromExtension = void 0;
+/**
+ * Converts a file extension to its corresponding MIME type.
+ *
+ * Used when creating attachments to determine the MIME type from a filename.
+ * The extension check is case-insensitive.
+ *
+ * @param ext - The file extension (with or without a dot, e.g., 'png', '.png')
+ * @returns The corresponding MIME type string
+ * @example
+ * ```typescript
+ * getMimeFromExtension('png'); // Returns 'image/png'
+ * getMimeFromExtension('JPG'); // Returns 'image/jpeg' (case-insensitive)
+ * getMimeFromExtension('unknown'); // Returns 'application/octet-stream'
+ * ```
+ */
+const getMimeFromExtension = (ext) => {
+    switch (ext.toLowerCase()) {
+        case 'jpg':
+        case 'jpeg': return 'image/jpeg';
+        case 'png': return 'image/png';
+        case 'gif': return 'image/gif';
+        case 'bmp': return 'image/bmp';
+        case 'tiff': return 'image/tiff';
+        case 'webp': return 'image/webp';
+        default: return 'application/octet-stream'; // Generic binary MIME type
+    }
+};
+exports.getMimeFromExtension = getMimeFromExtension;
+/**
+ * Detects the MIME type from file magic bytes (file signature).
+ *
+ * This is useful for files with incorrect or missing extensions (like .tmp files).
+ * Inspects the first few bytes of the file to determine the actual format.
+ *
+ * @param buffer - The file content as a Buffer
+ * @returns The detected MIME type, or undefined if not recognized
+ * @example
+ * ```typescript
+ * const pngBuffer = fs.readFileSync('image.tmp');
+ * getMimeFromBytes(pngBuffer); // Returns 'image/png' if it's a PNG file
+ * ```
+ */
+const getMimeFromBytes = (buffer) => {
+    if (buffer.length < 4)
+        return undefined;
+    // PNG: 89 50 4E 47 (0x89 "PNG")
+    if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4E && buffer[3] === 0x47) {
+        return 'image/png';
+    }
+    // JPEG: FF D8 FF
+    if (buffer[0] === 0xFF && buffer[1] === 0xD8 && buffer[2] === 0xFF) {
+        return 'image/jpeg';
+    }
+    // GIF: 47 49 46 38 ("GIF8")
+    if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38) {
+        return 'image/gif';
+    }
+    // BMP: 42 4D ("BM")
+    if (buffer[0] === 0x42 && buffer[1] === 0x4D) {
+        return 'image/bmp';
+    }
+    // TIFF: 49 49 2A 00 (little endian) or 4D 4D 00 2A (big endian)
+    if ((buffer[0] === 0x49 && buffer[1] === 0x49 && buffer[2] === 0x2A && buffer[3] === 0x00) ||
+        (buffer[0] === 0x4D && buffer[1] === 0x4D && buffer[2] === 0x00 && buffer[3] === 0x2A)) {
+        return 'image/tiff';
+    }
+    // WebP: 52 49 46 46 ... 57 45 42 50 ("RIFF" ... "WEBP")
+    if (buffer.length >= 12 &&
+        buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46 &&
+        buffer[8] === 0x57 && buffer[9] === 0x45 && buffer[10] === 0x42 && buffer[11] === 0x50) {
+        return 'image/webp';
+    }
+    return undefined;
+};
+exports.getMimeFromBytes = getMimeFromBytes;
+/**
+ * Creates an OfficeAttachment object from image data.
+ *
+ * This is a convenience function that:
+ * 1. Extracts the file extension from the filename
+ * 2. Determines the MIME type from the extension
+ * 3. Encodes the image buffer as Base64
+ * 4. Constructs a properly formatted OfficeAttachment object
+ *
+ * @param name - The filename of the image (e.g., 'image1.png', 'chart.jpg')
+ * @param content - The image data as a Node.js Buffer
+ * @returns An OfficeAttachment object ready to be added to the attachments array
+ *
+ * @example
+ * ```typescript
+ * const imageBuffer = fs.readFileSync('photo.png');
+ * const attachment = createAttachment('photo.png', imageBuffer);
+ *
+ * console.log(attachment.type); // 'image'
+ * console.log(attachment.mimeType); // 'image/png'
+ * console.log(attachment.name); // 'photo.png'
+ * console.log(attachment.extension); // 'png'
+ * console.log(attachment.data); // 'iVBORw0KGgoAAAANSUhEUgAA...' (Base64)
+ * ```
+ */
+const createAttachment = (name, content) => {
+    // Step 1: Extract file extension from the filename
+    // Example: 'image1.png' -> 'png'
+    const ext = name.split('.').pop() || '';
+    // Step 2: Try to detect MIME type from magic bytes first (more reliable)
+    // This handles cases like .tmp files or mismatched extensions
+    let mime = (0, exports.getMimeFromBytes)(content);
+    // Step 3: Fallback to extension if magic bytes couldn't detect it
+    // Useful for SVG or formats not covered by getMimeFromBytes
+    if (!mime) {
+        mime = (0, exports.getMimeFromExtension)(ext);
+    }
+    // Step 4: Create and return the attachment object
+    return {
+        type: 'image',
+        mimeType: mime,
+        data: content.toString('base64'),
+        name: name,
+        extension: ext // File extension for reference
+    };
+};
+exports.createAttachment = createAttachment;

package/dist/utils/ocrUtils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * OCR (Optical Character Recognition) Utilities
+ *
+ * This module provides functions for extracting text from images using Tesseract.js.
+ * Used when `config.ocr` is enabled to extract text from embedded images in documents.
+ *
+ * @module ocrUtils
+ */
+/// <reference types="node" />
+/**
+ * Performs Optical Character Recognition (OCR) on an image to extract text.
+ *
+ * Uses Tesseract.js to recognize text in the provided image buffer.
+ * This is useful for extracting text from screenshots, scanned documents,
+ * charts with labels, or any image containing text.
+ *
+ * The function creates a new Tesseract worker, processes the image,
+ * and properly terminates the worker to free resources.
+ *
+ * @param imageBuffer - The image data as a Node.js Buffer (PNG, JPEG, etc.)
+ * @param language - The language code for OCR (default: 'eng' for English).
+ *                   Supports ISO 639-2/T three-letter codes: 'eng', 'spa', 'fra', 'deu', etc.
+ *                   Multiple languages can be combined with '+': 'eng+fra'
+ * @returns A promise that resolves to the recognized text as a string
+ * @throws {Error} If the image cannot be processed or Tesseract initialization fails
+ *
+ * @example
+ * ```typescript
+ * // Extract text from an English image
+ * const text = await performOcr(imageBuffer, 'eng');
+ * console.log(text); // "Annual Revenue: $1.2M"
+ *
+ * // Extract text from a multilingual image
+ * const text = await performOcr(imageBuffer, 'eng+spa');
+ * ```
+ *
+ * @see https://github.com/naptha/tesseract.js for supported languages and options
+ */
+export declare const performOcr: (image: Buffer | string, language?: string) => Promise<string>;