mindee 5.5.0 → 5.6.0

package/src/v1/client.d.ts

@@ -60,34 +60,34 @@ export interface WorkflowOptions extends BaseOptions {
      */
     publicUrl?: string;
 }
+/** Timer options forwarded to `setTimeout` in polling loops. */
+export interface TimerOptions {
+    /** Whether the timer should keep the event loop active. */
+    ref?: boolean;
+    /** Optional signal used to abort timer waits. */
+    signal?: AbortSignal;
+}
 /**
  * Asynchronous polling parameters.
  */
 export interface OptionalAsyncOptions extends PredictOptions {
+    /** Delay in seconds before the first polling attempt. */
     initialDelaySec?: number;
+    /** Delay in seconds between polling attempts. */
     delaySec?: number;
+    /** Maximum number of polling attempts. */
     maxRetries?: number;
-    initialTimerOptions?: {
-        ref?: boolean;
-        signal?: AbortSignal;
-    };
-    recurringTimerOptions?: {
-        ref?: boolean;
-        signal?: AbortSignal;
-    };
+    /** Timer options used for the first delay. */
+    initialTimerOptions?: TimerOptions;
+    /** Timer options used for recurring polling delays. */
+    recurringTimerOptions?: TimerOptions;
 }
 export interface AsyncOptions extends PredictOptions {
     initialDelaySec: number;
     delaySec: number;
     maxRetries: number;
-    initialTimerOptions?: {
-        ref?: boolean;
-        signal?: AbortSignal;
-    };
-    recurringTimerOptions?: {
-        ref?: boolean;
-        signal?: AbortSignal;
-    };
+    initialTimerOptions?: TimerOptions;
+    recurringTimerOptions?: TimerOptions;
 }
 export interface ClientOptions {
     /** Your API key for all endpoints. */

package/src/v1/extraction/invoiceSplitterExtractor/extractedInvoiceSplitterImage.d.ts

@@ -3,7 +3,9 @@ import { ExtractedPdf } from "../../../pdf/index.js";
  * Wrapper class for extracted invoice pages.
  */
 export declare class ExtractedInvoiceSplitterImage extends ExtractedPdf {
+    /** Start page index of the extracted invoice segment. */
     readonly pageIdMin: number;
+    /** End page index of the extracted invoice segment. */
     readonly pageIdMax: number;
     constructor(bytes: Uint8Array, pageIndices: [number, number]);
 }

package/src/v1/extraction/invoiceSplitterExtractor/invoiceSplitterExtractor.js

@@ -3,6 +3,9 @@ import { InvoiceSplitterV1 } from "../../../v1/product/index.js";
 import { ExtractedInvoiceSplitterImage } from "../../../v1/extraction/index.js";
 import { loadOptionalDependency } from "../../../dependency/index.js";
 let pdfLib = null;
+/**
+ * Load the pdf-lib dependency.
+ */
 async function getPdfLib() {
     if (!pdfLib) {
         const pdfLibImport = await loadOptionalDependency("@cantoo/pdf-lib", "Text Embedding");
@@ -10,6 +13,12 @@ async function getPdfLib() {
     }
     return pdfLib;
 }
+/**
+ * Split the given PDF document into multiple PDF documents.
+ * @param pdfDoc PDF document.
+ * @param invoicePageGroups Page groups.
+ * @returns Extracted invoice splitter images.
+ */
 async function splitPdf(pdfDoc, invoicePageGroups) {
     const pdfLib = await getPdfLib();
     if (invoicePageGroups.length === 0) {
@@ -31,6 +40,11 @@ async function splitPdf(pdfDoc, invoicePageGroups) {
     }
     return generatedPdfs;
 }
+/**
+ * Load the PDF document from the given input file.
+ * @param inputFile Input file.
+ * @returns PDF document.
+ */
 async function getPdfDoc(inputFile) {
     const pdfLib = await getPdfLib();
     await inputFile.init();

package/src/v1/extraction/multiReceiptsExtractor/extractedMultiReceiptImage.d.ts

@@ -3,7 +3,9 @@ import { ExtractedImage } from "../../../image/index.js";
  * Wrapper class for extracted multiple-receipts images.
  */
 export declare class ExtractedMultiReceiptImage extends ExtractedImage {
+    /** Receipt index within the source page. */
     readonly receiptId: number;
+    /** Source page identifier. */
     readonly pageId: number;
     constructor(buffer: Uint8Array, pageId: number, receiptId: number);
 }

package/src/v1/extraction/multiReceiptsExtractor/multiReceiptsExtractor.js

@@ -4,6 +4,9 @@ import { ExtractedMultiReceiptImage } from "../../../v1/extraction/index.js";
 import { extractFromPage } from "../../../image/index.js";
 import { loadOptionalDependency } from "../../../dependency/index.js";
 let pdfLib = null;
+/**
+ * Load the pdf-lib dependency.
+ */
 async function getPdfLib() {
     if (!pdfLib) {
         const pdfLibImport = await loadOptionalDependency("@cantoo/pdf-lib", "Text Embedding");

package/src/v1/http/apiSettingsV1.d.ts

@@ -1,8 +1,13 @@
 import { BaseSettings, MindeeApiConstructorProps } from "../../http/baseSettings.js";
+/** Default account owner for built-in v1 APIs. */
 export declare const STANDARD_API_OWNER: string;
+/** Runtime settings container for v1 API calls. */
 export declare class ApiSettingsV1 extends BaseSettings {
+    /** Default headers sent with each v1 API request. */
     baseHeaders: Record<string, string>;
     constructor({ apiKey, dispatcher, }: MindeeApiConstructorProps);
+    /** Resolves the API key from environment variables. */
     protected apiKeyFromEnv(): string;
+    /** Resolves the API hostname from environment variables. */
     protected hostnameFromEnv(): string;
 }

package/src/v1/http/apiSettingsV1.js

@@ -1,10 +1,12 @@
 import { logger } from "../../logger.js";
 import { BaseSettings } from "../../http/baseSettings.js";
 import { MindeeConfigurationError } from "../../errors/index.js";
+/** Default account owner for built-in v1 APIs. */
 export const STANDARD_API_OWNER = "mindee";
 const API_V1_KEY_ENVVAR_NAME = "MINDEE_API_KEY";
 const API_V1_HOST_ENVVAR_NAME = "MINDEE_API_HOST";
 const DEFAULT_MINDEE_API_HOST = "api.mindee.net";
+/** Runtime settings container for v1 API calls. */
 export class ApiSettingsV1 extends BaseSettings {
     constructor({ apiKey, dispatcher, }) {
         super(apiKey, dispatcher);
@@ -18,6 +20,7 @@ export class ApiSettingsV1 extends BaseSettings {
             Authorization: `Token ${this.apiKey}`,
         };
     }
+    /** Resolves the API key from environment variables. */
     apiKeyFromEnv() {
         const envVarValue = process.env[API_V1_KEY_ENVVAR_NAME];
         if (envVarValue) {
@@ -26,6 +29,7 @@ export class ApiSettingsV1 extends BaseSettings {
         }
         return "";
     }
+    /** Resolves the API hostname from environment variables. */
     hostnameFromEnv() {
         const envVarValue = process.env[API_V1_HOST_ENVVAR_NAME];
         if (envVarValue) {

package/src/v1/http/errors.d.ts

@@ -1,6 +1,12 @@
 import { MindeeError } from "../../errors/index.js";
 import { StringDict } from "../../parsing/stringDict.js";
-import { BaseHttpResponse } from "../../http/apiCore.js";
+import { BaseHttpResponse } from "../../http/index.js";
+/**
+ * Handle the given error.
+ * @param urlName URL name.
+ * @param response Response.
+ * @param serverError Server error.
+ */
 export declare function handleError(urlName: string, response: BaseHttpResponse, serverError?: string): void;
 /**
  * `Error` wrapper for server (HTTP) errors.

package/src/v1/http/errors.js

@@ -1,109 +1,80 @@
 import { MindeeError } from "../../errors/index.js";
 import { errorHandler } from "../../errors/handler.js";
-export function handleError(urlName, response, serverError) {
-    let code;
+const HTML_ERROR_PATTERNS = [
+    ["Maximum pdf pages", { message: "TooManyPages", details: "Maximum amount of pdf pages reached." }],
+    ["Max file size is", { message: "FileTooLarge", details: "Maximum file size reached." }],
+    ["Invalid file type", { message: "InvalidFiletype", details: "Invalid file type." }],
+    ["Gateway timeout", { message: "RequestTimeout", details: "Request timed out." }],
+    ["Bad gateway", { message: "BadRequest", details: "Bad Gateway" }],
+    ["Too Many Requests", { message: "TooManyRequests", details: "Too Many Requests." }],
+];
+const ERROR_CLASSES_BY_CODE = new Map();
+/**
+ * Extract the status code from the given response.
+ * @param response Response.
+ * @returns Status code.
+ */
+function extractStatusCode(response) {
     try {
         if (response.data.api_request["status_code"] === 200 && response.data?.job?.error?.code) {
-            code = 500;
             response.data.api_request.error = response.data.job.error;
+            return 500;
         }
-        else if (response.data) {
-            code = response.data.api_request["status_code"];
+        if (response.data) {
+            return response.data.api_request["status_code"];
         }
     }
     catch {
-        code = 500;
+        return 500;
+    }
+    return undefined;
+}
+/**
+ * Extract the error object from an HTML error response body.
+ * @param reconstructed Reconstructed response body.
+ * @returns Error object.
+ */
+function errorObjFromHtml(reconstructed) {
+    for (const [needle, obj] of HTML_ERROR_PATTERNS) {
+        if (reconstructed.includes(needle)) {
+            return { ...obj };
+        }
     }
-    let errorObj;
+    return { message: "Unknown Server Error.", details: reconstructed };
+}
+/**
+ * Extract the error object from the given response.
+ * @param response Response.
+ * @returns Error object.
+ */
+function extractErrorObj(response) {
     try {
-        //Regular instances where the returned error is in JSON format.
-        errorObj = response.data.api_request.error;
+        // Regular instances where the returned error is in JSON format.
+        return response.data.api_request.error;
     }
     catch {
-        //Rare instances where errors are returned as HTML instead of JSON.
+        // Rare instances where errors are returned as HTML instead of JSON.
         if (!("reconstructedResponse" in response.data)) {
             response.data.reconstructedResponse = "";
         }
-        if (response.data.reconstructedResponse.includes("Maximum pdf pages")) {
-            errorObj = {
-                message: "TooManyPages",
-                details: "Maximum amount of pdf pages reached.",
-            };
-        }
-        else if (response.data.reconstructedResponse.includes("Max file size is")) {
-            errorObj = {
-                message: "FileTooLarge",
-                details: "Maximum file size reached.",
-            };
-        }
-        else if (response.data.reconstructedResponse.includes("Invalid file type")) {
-            errorObj = {
-                message: "InvalidFiletype",
-                details: "Invalid file type.",
-            };
-        }
-        else if (response.data.reconstructedResponse.includes("Gateway timeout")) {
-            errorObj = {
-                message: "RequestTimeout",
-                details: "Request timed out.",
-            };
-        }
-        else if (response.data.reconstructedResponse.includes("Bad gateway")) {
-            errorObj = {
-                message: "BadRequest",
-                details: "Bad Gateway",
-            };
-        }
-        else if (response.data.reconstructedResponse.includes("Too Many Requests")) {
-            errorObj = {
-                message: "TooManyRequests",
-                details: "Too Many Requests.",
-            };
-        }
-        else {
-            errorObj = {
-                message: "Unknown Server Error.",
-                details: response.data.reconstructedResponse,
-            };
-        }
+        return errorObjFromHtml(response.data.reconstructedResponse);
     }
+}
+/**
+ * Handle the given error.
+ * @param urlName URL name.
+ * @param response Response.
+ * @param serverError Server error.
+ */
+export function handleError(urlName, response, serverError) {
+    const code = extractStatusCode(response);
+    const errorObj = extractErrorObj(response);
     if (serverError !== undefined &&
-        (!("message" in errorObj) ||
-            !errorObj.message ||
-            errorObj.message.length === 0)) {
+        (!("message" in errorObj) || !errorObj.message || errorObj.message.length === 0)) {
         errorObj.message = serverError;
     }
-    let errorToThrow;
-    switch (code) {
-        case 400:
-            errorToThrow = new MindeeHttp400Error(errorObj, urlName, code);
-            break;
-        case 401:
-            errorToThrow = new MindeeHttp401Error(errorObj, urlName, code);
-            break;
-        case 403:
-            errorToThrow = new MindeeHttp403Error(errorObj, urlName, code);
-            break;
-        case 404:
-            errorToThrow = new MindeeHttp404Error(errorObj, urlName, code);
-            break;
-        case 413:
-            errorToThrow = new MindeeHttp413Error(errorObj, urlName, code);
-            break;
-        case 429:
-            errorToThrow = new MindeeHttp429Error(errorObj, urlName, code);
-            break;
-        case 500:
-            errorToThrow = new MindeeHttp500Error(errorObj, urlName, code);
-            break;
-        case 504:
-            errorToThrow = new MindeeHttp504Error(errorObj, urlName, code);
-            break;
-        default:
-            errorToThrow = new MindeeHttpErrorV1(errorObj, urlName, code);
-            break;
-    }
-    errorHandler.throw(errorToThrow);
+    const errorClass = (code !== undefined && ERROR_CLASSES_BY_CODE.get(code)) || MindeeHttpErrorV1;
+    errorHandler.throw(new errorClass(errorObj, urlName, code));
 }
 /**
  * `Error` wrapper for server (HTTP) errors.
@@ -196,3 +167,11 @@ export class MindeeHttp504Error extends MindeeHttpErrorV1 {
         this.name = "MindeeHttp504Error";
     }
 }
+ERROR_CLASSES_BY_CODE.set(400, MindeeHttp400Error);
+ERROR_CLASSES_BY_CODE.set(401, MindeeHttp401Error);
+ERROR_CLASSES_BY_CODE.set(403, MindeeHttp403Error);
+ERROR_CLASSES_BY_CODE.set(404, MindeeHttp404Error);
+ERROR_CLASSES_BY_CODE.set(413, MindeeHttp413Error);
+ERROR_CLASSES_BY_CODE.set(429, MindeeHttp429Error);
+ERROR_CLASSES_BY_CODE.set(500, MindeeHttp500Error);
+ERROR_CLASSES_BY_CODE.set(504, MindeeHttp504Error);

package/src/v1/http/httpParams.d.ts

@@ -1,19 +1,31 @@
 import { InputSource, PageOptions } from "../../input/index.js";
 import { ExecutionPriority } from "../../v1/parsing/common/index.js";
 interface HTTPParams {
+    /** Input source to submit to the API. */
     inputDoc: InputSource;
+    /** Enables full-text OCR output when supported. */
     fullText: boolean;
+    /** Optional local page filtering options applied before upload. */
     pageOptions?: PageOptions;
+    /** Enables Retrieval-Augmented Generation when supported. */
     rag?: boolean;
 }
+/** Parameters sent to synchronous/asynchronous prediction endpoints. */
 export interface PredictParams extends HTTPParams {
+    /** Enables word-level OCR details in the response. */
     includeWords: boolean;
+    /** Enables cropper extras in the response. */
     cropper: boolean;
+    /** Optional workflow ID used for workflow-backed inference. */
     workflowId?: string;
 }
+/** Parameters sent to workflow execution endpoints. */
 export interface WorkflowParams extends HTTPParams {
+    /** Custom alias assigned to the submitted file. */
     alias?: string;
+    /** Processing priority of the workflow execution. */
     priority?: ExecutionPriority;
+    /** Whether to request a public validation URL. */
     publicUrl?: string;
 }
 export {};

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

@@ -22,6 +22,10 @@ export declare class Job {
     milliSecsTaken?: number;
     constructor(jsonResponse: StringDict);
 }
+/**
+ * Parse a date string into UTC.
+ * @param date Date string.
+ */
 export declare function datetimeWithTimezone(date: string): Date;
 /** Wrapper for asynchronous jobs and parsing results.
  *

package/src/v1/parsing/common/asyncPredictResponse.js

@@ -20,9 +20,12 @@ export class Job {
         }
     }
 }
-// Hideous thing to make sure dates sent back by the server are parsed correctly in UTC.
+/**
+ * Parse a date string into UTC.
+ * @param date Date string.
+ */
 export function datetimeWithTimezone(date) {
-    if (date.search(/\+[0-9]{2}:[0-9]{2}$/) === -1) {
+    if (date.search(/\+\d{2}:\d{2}$/) === -1) {
         date += "+00:00";
     }
     return new Date(date);

package/src/v1/parsing/common/executionPriority.d.ts

@@ -1,5 +1,9 @@
+/** Execution priority levels available for workflow requests. */
 export declare enum ExecutionPriority {
+    /** Low-priority background processing. */
     low = "low",
+    /** Standard processing priority. */
     medium = "medium",
+    /** High-priority processing. */
     high = "high"
 }

package/src/v1/parsing/common/executionPriority.js

@@ -1,6 +1,10 @@
+/** Execution priority levels available for workflow requests. */
 export var ExecutionPriority;
 (function (ExecutionPriority) {
+    /** Low-priority background processing. */
     ExecutionPriority["low"] = "low";
+    /** Standard processing priority. */
     ExecutionPriority["medium"] = "medium";
+    /** High-priority processing. */
     ExecutionPriority["high"] = "high";
 })(ExecutionPriority || (ExecutionPriority = {}));

package/src/v1/parsing/common/extras/cropperExtra.d.ts

@@ -1,7 +1,9 @@
 import { PositionField } from "../../../../v1/parsing/standard/position.js";
 import { StringDict } from "../../../../parsing/stringDict.js";
 import { ExtraField } from "./extras.js";
+/** Cropper extra payload returned by compatible APIs. */
 export declare class CropperExtra extends ExtraField {
+    /** Cropped regions detected on the page. */
     cropping: PositionField[];
     constructor(rawPrediction: StringDict, pageId?: number);
     /**

package/src/v1/parsing/common/extras/cropperExtra.js

@@ -1,9 +1,12 @@
 import { PositionField } from "../../../../v1/parsing/standard/position.js";
+// eslint-disable-next-line no-restricted-imports
 import { cleanOutString } from "../summaryHelper.js";
 import { ExtraField } from "./extras.js";
+/** Cropper extra payload returned by compatible APIs. */
 export class CropperExtra extends ExtraField {
     constructor(rawPrediction, pageId) {
         super();
+        /** Cropped regions detected on the page. */
         this.cropping = [];
         if (rawPrediction["cropping"] !== undefined) {
             rawPrediction["cropping"].forEach((crop) => {

package/src/v1/parsing/common/extras/extras.d.ts

@@ -1,9 +1,12 @@
+/** Base class for optional extras attached to predictions. */
 export declare abstract class ExtraField {
 }
 interface ExtraDict<T extends ExtraField> {
     [key: string]: T | (() => string);
 }
+/** Dictionary-like container for extra fields. */
 export declare class Extras<ExtraT extends ExtraField = ExtraField> implements ExtraDict<ExtraT> {
+    /** Dynamic map of extra values keyed by extra name. */
     [key: string]: ExtraT | (() => string);
     constructor(fields: Record<string, ExtraT>);
     /**

package/src/v1/parsing/common/extras/extras.js

@@ -1,5 +1,7 @@
+/** Base class for optional extras attached to predictions. */
 export class ExtraField {
 }
+/** Dictionary-like container for extra fields. */
 export class Extras {
     constructor(fields) {
         if (Object.keys(fields).length > 0) {

package/src/v1/parsing/common/extras/fullTextOcrExtra.d.ts

@@ -1,7 +1,10 @@
 import { StringDict } from "../../../../parsing/stringDict.js";
 import { ExtraField } from "./extras.js";
+/** Full-text OCR extra payload returned by compatible APIs. */
 export declare class FullTextOcrExtra extends ExtraField {
+    /** Concatenated OCR content. */
     content?: string;
+    /** OCR language hints associated with the content. */
     languages?: string;
     constructor(rawPrediction: StringDict);
     /**

package/src/v1/parsing/common/extras/fullTextOcrExtra.js

@@ -1,4 +1,5 @@
 import { ExtraField } from "./extras.js";
+/** Full-text OCR extra payload returned by compatible APIs. */
 export class FullTextOcrExtra extends ExtraField {
     constructor(rawPrediction) {
         super();

package/src/v1/parsing/common/extras/ragExtra.d.ts

@@ -1,5 +1,6 @@
 import { ExtraField } from "./extras.js";
 import { StringDict } from "../../../../parsing/stringDict.js";
+/** RAG extra payload returned by compatible APIs. */
 export declare class RAGExtra extends ExtraField {
     /**
      * ID reference of the document matched by the Retrieval-Augmented Generation.

package/src/v1/parsing/common/extras/ragExtra.js

@@ -1,4 +1,5 @@
 import { ExtraField } from "./extras.js";
+/** RAG extra payload returned by compatible APIs. */
 export class RAGExtra extends ExtraField {
     constructor(rawPrediction) {
         super();

package/src/v1/parsing/common/feedback/feedbackResponse.js

@@ -1,3 +1,4 @@
+// eslint-disable-next-line no-restricted-imports
 import { ApiResponse } from "../apiResponse.js";
 /**
  * Wrapper for feedback response.

package/src/v1/parsing/common/index.d.ts

@@ -10,7 +10,7 @@ export { AsyncPredictResponse } from "./asyncPredictResponse.js";
 export { PredictResponse } from "./predictResponse.js";
 export { Prediction } from "./prediction.js";
 export { Page } from "./page.js";
-export { cleanOutString, lineSeparator, floatToString, cleanSpecialChars } from "./summaryHelper.js";
+export { cleanOutString, lineSeparator, floatToString, cleanSpecialChars, cleanAndTruncate } from "./summaryHelper.js";
 export * as extras from "./extras/index.js";
 export { parseDate } from "../../../parsing/dateParser.js";
 export { WorkflowResponse } from "./workflowResponse.js";

package/src/v1/parsing/common/index.js

@@ -9,7 +9,7 @@ export { AsyncPredictResponse } from "./asyncPredictResponse.js";
 export { PredictResponse } from "./predictResponse.js";
 export { Prediction } from "./prediction.js";
 export { Page } from "./page.js";
-export { cleanOutString, lineSeparator, floatToString, cleanSpecialChars } from "./summaryHelper.js";
+export { cleanOutString, lineSeparator, floatToString, cleanSpecialChars, cleanAndTruncate } from "./summaryHelper.js";
 export * as extras from "./extras/index.js";
 export { parseDate } from "../../../parsing/dateParser.js";
 export { WorkflowResponse } from "./workflowResponse.js";

package/src/v1/parsing/common/inference.d.ts

@@ -4,6 +4,7 @@ import type { Prediction } from "./prediction.js";
 import { Product } from "./product.js";
 import { Extras } from "./extras/index.js";
 /**
+ * Generic base class for parsed v1 inference payloads.
  *
  * @typeParam DocT an extension of a `Prediction`. Is generic by default to
  * allow for easier optional `PageT` generic typing.
@@ -29,6 +30,7 @@ export declare abstract class Inference<DocT extends Prediction = Prediction, Pa
     /**
      * Default string representation.
      */
+    /** Returns a human-readable representation of the inference payload. */
     toString(): string;
     /**
      * Takes in an input string and replaces line breaks with `\n`.

package/src/v1/parsing/common/inference.js

@@ -1,6 +1,7 @@
 import { CropperExtra, FullTextOcrExtra, RAGExtra } from "./extras/index.js";
 import { MindeeConfigurationError } from "../../../errors/index.js";
 /**
+ * Generic base class for parsed v1 inference payloads.
  *
  * @typeParam DocT an extension of a `Prediction`. Is generic by default to
  * allow for easier optional `PageT` generic typing.
@@ -35,6 +36,7 @@ export class Inference {
     /**
      * Default string representation.
      */
+    /** Returns a human-readable representation of the inference payload. */
     toString() {
         let pages = "";
         if (this.pages.toString().length > 0) {

package/src/v1/parsing/common/prediction.d.ts

@@ -1,2 +1,3 @@
+/** Marker base type for v1 prediction payload models. */
 export declare class Prediction {
 }

package/src/v1/parsing/common/prediction.js

@@ -1,2 +1,3 @@
+/** Marker base type for v1 prediction payload models. */
 export class Prediction {
 }

package/src/v1/parsing/common/summaryHelper.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Cleans a string by removing all new line characters.
+ * @param outStr Output string.
+ */
 export declare function cleanOutString(outStr: string): string;
 /**
  *
@@ -9,9 +13,16 @@ export declare function lineSeparator(columnSizes: number[], separator: string):
 /**
  * Replaces all special characters like \n, \r, \t, with an equivalent that can be displayed on a single line.
  * Also trims line breaks at the end of the string.
- * @param outStr
+ * @param outStr Output string.
  */
 export declare function cleanSpecialChars(outStr: string): string;
+/**
+ * Cleans a string with `cleanSpecialChars` and truncates it to `maxLength` characters,
+ * appending "..." when truncation occurs. Returns an empty string for null/undefined/empty input.
+ * @param value String to clean and truncate.
+ * @param maxLength Maximum length of the returned string (including the "..." suffix when truncated).
+ */
+export declare function cleanAndTruncate(value: string | null | undefined, maxLength: number): string;
 /**
  * Return a float as a string with at least 2 levels of precision.
  */

package/src/v1/parsing/common/summaryHelper.js

@@ -1,3 +1,7 @@
+/**
+ * Cleans a string by removing all new line characters.
+ * @param outStr Output string.
+ */
 export function cleanOutString(outStr) {
     const lines = / \n/gm;
     return outStr.replace(lines, "\n");
@@ -18,7 +22,7 @@ export function lineSeparator(columnSizes, separator) {
 /**
  * Replaces all special characters like \n, \r, \t, with an equivalent that can be displayed on a single line.
  * Also trims line breaks at the end of the string.
- * @param outStr
+ * @param outStr Output string.
  */
 export function cleanSpecialChars(outStr) {
     return outStr
@@ -26,6 +30,19 @@ export function cleanSpecialChars(outStr) {
         .replace(/\r/g, "\\r")
         .replace(/\t/g, "\\t");
 }
+/**
+ * Cleans a string with `cleanSpecialChars` and truncates it to `maxLength` characters,
+ * appending "..." when truncation occurs. Returns an empty string for null/undefined/empty input.
+ * @param value String to clean and truncate.
+ * @param maxLength Maximum length of the returned string (including the "..." suffix when truncated).
+ */
+export function cleanAndTruncate(value, maxLength) {
+    if (!value) {
+        return "";
+    }
+    const cleaned = cleanSpecialChars(value);
+    return cleaned.length <= maxLength ? cleaned : cleaned.slice(0, maxLength - 3) + "...";
+}
 /**
  * Return a float as a string with at least 2 levels of precision.
  */