mindee 3.5.0 → 3.7.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # CHANGELOG
 
+## v3.7.0 - 2023-03-31
+### Changes
+* :sparkles: add support for asynchronous predictions
+* :sparkles: add **experimental** support for line items in custom documents
+* :art: harmonize bbox and bounding box terminology
+* :arrow_up: update test files, minor updates to string output
+* :label: classification fields are always strings
+
+### Fixes
+* :bug: fix error message for missing API key, document type may be undefined
+
+
+## v3.6.0 - 2023-02-01
+### Changes
+* :sparkles: Add support for the mindee_vision API (for internal testing)
+* :sparkles: support Proof of Address V1
+* :sparkles: Add support for: financial document v1
+* :arrow_up: update jsdoc
+
+### ¡Warning!
+The `FinancialDocumentV1` class now uses an actual API call to the new route `financial_document`.
+Previously, determining whether a document is an invoice or a receipt was done internally by this library.
+
+The API call way is **much** better, however some fields have been renamed compared to the internal handling.
+This was done so field names now match exactly `Invoice` and `Receipt` classes.
+
+As such, we encourage users to migrate to the new field structure.
+
+If this is problematic, it's possible to use the deprecated way.
+Simply pass `FinancialDocumentV0` to the `parse` method.
+Usage is otherwise identical.
+
+
 ## v3.5.0 - 2023-01-17
 ### Changes
 * :memo: updates to class documentation
@@ -8,6 +41,7 @@
 ### Fixes
 * :bug: fix for CLI command option description
 
+
 ## v3.4.1 - 2023-01-05
 ### Changes
 * :label: Added typing information, get rid of `any` type in various places
@@ -17,16 +51,19 @@
 ### Fixes
 * :bug: Expose various class and type definitions to improve developer experience
 
+
 ## v3.4.0 - 2023-01-04
 ### Changes
 * :sparkles: Support Receipt V4.1
 * :sparkles: Support Invoice V4.1
 
+
 ## v3.3.0 - 2022-12-01
 ### Changes
 * :sparkles: Add Invoice V4 with line items
 * :sparkles: An env variable can be used to change the Mindee base API url
 
+
 ## v3.2.0 - 2022-11-14
 ### Changes
 * :sparkles: Add support for shipping container API V1
@@ -37,19 +74,23 @@
 * :memo: Export and add comments for method parameters.
 * :sparkles: Add support for US Bank Check V1
 
+
 ## v3.1.1 - 2022-11-08
 ### Changes
 * :bug: fix proper import and documentation of region-specific documents
 
+
 ## v3.1.0 - 2022-11-08
 ### Changes
 * :sparkles:  Add support for French ID cards.
 * :sparkles: add buffer input source
 
+
 ## v3.0.1 - 2022-11-02
 ### Fixes
 * :bug: Fix for `supplier` property name in `ReceiptV4` document.
 
+
 ## v3.0.0 - 2022-10-31
 ### ¡Breaking Changes!
 * :sparkles: New PDF cut system, which allows specifying exactly which pages to keep or remove.
@@ -62,6 +103,7 @@
 * :sparkles: New URL input source, `docFromUrl`.
 * :sparkles: Add support for expense receipts V4
 
+
 ## v2.1.1 - 2022-10-28
 ### Fixes
 * :bug: fix for sending base64 documents.
@@ -76,6 +118,7 @@
 ### Fixes
 * :bug: Fix for packaging and documentation related to commonJS imports
 
+
 ## v2.0.0 - 2022-08-26
 ### Note
 This is a complete rewrite in TypeScript!
@@ -90,6 +133,7 @@ It's **not** backwards compatible with previous versions.
   Allows for much easier auto-completion in your IDE.
 * :arrow_up: all major dependencies updated
 
+
 ## v1.4.0
 ### Fixes
 * :bug: cut/merge pages of an encrypted PDF leads to unexpected results
@@ -100,118 +144,98 @@ It's **not** backwards compatible with previous versions.
 * :sparkles: Add TIFF and HEIC support
 * :white_check_mark: fully test PDF cut function
 
-## v1.3.3
 
+## v1.3.3
 ### Fixes
 * :bug: reject errors instead of printing them only to the console
 
