mindee 4.0.1 → 4.0.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## v4.0.2 - 2023-08-24
+### Changes
+* :recycle: updated technical documentation
+
+### Fixes
+* :bug: fix url source document not being sent properly
+
+
 ## v4.0.1 - 2023-08-22
 ### Fixes
 * :bug: fixed pre-commit dependency script blocking installs

package/package.json

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

package/src/client.d.ts

@@ -4,10 +4,11 @@ import { Readable } from "stream";
 import { InputSource, PageOptions } from "./input";
 import { Endpoint } from "./http";
 import { Inference, AsyncPredictResponse, StringDict, PredictResponse } from "./parsing/common";
+/**
+ * Options relating to predictions.
+ */
 export interface PredictOptions {
-    endpointName?: string;
-    accountName?: string;
-    endpointVersion?: string;
+    /** A custom endpoint. */
     endpoint?: Endpoint;
     /**
      * Whether to include the full text for each page.
@@ -21,18 +22,11 @@ export interface PredictOptions {
      * This performs a cropping operation on the server and will increase response time.
      */
     cropper?: boolean;
-    pageOptions?: PageOptions;
-}
-export interface CustomConfigParams {
-    /** Your organization's username on the API Builder. */
-    accountName: string;
-    /** The "API name" field in the "Settings" page of the API Builder. */
-    endpointName: string;
     /**
-     * If set, locks the version of the model to use.
-     * If not set, use the latest version of the model.
+     * If set, remove pages from the document as specified.
+     * This is done before sending the file to the server and is useful to avoid page limitations.
      */
-    version?: string;
+    pageOptions?: PageOptions;
 }
 export interface ClientOptions {
     /** Your API key for all endpoints. */
@@ -43,35 +37,67 @@ export interface ClientOptions {
     debug?: boolean;
 }
 /**
- * Mindee Client
+ * Mindee Client class that centralizes most basic operations.
+ *
+ * @category Client
  */
 export declare class Client {
     #private;
+    /** Key of the API. */
     protected apiKey: string;
     /**
-     * @param options
+     * @param options options for the initialization of a client.
      */
     constructor({ apiKey, throwOnError, debug }?: ClientOptions);
     /**
      * Send a document to a synchronous endpoint and parse the predictions.
-     * @param productClass
-     * @param params
+     *
+     * @param productClass product class to use for calling the API and parsing the response.
+     * @param inputSource document to parse.
+     * @param params parameters relating to prediction options.
+     *
+     * @typeParam T an extension of an `Inference`. Can be omitted as it will be inferred from the `productClass`.
+     * @category Synchronous
+     * @returns a `Promise` containing parsing results.
      */
     parse<T extends Inference>(productClass: new (httpResponse: StringDict) => T, inputSource: InputSource, params?: PredictOptions): Promise<PredictResponse<T>>;
     /**
      * Send the document to an asynchronous endpoint and return its ID in the queue.
-     * @param productClass
-     * @param params
+     * @param productClass product class to use for calling  the API and parsing the response.
+     * @param params parameters relating to prediction options.
+     * @category Asynchronous
+     *
+     * @returns a `Promise` containing the job (queue) corresponding to a document.
      */
     enqueue<T extends Inference>(productClass: new (httpResponse: StringDict) => T, inputSource: InputSource, params?: PredictOptions): Promise<AsyncPredictResponse<T>>;
+    /**
+     * Polls a queue and returns its status as well as the prediction results if the parsing is done.
+     *
+     * @param productClass product class to use for calling  the API and parsing the response.
+     * @param queueId id of the queue to poll.
+     * @param params parameters relating to prediction options.
+     * @typeParam T an extension of an `Inference`. Can be omitted as it will be inferred from the `productClass`.
+     * @category Asynchronous
+     *
+     * @returns a `Promise` containing a `Job`, which also contains a `Document` if the
+     * parsing is complete.
+     */
     parseQueued<T extends Inference>(productClass: new (httpResponse: StringDict) => T, queueId: string, params?: PredictOptions): Promise<AsyncPredictResponse<T>>;
+    /**
+     * Forces boolean coercion on truthy/falsy parameters.
+     * @param param input parameter to check.
+     * @returns a strict boolean value.
+     */
     protected getBooleanParam(param?: boolean): boolean;
     /**
      * Creates a custom endpoint with the given values. Raises an error if the endpoint is invalid.
-     * @param productClass Class of the product
-     * @param endpointName Name of a custom Endpoint
-     * @param accountName Name of the account tied to the active Endpoint
-     * @param version Version of a custom Endpoint
+     * @param productClass product class to use for calling the API and parsing the response.
+     * @param endpointName Name of the custom Endpoint.
+     * @param accountName Name of the account tied to the Endpoint.
+     * @param version Version of the custom Endpoint.
+     * @typeParam T an extension of an `Inference`. Can be omitted as it will be inferred from the `productClass`.
+     *
+     * @returns a new endpoint
      */
     createEndpoint(endpointName: string, accountName: string, endpointVersion?: string): Endpoint;
     /**
@@ -81,31 +107,31 @@ export declare class Client {
     docFromPath(inputPath: string): InputSource;
     /**
      * Load an input document from a base64 encoded string.
-     * @param inputString
-     * @param filename
+     * @param inputString input content, as a string.
+     * @param filename file name.
      */
     docFromBase64(inputString: string, filename: string): InputSource;
     /**
      * Load an input document from a `stream.Readable` object.
-     * @param inputStream
-     * @param filename
+     * @param inputStream input content, as a readable stream.
+     * @param filename file name.
      */
     docFromStream(inputStream: Readable, filename: string): InputSource;
     /**
      * Load an input document from a bytes string.
-     * @param inputBytes
-     * @param filename
+     * @param inputBytes input content, as readable bytes.
+     * @param filename file name.
      */
     docFromBytes(inputBytes: string, filename: string): InputSource;
     /**
      * Load an input document from a URL.
-     * @param url
+     * @param url input url. Must be HTTPS.
      */
     docFromUrl(url: string): InputSource;
     /**
      * Load an input document from a Buffer.
-     * @param buffer
-     * @param filename
+     * @param buffer input content, as a buffer.
+     * @param filename file name.
      */
     docFromBuffer(buffer: Buffer, filename: string): InputSource;
 }

package/src/client.js

@@ -15,11 +15,13 @@ const logger_1 = require("./logger");
 const inference_1 = require("./parsing/common/inference");
 const product_1 = require("./product");
 /**
- * Mindee Client
+ * Mindee Client class that centralizes most basic operations.
+ *
+ * @category Client
  */
 class Client {
     /**
-     * @param options
+     * @param options options for the initialization of a client.
      */
     constructor({ apiKey, throwOnError, debug } = {
         apiKey: "",
@@ -37,8 +39,14 @@ class Client {
     }
     /**
      * Send a document to a synchronous endpoint and parse the predictions.
-     * @param productClass
-     * @param params
+     *
+     * @param productClass product class to use for calling the API and parsing the response.
+     * @param inputSource document to parse.
+     * @param params parameters relating to prediction options.
+     *
+     * @typeParam T an extension of an `Inference`. Can be omitted as it will be inferred from the `productClass`.
+     * @category Synchronous
+     * @returns a `Promise` containing parsing results.
      */
     async parse(productClass, inputSource, params = {
         endpoint: undefined,
@@ -60,8 +68,11 @@ class Client {
     }
     /**
      * Send the document to an asynchronous endpoint and return its ID in the queue.
-     * @param productClass
-     * @param params
+     * @param productClass product class to use for calling  the API and parsing the response.
+     * @param params parameters relating to prediction options.
+     * @category Asynchronous
+     *
+     * @returns a `Promise` containing the job (queue) corresponding to a document.
      */
     async enqueue(productClass, inputSource, params = {}) {
         const endpoint = params?.endpoint ?? __classPrivateFieldGet(this, _Client_instances, "m", _Client_initializeOTSEndpoint).call(this, productClass);
@@ -76,20 +87,40 @@ class Client {
         });
         return new common_1.AsyncPredictResponse(productClass, rawResponse.data);
     }
+    /**
+     * Polls a queue and returns its status as well as the prediction results if the parsing is done.
+     *
+     * @param productClass product class to use for calling  the API and parsing the response.
+     * @param queueId id of the queue to poll.
+     * @param params parameters relating to prediction options.
+     * @typeParam T an extension of an `Inference`. Can be omitted as it will be inferred from the `productClass`.
+     * @category Asynchronous
+     *
+     * @returns a `Promise` containing a `Job`, which also contains a `Document` if the
+     * parsing is complete.
+     */
     async parseQueued(productClass, queueId, params = {}) {
         const endpoint = params?.endpoint ?? __classPrivateFieldGet(this, _Client_instances, "m", _Client_initializeOTSEndpoint).call(this, productClass);
         const docResponse = await endpoint.getQueuedDocument(queueId);
         return new common_1.AsyncPredictResponse(productClass, docResponse.data);
     }
+    /**
+     * Forces boolean coercion on truthy/falsy parameters.
+     * @param param input parameter to check.
+     * @returns a strict boolean value.
+     */
     getBooleanParam(param) {
         return param !== undefined ? param : false;
     }
     /**
      * Creates a custom endpoint with the given values. Raises an error if the endpoint is invalid.
-     * @param productClass Class of the product
-     * @param endpointName Name of a custom Endpoint
-     * @param accountName Name of the account tied to the active Endpoint
-     * @param version Version of a custom Endpoint
+     * @param productClass product class to use for calling the API and parsing the response.
+     * @param endpointName Name of the custom Endpoint.
+     * @param accountName Name of the account tied to the Endpoint.
+     * @param version Version of the custom Endpoint.
+     * @typeParam T an extension of an `Inference`. Can be omitted as it will be inferred from the `productClass`.
+     *
+     * @returns a new endpoint
      */
     createEndpoint(endpointName, accountName, endpointVersion) {
         const cleanAccountName = __classPrivateFieldGet(this, _Client_instances, "m", _Client_cleanAccountName).call(this, product_1.CustomV1, accountName);
@@ -117,8 +148,8 @@ class Client {
     }
     /**
      * Load an input document from a base64 encoded string.
-     * @param inputString
-     * @param filename
+     * @param inputString input content, as a string.
+     * @param filename file name.
      */
     docFromBase64(inputString, filename) {
         return new input_1.Base64Input({
@@ -128,8 +159,8 @@ class Client {
     }
     /**
      * Load an input document from a `stream.Readable` object.
-     * @param inputStream
-     * @param filename
+     * @param inputStream input content, as a readable stream.
+     * @param filename file name.
      */
     docFromStream(inputStream, filename) {
         return new input_1.StreamInput({
@@ -139,8 +170,8 @@ class Client {
     }
     /**
      * Load an input document from a bytes string.
-     * @param inputBytes
-     * @param filename
+     * @param inputBytes input content, as readable bytes.
+     * @param filename file name.
      */
     docFromBytes(inputBytes, filename) {
         return new input_1.BytesInput({
@@ -150,7 +181,7 @@ class Client {
     }
     /**
      * Load an input document from a URL.
-     * @param url
+     * @param url input url. Must be HTTPS.
      */
     docFromUrl(url) {
         return new input_1.UrlInput({
@@ -159,8 +190,8 @@ class Client {
     }
     /**
      * Load an input document from a Buffer.
-     * @param buffer
-     * @param filename
+     * @param buffer input content, as a buffer.
+     * @param filename file name.
      */
     docFromBuffer(buffer, filename) {
         return new input_1.BufferInput({

package/src/http/endpoint.js

@@ -32,7 +32,7 @@ class Endpoint {
         }
         const response = await __classPrivateFieldGet(this, _Endpoint_instances, "m", _Endpoint_predictReqPost).call(this, params.inputDoc, params.includeWords, params.cropper);
         const statusCode = response.messageObj.statusCode;
-        if (statusCode === undefined || statusCode > 400) {
+        if (statusCode === undefined || statusCode >= 400) {
             (0, error_1.handleError)(this.urlName, response, statusCode);
         }
         return response;
@@ -44,7 +44,7 @@ class Endpoint {
         }
         const response = await __classPrivateFieldGet(this, _Endpoint_instances, "m", _Endpoint_predictAsyncReqPost).call(this, params.inputDoc, params.includeWords, params.cropper);
         const statusCode = response.messageObj.statusCode;
-        if (statusCode === undefined || statusCode > 400) {
+        if (statusCode === undefined || statusCode >= 400) {
             (0, error_1.handleError)(this.urlName, response, statusCode);
         }
         return response;
@@ -80,15 +80,13 @@ class Endpoint {
                 searchParams.append("cropper", "true");
             }
             const form = new form_data_1.default();
-            if (input instanceof base_1.LocalInputSource) {
-                if (input.fileObject instanceof Buffer) {
-                    form.append("document", input.fileObject, {
-                        filename: input.filename,
-                    });
-                }
-                else {
-                    form.append("document", input.fileObject);
-                }
+            if (input instanceof base_1.LocalInputSource && input.fileObject instanceof Buffer) {
+                form.append("document", input.fileObject, {
+                    filename: input.filename,
+                });
+            }
+            else {
+                form.append("document", input.fileObject);
             }
             if (includeWords) {
                 form.append("include_mvision", "true");

package/src/index.d.ts

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

package/src/input/base.d.ts

@@ -9,6 +9,7 @@ export declare const INPUT_TYPE_BYTES = "bytes";
 export declare const INPUT_TYPE_PATH = "path";
 export declare const INPUT_TYPE_BUFFER = "buffer";
 export declare abstract class InputSource {
+    fileObject: Buffer | string;
     init(): Promise<void>;
 }
 export declare abstract class LocalInputSource extends InputSource {

package/src/input/base.js

@@ -52,6 +52,9 @@ const ALLOWED_INPUT_TYPES = [
     exports.INPUT_TYPE_BUFFER,
 ];
 class InputSource {
+    constructor() {
+        this.fileObject = "";
+    }
     async init() {
         throw new Error("not Implemented");
     }

package/src/input/pageOptions.d.ts

@@ -1,3 +1,4 @@
+/** Options to pass to the `parse` method for cutting multi-page documents. */
 export interface PageOptions {
     /**
      * Zero-based list of page indexes.
@@ -14,7 +15,10 @@ export interface PageOptions {
      */
     onMinPages: number;
 }
+/** Operation to apply on the document, given the page indexes specified. */
 export declare enum PageOptionsOperation {
+    /** Only keep pages matching the provided indexes. */
     KeepOnly = "KEEP_ONLY",
+    /** Remove pages matching the provided indexes. */
     Remove = "REMOVE"
 }

package/src/input/pageOptions.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PageOptionsOperation = void 0;
+/** Operation to apply on the document, given the page indexes specified. */
 var PageOptionsOperation;
 (function (PageOptionsOperation) {
+    /** Only keep pages matching the provided indexes. */
     PageOptionsOperation["KeepOnly"] = "KEEP_ONLY";
+    /** Remove pages matching the provided indexes. */
     PageOptionsOperation["Remove"] = "REMOVE";
 })(PageOptionsOperation = exports.PageOptionsOperation || (exports.PageOptionsOperation = {}));

package/src/input/sources.d.ts

@@ -2,7 +2,7 @@
 /// <reference types="node" />
 import { Readable } from "stream";
 import { Buffer } from "buffer";
-import { LocalInputSource } from "./base";
+import { LocalInputSource, InputSource } from "./base";
 interface PathInputProps {
     inputPath: string;
 }
@@ -43,9 +43,8 @@ export declare class BytesInput extends LocalInputSource {
     constructor({ inputBytes, filename }: BytesInputProps);
     init(): Promise<void>;
 }
-export declare class UrlInput {
+export declare class UrlInput extends InputSource {
     private readonly url;
-    fileObject: string;
     constructor({ url }: {
         url: string;
     });

package/src/input/sources.js

@@ -106,8 +106,9 @@ exports.BytesInput = BytesInput;
 //
 // URL
 //
-class UrlInput {
+class UrlInput extends base_1.InputSource {
     constructor({ url }) {
+        super();
         this.url = url;
     }
     async init() {

package/src/parsing/common/apiRequest.d.ts

@@ -1,10 +1,19 @@
 import { StringDict } from "./stringDict";
+/**
+ * Holds the information relating to an API HTTP request.
+ *
+ * @category API Response
+ */
 export declare class ApiRequest {
+    /**  An object detailing the error. */
     error: StringDict;
+    /** Target of the request. */
     resources: string[];
+    /** Status of the request. Either "failure" or "success". */
     status: "failure" | "success";
     /** HTTP status code */
     statusCode: number;
+    /** URL of the request. */
     url: string;
     constructor(serverResponse: StringDict);
 }

package/src/parsing/common/apiRequest.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiRequest = void 0;
+/**
+ * Holds the information relating to an API HTTP request.
+ *
+ * @category API Response
+ */
 class ApiRequest {
     constructor(serverResponse) {
         this.error = serverResponse["error"];

package/src/parsing/common/apiResponse.d.ts

@@ -1,6 +1,15 @@
 import { ApiRequest } from "./apiRequest";
 import { StringDict } from "./stringDict";
+/** Base wrapper for API requests.
+ *
+ * @category API Response
+*/
 export declare abstract class ApiResponse {
+    /** Initial request sent to the API. */
     apiRequest: ApiRequest;
+    /**
+     *
+     * @param serverResponse JSON response from the server.
+     */
     constructor(serverResponse: StringDict);
 }

package/src/parsing/common/apiResponse.js

@@ -2,7 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiResponse = void 0;
 const apiRequest_1 = require("./apiRequest");
+/** Base wrapper for API requests.
+ *
+ * @category API Response
+*/
 class ApiResponse {
+    /**
+     *
+     * @param serverResponse JSON response from the server.
+     */
     constructor(serverResponse) {
         this.apiRequest = new apiRequest_1.ApiRequest(serverResponse["api_request"]);
     }

package/src/parsing/common/asyncPredictResponse.d.ts

@@ -2,20 +2,41 @@ import { ApiResponse } from "./apiResponse";
 import { StringDict } from "./stringDict";
 import { Inference } from "./inference";
 import { Document } from "./document";
+/** Wrapper for asynchronous request queues. Holds information regarding a job (queue).
+ *
+ * @category API Response
+ * @category Asynchronous
+*/
 export declare class Job {
+    /** Timestamp noting the enqueueing of a document. */
     issuedAt: Date;
+    /** Timestamp noting the availability of a prediction for an enqueued document. */
     availableAt?: Date;
+    /** ID of the job. */
     id: string;
+    /** Status of the job. */
     status?: "waiting" | "processing" | "completed";
-    /**
-     * The time taken to process the job, in milliseconds.
-     */
+    /** The time taken to process the job, in milliseconds. */
     milliSecsTaken?: number;
     constructor(jsonResponse: StringDict);
     protected datetimeWithTimezone(date: string): Date;
 }
+/** Wrapper for asynchronous jobs and parsing results.
+ *
+ * @category API Response
+ * @category Asynchronous
+*/
 export declare class AsyncPredictResponse<T extends Inference> extends ApiResponse {
+    /** Job for a queue. */
     job: Job;
+    /** Prediction for an asynchronous request. Will not be available so long as the job is not
+     * `completed`.
+     */
     document?: Document<T>;
+    /**
+     *
+     * @param inferenceClass constructor signature for an inference.
+     * @param httpResponse raw http response.
+     */
     constructor(inferenceClass: new (httpResponse: StringDict) => T, httpResponse: StringDict);
 }

package/src/parsing/common/asyncPredictResponse.js

@@ -3,6 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AsyncPredictResponse = exports.Job = void 0;
 const apiResponse_1 = require("./apiResponse");
 const document_1 = require("./document");
+/** Wrapper for asynchronous request queues. Holds information regarding a job (queue).
+ *
+ * @category API Response
+ * @category Asynchronous
+*/
 class Job {
     constructor(jsonResponse) {
         this.issuedAt = this.datetimeWithTimezone(jsonResponse["issued_at"]);
@@ -26,7 +31,17 @@ class Job {
     }
 }
 exports.Job = Job;
+/** Wrapper for asynchronous jobs and parsing results.
+ *
+ * @category API Response
+ * @category Asynchronous
+*/
 class AsyncPredictResponse extends apiResponse_1.ApiResponse {
+    /**
+     *
+     * @param inferenceClass constructor signature for an inference.
+     * @param httpResponse raw http response.
+     */
     constructor(inferenceClass, httpResponse) {
         super(httpResponse);
         this.job = new Job(httpResponse["job"]);

package/src/parsing/common/document.d.ts

@@ -2,12 +2,29 @@ import { Extras } from "./extras/extras";
 import { Inference } from "./inference";
 import { Ocr } from "./ocr";
 import { StringDict } from "./stringDict";
+/**
+ * Document prediction wrapper class. Holds the results of a parsed document.
+ * @typeParam T an extension of an `Inference`. Mandatory in order to properly create an inference.
+ */
 export declare class Document<T extends Inference> {
+    /** File name as sent back by the server. */
     filename: string;
+    /** Result of the base inference. */
     inference: T;
+    /** Id of the document as sent back by the server. */
     id: string;
+    /** Potential `Extras` fields sent back along the prediction. */
     extras?: Extras;
+    /** Raw-text response for `allWords` parsing. */
     ocr?: Ocr;
+    /**
+     *
+     * @param inferenceClass constructor signature for an inference.
+     * @param httpResponse raw http response.
+     */
     constructor(inferenceClass: new (httpResponse: StringDict) => T, httpResponse: StringDict);
+    /**
+     * Default string representation.
+     */
     toString(): string;
 }

package/src/parsing/common/document.js

@@ -3,14 +3,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Document = void 0;
 const cropperExtra_1 = require("./extras/cropperExtra");
 const extras_1 = require("./extras/extras");
+/**
+ * Document prediction wrapper class. Holds the results of a parsed document.
+ * @typeParam T an extension of an `Inference`. Mandatory in order to properly create an inference.
+ */
 class Document {
+    /**
+     *
+     * @param inferenceClass constructor signature for an inference.
+     * @param httpResponse raw http response.
+     */
     constructor(inferenceClass, httpResponse) {
-        this.id = httpResponse["id"] ?? "";
-        this.filename = httpResponse["name"] ?? "";
-        this.ocr = httpResponse["ocr"] ?? undefined;
+        this.id = httpResponse?.id ?? "";
+        this.filename = httpResponse?.name ?? "";
+        this.ocr = httpResponse?.ocr ?? undefined;
         this.inference = new inferenceClass(httpResponse["inference"]);
         // Note: this is a convoluted but functional way of being able to implement/use Extras fields
-        // as an extension of a Map object (like having an adapted toString() method, for instance)
+        // as an extension of a Map object (like having an adapted toString() method, for instance).
         if (httpResponse["extras"] &&
             Object.keys(httpResponse["extras"].length > 0)) {
             const extras = {};
@@ -23,6 +32,9 @@ class Document {
             this.extras = new extras_1.Extras(extras);
         }
     }
+    /**
+     * Default string representation.
+     */
     toString() {
         return `########\nDocument\n########
 :Mindee ID: ${this.id}