mindee 5.0.1 → 5.1.0

package/CHANGELOG.md

@@ -1,4 +1,18 @@
-# CHANGELOG
+# Mindee Node.js API Library Changelog
+
+
+## v5.1.0 - 2026-03-02
+### Changes
+* :sparkles: add to job information
+### Fixes
+* :bug: fix for printing crop results
+* :bug: proper init of webhook payload
+
+
+## v5.0.2 - 2026-02-27
+### Changes
+* :bug: always use the provided result URL
+
 
 ## v5.0.1 - 2026-02-24
 ### Changes

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mindee",
-    "version": "5.0.1",
+    "version": "5.1.0",
     "description": "Mindee Client Library for Node.js",
     "author": {
         "name": "Mindee",
@@ -61,7 +61,7 @@
     },
     "devDependencies": {
         "@types/mocha": "^10.0.10",
-        "@types/node": "^20.19.33",
+        "@types/node": "^20.19.35",
         "@types/tmp": "^0.2.6",
         "@typescript-eslint/eslint-plugin": "^8.56.1",
         "@typescript-eslint/parser": "^8.56.1",

package/src/geometry/polygon.js

@@ -37,6 +37,7 @@ export class Polygon extends Array {
         return isPointInY(point, yCoords.min, yCoords.max);
     }
     toString() {
-        return this.map((point) => `(${point})`).join(", ");
+        const points = this.map((point) => `(${point})`).join(", ");
+        return `(${points})`;
     }
 }

package/src/http/apiCore.d.ts