-## v1.3.2
 
+## v1.3.2
 ### Fixes
 * :bug: use PDF length instead of cut PDF size limit
 
-## v1.3.1
 
+## v1.3.1
 ### Fixes
 * :bug: forward api error to stderr instead of stdout
 
-## v1.3.0
 
+## v1.3.0
 ### Changes
-
 * :sparkles: allow sending the filename for streams and base64
 * :bug: not able to specify MIME type
 * :page_facing_up: change license to MIT
 * :white_check_mark: add node18 to tests
 * various package updates
 
-## v1.2.0
 
+## v1.2.0
 ### Fixes
-
 * :bug: Get `words` values when `includeWords` parameter is `true`
 
+
 ## v1.1.2
+### Changes
+* :sparkles: New Mindee Invoice API V3 support
+* :sparkles: Add new supplier and customer fields
 
 ### Fixes
-
 * :bug: Fix returned probability value
 * :bug: Fix returned bbox value
 
-### new
-
-* :sparkles: New Mindee Invoice API V3 support
-* :sparkles: Add new supplier and customer fields
 
 ## v1.1.0 (2022-01-03)
-
-### new
-
+### Changes
 * :sparkles: New Mindee API V2 support
 * :zap: Server side invoice reconstruction from multi-page pdfs
 * :sparkles: Added OS in User-Agent headers
 
 
 ## v1.0.9 (2021-12-09)
-
 ### Fixes
-
 * :bug: handle attribute of type array when merging pages
 
+
 ## v1.0.8 (2021-11-29)
+### Changes
+* :see_no_evil: add .DS_Store to ignore file
 
 ### Fixes
-
 * :bug: fix cutPDF for ReadableStream + add it for base64 file string
 * :bug: Updated api Input initialization to specifically declare parameters
 * :bug: prevent error when the mime type isn't detectable
 * :bug: raise proper error when the APi doesn't return a valid JSON
 
-### new
-
-* :see_no_evil: add .DS_Store to ignore file
 
 ## v1.0.7 (2021-11-25)
-
-### New
-
-* :sparkles: Added pdf page number parameter for multi-pages pdfs with file
-
 ### Changes
-
+* :sparkles: Added pdf page number parameter for multi-pages pdfs with file
 * :arrow_up: upgrade path-parse dependency
 * :arrow_up: upgrade browserslist dependency
 * :arrow_up: upgrade lodash dependency
 * :arrow_up: upgrade y18n dependency
 
-## v1.0.4 (2021-02-18)
-
-### New
-
-* :sparkles: :zap: Add a parameter `filename` and a default filename for streams
 
+## v1.0.4 (2021-02-18)
 ### Changes
-
+* :sparkles: :zap: Add a parameter `filename` and a default filename for streams
 * :zap: Change parse function to use an object instead of multiples parameters
 
-## v1.0.3 (2021-02-01)
 
+## v1.0.3 (2021-02-01)
 ### Fixes
-
 * :bug: \_request parameters
 * :bug: `pageNumber` default value
 * :bug: reconstruction method set fields to probability
 
-## v1.0.2 (2021-02-01)
 
+## v1.0.2 (2021-02-01)
 ### Changes
-
 * :zap: Better coverage for total tax
 
 ### Fixes
-
 * :bug: `includeWords` is now working
 
-## v1.0.1 (2021-01-11)
 
+## v1.0.1 (2021-01-11)
 * :tada: First release

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mindee",
-    "version": "3.5.0",
+    "version": "3.7.0",
     "description": "Mindee Client Library for Node.js",
     "main": "src/index.js",
     "bin": "bin/mindee.js",
@@ -12,7 +12,7 @@
         "test": "mocha 'tests/**/*.spec.ts'",
         "lint-fix": "eslint '**/*.ts' --fix",
         "lint": "eslint '**/*.ts' --report-unused-disable-directives && echo 'Your .ts files look good.'",
