@kreuzberg/node 4.0.0-rc.8 → 4.0.1

package/index.d.ts

@@ -1,5 +1,10 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+/** Opaque handle to a worker pool */
+export declare class JsWorkerPool {
+
+}
+
 /**
  * Batch extract from multiple byte arrays (asynchronous).
  *
@@ -96,6 +101,40 @@ export declare function batchExtractBytesSync(dataList: Array<Buffer>, mimeTypes
  */
 export declare function batchExtractFiles(paths: Array<string>, config?: JsExtractionConfig | undefined | null): Promise<Array<JsExtractionResult>>
 
+/**
+ * Extract multiple files using worker threads from the pool.
+ *
+ * Submits multiple file extraction tasks to the worker pool for concurrent
+ * processing. Files are processed in parallel up to the pool size limit.
+ *
+ * # Parameters
+ *
+ * * `pool` - Worker pool handle
+ * * `file_paths` - Array of file paths to extract
+ * * `config` - Optional extraction configuration applied to all files
+ *
+ * # Returns
+ *
+ * Promise resolving to array of extraction results in the same order as input paths.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { createWorkerPool, batchExtractFilesInWorker } from '@kreuzberg/node';
+ *
+ * const pool = createWorkerPool(4);
+ * const files = ['doc1.pdf', 'doc2.docx', 'doc3.xlsx'];
+ * const results = await batchExtractFilesInWorker(pool, files, {
+ *   useCache: true
+ * });
+ *
+ * results.forEach((result, i) => {
+ *   console.log(`File ${i + 1}: ${result.content.length} chars`);
+ * });
+ * ```
+ */
+export declare function batchExtractFilesInWorker(pool: JsWorkerPool, filePaths: Array<string>, config?: JsExtractionConfig | undefined | null): Promise<Array<JsExtractionResult>>
+
 /**
  * Batch extract from multiple files (synchronous).
  *
@@ -125,6 +164,8 @@ export declare function batchExtractFiles(paths: Array<string>, config?: JsExtra
  */
 export declare function batchExtractFilesSync(paths: Array<string>, config?: JsExtractionConfig | undefined | null): Array<JsExtractionResult>
 
+export declare function classifyError(errorMessage: string): ErrorClassification
+
 /**
  * Clear all registered document extractors.
  *
@@ -165,6 +206,107 @@ export declare function clearPostProcessors(): void
 /** Clear all registered validators */
 export declare function clearValidators(): void
 
+/**
+ * Close and shutdown a worker pool gracefully.
+ *
+ * Waits for all in-flight extraction tasks to complete before shutting down
+ * the pool. After calling this function, the pool handle becomes invalid.
+ *
+ * # Parameters
+ *
+ * * `pool` - Worker pool handle
+ *
+ * # Returns
+ *
+ * Promise that resolves when all workers have completed and pool is closed.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { createWorkerPool, closeWorkerPool } from '@kreuzberg/node';
+ *
+ * const pool = createWorkerPool(4);
+ * // ... use pool for extractions ...
+ * await closeWorkerPool(pool); // Wait for completion and cleanup
+ * ```
+ */
+export declare function closeWorkerPool(pool: JsWorkerPool): Promise<void>
+
+/**
+ * Get a specific field from config (represented as JSON string) by name via FFI.
+ *
+ * Retrieves a configuration field by path, supporting nested access with
+ * dot notation (e.g., "ocr.backend"). Returns the field value as a JSON string.
+ *
+ * # Arguments
+ *
+ * * `json_str` - A JSON string representation of the configuration
+ * * `field_name` - The field path to retrieve (e.g., "useCache", "ocr.backend")
+ *
+ * # Returns
+ *
+ * The field value as a JSON string, or null if not found
+ */
+export declare function configGetFieldInternal(jsonStr: string, fieldName: string): string | null
+
+/**
+ * Merge two configs (override takes precedence over base) via FFI.
+ *
+ * Performs a shallow merge where fields from the override config take
+ * precedence over fields in the base config.
+ *
+ * # Arguments
+ *
+ * * `base_json` - A JSON string representation of the base ExtractionConfig
+ * * `override_json` - A JSON string representation of the override ExtractionConfig
+ *
+ * # Returns
+ *
+ * The merged configuration as a JSON string, or error
+ */
+export declare function configMergeInternal(baseJson: string, overrideJson: string): string
+
+/**
+ * Validate and normalize an ExtractionConfig JSON string via FFI.
+ *
+ * This validates the JSON and returns a normalized version, using the shared
+ * FFI layer to ensure consistent validation across all language bindings.
+ *
+ * # Arguments
+ *
+ * * `json_str` - A JSON string containing the configuration
+ *
+ * # Returns
+ *
+ * The normalized JSON string representation of the config, or error
+ */
+export declare function configValidateAndNormalize(jsonStr: string): string
+
+/**
+ * Create a new worker pool for concurrent extraction operations.
+ *
+ * Creates a pool of worker threads for CPU-bound document extraction.
+ * Tasks submitted to the pool will be executed concurrently up to the pool size.
+ *
+ * # Parameters
+ *
+ * * `size` - Number of concurrent workers (defaults to CPU count)
+ *
+ * # Returns
+ *
+ * Worker pool handle that can be used with extraction functions.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { createWorkerPool } from '@kreuzberg/node';
+ *
+ * const pool = createWorkerPool(4); // 4 concurrent workers
+ * console.log(`Pool created with ${pool.size} workers`);
+ * ```
+ */
+export declare function createWorkerPool(size?: number | undefined | null): JsWorkerPool
+
 /**
  * Detect MIME type from raw bytes.
  *
@@ -198,7 +340,7 @@ export declare function clearValidators(): void
  * console.log(mimeType); // 'application/pdf'
  * ```
  */
