mindee 5.0.0-alpha2 → 5.0.0-rc1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## 5.0.0-rc1 - 2026-01-17
+### Changes
+* :boom: drop support for node.js 18
+* :boom: :recycle: separate polling options
+
+
 ## 5.0.0-alpha2 - 2026-01-16
 ### Changes
 * :recycle: use node test methods

package/package.json

@@ -1,9 +1,12 @@
 {
     "name": "mindee",
-    "version": "5.0.0-alpha2",
+    "version": "5.0.0-rc1",
     "description": "Mindee Client Library for Node.js",
     "main": "src/index.js",
-    "bin": "bin/mindee.js",
+    "bin": {
+        "mindeeV1": "bin/mindeeV1.js",
+        "mindeeV2": "bin/mindeeV2.js"
+    },
     "license": "MIT",
     "type": "module",
     "scripts": {
@@ -28,7 +31,7 @@
         "CHANGELOG.md"
     ],
     "engines": {
-        "node": ">= 18.17"
+        "node": ">= 20.1"
     },
     "repository": {
         "type": "git",
@@ -51,7 +54,7 @@
         "@typescript-eslint/parser": "^8.55.0",
         "eslint": "^9.39.2",
         "eslint-plugin-jsdoc": "^52.0.4",
-        "mocha": "^11.7.5",
+        "mocha": "^11.3.0",
         "tsc-alias": "^1.8.16",
         "tsx": "^4.21.0",
         "typedoc": "~0.28.16",
@@ -65,10 +68,10 @@
         "undici": "^6.23.0"
     },
     "optionalDependencies": {
-        "sharp": "~0.34.5",
         "@cantoo/pdf-lib": "^2.3.2",
+        "node-poppler": "^7.2.4",
         "pdf.js-extract": "^0.2.1",
-        "node-poppler": "^7.2.4"
+        "sharp": "~0.34.5"
     },
     "keywords": [
         "typescript",

package/src/v2/client/baseParameters.d.ts

@@ -1,5 +1,3 @@
-import { ValidatedPollingOptions } from "../../v2/client/pollingOptions.js";
-import { PollingOptions } from "../../v2/index.js";
 /**
  * Constructor parameters for BaseParameters and its subclasses.
  */
@@ -7,7 +5,6 @@ export interface BaseParametersConstructor {
     modelId: string;
     alias?: string;
     webhookIds?: string[];
-    pollingOptions?: PollingOptions;
     closeFile?: boolean;
 }
 /**
@@ -43,21 +40,12 @@ export declare abstract class BaseParameters {
      * If empty, no webhooks will be used.
      */
     webhookIds?: string[];
-    /**
-     * Client-side polling configuration (see {@link PollingOptions}).
-     */
-    pollingOptions?: PollingOptions;
     /**
      * By default, the file is closed once the upload is finished.
      * Set to `false` to keep it open.
      */
     closeFile?: boolean;
     protected constructor(params: BaseParametersConstructor);
-    /**
-     * Checks the values for asynchronous parsing. Returns their corrected value if they are undefined.
-     * @returns A valid `AsyncOptions`.
-     */
-    getValidatedPollingOptions(): ValidatedPollingOptions;
     /**
      * Returns the form data to send to the API.
      * @returns A `FormData` object.

package/src/v2/client/baseParameters.js

@@ -26,42 +26,6 @@ export class BaseParameters {
         this.alias = params.alias;
         this.webhookIds = params.webhookIds;
         this.closeFile = params.closeFile;
-        this.pollingOptions = params.pollingOptions;
-    }
-    /**
-     * Checks the values for asynchronous parsing. Returns their corrected value if they are undefined.
-     * @returns A valid `AsyncOptions`.
-     */
-    getValidatedPollingOptions() {
-        const minDelaySec = 1;
-        const minInitialDelay = 1;
-        const minRetries = 2;
-        let newAsyncParams;
-        if (this.pollingOptions === undefined) {
-            newAsyncParams = {
-                delaySec: 1.5,
-                initialDelaySec: 2,
-                maxRetries: 80
-            };
-        }
-        else {
-            newAsyncParams = { ...this.pollingOptions };
-            if (!newAsyncParams.delaySec ||
-                !newAsyncParams.initialDelaySec ||
-                !newAsyncParams.maxRetries) {
-                throw Error("Invalid polling options.");
-            }
-            if (newAsyncParams.delaySec < minDelaySec) {
-                throw Error(`Cannot set auto-parsing delay to less than ${minDelaySec} second(s).`);
-            }
-            if (newAsyncParams.initialDelaySec < minInitialDelay) {
-                throw Error(`Cannot set initial parsing delay to less than ${minInitialDelay} second(s).`);
-            }
-            if (newAsyncParams.maxRetries < minRetries) {
-                throw Error(`Cannot set retry to less than ${minRetries}.`);
-            }
-        }
-        return newAsyncParams;
     }
     /**
      * Returns the form data to send to the API.

package/src/v2/client/index.d.ts

@@ -1,2 +1,3 @@
-export type { PollingOptions, ValidatedPollingOptions } from "./pollingOptions.js";
+export { PollingOptions } from "./pollingOptions.js";
+export type { PollingOptionsConstructor } from "./pollingOptions.js";
 export { BaseParameters } from "./baseParameters.js";

package/src/v2/client/index.js

@@ -1 +1,2 @@
+export { PollingOptions } from "./pollingOptions.js";
 export { BaseParameters } from "./baseParameters.js";

package/src/v2/client/pollingOptions.d.ts

@@ -1,3 +1,14 @@
+export interface TimerOptions {
+    ref?: boolean;
+    signal?: AbortSignal;
+}
+export interface PollingOptionsConstructor {
+    initialDelaySec?: number;
+    delaySec?: number;
+    maxRetries?: number;
+    initialTimerOptions?: TimerOptions;
+    recurringTimerOptions?: TimerOptions;
+}
 /**
  * Parameters for the internal polling loop in `enqueueAndGetInference()`.
  *
@@ -24,13 +35,13 @@
  *
  * const inference = await client.enqueueAndGetInference(inputDoc, params);
  */
-export interface PollingOptions {
+export declare class PollingOptions {
     /** Number of seconds to wait *before the first poll*. */
-    initialDelaySec?: number;
+    initialDelaySec: number;
     /** Interval in seconds between two consecutive polls. */
-    delaySec?: number;
+    delaySec: number;
     /** Maximum number of polling attempts (including the first one). */
-    maxRetries?: number;
+    maxRetries: number;
     /** Options passed to the initial `setTimeout()`. */
     initialTimerOptions?: {
         ref?: boolean;
@@ -41,9 +52,7 @@ export interface PollingOptions {
         ref?: boolean;
         signal?: AbortSignal;
     };
-}
-export interface ValidatedPollingOptions extends PollingOptions {
-    initialDelaySec: number;
-    delaySec: number;
-    maxRetries: number;
+    constructor(params?: PollingOptionsConstructor);
+    validateOptions(): void;
+    toString(): string;
 }

package/src/v2/client/pollingOptions.js

@@ -1 +1,78 @@
-export {};
+import { MindeeConfigurationError } from "../../errors/index.js";
+import { logger } from "../../logger.js";
+const minInitialDelay = 1;
+const minDelaySec = 1;
+const minRetries = 2;
+/**
+ * Parameters for the internal polling loop in `enqueueAndGetInference()`.
+ *
+ * Default behavior:
+ * - `initialDelaySec` = 2s
+ * - `delaySec` = 1.5s
+ * - `maxRetries` = 80
+ *
+ * Validation rules:
+ * - `initialDelaySec` >= 1
+ * - `delaySec` >= 1
+ * - `maxRetries` >= 2
+ *
+ * The `initialTimerOptions` and `recurringTimerOptions` objects let you pass an
+ * `AbortSignal` or make the timer `unref`-ed to the `setTimeout()`.
+ *
+ * @category ClientV2
+ * @example
+ * const params = {
+ *   initialDelaySec: 4,
+ *   delaySec: 2,
+ *   maxRetries: 50
+ * };
+ *
+ * const inference = await client.enqueueAndGetInference(inputDoc, params);
+ */
+export class PollingOptions {
+    constructor(params) {
+        if (!params) {
+            params = {};
+        }
+        if (!params.initialDelaySec) {
+            this.initialDelaySec = 2;
+        }
+        else {
+            this.initialDelaySec = params.initialDelaySec;
+        }
+        if (!params.delaySec) {
+            this.delaySec = 1.5;
+        }
+        else {
+            this.delaySec = params.delaySec;
+        }
+        if (!params.maxRetries) {
+            this.maxRetries = 80;
+        }
+        else {
+            this.maxRetries = params.maxRetries;
+        }
+        if (params.initialTimerOptions) {
+            this.initialTimerOptions = params.initialTimerOptions;
+        }
+        if (params.recurringTimerOptions) {
+            this.recurringTimerOptions = params.recurringTimerOptions;
+        }
+        this.validateOptions();
+        logger.debug(`Polling options initialized: ${this.toString()}`);
+    }
+    validateOptions() {
+        if (this.delaySec < minDelaySec) {
+            throw new MindeeConfigurationError(`Cannot set auto-parsing delay to less than ${minDelaySec} second(s).`);
+        }
+        if (this.initialDelaySec < minInitialDelay) {
+            throw new MindeeConfigurationError(`Cannot set initial parsing delay to less than ${minInitialDelay} second(s).`);
+        }
+        if (this.maxRetries < minRetries) {
+            throw new MindeeConfigurationError(`Cannot set retry to less than ${minRetries}.`);
+        }
+    }
+    toString() {
+        return `{ initialDelaySec: ${this.initialDelaySec}, delaySec: ${this.delaySec}, maxRetries: ${this.maxRetries} }`;
+    }
+}

package/src/v2/client.d.ts

@@ -2,7 +2,7 @@ import { Dispatcher } from "undici";
 import { InputSource } from "../input/index.js";
 import { JobResponse } from "./parsing/index.js";
 import { MindeeApiV2 } from "./http/mindeeApiV2.js";
-import { ValidatedPollingOptions } from "./client/index.js";
+import { PollingOptions, PollingOptionsConstructor } from "./client/index.js";
 import { BaseProduct } from "../v2/product/baseProduct.js";
 /**
  * Options for the V2 Mindee Client.
@@ -65,15 +65,16 @@ export declare class Client {
      * @param inputSource file or URL to parse.
      * @param params parameters relating to prediction options.
      *
+     * @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]): Promise<InstanceType<P["responseClass"]>>;
+    enqueueAndGetResult<P extends typeof BaseProduct>(product: P, inputSource: InputSource, params: InstanceType<P["parametersClass"]> | ConstructorParameters<P["parametersClass"]>[0], pollingOptions?: PollingOptionsConstructor): Promise<InstanceType<P["responseClass"]>>;
     /**
      * Send a document to an endpoint and poll the server until the result is sent or
      * until the maximum number of tries is reached.
      * @protected
      */
-    protected pollForResult<P extends typeof BaseProduct>(product: typeof BaseProduct, pollingOptions: ValidatedPollingOptions, queueId: string): Promise<InstanceType<P["responseClass"]>>;
+    protected pollForResult<P extends typeof BaseProduct>(product: typeof BaseProduct, pollingOptions: PollingOptions, queueId: string): Promise<InstanceType<P["responseClass"]>>;
 }

package/src/v2/client.js

@@ -4,6 +4,7 @@ import { errorHandler } from "../errors/handler.js";
 import { LOG_LEVELS, logger } from "../logger.js";
 import { MindeeApiV2 } from "./http/mindeeApiV2.js";
 import { MindeeHttpErrorV2 } from "./http/errors.js";
+import { PollingOptions } from "./client/index.js";
 /**
  * Mindee Client V2 class that centralizes most basic operations.
  *
@@ -76,15 +77,16 @@ export class Client {
      * @param inputSource file or URL to parse.
      * @param params parameters relating to prediction options.
      *
+     * @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) {
+    async enqueueAndGetResult(product, inputSource, params, pollingOptions) {
         const paramsInstance = new product.parametersClass(params);
-        const pollingOptions = paramsInstance.getValidatedPollingOptions();
+        const pollingOptionsInstance = new PollingOptions(pollingOptions);
         const jobResponse = await this.enqueue(product, inputSource, paramsInstance);
-        return await this.pollForResult(product, pollingOptions, jobResponse.job.id);
+        return await this.pollForResult(product, pollingOptionsInstance, jobResponse.job.id);
     }
     /**
      * Send a document to an endpoint and poll the server until the result is sent or
@@ -114,8 +116,7 @@ export class Client {
             await setTimeout(pollingOptions.delaySec * 1000, undefined, pollingOptions.recurringTimerOptions);
             retryCounter++;
         }
-        throw new MindeeError("Asynchronous parsing request timed out after " +
-            pollingOptions.delaySec * retryCounter +
-            " seconds");
+        throw new MindeeError(`Polling failed to retrieve a result after ${retryCounter} attempts. ` +
+            "You can increase poll attempts by passing the pollingOptions argument to enqueueAndGetResult()");
     }
 }