-        "docs": "jsdoc -r src -d docs"
+        "docs": "jsdoc -r dist/src -d docs"
     },
     "files": [
         "src/*",
@@ -47,7 +47,7 @@
         "eslint": "^8.31.0",
         "eslint-config-prettier": "^8.6.0",
         "eslint-plugin-prettier": "^4.2.1",
-        "jsdoc": "^3.6.11",
+        "jsdoc": "~4.0",
         "mocha": "^10.1.0",
         "prettier": "^2.8.1",
         "ts-node": "^10.9.1",

package/src/api/{response.d.ts → documentResponse.d.ts}

@@ -4,7 +4,7 @@ import { InputSource } from "../inputs";
 export interface ResponseProps {
     httpResponse: any;
     documentType?: string;
-    input: InputSource;
+    input?: InputSource;
     error: boolean;
 }
 export type ResponseSig<DocType extends Document> = {
@@ -15,7 +15,7 @@ export type ResponseSig<DocType extends Document> = {
  */
 export declare class Response<DocType extends Document> {
     httpResponse: any;
-    inputFile: InputSource;
+    inputFile?: InputSource;
     document?: DocType;
     pages: Array<DocType>;
     readonly documentClass: DocumentSig<DocType>;

package/src/api/endpoint.d.ts

@@ -1,10 +1,10 @@
 /// <reference types="node" />
 import { InputSource } from "../inputs";
-import { IncomingMessage } from "http";
+import { IncomingMessage, RequestOptions, ClientRequest } from "http";
 export declare const STANDARD_API_OWNER = "mindee";
 export declare const API_KEY_ENVVAR_NAME = "MINDEE_API_KEY";
-export declare const API_BASE_URL_ENVVAR_NAME = "MINDEE_BASE_URL";
-export interface predictResponse {
+export declare const API_HOST_ENVVAR_NAME = "MINDEE_API_HOST";
+export interface EndpointResponse {
     messageObj: IncomingMessage;
     data: {
         [key: string]: any;
@@ -15,6 +15,7 @@ export declare class Endpoint {
     urlName: string;
     owner: string;
     version: string;
+    hostname: string;
     urlRoot: string;
     private readonly baseHeaders;
     constructor(owner: string, urlName: string, version: string, apiKey: string);
@@ -24,9 +25,35 @@ export declare class Endpoint {
      * @param includeWords
      * @param cropper
      */
-    predictReqPost(input: InputSource, includeWords?: boolean, cropper?: boolean): Promise<predictResponse>;
+    predictReqPost(input: InputSource, includeWords?: boolean, cropper?: boolean): Promise<EndpointResponse>;
+    /**
+     * Make a request to POST a document for async prediction.
+     * @param input
+     * @param includeWords
+     * @param cropper
+     */
+    predictAsyncReqPost(input: InputSource, includeWords?: boolean, cropper?: boolean): Promise<EndpointResponse>;
+    /**
+     * Make a request to GET the status of a document in the queue.
+     * @param queueId
+     */
+    documentQueueReqGet(queueId: string): Promise<EndpointResponse>;
+    /**
+     * Make a request to GET a document.
+     * @param documentId
+     */
+    documentGetReq(documentId: string): Promise<EndpointResponse>;
+    /**
+     * Send a file to a prediction API.
+     * @param input
+     * @param predictUrl
+     * @param includeWords
+     * @param cropper
+     */
+    protected sendFileForPrediction(input: InputSource, predictUrl: string, includeWords?: boolean, cropper?: boolean): Promise<EndpointResponse>;
+    protected readResponse(options: RequestOptions, resolve: (value: EndpointResponse | PromiseLike<EndpointResponse>) => void, reject: (reason?: any) => void): ClientRequest;
     protected apiKeyFromEnv(): string;
-    protected baseUrlFromEnv(): string;
+    protected hostnameFromEnv(): string;
 }
 export declare class StandardEndpoint extends Endpoint {
     constructor(endpointName: string, version: string, apiKey: string);

package/src/api/endpoint.js

@@ -26,25 +26,26 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CustomEndpoint = exports.StandardEndpoint = exports.Endpoint = exports.API_BASE_URL_ENVVAR_NAME = exports.API_KEY_ENVVAR_NAME = exports.STANDARD_API_OWNER = void 0;
+exports.CustomEndpoint = exports.StandardEndpoint = exports.Endpoint = exports.API_HOST_ENVVAR_NAME = exports.API_KEY_ENVVAR_NAME = exports.STANDARD_API_OWNER = void 0;
 const https = __importStar(require("https"));
 const os = __importStar(require("os"));
 const package_json_1 = require("../../package.json");
 const url_1 = require("url");
 const form_data_1 = __importDefault(require("form-data"));
 const logger_1 = require("../logger");
-const DEFAULT_MINDEE_API_URL = "https://api.mindee.net/v1";
+const DEFAULT_MINDEE_API_HOST = "api.mindee.net";
 const USER_AGENT = `mindee-api-nodejs@v${package_json_1.version} nodejs-${process.version} ${os.type().toLowerCase()}`;
 exports.STANDARD_API_OWNER = "mindee";
 exports.API_KEY_ENVVAR_NAME = "MINDEE_API_KEY";
-exports.API_BASE_URL_ENVVAR_NAME = "MINDEE_BASE_URL";
+exports.API_HOST_ENVVAR_NAME = "MINDEE_API_HOST";
 class Endpoint {
     constructor(owner, urlName, version, apiKey) {
         this.owner = owner;
         this.urlName = urlName;
         this.version = version;
         this.apiKey = apiKey || this.apiKeyFromEnv();
-        this.urlRoot = `${this.baseUrlFromEnv()}/products/${owner}/${urlName}/v${version}`;
+        this.hostname = this.hostnameFromEnv();
+        this.urlRoot = `/v1/products/${owner}/${urlName}/v${version}`;
         this.baseHeaders = {
             "User-Agent": USER_AGENT,
             Authorization: `Token ${this.apiKey}`,
@@ -57,12 +58,64 @@ class Endpoint {
      * @param cropper
      */
     predictReqPost(input, includeWords = false, cropper = false) {
+        return this.sendFileForPrediction(input, "predict", includeWords, cropper);
+    }
+    /**
+     * Make a request to POST a document for async prediction.
+     * @param input
+     * @param includeWords
+     * @param cropper
+     */
+    predictAsyncReqPost(input, includeWords = false, cropper = false) {
+        return this.sendFileForPrediction(input, "predict_async", includeWords, cropper);
+    }
+    /**
+     * Make a request to GET the status of a document in the queue.
+     * @param queueId
+     */
+    documentQueueReqGet(queueId) {
+        return new Promise((resolve, reject) => {
+            const options = {
+                method: "GET",
+                headers: this.baseHeaders,
+                hostname: this.hostname,
+                path: `${this.urlRoot}/documents/queue/${queueId}`,
+            };
+            const req = this.readResponse(options, resolve, reject);
+            // potential ECONNRESET if we don't end the request.
+            req.end();
+        });
+    }
+    /**
+     * Make a request to GET a document.
+     * @param documentId
+     */
+    documentGetReq(documentId) {
         return new Promise((resolve, reject) => {
-            const uri = new url_1.URL(`${this.urlRoot}/predict`);
+            const options = {
+                method: "GET",
+                headers: this.baseHeaders,
+                hostname: this.hostname,
+                path: `${this.urlRoot}/documents/${documentId}`,
+            };
+            const req = this.readResponse(options, resolve, reject);
+            // potential ECONNRESET if we don't end the request.
+            req.end();
+        });
+    }
+    /**
+     * Send a file to a prediction API.
+     * @param input
+     * @param predictUrl
+     * @param includeWords
+     * @param cropper
+     */
+    sendFileForPrediction(input, predictUrl, includeWords = false, cropper = false) {
+        return new Promise((resolve, reject) => {
+            const searchParams = new url_1.URLSearchParams();
             if (cropper) {
-                uri.searchParams.append("cropper", "true");
+                searchParams.append("cropper", "true");
             }
-            logger_1.logger.debug(`Request URI: ${uri}`);
             const form = new form_data_1.default();
             if (input.fileObject instanceof Buffer) {
                 form.append("document", input.fileObject, { filename: input.filename });
@@ -74,36 +127,53 @@ class Endpoint {
                 form.append("include_mvision", "true");
             }
             const headers = { ...this.baseHeaders, ...form.getHeaders() };
+            let path = `${this.urlRoot}/${predictUrl}`;
+            if (searchParams.keys.length > 0) {
+                path += `?${searchParams}`;
+            }
             const options = {
                 method: "POST",
                 headers: headers,
-                hostname: uri.hostname,
-                path: `${uri.pathname}${uri.search}`,
+                hostname: this.hostname,
+                path: path,
             };
-            const req = https.request(options, function (res) {
-                // when the encoding is set, data chunks will be strings
-                res.setEncoding("utf-8");
-                let responseBody = "";
-                res.on("data", function (chunk) {
-                    responseBody += chunk;
-                });
-                res.on("end", function () {
-                    try {
-                        resolve({
-                            messageObj: res,
-                            data: JSON.parse(responseBody),
-                        });
-                    }
-                    catch (error) {
-                        reject(error);
-                    }
-                });
-            });
+            const req = this.readResponse(options, resolve, reject);
             form.pipe(req);
-            req.on("error", (err) => {
-                reject(err);
+            // potential ECONNRESET if we don't end the request.
+            req.end();
+        });
+    }
+    readResponse(options, resolve, reject) {
+        logger_1.logger.debug(`${options.method}: https://${options.hostname}${options.path}`);
+        const req = https.request(options, function (res) {
+            // when the encoding is set, data chunks will be strings
+            res.setEncoding("utf-8");
+            let responseBody = "";
+            res.on("data", function (chunk) {
+                logger_1.logger.debug("receiving data ...");
+                responseBody += chunk;
             });
+            res.on("end", function () {
+                // handle empty responses from server, for example in the case of redirects
+                if (!responseBody) {
+                    responseBody = "{}";
+                }
+                try {
+                    resolve({
+                        messageObj: res,
+                        data: JSON.parse(responseBody),
+                    });
+                }
+                catch (error) {
+                    logger_1.logger.debug(responseBody);
+                    reject(error);
+                }
+            });
+        });
+        req.on("error", (err) => {
+            reject(err);
         });
+        return req;
     }
     apiKeyFromEnv() {
         const envVarValue = process.env[exports.API_KEY_ENVVAR_NAME];
@@ -113,13 +183,13 @@ class Endpoint {
         }
         return "";
     }
-    baseUrlFromEnv() {
-        const envVarValue = process.env[exports.API_BASE_URL_ENVVAR_NAME];
+    hostnameFromEnv() {
+        const envVarValue = process.env[exports.API_HOST_ENVVAR_NAME];
         if (envVarValue) {
-            logger_1.logger.debug(`Set the API base URL to ${envVarValue}`);
+            logger_1.logger.debug(`Set the API hostname to ${envVarValue}`);
             return envVarValue;
         }
-        return DEFAULT_MINDEE_API_URL;
+        return DEFAULT_MINDEE_API_HOST;
     }
 }
 exports.Endpoint = Endpoint;

package/src/api/index.d.ts

@@ -1,2 +1,3 @@
-export { Response, ResponseSig } from "./response";
-export { Endpoint, CustomEndpoint, StandardEndpoint, predictResponse, STANDARD_API_OWNER, API_KEY_ENVVAR_NAME, } from "./endpoint";
+export { Response, ResponseSig } from "./documentResponse";
+export { Endpoint, CustomEndpoint, StandardEndpoint, EndpointResponse, STANDARD_API_OWNER, API_KEY_ENVVAR_NAME, } from "./endpoint";
+export { AsyncPredictResponse } from "./predictResponse";

package/src/api/index.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.API_KEY_ENVVAR_NAME = exports.STANDARD_API_OWNER = exports.StandardEndpoint = exports.CustomEndpoint = exports.Endpoint = exports.Response = void 0;
-var response_1 = require("./response");
-Object.defineProperty(exports, "Response", { enumerable: true, get: function () { return response_1.Response; } });
+exports.AsyncPredictResponse = exports.API_KEY_ENVVAR_NAME = exports.STANDARD_API_OWNER = exports.StandardEndpoint = exports.CustomEndpoint = exports.Endpoint = exports.Response = void 0;
+var documentResponse_1 = require("./documentResponse");
+Object.defineProperty(exports, "Response", { enumerable: true, get: function () { return documentResponse_1.Response; } });
 var endpoint_1 = require("./endpoint");
 Object.defineProperty(exports, "Endpoint", { enumerable: true, get: function () { return endpoint_1.Endpoint; } });
 Object.defineProperty(exports, "CustomEndpoint", { enumerable: true, get: function () { return endpoint_1.CustomEndpoint; } });
 Object.defineProperty(exports, "StandardEndpoint", { enumerable: true, get: function () { return endpoint_1.StandardEndpoint; } });
 Object.defineProperty(exports, "STANDARD_API_OWNER", { enumerable: true, get: function () { return endpoint_1.STANDARD_API_OWNER; } });
 Object.defineProperty(exports, "API_KEY_ENVVAR_NAME", { enumerable: true, get: function () { return endpoint_1.API_KEY_ENVVAR_NAME; } });
+var predictResponse_1 = require("./predictResponse");
+Object.defineProperty(exports, "AsyncPredictResponse", { enumerable: true, get: function () { return predictResponse_1.AsyncPredictResponse; } });

package/src/api/predictResponse.d.ts

@@ -0,0 +1,33 @@
+import { StringDict } from "../fields";
+import { Document } from "../documents";
+import { Response } from "./documentResponse";
+export declare class Job {
+    issuedAt: Date;
+    availableAt?: Date;
+    id?: string;
+    status?: "waiting" | "processing" | "completed";
+    /**
+     * The time taken to process the job, in milliseconds.
+     */
+    milliSecsTaken?: number;
+    constructor(jsonResponse: StringDict);
+    protected datetimeWithTimezone(date: string): Date;
+}
+export declare class ApiRequest {
+    error: StringDict;
+    resources: string[];
+    status: "failure" | "success";
+    /** HTTP status code */
+    statusCode: number;
+    url: string;
+    constructor(serverResponse: StringDict);
+}
+export declare class BasePredictResponse {
+    apiRequest: ApiRequest;
+    constructor(serverResponse: StringDict);
+}
+export declare class AsyncPredictResponse<DocType extends Document> extends BasePredictResponse {
+    job: Job;
+    document?: Response<DocType>;
+    constructor(serverResponse: StringDict, document?: Response<DocType>);
+}

package/src/api/predictResponse.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncPredictResponse = exports.BasePredictResponse = exports.ApiRequest = exports.Job = void 0;
+class Job {
+    constructor(jsonResponse) {
+        this.issuedAt = this.datetimeWithTimezone(jsonResponse["issued_at"]);
+        if (jsonResponse["available_at"] !== undefined &&
+            jsonResponse["available_at"] !== null) {
+            this.availableAt = this.datetimeWithTimezone(jsonResponse["available_at"]);
+        }
+        this.id = jsonResponse["id"];
+        this.status = jsonResponse["status"];
+        if (this.availableAt !== undefined) {
+            this.milliSecsTaken =
+                this.availableAt.getTime() - this.issuedAt.getTime();
+        }
+    }
+    // Hideous thing to make sure dates sent back by the server are parsed correctly in UTC.
+    datetimeWithTimezone(date) {
+        if (date.search(/\+[0-9]{2}:[0-9]{2}$/) === -1) {
+            date += "+00:00";
+        }
+        return new Date(date);
+    }
+}
+exports.Job = Job;
+class ApiRequest {
+    constructor(serverResponse) {
+        this.error = serverResponse["error"];
+        this.resources = serverResponse["resources"];
+        this.status = serverResponse["status"];
+        this.statusCode = serverResponse["status_code"];
+        this.url = serverResponse["url"];
+    }
+}
+exports.ApiRequest = ApiRequest;
+// For upcoming v4, use this as the base for all responses.
+// To not break compatibility, in v3.x, we will only use it as the base for async responses.
+class BasePredictResponse {
+    constructor(serverResponse) {
+        this.apiRequest = new ApiRequest(serverResponse["api_request"]);
+    }
+}
+exports.BasePredictResponse = BasePredictResponse;
+class AsyncPredictResponse extends BasePredictResponse {
+    constructor(serverResponse, document) {
+        super(serverResponse);
+        this.job = new Job(serverResponse["job"]);
+        this.document = document;
+    }
+}
+exports.AsyncPredictResponse = AsyncPredictResponse;