@@ -2,8 +2,8 @@ import { Dispatcher, FormData } from "undici";
 import { InputSource, PageOptions } from "../input/index.js";
 export declare const TIMEOUT_SECS_DEFAULT: number;
 export interface RequestOptions {
-    hostname: string;
-    path: string;
+    hostname?: string;
+    path?: string;
     method: any;
     timeoutSecs: number;
     headers: any;
@@ -25,6 +25,7 @@ export declare function cutDocPages(inputDoc: InputSource, pageOptions: PageOpti
  * Reads a response from the API and processes it.
  * @param dispatcher custom dispatcher to use for the request.
  * @param options options related to the request itself.
+ * @param url override the URL of the request.
  * @returns the processed request.
  */
-export declare function sendRequestAndReadResponse(dispatcher: Dispatcher, options: RequestOptions): Promise<BaseHttpResponse>;
+export declare function sendRequestAndReadResponse(dispatcher: Dispatcher, options: RequestOptions, url?: string): Promise<BaseHttpResponse>;

package/src/http/apiCore.js

@@ -16,11 +16,11 @@ export async function cutDocPages(inputDoc, pageOptions) {
  * Reads a response from the API and processes it.
  * @param dispatcher custom dispatcher to use for the request.
  * @param options options related to the request itself.
+ * @param url override the URL of the request.
  * @returns the processed request.
  */
-export async function sendRequestAndReadResponse(dispatcher, options) {
-    const url = `https://${options.hostname}${options.path}`;
-    logger.debug(`${options.method}: ${url}`);
+export async function sendRequestAndReadResponse(dispatcher, options, url) {
+    url ?? (url = `https://${options.hostname}${options.path}`);
     const response = await request(url, {
         method: options.method,
         headers: options.headers,

package/src/v2/client.d.ts

@@ -6,8 +6,6 @@ import { PollingOptions, PollingOptionsConstructor } from "./clientOptions/index
 import { BaseProduct } from "../v2/product/baseProduct.js";
 /**
  * Options for the V2 Mindee Client.
- *
- * @category ClientV2
  * @example
  * const client = new MindeeClientV2({
  *   apiKey: "YOUR_API_KEY",
@@ -25,8 +23,6 @@ export interface ClientOptions {
 }
 /**
  * Mindee Client V2 class that centralizes most basic operations.
- *
- * @category ClientV2
  */
 export declare class Client {
     /** Mindee V2 API handler. */
@@ -42,7 +38,6 @@ export declare class Client {
      * @param product the product to retrieve.
      * @param inferenceId id of the queue to poll.
      * @typeParam T an extension of an `Inference`. Can be omitted as it will be inferred from the `productClass`.
-     * @category Asynchronous
      * @returns a `Promise` containing the inference.
      */
     getResult<P extends typeof BaseProduct>(product: P, inferenceId: string): Promise<InstanceType<P["responseClass"]>>;
@@ -52,7 +47,6 @@ export declare class Client {
      *
      * @param jobId id of the queue to poll.
      * @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.
      */
@@ -67,7 +61,6 @@ export declare class Client {
      *
      * @param pollingOptions options for the polling loop, see {@link PollingOptions}.
      * @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.
      */
     enqueueAndGetResult<P extends typeof BaseProduct>(product: P, inputSource: InputSource, params: InstanceType<P["parametersClass"]> | ConstructorParameters<P["parametersClass"]>[0], pollingOptions?: PollingOptionsConstructor): Promise<InstanceType<P["responseClass"]>>;
@@ -76,5 +69,5 @@ export declare class Client {
      * until the maximum number of tries is reached.
      * @protected
      */
-    protected pollForResult<P extends typeof BaseProduct>(product: typeof BaseProduct, pollingOptions: PollingOptions, queueId: string): Promise<InstanceType<P["responseClass"]>>;
+    protected pollForResult<P extends typeof BaseProduct>(product: typeof BaseProduct, pollingOptions: PollingOptions, jobId: string): Promise<InstanceType<P["responseClass"]>>;
 }

package/src/v2/client.js

@@ -7,8 +7,6 @@ import { MindeeHttpErrorV2 } from "./http/errors.js";
 import { PollingOptions } from "./clientOptions/index.js";
 /**
  * Mindee Client V2 class that centralizes most basic operations.
- *
- * @category ClientV2
  */
 export class Client {
     /**
@@ -49,12 +47,11 @@ export class Client {
      * @param product the product to retrieve.
      * @param inferenceId id of the queue to poll.
      * @typeParam T an extension of an `Inference`. Can be omitted as it will be inferred from the `productClass`.
-     * @category Asynchronous
      * @returns a `Promise` containing the inference.
      */
     async getResult(product, inferenceId) {
         logger.debug(`Attempting to get inference with ID: ${inferenceId} using response type: ${product.name}`);
-        return await this.mindeeApi.getProductResult(product, inferenceId);
+        return await this.mindeeApi.getProductResultById(product, inferenceId);
     }
     /**
      * Get the processing status of a previously enqueued request.
@@ -62,7 +59,6 @@ export class Client {
      *
      * @param jobId id of the queue to poll.
      * @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.
      */
@@ -79,7 +75,6 @@ export class Client {
      *
      * @param pollingOptions options for the polling loop, see {@link PollingOptions}.
      * @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 enqueueAndGetResult(product, inputSource, params, pollingOptions) {
@@ -93,15 +88,15 @@ export class Client {
      * until the maximum number of tries is reached.
      * @protected
      */
-    async pollForResult(product, pollingOptions, queueId) {
+    async pollForResult(product, pollingOptions, jobId) {
         logger.debug(`Waiting ${pollingOptions.initialDelaySec} seconds before polling.`);
         await setTimeout(pollingOptions.initialDelaySec * 1000, undefined, pollingOptions.initialTimerOptions);
-        logger.debug(`Start polling for inference using job ID: ${queueId}.`);
+        logger.debug(`Start polling for inference using job ID: ${jobId}.`);
         let retryCounter = 1;
         let pollResults;
         while (retryCounter < pollingOptions.maxRetries + 1) {
             logger.debug(`Attempt ${retryCounter} of ${pollingOptions.maxRetries}`);
-            pollResults = await this.getJob(queueId);
+            pollResults = await this.getJob(jobId);
             const error = pollResults.job.error;
             if (error) {
                 throw new MindeeHttpErrorV2(error);
@@ -111,7 +106,10 @@ export class Client {
                 break;
             }
             if (pollResults.job.status === "Processed") {
-                return this.getResult(product, pollResults.job.id);
+                if (!pollResults.job.resultUrl) {
+                    throw new MindeeError("The result URL is undefined. This is a server error, try again later or contact support.");
+                }
+                return this.mindeeApi.getProductResultByUrl(product, pollResults.job.resultUrl);
             }
             await setTimeout(pollingOptions.delaySec * 1000, undefined, pollingOptions.recurringTimerOptions);
             retryCounter++;

package/src/v2/http/apiSettings.d.ts

@@ -1,4 +1,7 @@
 import { BaseSettings, MindeeApiConstructorProps } from "../../http/baseSettings.js";
+/**
+ * Settings for the V2 API.
+ */
 export declare class ApiSettings extends BaseSettings {
     baseHeaders: Record<string, string>;
     constructor({ apiKey, dispatcher, }: MindeeApiConstructorProps);

package/src/v2/http/apiSettings.js

@@ -4,6 +4,9 @@ import { MindeeConfigurationError } from "../../errors/index.js";
 const API_V2_KEY_ENVVAR_NAME = "MINDEE_V2_API_KEY";
 const API_V2_HOST_ENVVAR_NAME = "MINDEE_V2_API_HOST";
 const DEFAULT_MINDEE_API_HOST = "api-v2.mindee.net";
+/**
+ * Settings for the V2 API.
+ */
 export class ApiSettings extends BaseSettings {
     constructor({ apiKey, dispatcher, }) {
         super(apiKey, dispatcher);

package/src/v2/http/mindeeApiV2.d.ts

@@ -4,35 +4,43 @@ import { BaseParameters } from "../../v2/index.js";
 import { JobResponse } from "../../v2/parsing/index.js";
 import { InputSource } from "../../input/index.js";
 import { BaseProduct } from "../../v2/product/baseProduct.js";
+/**
+ * Mindee V2 API handler.
+ */
 export declare class MindeeApiV2 {
     #private;
     settings: ApiSettings;
     constructor(dispatcher?: Dispatcher, apiKey?: string);
     /**
-     * Sends a file to the extraction inference queue.
+     * Sends a file to the product inference queue.
      * @param product product to enqueue.
      * @param inputSource Local file loaded as an input.
      * @param params {ExtractionParameters} parameters relating to the enqueueing options.
-     * @category V2
-     * @throws Error if the server's response contains one.
+     * @throws Error if the server's response contains an error.
      * @returns a `Promise` containing a job response.
      */
     enqueueProduct(product: typeof BaseProduct, inputSource: InputSource, params: BaseParameters): Promise<JobResponse>;
     /**
-     * Requests the results of a queued document from the API.
-     * Throws an error if the server's response contains one.
-     * @param jobId The document's ID in the queue.
-     * @category Asynchronous
-     * @returns a `Promise` containing information on the queue.
+     * Get the specified Job.
+     * Throws an error if the server's response contains an error.
+     * @param jobId The Job ID as returned by the enqueue request.
+     * @returns a `Promise` containing the job response.
      */
     getJob(jobId: string): Promise<JobResponse>;
     /**
-     * Requests the job of a queued document from the API.
-     * Throws an error if the server's response contains one.
+     * Get the result of a queued document from the API.
+     * Throws an error if the server's response contains an error.
      * @param product
-     * @param inferenceId The document's ID in the queue.
-     * @category Asynchronous
-     * @returns a `Promise` containing either the parsed result, or information on the queue.
+     * @param inferenceId The inference ID for the result.
+     * @returns a `Promise` containing the parsed result.
      */
-    getProductResult<P extends typeof BaseProduct>(product: P, inferenceId: string): Promise<InstanceType<P["responseClass"]>>;
+    getProductResultById<P extends typeof BaseProduct>(product: P, inferenceId: string): Promise<InstanceType<P["responseClass"]>>;
+    /**
+     * Get the result of a queued document from the API.
+     * Throws an error if the server's response contains an error.
+     * @param product
+     * @param url The URL as returned by a Job's resultUrl property.
+     * @returns a `Promise` containing the parsed result.
+     */
+    getProductResultByUrl<P extends typeof BaseProduct>(product: P, url: string): Promise<InstanceType<P["responseClass"]>>;
 }

package/src/v2/http/mindeeApiV2.js

@@ -8,21 +8,23 @@ import { ApiSettings } from "./apiSettings.js";
 import { ErrorResponse, JobResponse, } from "../../v2/parsing/index.js";
 import { sendRequestAndReadResponse } from "../../http/apiCore.js";
 import { LocalInputSource } from "../../input/index.js";
-import { MindeeDeserializationError } from "../../errors/index.js";
+import { MindeeDeserializationError, MindeeError } from "../../errors/index.js";
 import { MindeeHttpErrorV2 } from "./errors.js";
 import { logger } from "../../logger.js";
+/**
+ * Mindee V2 API handler.
+ */
 export class MindeeApiV2 {
     constructor(dispatcher, apiKey) {
         _MindeeApiV2_instances.add(this);
         this.settings = new ApiSettings({ dispatcher: dispatcher, apiKey: apiKey });
     }
     /**
-     * Sends a file to the extraction inference queue.
+     * Sends a file to the product inference queue.
      * @param product product to enqueue.
      * @param inputSource Local file loaded as an input.
      * @param params {ExtractionParameters} parameters relating to the enqueueing options.
-     * @category V2
-     * @throws Error if the server's response contains one.
+     * @throws Error if the server's response contains an error.
      * @returns a `Promise` containing a job response.
      */
     async enqueueProduct(product, inputSource, params) {
@@ -34,26 +36,35 @@ export class MindeeApiV2 {
         return __classPrivateFieldGet(this, _MindeeApiV2_instances, "m", _MindeeApiV2_processResponse).call(this, result, JobResponse);
     }
     /**
-     * Requests the results of a queued document from the API.
-     * Throws an error if the server's response contains one.
-     * @param jobId The document's ID in the queue.
-     * @category Asynchronous
-     * @returns a `Promise` containing information on the queue.
+     * Get the specified Job.
+     * Throws an error if the server's response contains an error.
+     * @param jobId The Job ID as returned by the enqueue request.
+     * @returns a `Promise` containing the job response.
      */
     async getJob(jobId) {
         const response = await __classPrivateFieldGet(this, _MindeeApiV2_instances, "m", _MindeeApiV2_reqGetJob).call(this, jobId);
         return __classPrivateFieldGet(this, _MindeeApiV2_instances, "m", _MindeeApiV2_processResponse).call(this, response, JobResponse);
     }
     /**
-     * Requests the job of a queued document from the API.
-     * Throws an error if the server's response contains one.
+     * Get the result of a queued document from the API.
+     * Throws an error if the server's response contains an error.
+     * @param product
+     * @param inferenceId The inference ID for the result.
+     * @returns a `Promise` containing the parsed result.
+     */
+    async getProductResultById(product, inferenceId) {
+        const queueResponse = await __classPrivateFieldGet(this, _MindeeApiV2_instances, "m", _MindeeApiV2_reqGetProductResult).call(this, `https://${this.settings.hostname}/v2/products/${product.slug}/results/${inferenceId}`);
+        return __classPrivateFieldGet(this, _MindeeApiV2_instances, "m", _MindeeApiV2_processResponse).call(this, queueResponse, product.responseClass);
+    }
+    /**
+     * Get the result of a queued document from the API.
+     * Throws an error if the server's response contains an error.
      * @param product
-     * @param inferenceId The document's ID in the queue.
-     * @category Asynchronous
-     * @returns a `Promise` containing either the parsed result, or information on the queue.
+     * @param url The URL as returned by a Job's resultUrl property.
+     * @returns a `Promise` containing the parsed result.
      */
-    async getProductResult(product, inferenceId) {
-        const queueResponse = await __classPrivateFieldGet(this, _MindeeApiV2_instances, "m", _MindeeApiV2_reqGetProductResult).call(this, inferenceId, product.slug);
+    async getProductResultByUrl(product, url) {
+        const queueResponse = await __classPrivateFieldGet(this, _MindeeApiV2_instances, "m", _MindeeApiV2_reqGetProductResult).call(this, url);
         return __classPrivateFieldGet(this, _MindeeApiV2_instances, "m", _MindeeApiV2_processResponse).call(this, queueResponse, product.responseClass);
     }
 }
@@ -80,7 +91,6 @@ _MindeeApiV2_instances = new WeakSet(), _MindeeApiV2_processResponse = function
 }, _MindeeApiV2_reqPostProductEnqueue = 
 /**
  * Sends a document to the inference queue.
- *
  * @param product Product to enqueue.
  * @param inputSource Local or remote file as an input.
  * @param params {ExtractionParameters} parameters relating to the enqueueing options.
@@ -115,18 +125,17 @@ async function _MindeeApiV2_reqPostProductEnqueue(product, inputSource, params)
 }, _MindeeApiV2_reqGetProductResult = 
 /**
  * Make a request to GET the status of a document in the queue.
- * @param inferenceId ID of the inference.
- * @param slug "jobs" or "inferences"...
- * @category Asynchronous
- * @returns a `Promise` containing either the parsed result, or information on the queue.
+ * @param url URL path to the result.
+ * @returns a `Promise` containing the parsed result.
  */
-async function _MindeeApiV2_reqGetProductResult(inferenceId, slug) {
+async function _MindeeApiV2_reqGetProductResult(url) {
     const options = {
         method: "GET",
         headers: this.settings.baseHeaders,
-        hostname: this.settings.hostname,
-        path: `/v2/products/${slug}/results/${inferenceId}`,
         timeoutSecs: this.settings.timeoutSecs,
     };
-    return await sendRequestAndReadResponse(this.settings.dispatcher, options);
+    if (!url.startsWith("https://")) {
+        throw new MindeeError(`Invalid URL: ${url}`);
+    }
+    return await sendRequestAndReadResponse(this.settings.dispatcher, options, url);
 };

package/src/v2/parsing/inference/field/fieldLocation.d.ts

@@ -1,13 +1,13 @@
 import { Polygon } from "../../../../geometry/index.js";
 import { StringDict } from "../../../../parsing/stringDict.js";
 /**
- * Location of a field.
+ * A field's location on the document.
  */
 export declare class FieldLocation {
-    /** Free polygon made up of points (can be null when not provided). */
-    readonly polygon: Polygon | null;
-    /** Page ID. */
-    readonly page: number | undefined;
+    /** Position information as a list of points in clockwise order. */
+    readonly polygon: Polygon;
+    /** 0-based page index of where the polygon is located. */
+    readonly page: any;
     constructor(serverResponse: StringDict);
     toString(): string;
 }

package/src/v2/parsing/inference/field/fieldLocation.js

@@ -1,13 +1,13 @@
 import { Polygon } from "../../../../geometry/index.js";
 /**
- * Location of a field.
+ * A field's location on the document.
  */
 export class FieldLocation {
     constructor(serverResponse) {
-        this.polygon = "polygon" in serverResponse ? new Polygon(...serverResponse["polygon"]) : null;
-        this.page = "page" in serverResponse ? serverResponse["page"] : undefined;
+        this.polygon = new Polygon(...serverResponse["polygon"]);
+        this.page = serverResponse["page"];
     }
     toString() {
-        return this.polygon?.toString() ?? "";
+        return `${this.polygon} on page ${this.page}`;
     }
 }

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

@@ -14,9 +14,13 @@ export declare class Job {
      */
     error?: ErrorResponse;
     /**
-     * Timestamp of the job creation.
+     * Date and time of the Job creation.
      */
     createdAt: Date | null;
+    /**
+     * Date and time of the Job completion. Filled once processing is finished.
+     */
+    completedAt: Date | null | undefined;
     /**
      * ID of the model.
      */

package/src/v2/parsing/job/job.js

@@ -1,5 +1,6 @@
 import { parseDate } from "../../../parsing/index.js";
 import { ErrorResponse } from "../../../v2/index.js";
+import { JobWebhook } from "./jobWebhook.js";
 /**
  * Job information for a V2 polling attempt.
  */
@@ -9,17 +10,21 @@ export class Job {
         if (serverResponse["status"] !== undefined) {
             this.status = serverResponse["status"];
         }
-        if (serverResponse["error"] !== undefined &&
-            serverResponse["error"] !== null &&
-            Object.keys(serverResponse["error"]).length > 0) {
+        if (serverResponse["error"]) {
             this.error = new ErrorResponse(serverResponse["error"]);
         }
         this.createdAt = parseDate(serverResponse["created_at"]);
+        if (!serverResponse["completed_at"]) {
+            this.completedAt = undefined;
+        }
+        else {
+            this.completedAt = parseDate(serverResponse["completed_at"]);
+        }
         this.modelId = serverResponse["model_id"];
         this.pollingUrl = serverResponse["polling_url"];
         this.filename = serverResponse["filename"];
         this.resultUrl = serverResponse["result_url"];
         this.alias = serverResponse["alias"];
-        this.webhooks = serverResponse["webhooks"];
+        this.webhooks = (serverResponse["webhooks"] ?? []).map((webhook) => new JobWebhook(webhook));
     }
 }

package/src/v2/parsing/job/jobWebhook.js

@@ -8,7 +8,7 @@ export class JobWebhook {
         this.id = serverResponse["id"];
         this.createdAt = parseDate(serverResponse["created_at"]);
         this.status = serverResponse["status"];
-        if (serverResponse["error"] !== undefined) {
+        if (serverResponse["error"]) {
             this.error = new ErrorResponse(serverResponse["error"]);
         }
     }

package/src/v2/product/crop/cropItem.js

@@ -5,6 +5,6 @@ export class CropItem {
         this.location = new FieldLocation(serverResponse["location"]);
     }
     toString() {
-        return `${this.objectType}: ${this.location}`;
+        return `* :Location: ${this.location}\n  :Object Type: ${this.objectType}`;
     }
 }

package/src/v2/product/crop/cropResult.js

@@ -8,7 +8,7 @@ export class CropResult {
         this.crops = serverResponse["crops"].map((cropItem) => new CropItem(cropItem));
     }
     toString() {
-        const crops = this.crops.map(item => item.toString()).join("\n * ");
-        return `Crop\n====\n * ${crops}`;
+        const crops = this.crops.map(item => item.toString()).join("\n");
+        return `Crops\n=====\n${crops}`;
     }
 }