-export declare function detectMimeType(bytes: Buffer): string
+export declare function detectMimeTypeFromBytes(bytes: Buffer): string
 
 /**
  * Detect MIME type from a file path.
@@ -285,6 +427,53 @@ export interface EmbeddingPreset {
   description: string
 }
 
+/**
+ * Classifies an error message string into an error code category.
+ *
+ * This function analyzes the error message content and returns the most likely
+ * error code (0-7) based on keyword patterns. Used to programmatically classify
+ * errors for handling purposes.
+ *
+ * # Arguments
+ *
+ * * `error_message` - The error message string to classify
+ *
+ * # Returns
+ *
+ * An object with:
+ * - `code`: The numeric error code (0-7)
+ * - `name`: The error code name string
+ * - `description`: Brief description of the error type
+ * - `confidence`: Confidence score (0.0-1.0) of the classification
+ *
+ * # Classification Rules
+ *
+ * - **Validation (0)**: Keywords: invalid, validation, invalid_argument, schema, required, unexpected field
+ * - **Parsing (1)**: Keywords: parsing, parse_error, corrupted, malformed, invalid format, decode, encoding
+ * - **Ocr (2)**: Keywords: ocr, optical, character, recognition, tesseract, language, model
+ * - **MissingDependency (3)**: Keywords: not found, not installed, missing, dependency, require, unavailable
+ * - **Io (4)**: Keywords: io, file, disk, read, write, permission, access, path
+ * - **Plugin (5)**: Keywords: plugin, register, extension, handler, processor
+ * - **UnsupportedFormat (6)**: Keywords: unsupported, format, mime, type, codec
+ * - **Internal (7)**: Keywords: internal, bug, panic, unexpected, invariant
+ *
+ * # Examples
+ *
+ * ```typescript
+ * const result = classifyError("PDF file is corrupted");
+ * // Returns: { code: 1, name: "parsing", confidence: 0.95 }
+ *
+ * const result = classifyError("Tesseract not found");
+ * // Returns: { code: 3, name: "missing_dependency", confidence: 0.9 }
+ * ```
+ */
+export interface ErrorClassification {
+  code: number
+  name: string
+  description: string
+  confidence: number
+}
+
 /**
  * Extract content from bytes (asynchronous).
  *
@@ -383,6 +572,38 @@ export declare function extractBytesSync(data: Buffer, mimeType: string, config?
  */
 export declare function extractFile(filePath: string, mimeType?: string | undefined | null, config?: JsExtractionConfig | undefined | null): Promise<JsExtractionResult>
 
