mindee 4.33.1 → 4.35.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # CHANGELOG
 
+## v4.35.0 - 2025-12-16
+### Changes
+* :sparkles: add multi-receipt custom file saving formats
+### Fixes
+* :bug: fix image extractor dropping quality of extracted PDFs
+
+
+## v4.34.0 - 2025-12-02
+### Changes
+* :sparkles: add support for text context
+
+
 ## v4.33.1 - 2025-10-28
 ### Changes
 * :loud_sound: add error code to v2 exceptions

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mindee",
-    "version": "4.33.1",
+    "version": "4.35.0",
     "description": "Mindee Client Library for Node.js",
     "main": "src/index.js",
     "bin": "bin/mindee.js",
@@ -24,7 +24,7 @@
         "CHANGELOG.md"
     ],
     "engines": {
-        "node": ">= 16"
+        "node": ">= 18"
     },
     "repository": {
         "type": "git",

package/src/clientV2.d.ts

@@ -17,12 +17,6 @@ import { MindeeApiV2 } from "./http/mindeeApiV2";
  * The `initialTimerOptions` and `recurringTimerOptions` objects let you pass an
  * `AbortSignal` or make the timer `unref`-ed to the `setTimeout()`.
  *
- * @property initialDelaySec Number of seconds to wait **before the first poll**.
- * @property delaySec Interval in seconds between two consecutive polls.
- * @property maxRetries Maximum number of polling attempts (including the first one).
- * @property initialTimerOptions Options passed to the initial `setTimeout()`.
- * @property recurringTimerOptions Options passed to every recurring `setTimeout()`.
- *
  * @category ClientV2
  * @example
  * const params = {
@@ -34,13 +28,18 @@ import { MindeeApiV2 } from "./http/mindeeApiV2";
  * const inference = await client.enqueueAndGetInference(inputDoc, params);
  */
 export interface PollingOptions {
+    /** Number of seconds to wait *before the first poll*. */
     initialDelaySec?: number;
+    /** Interval in seconds between two consecutive polls. */
     delaySec?: number;
+    /** Maximum number of polling attempts (including the first one). */
     maxRetries?: number;
+    /** Options passed to the initial `setTimeout()`. */
     initialTimerOptions?: {
         ref?: boolean;
         signal?: AbortSignal;
     };
+    /** Options passed to every recurring `setTimeout()`. */
     recurringTimerOptions?: {
         ref?: boolean;
         signal?: AbortSignal;
@@ -51,16 +50,6 @@ export interface PollingOptions {
  *
  * All fields are optional except `modelId`.
  *
- * @property modelId Identifier of the model that must process the document. **Required**.
- * @property rag Enhance extraction accuracy with Retrieval-Augmented Generation.
- * @property rawText Extract the full text content from the document as strings, and fill the `raw_text` attribute.
- * @property polygon Calculate bounding box polygons for all fields, and fill their `locations` attribute.
- * @property confidence Boost the precision and accuracy of all extractions.
- *     Calculate confidence scores for all fields and fill their `confidence` attribute.
- * @property alias Custom alias assigned to the uploaded document.
- * @property webhookIds List of webhook UUIDs that will receive the final API response.
- * @property pollingOptions Client-side polling configuration (see {@link PollingOptions}).
- * @property closeFile By default the file is closed once the upload is finished, set to `false` to keep it open.
  * @category ClientV2
  * @example
  * const params = {
@@ -75,23 +64,34 @@ export interface PollingOptions {
  * };
  */
 export interface InferenceParameters {
+    /** Model ID to use for the inference. **Required** */
     modelId: string;
+    /** Use Retrieval-Augmented Generation during inference. */
     rag?: boolean;
+    /** Extract the entire text from the document as strings, and fill the `rawText` attribute. */
     rawText?: boolean;
+    /** Calculate bounding box polygons for values, and fill the `locations` attribute of fields. */
     polygon?: boolean;
+    /** Calculate confidence scores for values, and fill the `confidence` attribute of fields.
+     * Useful for automation.*/
     confidence?: boolean;
+    /** Use an alias to link the file to your own DB. If empty, no alias will be used. */
     alias?: string;
+    /** Additional text context used by the model during inference.
+     * *Not recommended*, for specific use only. */
+    textContext?: string;
+    /** Webhook IDs to call after all processing is finished.
+     * If empty, no webhooks will be used. */
     webhookIds?: string[];
+    /** Client-side polling configuration (see {@link PollingOptions}). */
     pollingOptions?: PollingOptions;
+    /** By default, the file is closed once the upload is finished.
+     * Set to `false` to keep it open. */
     closeFile?: boolean;
 }
 /**
  * Options for the V2 Mindee Client.
  *
- * @property apiKey Your API key for all endpoints.
- * @property throwOnError Raise an `Error` on errors.
- * @property debug Log debug messages.
- *
  * @category ClientV2
  * @example
  * const client = new MindeeClientV2({
@@ -101,8 +101,11 @@ export interface InferenceParameters {
  * });
  */
 export interface ClientOptions {
+    /** Your API key for all endpoints. */
     apiKey?: string;
+    /** Raise an `Error` on errors. */
     throwOnError?: boolean;
+    /** Log debug messages. */
     debug?: boolean;
 }
 /**

package/src/http/mindeeApiV2.js

@@ -99,6 +99,9 @@ _MindeeApiV2_instances = new WeakSet(), _MindeeApiV2_processResponse = function
     if (params.rawText !== undefined && params.rawText !== null) {
         form.append("raw_text", params.rawText.toString().toLowerCase());
     }
+    if (params.textContext !== undefined && params.textContext !== null) {
+        form.append("text_context", params.textContext);
+    }
     if (params.webhookIds && params.webhookIds.length > 0) {
         form.append("webhook_ids", params.webhookIds.join(","));
     }

package/src/imageOperations/common/extractedImage.d.ts

@@ -12,6 +12,13 @@ export declare class ExtractedImage {
      *
      * @param outputPath Path to save the file to.
      */
+    saveToFileAsync(outputPath: string): Promise<void>;
+    /**
+     * Attempts to saves the document to a file synchronously.
+     * Throws an error if the file extension is not supported or if the file could not be saved to disk for some reason.
+     *
+     * @param outputPath Path to save the file to.
+     */
     saveToFile(outputPath: string): void;
     /**
      * Return the file as a Mindee-compatible BufferInput source.

package/src/imageOperations/common/extractedImage.js

@@ -10,6 +10,9 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 const logger_1 = require("../../logger");
 const input_1 = require("../../input");
+const localInputSource_1 = require("../../input/sources/localInputSource");
+const node_poppler_1 = require("node-poppler");
+const promises_1 = require("fs/promises");
 /**
  * Generic class for image extraction
  */
@@ -23,9 +26,33 @@ class ExtractedImage {
      *
      * @param outputPath Path to save the file to.
      */
-    saveToFile(outputPath) {
+    async saveToFileAsync(outputPath) {
+        const fileExt = node_path_1.default.extname(outputPath).toLowerCase();
+        if (!localInputSource_1.MIMETYPES.has(fileExt)) {
+            throw new errors_1.MindeeError(`Unsupported file extension: ${fileExt}`);
+        }
         try {
-            (0, node_fs_1.writeFileSync)(node_path_1.default.resolve(outputPath), this.buffer);
+            let outputBuffer = this.buffer;
+            if (fileExt !== ".pdf") {
+                const poppler = new node_poppler_1.Poppler();
+                const options = {
+                    firstPageToConvert: 1,
+                    lastPageToConvert: 1,
+                    singleFile: true,
+                };
+                if (fileExt === ".png") {
+                    options.pngFile = true;
+                }
+                else if (fileExt === ".jpg" || fileExt === ".jpeg") {
+                    options.jpegFile = true;
+                }
+                else if (fileExt === ".tiff" || fileExt === ".tif") {
+                    options.tiffFile = true;
+                }
+                const result = await poppler.pdfToCairo(this.buffer, undefined, options);
+                outputBuffer = node_buffer_1.Buffer.from(result, "latin1");
+            }
+            await (0, promises_1.writeFile)(node_path_1.default.resolve(outputPath), outputBuffer);
             logger_1.logger.info(`File saved successfully to ${node_path_1.default.resolve(outputPath)}.`);
         }
         catch (e) {
@@ -37,6 +64,32 @@ class ExtractedImage {
             }
         }
     }
+    /**
+     * Attempts to saves the document to a file synchronously.
+     * Throws an error if the file extension is not supported or if the file could not be saved to disk for some reason.
+     *
+     * @param outputPath Path to save the file to.
+     */
+    saveToFile(outputPath) {
+        const fileExt = node_path_1.default.extname(outputPath).toLowerCase();
+        if (fileExt !== ".pdf") {
+            throw new errors_1.MindeeError(`Unsupported file extension: ${fileExt}. For image formats, use saveToFileAsync() instead.`);
+        }
+        else {
+            try {
+                (0, node_fs_1.writeFileSync)(node_path_1.default.resolve(outputPath), this.buffer);
+                logger_1.logger.info(`File saved successfully to ${node_path_1.default.resolve(outputPath)}.`);
+            }
+            catch (e) {
+                if (e instanceof TypeError) {
+                    throw new errors_1.MindeeError("Invalid path/filename provided.");
+                }
+                else {
+                    throw e;
+                }
+            }
+        }
+    }
     /**
      * Return the file as a Mindee-compatible BufferInput source.
      *

package/src/imageOperations/common/imageExtractor.js

@@ -12,6 +12,9 @@ const geometry_1 = require("../../geometry");
 async function extractFromPage(pdfPage, polygons) {
     const { width, height } = pdfPage.getSize();
     const extractedElements = [];
+    // Manual upscale.
+    // Fixes issues with the OCR.
+    const qualityScale = 300 / 72;
     for (const polygon of polygons) {
         const tempPdf = await pdf_lib_1.PDFDocument.create();
         const newWidth = width * ((0, geometry_1.getMinMaxX)(polygon).max - (0, geometry_1.getMinMaxX)(polygon).min);
@@ -22,10 +25,16 @@ async function extractFromPage(pdfPage, polygons) {
             top: height - ((0, geometry_1.getMinMaxY)(polygon).min * height),
             bottom: height - ((0, geometry_1.getMinMaxY)(polygon).max * height),
         });
-        const samplePage = tempPdf.addPage([newWidth, newHeight]);
+        const samplePage = tempPdf.addPage([newWidth * qualityScale, newHeight * qualityScale]);
+        samplePage.drawRectangle({
+            x: 0,
+            y: 0,
+            width: newWidth * qualityScale,
+            height: newHeight * qualityScale,
+        });
         samplePage.drawPage(cropped, {
-            width: newWidth,
-            height: newHeight,
+            width: newWidth * qualityScale,
+            height: newHeight * qualityScale,
         });
         extractedElements.push(await tempPdf.save());
     }

package/src/input/sources/localInputSource.d.ts

@@ -1,5 +1,6 @@
 import { PageOptions } from "../pageOptions";
 import { InputSource, InputConstructor } from "./inputSource";
+export declare const MIMETYPES: Map<string, string>;
 export declare abstract class LocalInputSource extends InputSource {
     inputType: string;
     filename: string;

package/src/input/sources/localInputSource.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocalInputSource = void 0;
+exports.LocalInputSource = exports.MIMETYPES = void 0;
 const handler_1 = require("../../errors/handler");
 const logger_1 = require("../../logger");
 const imageOperations_1 = require("../../imageOperations");
@@ -45,7 +45,7 @@ const path_1 = __importDefault(require("path"));
 const fileType = __importStar(require("file-type"));
 const pdf_2 = require("../../pdf");
 const inputSource_1 = require("./inputSource");
-const MIMETYPES = new Map([
+exports.MIMETYPES = new Map([
     [".pdf", "application/pdf"],
     [".heic", "image/heic"],
     [".jpg", "image/jpeg"],
@@ -85,7 +85,7 @@ class LocalInputSource extends inputSource_1.InputSource {
         let mimeType;
         const fileExt = path_1.default.extname(this.filename);
         if (fileExt) {
-            mimeType = MIMETYPES.get(fileExt.toLowerCase()) || "";
+            mimeType = exports.MIMETYPES.get(fileExt.toLowerCase()) || "";
         }
         else {
             const guess = await fileType.fromBuffer(this.fileObject);
@@ -97,7 +97,7 @@ class LocalInputSource extends inputSource_1.InputSource {
             }
         }
         if (!mimeType) {
-            const allowed = Array.from(MIMETYPES.keys()).join(", ");
+            const allowed = Array.from(exports.MIMETYPES.keys()).join(", ");
             const err = new Error(`Invalid file type, must be one of ${allowed}.`);
             handler_1.errorHandler.throw(err);
         }

package/src/parsing/v2/errorItem.d.ts

@@ -1,7 +1,10 @@
 import { StringDict } from "../common";
+/**
+ * Explicit details on a problem.
+ */
 export declare class ErrorItem {
     /**
-     * The HTTP status code returned by the server.
+     * A JSON Pointer to the location of the body property.
      */
     pointer?: string;
     /**

package/src/parsing/v2/errorItem.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorItem = void 0;
+/**
+ * Explicit details on a problem.
+ */
 class ErrorItem {
     /**
      * @param serverResponse JSON response from the server.

package/src/parsing/v2/errorResponse.d.ts

@@ -18,7 +18,7 @@ export interface ErrorDetails {
      */
     code: string;
     /**
-     * A machine-readable code specific to the occurrence of the problem.
+     * A list of explicit error details.
      */
     errors: ErrorItem[];
 }

package/src/parsing/v2/inferenceActiveOptions.d.ts

@@ -16,6 +16,10 @@ export declare class InferenceActiveOptions {
      * Whether the confidence feature was activated.
      */
     confidence: boolean;
+    /**
+     * Whether the text context feature was activated.
+     */
+    textContext: boolean;
     constructor(serverResponse: StringDict);
     toString(): string;
 }

package/src/parsing/v2/inferenceActiveOptions.js

@@ -7,6 +7,7 @@ class InferenceActiveOptions {
         this.rawText = serverResponse["raw_text"];
         this.polygon = serverResponse["polygon"];
         this.confidence = serverResponse["confidence"];
+        this.textContext = serverResponse["text_context"];
     }
     toString() {
         return "Active Options\n" +