mindee 3.10.2 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # CHANGELOG
 
+## v4.0.0 - 2023-08-14
+### ¡Breaking Changes!
+* :art: :boom: harmonize response types with other libraries
+* :art: :boom: change endpoint management & syntax
+* :art: :boom: move products to `product` module
+
+### Changes
+* :sparkles: add full support for page-specific attributes
+* :sparkles: add support for FR Id Card
+* :sparkles: add support for US Driver License
+* :sparkles: add auto-generated md documentation
+* :sparkles: add text reconstruction when using the `allWords` parameter (full OCR)
+* :recycle: updated CLI to accommodate for newest changes
+* :coffin: remove InvoiceV3
+* :coffin: remove ReceiptV3
+* :recycle: update tests to accommodate for newest changes
+* :recycle: re-organized parsing module (common/standard/custom)
+
+
 ## v3.10.2 - 2023-08-11
 ### Changes
 * :loud_sound: better logging of JSON errors

package/README.md

@@ -1,7 +1,4 @@
-[![License: MIT](https://img.shields.io/github/license/mindee/mindee-api-nodejs)](https://opensource.org/licenses/MIT)
-[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mindee/mindee-api-nodejs/test.yml)](https://github.com/mindee/mindee-api-nodejs)
-[![NPM Version](https://img.shields.io/npm/v/mindee)](https://www.npmjs.com/package/mindee)
-[![Downloads](https://img.shields.io/npm/dm/mindee)](https://www.npmjs.com/package/mindee)
+[![License: MIT](https://img.shields.io/github/license/mindee/mindee-api-nodejs)](https://opensource.org/licenses/MIT) [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mindee/mindee-api-nodejs/test.yml)](https://github.com/mindee/mindee-api-nodejs) [![NPM Version](https://img.shields.io/npm/v/mindee)](https://www.npmjs.com/package/mindee) [![Downloads](https://img.shields.io/npm/dm/mindee)](https://www.npmjs.com/package/mindee)
 
 # Mindee API Helper Library for Node.js
 Quickly and easily connect to Mindee's API services using Node.js.
@@ -29,75 +26,140 @@ const mindee = require("mindee");
 // Init a new client
 const mindeeClient = new mindee.Client({ apiKey: "my-api-key" });
 
-// Load a file from disk and parse it
-const apiResponse = mindeeClient
-    .docFromPath("/path/to/the/file.ext")
-    .parse(mindee.InvoiceV4);
+// Load a file from disk
+const inputSource = mindeeClient.docFromPath("/path/to/the/file.ext");
+
+// Parse it on the API of your choice
+const apiResponse = mindeeClient.parse(mindee.product.InvoiceV4, inputSource);
+```
+
+**Note:** Files can also be loaded from:
+
+A URL (`https` only): 
+```js
+const inputSource = mindeeClient.docFromUrl("https://my-url");
+```
+
+A base64 encoded string:
+```js
+const inputSource = mindeeClient.docFromBase64(myInputString, "my-file-name")
+```
+
+A stream:
+```js
+const inputSource = mindeeClient.docFromBuffer(myReadableStream, "my-file-name")
+```
+
+A buffer:
+```js
+const inputSource = mindeeClient.docFromBuffer(myBuffer, "my-file-name")
 ```
 
 #### Region-Specific Documents
+
+Region-Specific Documents use the following syntax:
+
 ```js
 const mindee = require("mindee");
 // for TS or modules:
 // import * as mindee from "mindee";
 
-// Init a new client
 const mindeeClient = new mindee.Client({ apiKey: "my-api-key" });
 
-// Load a file from disk and parse it
-const apiResponse = mindeeClient
-    .docFromPath("/path/to/the/file.ext")
-    .parse(mindee.fr.IdCardV1);
+const inputSource = mindeeClient.docFromPath("/path/to/the/file.ext");
+
+// The IdCardV1 product belongs to mindee.product.fr, not mindee.product itself
+const apiResponse = mindeeClient.parse(mindee.product.fr.IdCardV1, inputSource);
 ```
 
 #### Custom Documents (API Builder)
+
+Custom documents will require you to provide their endpoint manually.
+
 ```js
 const mindee = require("mindee");
 // for TS or modules:
 // import * as mindee from "mindee";
 
-// Init a new client and add your document endpoint
-const mindeeClient = new mindee.Client({ apiKey: "my-api-key" })
-    .addEndpoint({
-        accountName: "my-account",
-        endpointName: "my-endpoint",
-    });
+// Init a new client
+const mindeeClient = new mindee.Client({
+  apiKey: "my-api-key"
+});
+
+// Load a file from disk
+const inputSource = mindeeClient.docFromPath("/path/to/the/file.ext");
 
-// Load a file from disk and parse it
+// Create a custom endpoint for your product
+const customEndpoint = mindeeClient.createEndpoint(
+  "my-endpoint",
+  "my-account",
+  "my-version" // will default to 1 if not provided
+);
+
+// Parse it
 const apiResponse = mindeeClient
-    .docFromPath("/path/to/the/file.ext")
-    .parse(mindee.CustomV1, { endpointName: "my-endpoint" });
+  .parse(
+    mindee.product.CustomV1,
+    inputSource,
+    {
+      endpoint: customEndpoint
+    }
+  );
 ```
 
 ### Handling the Return
 ```js
 // Handle the response Promise
 apiResponse.then((resp) => {
-
-    // The `document` property can be undefined:
-    // * TypeScript will not compile without this guard clause
-    //   (or consider using the '?' notation)
-    // * JavaScript will be very happy to produce subtle bugs
-    //   without this guard clause
-    if (resp.document === undefined) return;
-
-    // full object
-    console.log(resp.document);
-
-    // string summary
+    // print a string summary
     console.log(resp.document.toString());
+
+    // individual pages (array)
+    console.log(res.document.inference.pages);
 });
 ```
 
-## Further Reading
-There's more to it than that for those that need more features, or want to
-customize the experience.
+### Additional Options
+Options to pass when sending a file to be parsed.
+
+#### Page Options
+Allows only sending certain pages in a PDF.
 
-All the juicy details are described in the
-**[Official Guide](https://developers.mindee.com/docs/nodejs-sdk)**.
+In this example we only send the first, penultimate, and last pages:
 
-You can also take a look at the
-**[Reference Documentation](https://mindee.github.io/mindee-api-nodejs/)**.
+```js
+const apiResponse = mindeeClient.parse(
+  mindee.product.InvoiceV4,
+  inputSource,
+  {
+    pageOptions: {
+      pageIndexes: [0, -2, -1],
+      operation: mindee.PageOptionsOperation.KeepOnly,
+      onMinPages: 2
+    }
+  });
+```
+
+## Further Reading
+Complete details on the working of the library are available in the following guides: 
+
+* [Node.js Getting Started](https://developers.mindee.com/docs/nodejs-getting-started)
+* [Node.js Custom OCR](https://developers.mindee.com/docs/nodejs-api-builder)
+* [Node.js Invoice OCR](https://developers.mindee.com/docs/nodejs-invoice-ocr)
+* [Node.js Receipt OCR](https://developers.mindee.com/docs/nodejs-receipt-ocr)
+* [Node.js Financial Document OCR](https://developers.mindee.com/docs/nodejs-financial-document-ocr)
+* [Node.js Passport OCR](https://developers.mindee.com/docs/nodejs-passport-ocr)
+* [Node.js Proof of Address OCR](https://developers.mindee.com/docs/nodejs-proof-of-address-ocr)
+* [Node.js EU License Plate OCR](https://developers.mindee.com/docs/nodejs-eu-license-plates-ocr)
+* [Node.js FR Bank Account Detail OCR](https://developers.mindee.com/docs/nodejs-fr-bank-account-details-ocr)
+* [Node.js FR Carte Vitale OCR](https://developers.mindee.com/docs/nodejs-fr-carte-vitale-ocr)
+* [Node.js FR ID Card OCR](https://developers.mindee.com/docs/nodejs-fr-id-card-ocr)
+* [Node.js US Bank Check OCR](https://developers.mindee.com/docs/nodejs-us-bank-checks-ocr)
+* [Node.js US Driver License OCR](https://developers.mindee.com/docs/nodejs-us-driver-license-ocr)
+* [Node.js Cropper API](https://developers.mindee.com/docs/nodejs-cropper-api)
+* [Node.js Invoice Splitter API](https://developers.mindee.com/docs/nodejs-invoice-splitter-api)
+
+You can also take a look at the **[Reference Documentation](https://mindee.github.io/mindee-api-nodejs/)**.
 
 ## License
 Copyright © Mindee

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mindee",
-    "version": "3.10.2",
+    "version": "4.0.0",
     "description": "Mindee Client Library for Node.js",
     "main": "src/index.js",
     "bin": "bin/mindee.js",
@@ -10,10 +10,10 @@
         "build-for-dist": "tsc --build && cp LICENSE README.md CHANGELOG.md ./dist",
         "clean": "rm -rf ./dist ./docs/_build",
         "test": "mocha 'tests/**/*.spec.ts'",
-        "lint-fix": "eslint './src/**/*.ts' --fix",
         "lint": "eslint  './src/**/*.ts' --report-unused-disable-directives && echo 'Your .ts files look good.'",
         "docs": "typedoc --out docs/_build ./src/index.ts",
-        "docs-for-dist": "typedoc --out docs/_build ./src/index.ts && cp -r ./docs/code_samples ./docs/_build/"
+        "docs-for-dist": "typedoc --out docs/_build ./src/index.ts && cp -r ./docs/code_samples ./docs/_build/",
+        "postinstall": "husky install"
     },
     "files": [
         "src/*",
@@ -40,16 +40,16 @@
     "homepage": "https://mindee.com/",
     "devDependencies": {
         "@types/chai": "^4.3.4",
+        "@types/lint-staged": "^13.2.0",
         "@types/mocha": "^9.1.1",
         "@types/node": "^18.15.11",
         "@typescript-eslint/eslint-plugin": "^5.57.1",
         "@typescript-eslint/parser": "^5.57.1",
         "chai": "^4.3.7",
         "eslint": "^8.32.0",
-        "eslint-config-prettier": "^8.6.0",
-        "eslint-plugin-prettier": "^4.2.1",
+        "husky": "^8.0.3",
+        "lint-staged": "^13.2.3",
         "mocha": "^10.1.0",
-        "prettier": "^2.8.1",
         "ts-node": "^10.9.1",
         "typedoc": "~0.23",
         "typescript": "^5.0.4"

package/src/cli.js

@@ -25,10 +25,9 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cli = void 0;
 const commander_1 = require("commander");
-const _1 = require("./");
-const api_1 = require("./api");
+const product = __importStar(require("./product"));
 const client_1 = require("./client");
-const inputs_1 = require("./inputs");
+const input_1 = require("./input");
 const console = __importStar(require("console"));
 const program = new commander_1.Command();
 const COMMAND_CUSTOM = "custom";
@@ -42,8 +41,18 @@ const CLI_COMMAND_CONFIG = new Map([
         COMMAND_CUSTOM,
         {
             displayName: "Custom Document",
-            docClass: _1.CustomV1,
-            fullText: false,
+            docClass: product.CustomV1,
+            allWords: false,
+            async: false,
+            sync: true,
+        },
+    ],
+    [
+        "cropper",
+        {
+            displayName: "Cropper",
+            docClass: product.CropperV1,
+            allWords: false,
             async: false,
             sync: true,
         },
@@ -52,8 +61,8 @@ const CLI_COMMAND_CONFIG = new Map([
         "invoice",
         {
             displayName: "Invoice",
-            docClass: _1.InvoiceV4,
-            fullText: true,
+            docClass: product.InvoiceV4,
+            allWords: true,
             async: false,
             sync: true,
         },
@@ -62,8 +71,8 @@ const CLI_COMMAND_CONFIG = new Map([
         "invoice-splitter",
         {
             displayName: "Invoice Splitter",
-            docClass: _1.InvoiceSplitterV1,
-            fullText: false,
+            docClass: product.InvoiceSplitterV1,
+            allWords: false,
             async: true,
             sync: false,
         },
@@ -72,8 +81,8 @@ const CLI_COMMAND_CONFIG = new Map([
         "receipt",
         {
             displayName: "Expense Receipt",
-            docClass: _1.ReceiptV5,
-            fullText: true,
+            docClass: product.ReceiptV5,
+            allWords: true,
             async: false,
             sync: true,
         },
@@ -82,8 +91,8 @@ const CLI_COMMAND_CONFIG = new Map([
         "passport",
         {
             displayName: "Passport",
-            docClass: _1.PassportV1,
-            fullText: false,
+            docClass: product.PassportV1,
+            allWords: false,
             async: false,
             sync: true,
         },
@@ -92,8 +101,8 @@ const CLI_COMMAND_CONFIG = new Map([
         "financial",
         {
             displayName: "Financial Document",
-            docClass: _1.FinancialDocumentV1,
-            fullText: true,
+            docClass: product.FinancialDocumentV1,
+            allWords: true,
             async: false,
             sync: true,
         },
@@ -102,8 +111,8 @@ const CLI_COMMAND_CONFIG = new Map([
         "fr-id-card",
         {
             displayName: "FR ID Card",
-            docClass: _1.fr.IdCardV1,
-            fullText: false,
+            docClass: product.fr.IdCardV1,
+            allWords: false,
             async: false,
             sync: true,
         },
@@ -112,8 +121,8 @@ const CLI_COMMAND_CONFIG = new Map([
         "fr-bank-account-details",
         {
             displayName: "FR Bank Account Details",
-            docClass: _1.fr.BankAccountDetailsV1,
-            fullText: false,
+            docClass: product.fr.BankAccountDetailsV2,
+            allWords: false,
             async: false,
             sync: true,
         },
@@ -122,8 +131,8 @@ const CLI_COMMAND_CONFIG = new Map([
         "fr-carte-vitale",
         {
             displayName: "FR Carte Vitale",
-            docClass: _1.fr.CarteVitaleV1,
-            fullText: false,
+            docClass: product.fr.CarteVitaleV1,
+            allWords: false,
             async: false,
             sync: true,
         },
@@ -132,8 +141,8 @@ const CLI_COMMAND_CONFIG = new Map([
         "eu-license-plate",
         {
             displayName: "EU License Plate",
-            docClass: _1.eu.LicensePlateV1,
-            fullText: false,
+            docClass: product.eu.LicensePlateV1,
+            allWords: false,
             async: false,
             sync: true,
         },
@@ -142,18 +151,8 @@ const CLI_COMMAND_CONFIG = new Map([
         "us-bank-check",
         {
             displayName: "US Bank Check",
-            docClass: _1.us.BankCheckV1,
-            fullText: false,
-            async: false,
-            sync: true,
-        },
-    ],
-    [
-        "mvision",
-        {
-            displayName: "Mindee Vision",
-            docClass: _1.MindeeVisionV1,
-            fullText: false,
+            docClass: product.us.BankCheckV1,
+            allWords: false,
             async: false,
             sync: true,
         },
@@ -162,17 +161,11 @@ const CLI_COMMAND_CONFIG = new Map([
 //
 // EXECUTE THE COMMANDS
 //
-function initClient(command, options) {
+function initClient(options) {
     const mindeeClient = new client_1.Client({
         apiKey: options.apiKey,
         debug: options.debug,
     });
-    if (command === COMMAND_CUSTOM) {
-        mindeeClient.addEndpoint({
-            accountName: options.user,
-            endpointName: options.documentType,
-        });
-    }
     return mindeeClient;
 }
 function getConfig(command) {
@@ -182,45 +175,78 @@ function getConfig(command) {
     }
     return conf;
 }
-function getPredictParams(command, options, conf) {
+function getPageOptions(options) {
     let pageOptions = undefined;
     if (options.cutPages) {
         pageOptions = {
-            operation: inputs_1.PageOptionsOperation.KeepOnly,
+            operation: input_1.PageOptionsOperation.KeepOnly,
             pageIndexes: [0, 1, 2, 3, 4],
             onMinPages: 5,
         };
     }
+    return pageOptions;
+}
+function getPredictParams(options) {
     const predictParams = {
-        endpointName: command === COMMAND_CUSTOM ? options.documentType : conf.docClass.name,
-        accountName: command === COMMAND_CUSTOM ? options.user : api_1.STANDARD_API_OWNER,
-        fullText: options.fullText,
-        pageOptions: pageOptions,
+        allWords: options.allWords,
+        cropper: options.cropper,
     };
     return predictParams;
 }
 async function callParse(command, inputPath, options) {
     const conf = getConfig(command);
-    const mindeeClient = initClient(command, options);
-    const predictParams = getPredictParams(command, options, conf);
-    const doc = mindeeClient.docFromPath(inputPath);
-    const response = await doc.parse(conf.docClass, predictParams);
-    printResponse(response, options);
+    const mindeeClient = initClient(options);
+    const predictParams = getPredictParams(options);
+    const pageOptions = getPageOptions(options);
+    const inputSource = mindeeClient.docFromPath(inputPath);
+    let response;
+    if (command === COMMAND_CUSTOM) {
+        const customEndpoint = mindeeClient.createEndpoint(options.endpoint, options.account, options.version);
+        response = await mindeeClient.parse(conf.docClass, inputSource, {
+            endpoint: customEndpoint,
+            pageOptions: pageOptions,
+            allWords: predictParams.allWords,
+            cropper: predictParams.cropper,
+        });
+    }
+    else {
+        response = await mindeeClient.parse(conf.docClass, inputSource, {
+            pageOptions: pageOptions,
+            allWords: predictParams.allWords,
+            cropper: predictParams.cropper,
+        });
+    }
+    printResponse(response.document, options);
 }
 async function callEnqueue(command, inputPath, options) {
     const conf = getConfig(command);
-    const mindeeClient = initClient(command, options);
-    const predictParams = getPredictParams(command, options, conf);
-    const doc = mindeeClient.docFromPath(inputPath);
-    const response = await doc.enqueue(conf.docClass, predictParams);
+    const mindeeClient = initClient(options);
+    const predictParams = getPredictParams(options);
+    const pageOptions = getPageOptions(options);
+    const inputSource = mindeeClient.docFromPath(inputPath);
+    let response;
+    if (command === COMMAND_CUSTOM) {
+        const customEndpoint = mindeeClient.createEndpoint(options.endpoint, options.account, options.version);
+        response = await mindeeClient.enqueue(conf.docClass, inputSource, {
+            endpoint: customEndpoint,
+            pageOptions: pageOptions,
+            allWords: predictParams.allWords,
+            cropper: predictParams.cropper,
+        });
+    }
+    else {
+        response = await mindeeClient.enqueue(conf.docClass, inputSource, {
+            pageOptions: pageOptions,
+            allWords: predictParams.allWords,
+            cropper: predictParams.cropper,
+        });
+    }
     console.log(response.job);
 }
 async function callParseQueued(command, queueId, options) {
     const conf = getConfig(command);
-    const mindeeClient = initClient(command, options);
-    const predictParams = getPredictParams(command, options, conf);
-    const doc = mindeeClient.docForAsync();
-    const response = await doc.parseQueued(conf.docClass, queueId, predictParams);
+    const mindeeClient = initClient(options);
+    const response = await mindeeClient.parseQueued(conf.docClass, queueId);
     if (response.document !== undefined) {
         printResponse(response.document, options);
     }
@@ -228,19 +254,19 @@ async function callParseQueued(command, queueId, options) {
         console.log(response.job);
     }
 }
-function printResponse(response, options) {
-    if (options.fullText) {
-        response.pages.forEach((page) => {
-            console.log(page.fullText?.toString());
+function printResponse(document, options) {
+    if (options.allWords) {
+        document.ocr?.mVisionV1.pages.forEach((page) => {
+            console.log(page.allWords.toString());
         });
     }
     if (options.pages) {
-        response.pages.forEach((page) => {
+        document.inference.pages.forEach((page) => {
             console.log(`\n${page}`);
         });
     }
-    if (response.document) {
-        console.log(`\n${response.document}`);
+    if (document) {
+        console.log(`\n${document}`);
     }
 }
 //
@@ -251,8 +277,8 @@ function addMainOptions(prog) {
 }
 function addPostOptions(prog, info) {
     prog.option("-c, --cut-pages", "keep only the first 5 pages of the document");
-    if (info.fullText) {
-        prog.option("-t, --full-text", "include full document text in response");
+    if (info.allWords) {
+        prog.option("-w, --all-words", "to get all the words in the current document. False by default.");
     }
     prog.argument("<input_path>", "full path to the file");
 }