+/**
+ * Extract a file using a worker thread from the pool.
+ *
+ * Submits a file extraction task to the worker pool. The task will execute
+ * when a worker thread becomes available. This is useful for CPU-bound
+ * extraction operations that need to be run concurrently.
+ *
+ * # Parameters
+ *
+ * * `pool` - Worker pool handle
+ * * `file_path` - Path to the file to extract
+ * * `password` - Optional password for encrypted files
+ * * `config` - Optional extraction configuration
+ *
+ * # Returns
+ *
+ * Promise resolving to extraction result.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { createWorkerPool, extractFileInWorker } from '@kreuzberg/node';
+ *
+ * const pool = createWorkerPool(4);
+ * const result = await extractFileInWorker(pool, 'document.pdf', null, {
+ *   useCache: true
+ * });
+ * console.log(result.content);
+ * ```
+ */
+export declare function extractFileInWorker(pool: JsWorkerPool, filePath: string, password?: string | undefined | null, config?: JsExtractionConfig | undefined | null): Promise<JsExtractionResult>
+
 /**
  * Extract content from a file (synchronous).
  *
@@ -473,6 +694,52 @@ export declare function extractFileSync(filePath: string, mimeType?: string | un
  */
 export declare function getEmbeddingPreset(name: string): EmbeddingPreset | null
 
+/**
+ * Returns the description for an error code.
+ *
+ * Maps to FFI function kreuzberg_error_code_description().
+ *
+ * # Arguments
+ *
+ * * `code` - Numeric error code (0-7)
+ *
+ * # Returns
+ *
+ * A string containing a brief description of the error
+ *
+ * # Examples
+ *
+ * ```typescript
+ * const desc = getErrorCodeDescription(0);  // returns "Input validation error"
+ * const desc = getErrorCodeDescription(4);  // returns "File system I/O error"
+ * const desc = getErrorCodeDescription(99); // returns "Unknown error code"
+ * ```
+ */
+export declare function getErrorCodeDescription(code: number): string
+
+/**
+ * Returns the human-readable name for an error code.
+ *
+ * Maps to FFI function kreuzberg_error_code_name().
+ *
+ * # Arguments
+ *
+ * * `code` - Numeric error code (0-7)
+ *
+ * # Returns
+ *
+ * A string containing the error code name (e.g., "validation", "ocr", "unknown")
+ *
+ * # Examples
+ *
+ * ```typescript
+ * const name = getErrorCodeName(0);  // returns "validation"
+ * const name = getErrorCodeName(2);  // returns "ocr"
+ * const name = getErrorCodeName(99); // returns "unknown"
+ * ```
+ */
+export declare function getErrorCodeName(code: number): string
+
 /**
  * Get file extensions for a given MIME type.
  *
@@ -580,6 +847,112 @@ export declare function getLastErrorCode(): number
  */
 export declare function getLastPanicContext(): any | null
 
