mindee 5.4.0 → 5.6.0

package/src/input/bufferInput.d.ts

@@ -3,8 +3,10 @@ interface BufferInputProps {
     buffer: Buffer;
     filename: string;
 }
+/** Local input source backed by an in-memory `Buffer`. */
 export declare class BufferInput extends LocalInputSource {
     constructor({ buffer, filename }: BufferInputProps);
+    /** Validates and initializes the in-memory buffer input. */
     init(): Promise<void>;
 }
 export {};

package/src/input/bufferInput.js

@@ -1,6 +1,7 @@
 import { LocalInputSource } from "./localInputSource.js";
 import { INPUT_TYPE_BUFFER } from "./inputSource.js";
 import { logger } from "../logger.js";
+/** Local input source backed by an in-memory `Buffer`. */
 export class BufferInput extends LocalInputSource {
     constructor({ buffer, filename }) {
         super({
@@ -9,6 +10,7 @@ export class BufferInput extends LocalInputSource {
         this.fileObject = buffer;
         this.filename = filename;
     }
+    /** Validates and initializes the in-memory buffer input. */
     async init() {
         if (this.initialized) {
             return;

package/src/input/bytesInput.d.ts

@@ -3,10 +3,13 @@ interface BytesInputProps {
     inputBytes: Uint8Array;
     filename: string;
 }
+/** Local input source backed by a `Uint8Array`. */
 export declare class BytesInput extends LocalInputSource {
     private inputBytes;
+    /** Binary payload built from the byte array. */
     fileObject: Buffer;
     constructor({ inputBytes, filename }: BytesInputProps);
+    /** Converts bytes to a buffer and validates MIME type. */
     init(): Promise<void>;
 }
 export {};

package/src/input/bytesInput.js

@@ -1,15 +1,18 @@
 import { INPUT_TYPE_BYTES } from "./inputSource.js";
 import { LocalInputSource } from "./localInputSource.js";
 import { logger } from "../logger.js";
+/** Local input source backed by a `Uint8Array`. */
 export class BytesInput extends LocalInputSource {
     constructor({ inputBytes, filename }) {
         super({
             inputType: INPUT_TYPE_BYTES,
         });
+        /** Binary payload built from the byte array. */
         this.fileObject = Buffer.alloc(0);
         this.filename = filename;
         this.inputBytes = inputBytes;
     }
+    /** Converts bytes to a buffer and validates MIME type. */
     async init() {
         if (this.initialized) {
             return;

package/src/input/inputSource.d.ts

@@ -10,9 +10,24 @@ export declare const INPUT_TYPE_BASE64 = "base64";
 export declare const INPUT_TYPE_BYTES = "bytes";
 export declare const INPUT_TYPE_PATH = "path";
 export declare const INPUT_TYPE_BUFFER = "buffer";
+/**
+ * Abstract class for input sources.
+ */
 export declare abstract class InputSource {
+    /**
+     * The file object used by the input source.
+     */
     fileObject: Buffer | string;
+    /**
+     * Whether the input source has been initialized.
+     * @protected
+     */
+    /** Whether the source has already been initialized. */
     protected initialized: boolean;
+    /** Initializes the input source and populates its file object. */
     init(): Promise<void>;
+    /**
+     * Returns whether the input source has been initialized.
+     */
     isInitialized(): boolean;
 }

package/src/input/inputSource.js

@@ -4,14 +4,29 @@ export const INPUT_TYPE_BASE64 = "base64";
 export const INPUT_TYPE_BYTES = "bytes";
 export const INPUT_TYPE_PATH = "path";
 export const INPUT_TYPE_BUFFER = "buffer";
+/**
+ * Abstract class for input sources.
+ */
 export class InputSource {
     constructor() {
+        /**
+         * The file object used by the input source.
+         */
         this.fileObject = "";
+        /**
+         * Whether the input source has been initialized.
+         * @protected
+         */
+        /** Whether the source has already been initialized. */
         this.initialized = false;
     }
+    /** Initializes the input source and populates its file object. */
     async init() {
         throw new MindeeInputSourceError("not Implemented");
     }
+    /**
+     * Returns whether the input source has been initialized.
+     */
     isInitialized() {
         return this.initialized;
     }

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,10 +1,16 @@
 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;
-    constructor(pdfData: Buffer<ArrayBufferLike>, filename: string, pageCount: number);
+    /** Zero-based indexes of pages included in this extracted PDF. */
+    readonly pageIndexes: number[];
+    constructor(pdfData: Buffer<ArrayBufferLike>, filename: string, pageIndexes: number[]);
     /**
      * Saves the document to a file.
      *
@@ -21,5 +27,5 @@ export declare class ExtractedPdf {
      *
      * @returns A BufferInput source.
      */
-    asSource(): BufferInput;
+    asInputSource(): BufferInput;
 }

package/src/pdf/extractedPdf.js

@@ -4,11 +4,13 @@ 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, pageCount) {
+    constructor(pdfData, filename, pageIndexes) {
         this.buffer = pdfData;
         this.filename = filename;
-        this.pageCount = pageCount;
+        this.pageCount = pageIndexes.length;
+        this.pageIndexes = pageIndexes;
     }
     /**
      * Saves the document to a file.
@@ -56,7 +58,7 @@ export class ExtractedPdf {
      *
      * @returns A BufferInput source.
      */
-    asSource() {
+    asInputSource() {
         return new BufferInput({
             buffer: this.buffer,
             filename: this.filename,

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.d.ts

@@ -1,5 +1,5 @@
 import { LocalInputSource } from "../input/index.js";
-import { ExtractedPdf } from "../pdf/extractedPdf.js";
+import { ExtractedPdfs } from "../pdf/extractedPdfs.js";
 export declare class PdfExtractor {
     /**
      * Buffer containing the PDF data.
@@ -42,5 +42,5 @@ export declare class PdfExtractor {
      * Extracts pages from the PDF.
      * @param pageIndexes
      */
-    extractSubDocuments(pageIndexes: number[][]): Promise<ExtractedPdf[]>;
+    extractSubDocuments(pageIndexes: number[][]): Promise<ExtractedPdfs>;
 }

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");
@@ -121,7 +124,7 @@ export class PdfExtractor {
             const endPage = String(pageRange[pageRange.length - 1] + 1).padStart(3, "0");
             const fieldFilename = `${splitName}_page_${startPage}-${endPage}.pdf`;
             const page = await extractPages(this.sourcePdf, pageOptions);
-            this.extractedPdfs.push(new ExtractedPdf(page.file, fieldFilename, pageRange.length));
+            this.extractedPdfs.push(new ExtractedPdf(page.file, fieldFilename, pageRange));
         }
         return this.extractedPdfs;
     }

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;