mindee 4.4.0 → 4.6.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # CHANGELOG
 
+## v4.6.0 - 2023-12-11
+### Changes
+* :sparkles: add invoice-splitter auto-splitting feature
+* :memo: add examples to illustrate auto-splitting feature
+* :recycle: add unit tests for auto-splitting feature
+* :recycle: rename `exemple` folder to `example`
+* :arrow_up: update testing library
+
+
+## v4.5.0 - 2023-11-29
+### Changes
+* :sparkles: add Multi-Receipts auto-extraction feature
+* :art: add example file to illustrate multi-receipt image extraction feature
+* :recycle: add new imageOperations namespace
+* :recycle: fix loose typing issues for inputsources
+
+
 ## v4.4.0 - 2023-11-17
 ### Changes
 * :sparkles: add support for Carte Grise V1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mindee",
-    "version": "4.4.0",
+    "version": "4.6.0",
     "description": "Mindee Client Library for Node.js",
     "main": "src/index.js",
     "bin": "bin/mindee.js",

package/src/client.d.ts

@@ -2,7 +2,7 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import { Readable } from "stream";
-import { InputSource, PageOptions } from "./input";
+import { Base64Input, BytesInput, InputSource, PathInput, StreamInput, PageOptions, UrlInput, BufferInput } from "./input";
 import { Endpoint } from "./http";
 import { AsyncPredictResponse, FeedbackResponse, Inference, PredictResponse, StringDict } from "./parsing/common";
 /**
@@ -160,34 +160,34 @@ export declare class Client {
      * Load an input document from a local path.
      * @param inputPath
      */
-    docFromPath(inputPath: string): InputSource;
+    docFromPath(inputPath: string): PathInput;
     /**
      * Load an input document from a base64 encoded string.
      * @param inputString input content, as a string.
      * @param filename file name.
      */
-    docFromBase64(inputString: string, filename: string): InputSource;
+    docFromBase64(inputString: string, filename: string): Base64Input;
     /**
      * Load an input document from a `stream.Readable` object.
      * @param inputStream input content, as a readable stream.
      * @param filename file name.
      */
-    docFromStream(inputStream: Readable, filename: string): InputSource;
+    docFromStream(inputStream: Readable, filename: string): StreamInput;
     /**
      * Load an input document from a bytes string.
      * @param inputBytes input content, as readable bytes.
      * @param filename file name.
      */
-    docFromBytes(inputBytes: string, filename: string): InputSource;
+    docFromBytes(inputBytes: string, filename: string): BytesInput;
     /**
      * Load an input document from a URL.
      * @param url input url. Must be HTTPS.
      */
-    docFromUrl(url: string): InputSource;
+    docFromUrl(url: string): UrlInput;
     /**
      * Load an input document from a Buffer.
      * @param buffer input content, as a buffer.
      * @param filename file name.
      */
-    docFromBuffer(buffer: Buffer, filename: string): InputSource;
+    docFromBuffer(buffer: Buffer, filename: string): BufferInput;
 }

package/src/errors/MindeeError.d.ts

@@ -1,3 +1,6 @@
 export declare class MindeeError extends Error {
     constructor(message: string);
 }
+export declare class MindeeMimeTypeError extends MindeeError {
+    constructor(message: string);
+}

