✨ add Job to inference responses (#445)

Author: ianardee

src/v2/client/baseParameters.ts

@@ -11,7 +11,7 @@ export interface BaseParametersConstructor {
 }
 
 /**
- * Parameters accepted by the asynchronous **inference** v2 endpoint.
+ * Parameters accepted by all v2 products.
  *
  * All fields are optional except `modelId`.
  *
@@ -22,10 +22,6 @@ export interface BaseParametersConstructor {
  *   rag: true,
  *   alias: "YOUR_ALIAS",
  *   webhookIds: ["YOUR_WEBHOOK_ID_1", "YOUR_WEBHOOK_ID_2"],
- *   pollingOptions: {
- *     initialDelaySec: 2,
- *     delaySec: 1.5,
- *   }
  * };
  */
 export abstract class BaseParameters {

src/v2/client/index.ts

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

src/v2/client/pollingOptions.ts

@@ -22,8 +22,8 @@ const minRetries = 2;
  * Parameters for the internal polling loop in `enqueueAndGetInference()`.
  *
  * Default behavior:
- * - `initialDelaySec` = 2s
- * - `delaySec` = 1.5s
+ * - `initialDelaySec` = 2
+ * - `delaySec` = 1.5
  * - `maxRetries` = 80
  *
  * Validation rules:
@@ -32,17 +32,21 @@ const minRetries = 2;
  * - `maxRetries` >= 2
  *
  * The `initialTimerOptions` and `recurringTimerOptions` objects let you pass an
- * `AbortSignal` or make the timer `unref`-ed to the `setTimeout()`.
+ * `AbortSignal` or make the timer `ref`-ed to the `setTimeout()`.
  *
  * @category ClientV2
  * @example
- * const params = {
+ * ```
+ * const pollingOptions = {
  *   initialDelaySec: 4,
  *   delaySec: 2,
  *   maxRetries: 50
  * };
  *
- * const inference = await client.enqueueAndGetInference(inputDoc, params);
+ * const inference = await client.enqueueAndGetInference(
+ *   inputDoc, params, pollingOptions
+ * );
+ * ```
  */
 export class PollingOptions {
   /** Number of seconds to wait *before the first poll*. */
@@ -52,15 +56,9 @@ export class PollingOptions {
   /** Maximum number of polling attempts (including the first one). */
   maxRetries: number;
   /** Options passed to the initial `setTimeout()`. */
-  initialTimerOptions?: {
-    ref?: boolean,
-    signal?: AbortSignal
-  };
+  initialTimerOptions?: TimerOptions;
   /** Options passed to every recurring `setTimeout()`. */
-  recurringTimerOptions?: {
-    ref?: boolean,
-    signal?: AbortSignal
-  };
+  recurringTimerOptions?: TimerOptions;
 
   constructor(params?: PollingOptionsConstructor) {
     if (!params) {

src/v2/http/apiSettingsV2.ts src/v2/http/apiSettings.tssrc/v2/http/apiSettingsV2.ts renamed to src/v2/http/apiSettings.ts

@@ -6,7 +6,7 @@ const API_V2_KEY_ENVVAR_NAME: string = "MINDEE_V2_API_KEY";
 const API_V2_HOST_ENVVAR_NAME: string = "MINDEE_V2_API_HOST";
 const DEFAULT_MINDEE_API_HOST: string = "api-v2.mindee.net";
 
-export class ApiSettingsV2 extends BaseSettings {
+export class ApiSettings extends BaseSettings {
   baseHeaders: Record<string, string>;
 
   constructor({
@@ -25,6 +25,7 @@ export class ApiSettingsV2 extends BaseSettings {
       "User-Agent": this.getUserAgent(),
       Authorization: `${this.apiKey}`,
     };
+    /* eslint-enable @typescript-eslint/naming-convention */
   }
 
   protected apiKeyFromEnv(): string {

src/v2/http/errors.ts

@@ -1,6 +1,9 @@
 import { ErrorDetails, ErrorItem, ErrorResponse } from "@/v2/parsing/index.js";
 import { MindeeError } from "@/errors/index.js";
 
+/**
+ * HTTP error returned by the API.
+ */
 export class MindeeHttpErrorV2 extends MindeeError implements ErrorDetails {
   public status: number;
   public detail: string;

src/v2/http/mindeeApiV2.ts

@@ -1,4 +1,4 @@
-import { ApiSettingsV2 } from "./apiSettingsV2.js";
+import { ApiSettings } from "./apiSettings.js";
 import { Dispatcher } from "undici";
 import { BaseParameters } from "@/v2/client/index.js";
 import {
@@ -16,10 +16,10 @@ import { BaseProduct } from "@/v2/product/baseProduct.js";
 
 
 export class MindeeApiV2 {
-  settings: ApiSettingsV2;
+  settings: ApiSettings;
 
   constructor(dispatcher?: Dispatcher, apiKey?: string) {
-    this.settings = new ApiSettingsV2({ dispatcher: dispatcher, apiKey: apiKey });
+    this.settings = new ApiSettings({ dispatcher: dispatcher, apiKey: apiKey });
   }
 
   /**
@@ -80,7 +80,10 @@ export class MindeeApiV2 {
     result: BaseHttpResponse,
     responseClass: ResponseConstructor<T>,
   ): T {
-    if (result.messageObj?.statusCode && (result.messageObj?.statusCode > 399 || result.messageObj?.statusCode < 200)) {
+    if (
+      result.messageObj?.statusCode
+      && (result.messageObj?.statusCode > 399 || result.messageObj?.statusCode < 200)
+    ) {
       if (result.data?.status !== null) {
         throw new MindeeHttpErrorV2(new ErrorResponse(result.data));
       }
@@ -98,7 +101,9 @@ export class MindeeApiV2 {
     try {
       return new responseClass(result.data);
     } catch (e) {
-      logger.error(`Raised '${e}' Couldn't deserialize response object:\n${JSON.stringify(result.data)}`);
+      logger.error(
+        `Raised '${e}' Couldn't deserialize response object:\n${JSON.stringify(result.data)}`
+      );
       throw new MindeeDeserializationError("Couldn't deserialize response object.");
     }
   }

src/v2/index.ts

@@ -7,4 +7,5 @@ export {
   ErrorResponse,
   LocalResponse,
 } from "./parsing/index.js";
-export type { PollingOptions, BaseParameters } from "./client/index.js";
+export type { BaseParameters, TimerOptions } from "./client/index.js";
+export { PollingOptions } from "./client/index.js";

src/v2/parsing/inference/baseInference.ts

@@ -1,12 +1,17 @@
+import { StringDict } from "@/parsing/index.js";
 import { InferenceModel } from "./inferenceModel.js";
 import { InferenceFile } from "./inferenceFile.js";
-import { StringDict } from "@/parsing/index.js";
+import { InferenceJob } from "./inferenceJob.js";
 
 export abstract class BaseInference {
   /**
    * Model info for the inference.
    */
   public model: InferenceModel;
+  /**
+   * Job the inference belongs to.
+   */
+  public job: InferenceJob;
   /**
    * File info for the inference.
    */
@@ -18,6 +23,7 @@ export abstract class BaseInference {
 
   protected constructor(serverResponse: StringDict) {
     this.id = serverResponse["id"];
+    this.job = new InferenceJob(serverResponse["job"]);
     this.model = new InferenceModel(serverResponse["model"]);
     this.file = new InferenceFile(serverResponse["file"]);
   }

src/v2/parsing/inference/inferenceJob.ts

@@ -0,0 +1,20 @@
+import { StringDict } from "@/parsing/stringDict.js";
+
+export class InferenceJob {
+  /**
+   * UUID of the Job.
+   */
+  public id: string;
+
+  constructor(serverResponse: StringDict) {
+    this.id = serverResponse["id"];
+  }
+
+  toString () {
+    return(
+      "Job\n" +
+      "===\n" +
+      `:ID: ${this.id}\n`
+    );
+  }
+}

src/v2/product/baseProduct.ts

@@ -1,6 +1,11 @@
 import { BaseParameters } from "@/v2/client/index.js";
 import { ResponseConstructor } from "@/v2/parsing/index.js";
 
+/**
+ * Base class for all V2 product definitions.
+ *
+ * Child classes are passed to the Client when making requests.
+ */
 export abstract class BaseProduct {
   static get parametersClass(): new (...args: any[]) => BaseParameters {
     throw new Error("Must define static parameters property");