+/**
+ * Get valid binarization methods.
+ *
+ * Returns a list of all valid binarization method values.
+ *
+ * # Returns
+ *
+ * Array of valid binarization methods: ["otsu", "adaptive", "sauvola"]
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { getValidBinarizationMethods } from '@kreuzberg/node';
+ *
+ * const methods = getValidBinarizationMethods();
+ * console.log(methods); // ['otsu', 'adaptive', 'sauvola']
+ * ```
+ */
+export declare function getValidBinarizationMethods(): Array<string>
+
+/**
+ * Get valid language codes.
+ *
+ * Returns a list of all valid language codes in ISO 639-1 and 639-3 formats.
+ *
+ * # Returns
+ *
+ * Array of valid language codes (both 2-letter and 3-letter codes)
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { getValidLanguageCodes } from '@kreuzberg/node';
+ *
+ * const codes = getValidLanguageCodes();
+ * console.log(codes); // ['en', 'de', 'fr', ..., 'eng', 'deu', 'fra', ...]
+ * ```
+ */
+export declare function getValidLanguageCodes(): Array<string>
+
+/**
+ * Get valid OCR backends.
+ *
+ * Returns a list of all valid OCR backend values.
+ *
+ * # Returns
+ *
+ * Array of valid OCR backends: ["tesseract", "easyocr", "paddleocr"]
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { getValidOcrBackends } from '@kreuzberg/node';
+ *
+ * const backends = getValidOcrBackends();
+ * console.log(backends); // ['tesseract', 'easyocr', 'paddleocr']
+ * ```
+ */
+export declare function getValidOcrBackends(): Array<string>
+
+/**
+ * Get valid token reduction levels.
+ *
+ * Returns a list of all valid token reduction level values.
+ *
+ * # Returns
+ *
+ * Array of valid levels: ["off", "light", "moderate", "aggressive", "maximum"]
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { getValidTokenReductionLevels } from '@kreuzberg/node';
+ *
+ * const levels = getValidTokenReductionLevels();
+ * console.log(levels); // ['off', 'light', 'moderate', 'aggressive', 'maximum']
+ * ```
+ */
+export declare function getValidTokenReductionLevels(): Array<string>
+
+/**
+ * Get worker pool statistics.
+ *
+ * Returns current statistics about the worker pool including size,
+ * active workers, and queued tasks.
+ *
+ * # Parameters
+ *
+ * * `pool` - Worker pool handle
+ *
+ * # Returns
+ *
+ * Pool statistics object with size, activeWorkers, and queuedTasks fields.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { createWorkerPool, getWorkerPoolStats } from '@kreuzberg/node';
+ *
+ * const pool = createWorkerPool(4);
+ * const stats = getWorkerPoolStats(pool);
+ * console.log(`Active: ${stats.activeWorkers}/${stats.size}`);
+ * ```
+ */
+export declare function getWorkerPoolStats(pool: JsWorkerPool): WorkerPoolStats
+
 export interface JsChunk {
   content: string
   embedding?: number[] | undefined
@@ -675,6 +1048,21 @@ export interface JsExtractionResult {
   detectedLanguages?: Array<string>
   chunks?: Array<JsChunk>
   images?: Array<JsExtractedImage>
+  pages?: Array<JsPageContent>
+}
+
+export interface JsHierarchicalBlock {
+  text: string
+  fontSize: number
+  level: string
+  bbox?: [number, number, number, number] | undefined
+}
+
+export interface JsHierarchyConfig {
+  enabled?: boolean
+  kClusters?: number
+  includeBbox?: boolean
+  ocrCoverageThreshold?: number
 }
 
 export interface JsHtmlOptions {
@@ -755,10 +1143,24 @@ export interface JsPageConfig {
   markerFormat?: string
 }
 
+export interface JsPageContent {
+  pageNumber: number
+  content: string
+  tables: Array<JsTable>
+  images: Array<JsExtractedImage>
+  hierarchy?: JsPageHierarchy
+}
+
+export interface JsPageHierarchy {
+  blockCount: number
+  blocks: Array<JsHierarchicalBlock>
+}
+
 export interface JsPdfConfig {
   extractImages?: boolean
   passwords?: Array<string>
   extractMetadata?: boolean
+  hierarchy?: JsHierarchyConfig
 }
 
 export interface JsPostProcessorConfig {
@@ -1076,6 +1478,134 @@ export declare function unregisterPostProcessor(name: string): void
 /** Unregister a validator by name */
 export declare function unregisterValidator(name: string): void
 
+/**
+ * Validates a binarization method string.
+ *
+ * Valid methods: "otsu", "adaptive", "sauvola"
+ *
+ * # Arguments
+ *
+ * * `method` - The binarization method to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateBinarizationMethod } from '@kreuzberg/node';
+ *
+ * if (validateBinarizationMethod('otsu')) {
+ *   console.log('Valid method');
+ * } else {
+ *   console.log('Invalid method');
+ * }
+ * ```
+ */
+export declare function validateBinarizationMethod(method: string): boolean
+
+/**
+ * Validates chunking parameters.
+ *
+ * Checks that `maxChars > 0` and `maxOverlap < maxChars`.
+ *
+ * # Arguments
+ *
+ * * `max_chars` - Maximum characters per chunk
+ * * `max_overlap` - Maximum overlap between chunks
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateChunkingParams } from '@kreuzberg/node';
+ *
+ * if (validateChunkingParams(1000, 200)) {
+ *   console.log('Valid chunking parameters');
+ * }
+ * ```
+ */
+export declare function validateChunkingParams(maxChars: number, maxOverlap: number): boolean
+
+/**
+ * Validates a confidence threshold value.
+ *
+ * Valid range: 0.0 to 1.0 (inclusive)
+ *
+ * # Arguments
+ *
+ * * `confidence` - The confidence threshold to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateConfidence } from '@kreuzberg/node';
+ *
+ * if (validateConfidence(0.75)) {
+ *   console.log('Valid confidence threshold');
+ * }
+ * ```
+ */
+export declare function validateConfidence(confidence: number): boolean
+
+/**
+ * Validates a DPI (dots per inch) value.
+ *
+ * Valid range: 1-2400
+ *
+ * # Arguments
+ *
+ * * `dpi` - The DPI value to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateDpi } from '@kreuzberg/node';
+ *
+ * if (validateDpi(300)) {
+ *   console.log('Valid DPI');
+ * }
+ * ```
+ */
+export declare function validateDpi(dpi: number): boolean
+
+/**
+ * Validates a language code (ISO 639-1 or 639-3 format).
+ *
+ * Accepts both 2-letter codes (e.g., "en", "de") and 3-letter codes (e.g., "eng", "deu").
+ *
+ * # Arguments
+ *
+ * * `code` - The language code to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateLanguageCode } from '@kreuzberg/node';
+ *
+ * if (validateLanguageCode('en')) {
+ *   console.log('Valid language code');
+ * }
+ * ```
+ */
+export declare function validateLanguageCode(code: string): boolean
+
 /**
  * Validate that a MIME type is supported by Kreuzberg.
  *
@@ -1116,3 +1646,134 @@ export declare function unregisterValidator(name: string): void
  * ```
  */
 export declare function validateMimeType(mimeType: string): string
+
+/**
+ * Validates an OCR backend string.
+ *
+ * Valid backends: "tesseract", "easyocr", "paddleocr"
+ *
+ * # Arguments
+ *
+ * * `backend` - The OCR backend to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateOcrBackend } from '@kreuzberg/node';
+ *
+ * if (validateOcrBackend('tesseract')) {
+ *   console.log('Valid backend');
+ * }
+ * ```
+ */
+export declare function validateOcrBackend(backend: string): boolean
+
+/**
+ * Validates a tesseract output format string.
+ *
+ * Valid formats: "text", "markdown"
+ *
+ * # Arguments
+ *
+ * * `format` - The output format to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateOutputFormat } from '@kreuzberg/node';
+ *
+ * if (validateOutputFormat('markdown')) {
+ *   console.log('Valid output format');
+ * }
+ * ```
+ */
+export declare function validateOutputFormat(format: string): boolean
+
+/**
+ * Validates a Tesseract OCR Engine Mode (OEM) value.
+ *
+ * Valid range: 0-3
+ *
+ * # Arguments
+ *
+ * * `oem` - The OEM value to validate
+ *
+ * # Returns
+ *
+ * `true` if valid (0-3), `false` otherwise.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateTesseractOem } from '@kreuzberg/node';
+ *
+ * if (validateTesseractOem(1)) {
+ *   console.log('Valid OEM');
+ * }
+ * ```
+ */
+export declare function validateTesseractOem(oem: number): boolean
+
+/**
+ * Validates a Tesseract Page Segmentation Mode (PSM) value.
+ *
+ * Valid range: 0-13
+ *
+ * # Arguments
+ *
+ * * `psm` - The PSM value to validate
+ *
+ * # Returns
+ *
+ * `true` if valid (0-13), `false` otherwise.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateTesseractPsm } from '@kreuzberg/node';
+ *
+ * if (validateTesseractPsm(3)) {
+ *   console.log('Valid PSM');
+ * }
+ * ```
+ */
+export declare function validateTesseractPsm(psm: number): boolean
+
+/**
+ * Validates a token reduction level string.
+ *
+ * Valid levels: "off", "light", "moderate", "aggressive", "maximum"
+ *
+ * # Arguments
+ *
+ * * `level` - The token reduction level to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateTokenReductionLevel } from '@kreuzberg/node';
+ *
+ * if (validateTokenReductionLevel('moderate')) {
+ *   console.log('Valid token reduction level');
+ * }
+ * ```
+ */
+export declare function validateTokenReductionLevel(level: string): boolean
+
+export interface WorkerPoolStats {
+  size: number
+  activeWorkers: number
+  queuedTasks: number
+}