package/src/errors/MindeeError.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MindeeError = void 0;
+exports.MindeeMimeTypeError = exports.MindeeError = void 0;
 class MindeeError extends Error {
     constructor(message) {
         super(message);
@@ -8,3 +8,10 @@ class MindeeError extends Error {
     }
 }
 exports.MindeeError = MindeeError;
+class MindeeMimeTypeError extends MindeeError {
+    constructor(message) {
+        super(message);
+        this.name = "MindeeMimeTypeError";
+    }
+}
+exports.MindeeMimeTypeError = MindeeMimeTypeError;

package/src/errors/index.d.ts

@@ -1 +1 @@
-export { MindeeError } from "./MindeeError";
+export { MindeeError, MindeeMimeTypeError } from "./MindeeError";

package/src/errors/index.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MindeeError = void 0;
+exports.MindeeMimeTypeError = exports.MindeeError = void 0;
 var MindeeError_1 = require("./MindeeError");
 Object.defineProperty(exports, "MindeeError", { enumerable: true, get: function () { return MindeeError_1.MindeeError; } });
+Object.defineProperty(exports, "MindeeMimeTypeError", { enumerable: true, get: function () { return MindeeError_1.MindeeMimeTypeError; } });

package/src/imageOperations/extractedImage.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+import { Buffer } from "node:buffer";
+import { BufferInput } from "../input";
+export declare abstract class ExtractedImage {
+    buffer: Buffer;
+    protected internalFileName: string;
+    constructor(buffer: Uint8Array, fileName: string);
+    /**
+     * Saves the document to a file.
+     *
+     * @param outputPath Path to save the file to.
+     */
+    saveToFile(outputPath: string): void;
+    /**
+     * Return the file as a Mindee-compatible BufferInput source.
+     *
+     * @returns A BufferInput source.
+     */
+    asSource(): BufferInput;
+}

package/src/imageOperations/extractedImage.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtractedImage = void 0;
+const node_buffer_1 = require("node:buffer");
+const errors_1 = require("../errors");
+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");
+class ExtractedImage {
+    constructor(buffer, fileName) {
+        this.buffer = node_buffer_1.Buffer.from(buffer);
+        this.internalFileName = fileName;
+    }
+    /**
+     * Saves the document to a file.
+     *
+     * @param outputPath Path to save the file to.
+     */
+    saveToFile(outputPath) {
+        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.
+     *
+     * @returns A BufferInput source.
+     */
+    asSource() {
+        return new input_1.BufferInput({
+            buffer: this.buffer,
+            filename: this.internalFileName,
+        });
+    }
+}
+exports.ExtractedImage = ExtractedImage;

package/src/imageOperations/extractedInvoiceSplitterDocument.d.ts

@@ -0,0 +1,6 @@
+import { ExtractedImage } from "./extractedImage";
+export declare class ExtractedInvoiceSplitterImage extends ExtractedImage {
+    readonly pageIdMin: number;
+    readonly pageIdMax: number;
+    constructor(buffer: Uint8Array, pageIndices: [number, number]);
+}

package/src/imageOperations/extractedInvoiceSplitterDocument.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtractedInvoiceSplitterImage = void 0;
+const extractedImage_1 = require("./extractedImage");
+class ExtractedInvoiceSplitterImage extends extractedImage_1.ExtractedImage {
+    constructor(buffer, pageIndices) {
+        super(buffer, `invoice_p_${pageIndices[0]}-${pageIndices[1]}.pdf`);
+        this.pageIdMin = pageIndices[0];
+        this.pageIdMax = pageIndices[1];
+    }
+}
+exports.ExtractedInvoiceSplitterImage = ExtractedInvoiceSplitterImage;

package/src/imageOperations/extractedMultiReceiptImage.d.ts

@@ -0,0 +1,6 @@
+import { ExtractedImage } from "./extractedImage";
+export declare class ExtractedMultiReceiptImage extends ExtractedImage {
+    readonly receiptId: number;
+    readonly pageId: number;
+    constructor(buffer: Uint8Array, pageId: number, receiptId: number);
+}

package/src/imageOperations/extractedMultiReceiptImage.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtractedMultiReceiptImage = void 0;
+const extractedImage_1 = require("./extractedImage");
+class ExtractedMultiReceiptImage extends extractedImage_1.ExtractedImage {
+    constructor(buffer, pageId, receiptId) {
+        super(buffer, `receipt_p${pageId}_${receiptId}.pdf`);
+        this.pageId = pageId;
+        this.receiptId = receiptId;
+    }
+}
+exports.ExtractedMultiReceiptImage = ExtractedMultiReceiptImage;

package/src/imageOperations/index.d.ts

@@ -0,0 +1,4 @@
+export { extractReceipts } from "./multiReceiptsExtractor";
+export { extractInvoices } from "./invoiceSplitterExtractor";
+export { ExtractedMultiReceiptImage } from "./extractedMultiReceiptImage";
+export { ExtractedInvoiceSplitterImage } from "./extractedInvoiceSplitterDocument";

package/src/imageOperations/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtractedInvoiceSplitterImage = exports.ExtractedMultiReceiptImage = exports.extractInvoices = exports.extractReceipts = void 0;
+var multiReceiptsExtractor_1 = require("./multiReceiptsExtractor");
+Object.defineProperty(exports, "extractReceipts", { enumerable: true, get: function () { return multiReceiptsExtractor_1.extractReceipts; } });
+var invoiceSplitterExtractor_1 = require("./invoiceSplitterExtractor");
+Object.defineProperty(exports, "extractInvoices", { enumerable: true, get: function () { return invoiceSplitterExtractor_1.extractInvoices; } });
+var extractedMultiReceiptImage_1 = require("./extractedMultiReceiptImage");
+Object.defineProperty(exports, "ExtractedMultiReceiptImage", { enumerable: true, get: function () { return extractedMultiReceiptImage_1.ExtractedMultiReceiptImage; } });
+var extractedInvoiceSplitterDocument_1 = require("./extractedInvoiceSplitterDocument");
+Object.defineProperty(exports, "ExtractedInvoiceSplitterImage", { enumerable: true, get: function () { return extractedInvoiceSplitterDocument_1.ExtractedInvoiceSplitterImage; } });

package/src/imageOperations/internal.d.ts

@@ -0,0 +1,5 @@
+export { extractReceipts } from "./multiReceiptsExtractor";
+export { extractInvoices } from "./invoiceSplitterExtractor";
+export { ExtractedMultiReceiptImage } from "./extractedMultiReceiptImage";
+export { ExtractedInvoiceSplitterImage } from "./extractedInvoiceSplitterDocument";
+export { ExtractedImage } from "./extractedImage";

package/src/imageOperations/internal.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtractedImage = exports.ExtractedInvoiceSplitterImage = exports.ExtractedMultiReceiptImage = exports.extractInvoices = exports.extractReceipts = void 0;
+var multiReceiptsExtractor_1 = require("./multiReceiptsExtractor");
+Object.defineProperty(exports, "extractReceipts", { enumerable: true, get: function () { return multiReceiptsExtractor_1.extractReceipts; } });
+var invoiceSplitterExtractor_1 = require("./invoiceSplitterExtractor");
+Object.defineProperty(exports, "extractInvoices", { enumerable: true, get: function () { return invoiceSplitterExtractor_1.extractInvoices; } });
+var extractedMultiReceiptImage_1 = require("./extractedMultiReceiptImage");
+Object.defineProperty(exports, "ExtractedMultiReceiptImage", { enumerable: true, get: function () { return extractedMultiReceiptImage_1.ExtractedMultiReceiptImage; } });
+var extractedInvoiceSplitterDocument_1 = require("./extractedInvoiceSplitterDocument");
+Object.defineProperty(exports, "ExtractedInvoiceSplitterImage", { enumerable: true, get: function () { return extractedInvoiceSplitterDocument_1.ExtractedInvoiceSplitterImage; } });
+var extractedImage_1 = require("./extractedImage");
+Object.defineProperty(exports, "ExtractedImage", { enumerable: true, get: function () { return extractedImage_1.ExtractedImage; } });

package/src/imageOperations/invoiceSplitterExtractor.d.ts

@@ -0,0 +1,12 @@
+import { InvoiceSplitterV1 } from "../product";
+import { LocalInputSource } from "../input/base";
+import { ExtractedInvoiceSplitterImage } from "./extractedInvoiceSplitterDocument";
+/**
+ * Extracts & cuts the pages of a main document invoice according to the provided indexes.
+ *
+ * @param inputFile File to extract sub-invoices from.
+ * @param indexes List of indexes to cut the document according to. Can be provided either as a InvoiceSplitterV1 inference, or a direct list of splits.
+ * @param strict If set to true, doesn't cut pages where the API isn't 100% confident.
+ * @returns A promise of extracted images, as an array of ExtractedInvoiceSplitterImage.
+ */
+export declare function extractInvoices(inputFile: LocalInputSource, indexes: InvoiceSplitterV1 | number[][], strict?: boolean): Promise<ExtractedInvoiceSplitterImage[]>;

package/src/imageOperations/invoiceSplitterExtractor.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractInvoices = void 0;
+const pdf_lib_1 = require("pdf-lib");
+const errors_1 = require("../errors");
+const product_1 = require("../product");
+const extractedInvoiceSplitterDocument_1 = require("./extractedInvoiceSplitterDocument");
+async function splitPdf(pdfDoc, invoicePageGroups) {
+    if (invoicePageGroups.length === 0) {
+        return [];
+    }
+    const generatedPdfs = [];
+    for (let i = 0; i < invoicePageGroups.length; i++) {
+        const subdocument = await pdf_lib_1.PDFDocument.create();
+        const fullIndexes = [];
+        for (let j = invoicePageGroups[i][0]; j <= invoicePageGroups[i][invoicePageGroups[i].length - 1]; j++) {
+            fullIndexes.push(j);
+        }
+        const copiedPages = await subdocument.copyPages(pdfDoc, fullIndexes);
+        copiedPages.map((page) => {
+            subdocument.addPage(page);
+        });
+        const subdocumentBytes = await subdocument.save();
+        generatedPdfs.push(new extractedInvoiceSplitterDocument_1.ExtractedInvoiceSplitterImage(subdocumentBytes, [invoicePageGroups[i][0], invoicePageGroups[i][invoicePageGroups[i].length - 1]]));
+    }
+    return generatedPdfs;
+}
+async function getPdfDoc(inputFile) {
+    await inputFile.init();
+    if (!inputFile.isPdf()) {
+        throw new errors_1.MindeeMimeTypeError("Invoice Splitter is only compatible with pdf documents.");
+    }
+    const pdfDoc = await pdf_lib_1.PDFDocument.load(inputFile.fileObject);
+    if (pdfDoc.getPageCount() < 2) {
+        throw new errors_1.MindeeError("Invoice Splitter is only compatible with multi-page-pdf documents.");
+    }
+    return pdfDoc;
+}
+/**
+ * Extracts & cuts the pages of a main document invoice according to the provided indexes.
+ *
+ * @param inputFile File to extract sub-invoices from.
+ * @param indexes List of indexes to cut the document according to. Can be provided either as a InvoiceSplitterV1 inference, or a direct list of splits.
+ * @param strict If set to true, doesn't cut pages where the API isn't 100% confident.
+ * @returns A promise of extracted images, as an array of ExtractedInvoiceSplitterImage.
+ */
+async function extractInvoices(inputFile, indexes, strict = false) {
+    if (!indexes) {
+        throw new errors_1.MindeeError("No possible receipts candidates found for MultiReceipts extraction.");
+    }
+    let customIndexes = [];
+    if (indexes instanceof product_1.InvoiceSplitterV1) {
+        indexes.prediction.invoicePageGroups.map((invoicePageGroup) => {
+            if (!strict || invoicePageGroup.confidence === 1) {
+                customIndexes.push(invoicePageGroup.pageIndexes);
+            }
+        });
+    }
+    else {
+        customIndexes = indexes;
+    }
+    const pdfDoc = await getPdfDoc(inputFile);
+    const pageCount = pdfDoc.getPageCount();
+    customIndexes.forEach((pageGroup) => {
+        pageGroup.forEach((index) => {
+            if (index >= pageCount) {
+                throw new errors_1.MindeeError(`Given index ${index} doesn't exist in page range (0-${pageCount - 1})`);
+            }
+        });
+    });
+    return await splitPdf(pdfDoc, customIndexes);
+}
+exports.extractInvoices = extractInvoices;

package/src/imageOperations/multiReceiptsExtractor.d.ts

@@ -0,0 +1,11 @@
+import { MultiReceiptsDetectorV1 } from "../product";
+import { ExtractedMultiReceiptImage } from "./extractedMultiReceiptImage";
+import { LocalInputSource } from "../input/base";
+/**
+ * Extracts individual receipts from multi-receipts documents.
+ *
+ * @param inputFile File to extract sub-receipts from.
+ * @param inference Results of the inference.
+ * @returns Individual extracted receipts as an array of ExtractedMultiReceiptsImage.
+ */
+export declare function extractReceipts(inputFile: LocalInputSource, inference: MultiReceiptsDetectorV1): Promise<ExtractedMultiReceiptImage[]>;

package/src/imageOperations/multiReceiptsExtractor.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractReceipts = void 0;
+const pdf_lib_1 = require("pdf-lib");
+const errors_1 = require("../errors");
+const geometry_1 = require("../geometry");
+const extractedMultiReceiptImage_1 = require("./extractedMultiReceiptImage");
+async function addPage(pdfPage, boundingBox, pageId, receiptId) {
+    const { width, height } = pdfPage.getSize();
+    const receiptPdf = await pdf_lib_1.PDFDocument.create();
+    const newWidth = width * ((0, geometry_1.getMinMaxX)(boundingBox).max - (0, geometry_1.getMinMaxX)(boundingBox).min);
+    const newHeight = height * ((0, geometry_1.getMinMaxY)(boundingBox).max - (0, geometry_1.getMinMaxY)(boundingBox).min);
+    const croppedReceipt = await receiptPdf.embedPage(pdfPage, {
+        left: (0, geometry_1.getMinMaxX)(boundingBox).min * width,
+        right: (0, geometry_1.getMinMaxX)(boundingBox).max * width,
+        top: height - ((0, geometry_1.getMinMaxY)(boundingBox).min * height),
+        bottom: height - ((0, geometry_1.getMinMaxY)(boundingBox).max * height),
+    });
+    const receiptPage = receiptPdf.addPage([newWidth, newHeight]);
+    receiptPage.drawPage(croppedReceipt, {
+        width: newWidth,
+        height: newHeight,
+    });
+    const receiptBytes = await receiptPdf.save();
+    return new extractedMultiReceiptImage_1.ExtractedMultiReceiptImage(receiptBytes, pageId, receiptId);
+}
+async function loadPdfDoc(inputFile) {
+    let pdfDoc;
+    if (!["image/jpeg", "image/jpg", "image/png", "application/pdf"].includes(inputFile.mimeType)) {
+        throw new errors_1.MindeeMimeTypeError(`Unsupported file type "${inputFile.mimeType}" Currently supported types are .png, .jpg and .pdf`);
+    }
+    else if (inputFile.isPdf()) {
+        pdfDoc = await pdf_lib_1.PDFDocument.load(inputFile.fileObject);
+    }
+    else {
+        pdfDoc = await pdf_lib_1.PDFDocument.create();
+        let image;
+        if (inputFile.mimeType === "image/png") {
+            image = await pdfDoc.embedPng(inputFile.fileObject);
+        }
+        else {
+            image = await pdfDoc.embedJpg(inputFile.fileObject);
+        }
+        const imageDims = image.scale(1);
+        const pageImage = pdfDoc.addPage([imageDims.width, imageDims.height]);
+        pageImage.drawImage(image);
+    }
+    return pdfDoc;
+}
+/**
+ * Extracts individual receipts from multi-receipts documents.
+ *
+ * @param inputFile File to extract sub-receipts from.
+ * @param inference Results of the inference.
+ * @returns Individual extracted receipts as an array of ExtractedMultiReceiptsImage.
+ */
+async function extractReceipts(inputFile, inference) {
+    const images = [];
+    if (!inference.prediction.receipts) {
+        throw new errors_1.MindeeError("No possible receipts candidates found for MultiReceipts extraction.");
+    }
+    const pdfDoc = await loadPdfDoc(inputFile);
+    for (let pageId = 0; pageId < pdfDoc.getPageCount(); pageId++) {
+        const [page] = await pdfDoc.copyPages(pdfDoc, [pageId]);
+        for (let receiptId = 0; receiptId < inference.pages[pageId].prediction.receipts.length; receiptId++) {
+            const receipt = inference.pages[pageId].prediction.receipts[receiptId];
+            images.push(await addPage(page, receipt.boundingBox, pageId, receiptId));
+        }
+    }
+    return images;
+}
+exports.extractReceipts = extractReceipts;

package/src/index.d.ts

@@ -3,3 +3,4 @@ export { Client, PredictOptions } from "./client";
 export { AsyncPredictResponse, PredictResponse, Document, Page, } from "./parsing/common";
 export { InputSource, PageOptionsOperation } from "./input";
 export * as internal from "./internal";
+export * as imageOperations from "./imageOperations";

package/src/index.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.internal = exports.PageOptionsOperation = exports.InputSource = exports.Page = exports.Document = exports.PredictResponse = exports.AsyncPredictResponse = exports.Client = exports.product = void 0;
+exports.imageOperations = exports.internal = exports.PageOptionsOperation = exports.InputSource = exports.Page = exports.Document = exports.PredictResponse = exports.AsyncPredictResponse = exports.Client = exports.product = void 0;
 exports.product = __importStar(require("./product"));
 var client_1 = require("./client");
 Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_1.Client; } });
@@ -36,3 +36,4 @@ var input_1 = require("./input");
 Object.defineProperty(exports, "InputSource", { enumerable: true, get: function () { return input_1.InputSource; } });
 Object.defineProperty(exports, "PageOptionsOperation", { enumerable: true, get: function () { return input_1.PageOptionsOperation; } });
 exports.internal = __importStar(require("./internal"));
+exports.imageOperations = __importStar(require("./imageOperations"));

package/src/input/base.d.ts

@@ -29,7 +29,7 @@ export declare abstract class LocalInputSource extends InputSource {
     isPdf(): boolean;
     checkMimetype(): Promise<string>;
     /**
-     * Merge PDF pages.
+     * Cut PDF pages.
      * @param pageOptions
      */
     cutPdf(pageOptions: PageOptions): Promise<void>;

package/src/input/base.js

@@ -106,7 +106,7 @@ class LocalInputSource extends InputSource {
         return mimeType;
     }
     /**
-     * Merge PDF pages.
+     * Cut PDF pages.
      * @param pageOptions
      */
     async cutPdf(pageOptions) {