mindee 5.5.0 → 5.6.0

package/src/input/localInputSource.d.ts

@@ -2,15 +2,21 @@ import { PageOptions } from "../input/pageOptions.js";
 import { InputSource, InputConstructor } from "./inputSource.js";
 export declare const MIMETYPES: Map<string, string>;
 export declare abstract class LocalInputSource extends InputSource {
+    /** Type of local input source (path, stream, bytes, ...). */
     inputType: string;
+    /** Original filename associated with the input. */
     filename: string;
+    /** Original filepath when available. */
     filepath?: string;
+    /** MIME type detected for the source content. */
     mimeType: string;
+    /** Binary payload for local sources. */
     fileObject: Buffer | string;
     /**
      * @param {InputConstructor} constructor Constructor parameters.
      */
     protected constructor({ inputType }: InputConstructor);
+    /** Detects and validates the MIME type from the current file object. */
     protected checkMimetype(): Promise<string>;
     /**
      * Returns the file object as a Buffer.

package/src/input/localInputSource.js

@@ -29,7 +29,9 @@ export class LocalInputSource extends InputSource {
      */
     constructor({ inputType }) {
         super();
+        /** Original filename associated with the input. */
         this.filename = "";
+        /** MIME type detected for the source content. */
         this.mimeType = "";
         // Check if inputType is valid
         if (!ALLOWED_INPUT_TYPES.includes(inputType)) {
@@ -39,6 +41,7 @@ export class LocalInputSource extends InputSource {
         this.inputType = inputType;
         logger.debug(`Initialized local input source of type: ${inputType}`);
     }
+    /** Detects and validates the MIME type from the current file object. */
     async checkMimetype() {
         if (!(this.fileObject instanceof Buffer)) {
             throw new MindeeInputSourceError(`MIME type cannot be verified on input source of type ${this.inputType}.`);

package/src/input/pathInput.d.ts

@@ -2,10 +2,14 @@ import { LocalInputSource } from "./localInputSource.js";
 interface PathInputProps {
     inputPath: string;
 }
+/** Local input source that reads a file from disk by path. */
 export declare class PathInput extends LocalInputSource {
+    /** Path used to read the local file. */
     readonly inputPath: string;
+    /** File content loaded from disk. */
     fileObject: Buffer;
     constructor({ inputPath }: PathInputProps);
+    /** Reads the file from disk and validates MIME type. */
     init(): Promise<void>;
 }
 export {};

package/src/input/pathInput.js

@@ -3,15 +3,18 @@ import { LocalInputSource } from "./localInputSource.js";
 import path from "path";
 import { logger } from "../logger.js";
 import { promises as fs } from "fs";
+/** Local input source that reads a file from disk by path. */
 export class PathInput extends LocalInputSource {
     constructor({ inputPath }) {
         super({
             inputType: INPUT_TYPE_PATH,
         });
+        /** File content loaded from disk. */
         this.fileObject = Buffer.alloc(0);
         this.inputPath = inputPath;
         this.filename = path.basename(this.inputPath);
     }
+    /** Reads the file from disk and validates MIME type. */
     async init() {
         if (this.initialized) {
             return;

package/src/input/streamInput.d.ts

@@ -4,11 +4,15 @@ interface StreamInputProps {
     inputStream: Readable;
     filename: string;
 }
+/** Local input source backed by a readable stream. */
 export declare class StreamInput extends LocalInputSource {
     private readonly inputStream;
+    /** Buffered payload created from the stream. */
     fileObject: Buffer;
     constructor({ inputStream, filename }: StreamInputProps);
+    /** Reads the stream to completion and validates MIME type. */
     init(): Promise<void>;
+    /** Converts a readable stream into a single buffer. */
     stream2buffer(stream: Readable, signal?: AbortSignal): Promise<Buffer>;
 }
 export {};

package/src/input/streamInput.js

@@ -2,15 +2,18 @@ import { LocalInputSource } from "./localInputSource.js";
 import { INPUT_TYPE_STREAM } from "./inputSource.js";
 import { logger } from "../logger.js";
 import { MindeeInputSourceError } from "../errors/index.js";
+/** Local input source backed by a readable stream. */
 export class StreamInput extends LocalInputSource {
     constructor({ inputStream, filename }) {
         super({
             inputType: INPUT_TYPE_STREAM,
         });
+        /** Buffered payload created from the stream. */
         this.fileObject = Buffer.alloc(0);
         this.filename = filename;
         this.inputStream = inputStream;
     }
+    /** Reads the stream to completion and validates MIME type. */
     async init() {
         if (this.initialized) {
             return;
@@ -20,6 +23,7 @@ export class StreamInput extends LocalInputSource {
         this.mimeType = await this.checkMimetype();
         this.initialized = true;
     }
+    /** Converts a readable stream into a single buffer. */
     async stream2buffer(stream, signal) {
         return new Promise((resolve, reject) => {
             if (stream.closed || stream.destroyed) {

package/src/input/urlInput.d.ts

@@ -1,15 +1,24 @@
 import { InputSource } from "./inputSource.js";
 import { Dispatcher } from "undici";
 import { BytesInput } from "./bytesInput.js";
+/** Remote input source represented by a validated HTTPS URL. */
 export declare class UrlInput extends InputSource {
+    /** HTTPS URL of the remote input file. */
     readonly url: string;
+    /** Dispatcher used for HTTP requests. */
     readonly dispatcher: Dispatcher;
     constructor({ url, dispatcher }: {
         url: string;
         dispatcher?: Dispatcher;
     });
+    /** Initializes this source by validating and storing the URL. */
     init(): Promise<void>;
+    /**
+     * Validates that a URL is safe to fetch: scheme must be https.
+     */
+    static validateUrl(url: string): void;
     private fetchFileContent;
+    /** Downloads the URL content and writes it to disk. */
     saveToFile(options: {
         filepath: string;
         filename?: string;
@@ -19,6 +28,7 @@ export declare class UrlInput extends InputSource {
         headers?: Record<string, string>;
         maxRedirects?: number;
     }): Promise<string>;
+    /** Downloads the URL content and returns it as a local bytes source. */
     asLocalInputSource(options?: {
         filename?: string;
         username?: string;
@@ -31,5 +41,7 @@ export declare class UrlInput extends InputSource {
     private static generateFileName;
     private static getFileExtension;
     private fillFilename;
+    private static maskCredentials;
+    private static isSameOrigin;
     private makeRequest;
 }

package/src/input/urlInput.js

@@ -7,6 +7,7 @@ import { request, getGlobalDispatcher } from "undici";
 import { logger } from "../logger.js";
 import { MindeeInputSourceError } from "../errors/index.js";
 import { BytesInput } from "./bytesInput.js";
+/** Remote input source represented by a validated HTTPS URL. */
 export class UrlInput extends InputSource {
     constructor({ url, dispatcher }) {
         super();
@@ -14,25 +15,43 @@ export class UrlInput extends InputSource {
         this.dispatcher = dispatcher ?? getGlobalDispatcher();
         logger.debug("Initialized URL input source.");
     }
+    /** Initializes this source by validating and storing the URL. */
     async init() {
         if (this.initialized) {
             return;
         }
-        logger.debug(`source URL: ${this.url}`);
-        if (!this.url.toLowerCase().startsWith("https")) {
-            throw new MindeeInputSourceError("URL must be HTTPS");
-        }
+        logger.debug(`source URL: ${UrlInput.maskCredentials(this.url)}`);
+        UrlInput.validateUrl(this.url);
         this.fileObject = this.url;
         this.initialized = true;
     }
+    /**
+     * Validates that a URL is safe to fetch: scheme must be https.
+     */
+    static validateUrl(url) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new MindeeInputSourceError("Invalid URL");
+        }
+        if (parsed.protocol !== "https:") {
+            throw new MindeeInputSourceError("URL must be HTTPS");
+        }
+    }
     async fetchFileContent(options) {
         const { username, password, token, headers = {}, maxRedirects = 3 } = options;
         if (token) {
             headers["Authorization"] = `Bearer ${token}`;
         }
-        const auth = username && password ? `${username}:${password}` : undefined;
-        return await this.makeRequest(this.url, auth, headers, 0, maxRedirects);
+        else if (username && password) {
+            const encoded = Buffer.from(`${username}:${password}`).toString("base64");
+            headers["Authorization"] = `Basic ${encoded}`;
+        }
+        return await this.makeRequest(this.url, headers, 0, maxRedirects);
     }
+    /** Downloads the URL content and writes it to disk. */
     async saveToFile(options) {
         const { filepath, filename, ...fetchOptions } = options;
         const { content, finalUrl } = await this.fetchFileContent(fetchOptions);
@@ -41,6 +60,7 @@ export class UrlInput extends InputSource {
         await writeFile(fullPath, content);
         return fullPath;
     }
+    /** Downloads the URL content and returns it as a local bytes source. */
     async asLocalInputSource(options = {}) {
         const { filename, ...fetchOptions } = options;
         const { content, finalUrl } = await this.fetchFileContent(fetchOptions);
@@ -68,21 +88,43 @@ export class UrlInput extends InputSource {
         }
         return filename;
     }
-    async makeRequest(url, auth, headers, redirects, maxRedirects) {
+    static maskCredentials(url) {
+        try {
+            const parsed = new URL(url);
+            if (parsed.username || parsed.password) {
+                parsed.username = "******";
+                parsed.password = "******";
+            }
+            return parsed.toString();
+        }
+        catch {
+            return url;
+        }
+    }
+    static isSameOrigin(a, b) {
+        const urlA = new URL(a);
+        const urlB = new URL(b);
+        return urlA.origin === urlB.origin;
+    }
+    async makeRequest(url, headers, redirects, maxRedirects) {
         const parsedUrl = new URL(url);
         const response = await request(parsedUrl, {
             method: "GET",
             headers: headers,
-            throwOnError: false,
             dispatcher: this.dispatcher,
         });
         if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400) {
-            logger.debug(`Redirecting to: ${response.headers.location}`);
+            logger.debug(`Redirecting to: ${UrlInput.maskCredentials(response.headers.location?.toString() ?? "")}`);
             if (redirects === maxRedirects) {
                 throw new MindeeInputSourceError(`Can't reach URL after ${redirects} out of ${maxRedirects} redirects, aborting operation.`);
             }
             if (response.headers.location) {
-                return await this.makeRequest(response.headers.location.toString(), auth, headers, redirects + 1, maxRedirects);
+                const redirectUrl = new URL(response.headers.location.toString(), url).toString();
+                UrlInput.validateUrl(redirectUrl);
+                const redirectHeaders = UrlInput.isSameOrigin(url, redirectUrl)
+                    ? headers
+                    : Object.fromEntries(Object.entries(headers).filter(([k]) => k.toLowerCase() !== "authorization"));
+                return await this.makeRequest(redirectUrl, redirectHeaders, redirects + 1, maxRedirects);
             }
             throw new MindeeInputSourceError("Redirect location not found");
         }

package/src/logger.js

@@ -10,7 +10,7 @@ class Logger {
         if (!(levelToSet in LOG_LEVELS)) {
             this.level = LOG_LEVELS["debug"];
         }
-        this.level = LOG_LEVELS[levelToSet];
+        this.level = LOG_LEVELS[levelToSet.toString()];
     }
     debug(...args) {
         if (this.level <= LOG_LEVELS["debug"])

package/src/parsing/dateParser.d.ts

@@ -1 +1,5 @@
+/**
+ * Parse a date string into a Date object.
+ * @param dateString The date string to parse.
+ */
 export declare function parseDate(dateString: string | null): Date | null;

package/src/parsing/dateParser.js

@@ -1,8 +1,12 @@
+/**
+ * Parse a date string into a Date object.
+ * @param dateString The date string to parse.
+ */
 export function parseDate(dateString) {
     if (!dateString) {
         return null;
     }
-    if (!/Z$/.test(dateString) && !/[+-][0-9]{2}:[0-9]{2}$/.test(dateString)) {
+    if (!/Z$/.test(dateString) && !/[+-]\d{2}:\d{2}$/.test(dateString)) {
         dateString += "Z";
     }
     return new Date(dateString);

package/src/parsing/localResponseBase.d.ts

@@ -7,11 +7,13 @@ import { Buffer } from "buffer";
 export declare abstract class LocalResponseBase {
     private file;
     private readonly inputHandle;
+    /** Whether the local response payload has been loaded. */
     protected initialized: boolean;
     /**
      * Creates an instance of LocalResponse.
      */
     constructor(inputFile: Buffer | string);
+    /** Loads the local payload from a string, buffer, or file path. */
     init(): Promise<void>;
     /**
      * Returns the dictionary representation of the file.

package/src/parsing/localResponseBase.js

@@ -11,10 +11,12 @@ export class LocalResponseBase {
      * Creates an instance of LocalResponse.
      */
     constructor(inputFile) {
+        /** Whether the local response payload has been loaded. */
         this.initialized = false;
         this.file = Buffer.alloc(0);
         this.inputHandle = inputFile;
     }
+    /** Loads the local payload from a string, buffer, or file path. */
     async init() {
         /**
          * @param inputFile - The input file, which can be a Buffer, string, or PathLike.

package/src/parsing/stringDict.d.ts

@@ -1,3 +1,4 @@
+/** Generic string-keyed dictionary used for raw API payloads. */
 export type StringDict = {
     [index: string]: any;
 };

package/src/pdf/extractedPdf.d.ts

@@ -1,9 +1,14 @@
 import { BufferInput } from "../input/index.js";
 import { Buffer } from "node:buffer";
+/** Represents a PDF artifact produced by an extraction/splitting operation. */
 export declare class ExtractedPdf {
+    /** Raw bytes of the extracted PDF segment. */
     readonly buffer: Buffer;
+    /** Filename suggested for export. */
     readonly filename: string;
+    /** Number of pages in this extracted PDF. */
     readonly pageCount: number;
+    /** Zero-based indexes of pages included in this extracted PDF. */
     readonly pageIndexes: number[];
     constructor(pdfData: Buffer<ArrayBufferLike>, filename: string, pageIndexes: number[]);
     /**

package/src/pdf/extractedPdf.js

@@ -4,6 +4,7 @@ import { MindeeError } from "../errors/index.js";
 import { writeFile } from "fs/promises";
 import { logger } from "../logger.js";
 import { writeFileSync } from "node:fs";
+/** Represents a PDF artifact produced by an extraction/splitting operation. */
 export class ExtractedPdf {
     constructor(pdfData, filename, pageIndexes) {
         this.buffer = pdfData;

package/src/pdf/extractedPdfs.d.ts

@@ -1,4 +1,5 @@
 import { ExtractedPdf } from "../pdf/extractedPdf.js";
+/** Collection of extracted PDF artifacts. */
 export declare class ExtractedPdfs extends Array<ExtractedPdf> {
     constructor(...items: ExtractedPdf[]);
 }

package/src/pdf/extractedPdfs.js

@@ -1,3 +1,4 @@
+/** Collection of extracted PDF artifacts. */
 export class ExtractedPdfs extends Array {
     constructor(...items) {
         super(...items);

package/src/pdf/pdfCompressor.js

@@ -3,6 +3,9 @@ import { compressImage } from "../image/index.js";
 import { loadOptionalDependency } from "../dependency/index.js";
 import { extractTextFromPdf, hasSourceText, rasterizePage } from "./pdfUtils.js";
 let pdfLib = null;
+/**
+ * Load the PDF library if not already loaded.
+ */
 async function getPdfLib() {
     if (!pdfLib) {
         const pdfLibImport = await loadOptionalDependency("@cantoo/pdf-lib", "Text Embedding");
@@ -155,6 +158,11 @@ async function createNewPdfFromCompressedPages(compressedPages) {
     const compressedPdfBytes = await newPdfDoc.save();
     return Buffer.from(compressedPdfBytes);
 }
+/**
+ * Add text to a PDF page.
+ * @param page The PDF page to add text to.
+ * @param textInfo The extracted text information to add to the page.
+ */
 async function addTextToPdfPage(page, textInfo) {
     if (textInfo === null) {
         return;
@@ -172,6 +180,10 @@ async function addTextToPdfPage(page, textInfo) {
         }
     }
 }
+/**
+ * Get a font from a given font name.
+ * @param fontName The name of the font to get.
+ */
 async function getFontFromName(fontName) {
     const pdfLib = await getPdfLib();
     const pdfDoc = await pdfLib.PDFDocument.create();

package/src/pdf/pdfExtractor.js

@@ -6,6 +6,9 @@ import { MindeeInputSourceError, MindeePdfError } from "../errors/index.js";
 import { ExtractedPdf } from "../pdf/extractedPdf.js";
 import { createPdfFromInputSource, extractPages } from "../pdf/pdfOperation.js";
 let pdfLib = null;
+/**
+ * Load the PDF library if not already loaded.
+ */
 async function getPdfLib() {
     if (!pdfLib) {
         const pdfLibImport = await loadOptionalDependency("@cantoo/pdf-lib", "Text Embedding");

package/src/pdf/pdfOperation.d.ts

@@ -1,8 +1,11 @@
 import type * as pdfLibTypes from "@cantoo/pdf-lib";
 import { PageOptions } from "../input/pageOptions.js";
 import { LocalInputSource } from "../input/index.js";
+/** Result of a PDF split/extract operation. */
 export interface SplitPdf {
+    /** PDF content after page extraction. */
     file: Buffer;
+    /** Number of pages removed from the source PDF. */
     totalPagesRemoved: number;
 }
 /**

package/src/pdf/pdfOperation.js

@@ -4,6 +4,9 @@ import { MindeeError, MindeeInputSourceError } from "../errors/index.js";
 import { logger } from "../logger.js";
 import { loadOptionalDependency } from "../dependency/index.js";
 let pdfLib = null;
+/**
+ * Load the PDF library if not already loaded.
+ */
 async function getPdfLib() {
     if (!pdfLib) {
         const pdfLibImport = await loadOptionalDependency("@cantoo/pdf-lib", "Text Embedding");

package/src/pdf/pdfUtils.js

@@ -3,6 +3,11 @@ import * as fs from "node:fs";
 import { MindeePdfError } from "../errors/index.js";
 import { loadOptionalDependency } from "../dependency/index.js";
 import { logger } from "../logger.js";
+/**
+ * Concatenate the text from all pages in a PDF document.
+ * @param pages The pages to concatenate.
+ * @returns The concatenated text.
+ */
 function getConcatenatedText(pages) {
     return pages.flatMap(page => page.content.map(item => item.str)).join(" ");
 }

package/src/v1/cli.d.ts

@@ -1 +1,4 @@
+/**
+ * Add the main CLI action.
+ */
 export declare function cli(): void;

package/src/v1/cli.js

@@ -1,18 +1,26 @@
-import { Command, Option, } from "commander";
-import { Client, } from "./client.js";
-import { PageOptionsOperation, PathInput, } from "../input/index.js";
+import { PageOptionsOperation, PathInput } from "../input/index.js";
+import { Command, Option } from "commander";
 import * as console from "console";
-import { CLI_COMMAND_CONFIG, COMMAND_GENERATED, } from "./product/cliProducts.js";
+import { Client } from "./client.js";
+import { CLI_COMMAND_CONFIG, COMMAND_GENERATED } from "./product/cliProducts.js";
 const program = new Command();
 //
 // EXECUTE THE COMMANDS
 //
+/**
+ * Load the client with the given options.
+ * @param options Command options.
+ */
 function initClient(options) {
     return new Client({
         apiKey: options.apiKey,
         debug: options.debug,
     });
 }
+/**
+ * Load the product configuration for the given command.
+ * @param command Command name.
+ */
 function getConfig(command) {
     const conf = CLI_COMMAND_CONFIG.get(command);
     if (conf === undefined) {
@@ -20,6 +28,10 @@ function getConfig(command) {
     }
     return conf;
 }
+/**
+ * Load the page options for the given command.
+ * @param options Command options.
+ */
 function getPageOptions(options) {
     let pageOptions = undefined;
     if (options.cutPages) {
@@ -31,12 +43,23 @@ function getPageOptions(options) {
     }
     return pageOptions;
 }
+/**
+ * Load the prediction parameters for the given command.
+ * @param options Command options.
+ */
 function getPredictParams(options) {
     return {
         allWords: options.allWords,
         cropper: options.cropper,
     };
 }
+/**
+ * Call the parse endpoint for the given command.
+ * @param productClass Product class.
+ * @param command Command name.
+ * @param inputPath Input path.
+ * @param options Command options.
+ */
 async function callParse(productClass, command, inputPath, options) {
     const mindeeClient = initClient(options);
     const predictParams = getPredictParams(options);
@@ -61,6 +84,13 @@ async function callParse(productClass, command, inputPath, options) {
     }
     printResponse(response.document, options);
 }
+/**
+ * Call the enqueue and parse endpoint for the given command.
+ * @param productClass Product class.
+ * @param command Command name.
+ * @param inputPath Input path.
+ * @param options Command options.
+ */
 async function callEnqueueAndParse(productClass, command, inputPath, options) {
     const mindeeClient = initClient(options);
     const predictParams = getPredictParams(options);
@@ -84,11 +114,22 @@ async function callEnqueueAndParse(productClass, command, inputPath, options) {
     }
     printResponse(response.document, options);
 }
+/**
+ * Call the get document endpoint for the given command.
+ * @param productClass Product class.
+ * @param documentId Document ID.
+ * @param options Command options.
+ */
 async function callGetDocument(productClass, documentId, options) {
     const mindeeClient = initClient(options);
     const response = await mindeeClient.getDocument(productClass, documentId);
     printResponse(response.document, options);
 }
+/**
+ * Print the response for the given command.
+ * @param document Document.
+ * @param options Command options.
+ */
 function printResponse(document, options) {
     if (options.allWords) {
         document.ocr?.mVisionV1.pages.forEach((page) => {
@@ -107,9 +148,18 @@ function printResponse(document, options) {
 //
 // BUILD THE COMMANDS
 //
+/**
+ * Add the main options to the given command.
+ * @param prog Command.
+ */
 function addMainOptions(prog) {
     prog.option("-k, --api-key <api_key>", "API key for document endpoint");
 }
+/**
+ * Add the post options to the given command.
+ * @param prog Command.
+ * @param info Product configuration.
+ */
 function addPostOptions(prog, info) {
     prog.option("-c, --cut-pages", "keep only the first 5 pages of the document");
     if (info.allWords) {
@@ -117,14 +167,28 @@ function addPostOptions(prog, info) {
     }
     prog.argument("<input_path>", "full path to the file");
 }
+/**
+ * Add the custom post options to the given command.
+ * @param prog Command.
+ */
 function addCustomPostOptions(prog) {
     prog.requiredOption("-e, --endpoint <endpoint_name>", "API endpoint name (required)");
     prog.requiredOption("-a, --account <account_name>", "API account name for the endpoint (required)");
     prog.option("-v, --version <version>", "version for the endpoint, use the latest version if not specified");
 }
+/**
+ * Add the display options to the given command.
+ * @param prog Command.
+ */
 function addDisplayOptions(prog) {
     prog.option("-p, --pages", "show content of individual pages");
 }
+/**
+ * Route the command to the appropriate action.
+ * @param command Command.
+ * @param inputPath Input path.
+ * @param allOptions All options.
+ */
 function routeSwitchboard(command, inputPath, allOptions) {
     if (command.parent === null || command.parent === undefined) {
         throw new Error(`Improperly configured command: ${command.name()}`);
@@ -135,30 +199,24 @@ function routeSwitchboard(command, inputPath, allOptions) {
     }
     return callParse(docClass, command.name(), inputPath, allOptions);
 }
+/**
+ * Add the predict action to the given command.
+ * @param prog Command.
+ */
 function addPredictAction(prog) {
-    if (prog.name() === COMMAND_GENERATED) {
-        prog.action(function (inputPath, options, command) {
-            const allOptions = {
-                ...prog.parent?.parent?.opts(),
-                ...prog.parent?.opts(),
-                ...prog.opts(),
-                ...options,
-            };
-            return routeSwitchboard(command, inputPath, allOptions);
-        });
-    }
-    else {
-        prog.action(function (inputPath, options, command) {
-            const allOptions = {
-                ...prog.parent?.parent?.opts(),
-                ...prog.parent?.opts(),
-                ...prog.opts(),
-                ...options,
-            };
-            return routeSwitchboard(command, inputPath, allOptions);
-        });
-    }
+    prog.action(function (inputPath, options, command) {
+        const allOptions = {
+            ...prog.parent?.parent?.opts(),
+            ...prog.parent?.opts(),
+            ...prog.opts(),
+            ...options,
+        };
+        return routeSwitchboard(command, inputPath, allOptions);
+    });
 }
+/**
+ * Add the main CLI action.
+ */
 export function cli() {
     program.name("mindee")
         .description("Command line interface for Mindee products.")