@kreuzberg/node 4.0.0-rc.6 → 4.0.0-rc.8

package/dist/index.d.ts

@@ -0,0 +1,857 @@
+import { PanicContext } from './errors.js';
+export { CacheError, ErrorCode, ImageProcessingError, KreuzbergError, MissingDependencyError, OcrError, ParsingError, PluginError, ValidationError } from './errors.js';
+import { ExtractionConfig as ExtractionConfig$1, ExtractionResult, PostProcessorProtocol, ValidatorProtocol, OcrBackendProtocol } from './types.js';
+export { ArchiveMetadata, Chunk, ChunkMetadata, ChunkingConfig, EmailMetadata, ErrorMetadata, ExcelMetadata, ExtractedImage, HtmlConversionOptions, HtmlMetadata, HtmlPreprocessingOptions, ImageExtractionConfig, ImageMetadata, ImagePreprocessingMetadata, KeywordAlgorithm, KeywordConfig, LanguageDetectionConfig, Metadata, OcrConfig, OcrMetadata, PageBoundary, PageConfig, PageContent, PageInfo, PageStructure, PageUnitType, PdfConfig, PdfMetadata, PostProcessorConfig, PptxMetadata, ProcessingStage, RakeParams, Table, TesseractConfig, TextMetadata, TokenReductionConfig, XmlMetadata, YakeParams } from './types.js';
+export { GutenOcrBackend } from './ocr/guten-ocr.js';
+
+/**
+ * Kreuzberg - Multi-language document intelligence framework.
+ *
+ * This is a TypeScript SDK around a high-performance Rust core.
+ * All extraction logic, chunking, quality processing, and language detection
+ * are implemented in Rust for maximum performance.
+ *
+ * ## API Usage Recommendations
+ *
+ * **For processing multiple documents**, prefer batch APIs:
+ * - Use `batchExtractFiles()` / `batchExtractFilesSync()` for multiple files
+ * - Use `batchExtractBytes()` / `batchExtractBytesSync()` for multiple byte arrays
+ *
+ * **Batch APIs provide**:
+ * - Better performance (parallel processing in Rust)
+ * - More reliable memory management
+ * - Recommended for all multi-document workflows
+ *
+ * **Single extraction APIs** (`extractFile`, `extractBytes`) are suitable for:
+ * - One-off document processing
+ * - Interactive applications processing documents on-demand
+ * - Avoid calling these in tight loops - use batch APIs instead
+ *
+ * ## Supported Formats
+ *
+ * - **Documents**: PDF, DOCX, PPTX, XLSX, DOC, PPT (with LibreOffice)
+ * - **Text**: Markdown, Plain Text, XML
+ * - **Web**: HTML (converted to Markdown)
+ * - **Data**: JSON, YAML, TOML
+ * - **Email**: EML, MSG
+ * - **Images**: PNG, JPEG, TIFF (with OCR support)
+ *
+ * @example
+ * ```typescript
+ * import { extractFile, batchExtractFiles } from '@kreuzberg/node';
+ *
+ * // Single file extraction
+ * const result = await extractFile('document.pdf');
+ * console.log(result.content);
+ *
+ * // Multiple files (recommended approach)
+ * const files = ['doc1.pdf', 'doc2.docx', 'doc3.xlsx'];
+ * const results = await batchExtractFiles(files);
+ * results.forEach(r => console.log(r.content));
+ * ```
+ */
+
+/**
+ * @internal Allows tests to provide a mocked native binding.
+ */
+declare function __setBindingForTests(mock: unknown): void;
+/**
+ * @internal Resets the cached native binding for tests.
+ */
+declare function __resetBindingForTests(): void;
+/**
+ * Extract content from a single file (synchronous).
+ *
+ * **Usage Note**: For processing multiple files, prefer `batchExtractFilesSync()` which
+ * provides better performance and memory management.
+ *
+ * @param filePath - Path to the file (string)
+ * @param mimeType - Optional MIME type hint (auto-detected if null)
+ * @param config - Extraction configuration (uses defaults if null)
+ * @returns ExtractionResult with content, metadata, and tables
+ *
+ * @example
+ * ```typescript
+ * import { extractFileSync } from '@kreuzberg/node';
+ *
+ * // Basic usage
+ * const result = extractFileSync('document.pdf');
+ * console.log(result.content);
+ *
+ * // With OCR configuration
+ * const config = {
+ *   ocr: {
+ *     backend: 'tesseract',
+ *     language: 'eng',
+ *     tesseractConfig: {
+ *       psm: 6,
+ *       enableTableDetection: true,
+ *     },
+ *   },
+ * };
+ * const result2 = extractFileSync('scanned.pdf', null, config);
+ * ```
+ */
+declare function extractFileSync(filePath: string, mimeType?: string | null, config?: ExtractionConfig$1 | null): ExtractionResult;
+/**
+ * Extract content from a single file (asynchronous).
+ *
+ * **Usage Note**: For processing multiple files, prefer `batchExtractFiles()` which
+ * provides better performance and memory management.
+ *
+ * @param filePath - Path to the file (string)
+ * @param mimeType - Optional MIME type hint (auto-detected if null)
+ * @param config - Extraction configuration (uses defaults if null)
+ * @returns Promise<ExtractionResult> with content, metadata, and tables
+ *
+ * @example
+ * ```typescript
+ * import { extractFile } from '@kreuzberg/node';
+ *
+ * // Basic usage
+ * const result = await extractFile('document.pdf');
+ * console.log(result.content);
+ *
+ * // With chunking enabled
+ * const config = {
+ *   chunking: {
+ *     maxChars: 1000,
+ *     maxOverlap: 200,
+ *   },
+ * };
+ * const result2 = await extractFile('long_document.pdf', null, config);
+ * console.log(result2.chunks); // Array of text chunks
+ * ```
+ */
+declare function extractFile(filePath: string, mimeType?: string | null, config?: ExtractionConfig$1 | null): Promise<ExtractionResult>;
+/**
+ * Extract content from raw bytes (synchronous).
+ *
+ * **Usage Note**: For processing multiple byte arrays, prefer `batchExtractBytesSync()`
+ * which provides better performance and memory management.
+ *
+ * @param data - File content as Uint8Array
+ * @param mimeType - MIME type of the data (required for format detection)
+ * @param config - Extraction configuration (uses defaults if null)
+ * @returns ExtractionResult with content, metadata, and tables
+ *
+ * @example
+ * ```typescript
+ * import { extractBytesSync } from '@kreuzberg/node';
+ * import { readFileSync } from 'fs';
+ *
+ * const data = readFileSync('document.pdf');
+ * const result = extractBytesSync(data, 'application/pdf');
+ * console.log(result.content);
+ * ```
+ */
+declare function extractBytesSync(data: Uint8Array, mimeType: string, config?: ExtractionConfig$1 | null): ExtractionResult;
+/**
+ * Extract content from raw bytes (asynchronous).
+ *
+ * **Usage Note**: For processing multiple byte arrays, prefer `batchExtractBytes()`
+ * which provides better performance and memory management.
+ *
+ * @param data - File content as Uint8Array
+ * @param mimeType - MIME type of the data (required for format detection)
+ * @param config - Extraction configuration (uses defaults if null)
+ * @returns Promise<ExtractionResult> with content, metadata, and tables
+ *
+ * @example
+ * ```typescript
+ * import { extractBytes } from '@kreuzberg/node';
+ * import { readFile } from 'fs/promises';
+ *
+ * const data = await readFile('document.pdf');
+ * const result = await extractBytes(data, 'application/pdf');
+ * console.log(result.content);
+ * ```
+ */
+declare function extractBytes(data: Uint8Array, mimeType: string, config?: ExtractionConfig$1 | null): Promise<ExtractionResult>;
+/**
+ * Extract content from multiple files in parallel (synchronous).
+ *
+ * **Recommended for**: Processing multiple documents efficiently with better
+ * performance and memory management compared to individual `extractFileSync()` calls.
+ *
+ * **Benefits**:
+ * - Parallel processing in Rust for maximum performance
+ * - Optimized memory usage across all extractions
+ * - More reliable for batch document processing
+ *
+ * @param paths - List of file paths to extract
+ * @param config - Extraction configuration (uses defaults if null)
+ * @returns Array of ExtractionResults (one per file, in same order as input)
+ *
+ * @example
+ * ```typescript
+ * import { batchExtractFilesSync } from '@kreuzberg/node';
+ *
+ * const files = ['doc1.pdf', 'doc2.docx', 'doc3.xlsx'];
+ * const results = batchExtractFilesSync(files);
+ *
+ * results.forEach((result, i) => {
+ *   console.log(`File ${files[i]}: ${result.content.substring(0, 100)}...`);
+ * });
+ * ```
+ */
+declare function batchExtractFilesSync(paths: string[], config?: ExtractionConfig$1 | null): ExtractionResult[];
+/**
+ * Extract content from multiple files in parallel (asynchronous).
+ *
+ * **Recommended for**: Processing multiple documents efficiently with better
+ * performance and memory management compared to individual `extractFile()` calls.
+ *
+ * **Benefits**:
+ * - Parallel processing in Rust for maximum performance
+ * - Optimized memory usage across all extractions
+ * - More reliable for batch document processing
+ *
+ * @param paths - List of file paths to extract
+ * @param config - Extraction configuration (uses defaults if null)
+ * @returns Promise resolving to array of ExtractionResults (one per file, in same order as input)
+ *
+ * @example
+ * ```typescript
+ * import { batchExtractFiles } from '@kreuzberg/node';
+ *
+ * const files = ['invoice1.pdf', 'invoice2.pdf', 'invoice3.pdf'];
+ * const results = await batchExtractFiles(files, {
+ *   ocr: { backend: 'tesseract', language: 'eng' }
+ * });
+ *
+ * // Process all results
+ * const totalAmount = results
+ *   .map(r => extractAmount(r.content))
+ *   .reduce((a, b) => a + b, 0);
+ * ```
+ */
+declare function batchExtractFiles(paths: string[], config?: ExtractionConfig$1 | null): Promise<ExtractionResult[]>;
+/**
+ * Extract content from multiple byte arrays in parallel (synchronous).
+ *
+ * **Recommended for**: Processing multiple documents from memory efficiently with better
+ * performance and memory management compared to individual `extractBytesSync()` calls.
+ *
+ * **Benefits**:
+ * - Parallel processing in Rust for maximum performance
+ * - Optimized memory usage across all extractions
+ * - More reliable for batch document processing
+ *
+ * @param dataList - List of file contents as Uint8Arrays
+ * @param mimeTypes - List of MIME types (one per data item, required for format detection)
+ * @param config - Extraction configuration (uses defaults if null)
+ * @returns Array of ExtractionResults (one per data item, in same order as input)
+ *
+ * @example
+ * ```typescript
+ * import { batchExtractBytesSync } from '@kreuzberg/node';
+ * import { readFileSync } from 'fs';
+ *
+ * const files = ['doc1.pdf', 'doc2.docx', 'doc3.xlsx'];
+ * const dataList = files.map(f => readFileSync(f));
+ * const mimeTypes = ['application/pdf', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'];
+ *
+ * const results = batchExtractBytesSync(dataList, mimeTypes);
+ * results.forEach((result, i) => {
+ *   console.log(`File ${files[i]}: ${result.content.substring(0, 100)}...`);
+ * });
+ * ```
+ */
+declare function batchExtractBytesSync(dataList: Uint8Array[], mimeTypes: string[], config?: ExtractionConfig$1 | null): ExtractionResult[];
+/**
+ * Extract content from multiple byte arrays in parallel (asynchronous).
+ *
+ * **Recommended for**: Processing multiple documents from memory efficiently with better
+ * performance and memory management compared to individual `extractBytes()` calls.
+ *
+ * **Benefits**:
+ * - Parallel processing in Rust for maximum performance
+ * - Optimized memory usage across all extractions
+ * - More reliable for batch document processing
+ *
+ * @param dataList - List of file contents as Uint8Arrays
+ * @param mimeTypes - List of MIME types (one per data item, required for format detection)
+ * @param config - Extraction configuration (uses defaults if null)
+ * @returns Promise resolving to array of ExtractionResults (one per data item, in same order as input)
+ *
+ * @example
+ * ```typescript
+ * import { batchExtractBytes } from '@kreuzberg/node';
+ * import { readFile } from 'fs/promises';
+ *
+ * const files = ['invoice1.pdf', 'invoice2.pdf', 'invoice3.pdf'];
+ * const dataList = await Promise.all(files.map(f => readFile(f)));
+ * const mimeTypes = files.map(() => 'application/pdf');
+ *
+ * const results = await batchExtractBytes(dataList, mimeTypes, {
+ *   ocr: { backend: 'tesseract', language: 'eng' }
+ * });
+ *
+ * // Process all results
+ * const totalAmount = results
+ *   .map(r => extractAmount(r.content))
+ *   .reduce((a, b) => a + b, 0);
+ * ```
+ */
+declare function batchExtractBytes(dataList: Uint8Array[], mimeTypes: string[], config?: ExtractionConfig$1 | null): Promise<ExtractionResult[]>;
+/**
+ * Register a custom postprocessor.
+ *
+ * **IMPORTANT**: Custom processors only work with **async extraction functions**:
+ * - ✅ `extractFile()`, `extractBytes()`, `batchExtractFiles()`, `batchExtractBytes()`
+ * - ❌ `extractFileSync()`, `extractBytesSync()`, etc. (will skip custom processors)
+ *
+ * This limitation exists because sync extraction blocks the Node.js event loop,
+ * preventing JavaScript callbacks from executing. For v4.0, use async extraction
+ * when you need custom processors.
+ *
+ * @param processor - PostProcessorProtocol implementation
+ *
+ * @example
+ * ```typescript
+ * import { registerPostProcessor, extractFile, ExtractionResult } from '@kreuzberg/node';
+ *
+ * class MyProcessor implements PostProcessorProtocol {
+ *   name(): string {
+ *     return 'my_processor';
+ *   }
+ *
+ *   process(result: ExtractionResult): ExtractionResult {
+ *     result.metadata.customField = 'custom_value';
+ *     return result;
+ *   }
+ *
+ *   processingStage(): 'early' | 'middle' | 'late' {
+ *     return 'middle';
+ *   }
+ * }
+ *
+ * registerPostProcessor(new MyProcessor());
+ *
+ * // Use async extraction (required for custom processors)
+ * const result = await extractFile('document.pdf');
+ * console.log(result.metadata.customField); // 'custom_value'
+ * ```
+ */
+declare function registerPostProcessor(processor: PostProcessorProtocol): void;
+/**
+ * Unregister a postprocessor by name.
+ *
+ * Removes a previously registered postprocessor from the registry.
+ *
+ * @param name - Name of the processor to unregister
+ *
+ * @example
+ * ```typescript
+ * import { unregisterPostProcessor } from '@kreuzberg/node';
+ *
+ * unregisterPostProcessor('my_processor');
+ * ```
+ */
+declare function unregisterPostProcessor(name: string): void;
+/**
+ * Clear all registered postprocessors.
+ *
+ * Removes all postprocessors from the registry.
+ *
+ * @example
+ * ```typescript
+ * import { clearPostProcessors } from '@kreuzberg/node';
+ *
+ * clearPostProcessors();
+ * ```
+ */
+declare function clearPostProcessors(): void;
+/**
+ * List all registered post-processors.
+ *
+ * Returns the names of all currently registered post-processors.
+ *
+ * @returns Array of post-processor names
+ *
+ * @example
+ * ```typescript
+ * import { listPostProcessors } from '@kreuzberg/node';
+ *
+ * const names = listPostProcessors();
+ * console.log('Registered post-processors:', names);
+ * ```
+ */
+declare function listPostProcessors(): string[];
+/**
+ * Register a custom validator.
+ *
+ * Validators check extraction results for quality, completeness, or correctness.
+ * Unlike post-processors, validator errors **fail fast** - if a validator throws an error,
+ * the extraction fails immediately.
+ *
+ * @param validator - ValidatorProtocol implementation
+ *
+ * @example
+ * ```typescript
+ * import { registerValidator } from '@kreuzberg/node';
+ *
+ * class MinLengthValidator implements ValidatorProtocol {
+ *   name(): string {
+ *     return 'min_length_validator';
+ *   }
+ *
+ *   priority(): number {
+ *     return 100; // Run early
+ *   }
+ *
+ *   validate(result: ExtractionResult): void {
+ *     if (result.content.length < 100) {
+ *       throw new Error('Content too short: minimum 100 characters required');
+ *     }
+ *   }
+ * }
+ *
+ * registerValidator(new MinLengthValidator());
+ * ```
+ */
+declare function registerValidator(validator: ValidatorProtocol): void;
+/**
+ * Unregister a validator by name.
+ *
+ * Removes a previously registered validator from the global registry.
+ *
+ * @param name - Validator name to unregister
+ *
+ * @example
+ * ```typescript
+ * import { unregisterValidator } from '@kreuzberg/node';
+ *
+ * unregisterValidator('min_length_validator');
+ * ```
+ */
+declare function unregisterValidator(name: string): void;
+/**
+ * Clear all registered validators.
+ *
+ * Removes all validators from the global registry. Useful for test cleanup
+ * or resetting state.
+ *
+ * @example
+ * ```typescript
+ * import { clearValidators } from '@kreuzberg/node';
+ *
+ * clearValidators();
+ * ```
+ */
+declare function clearValidators(): void;
+/**
+ * List all registered validators.
+ *
+ * Returns the names of all currently registered validators.
+ *
+ * @returns Array of validator names
+ *
+ * @example
+ * ```typescript
+ * import { listValidators } from '@kreuzberg/node';
+ *
+ * const names = listValidators();
+ * console.log('Registered validators:', names);
+ * ```
+ */
+declare function listValidators(): string[];
+declare function registerOcrBackend(backend: OcrBackendProtocol): void;
+/**
+ * List all registered OCR backends.
+ *
+ * Returns an array of names of all currently registered OCR backends,
+ * including built-in backends like "tesseract".
+ *
+ * @returns Array of OCR backend names
+ *
+ * @example
+ * ```typescript
+ * import { listOcrBackends } from '@kreuzberg/node';
+ *
+ * const backends = listOcrBackends();
+ * console.log(backends); // ['tesseract', 'my-custom-backend', ...]
+ * ```
+ */
+declare function listOcrBackends(): string[];
+/**
+ * Unregister an OCR backend by name.
+ *
+ * Removes the specified OCR backend from the registry. If the backend doesn't exist,
+ * this operation is a no-op (does not throw an error).
+ *
+ * @param name - Name of the OCR backend to unregister
+ *
+ * @example
+ * ```typescript
+ * import { unregisterOcrBackend } from '@kreuzberg/node';
+ *
+ * // Unregister a custom backend
+ * unregisterOcrBackend('my-custom-ocr');
+ * ```
+ */
+declare function unregisterOcrBackend(name: string): void;
+/**
+ * Clear all registered OCR backends.
+ *
+ * Removes all OCR backends from the registry, including built-in backends.
+ * Use with caution as this will make OCR functionality unavailable until
+ * backends are re-registered.
+ *
+ * @example
+ * ```typescript
+ * import { clearOcrBackends } from '@kreuzberg/node';
+ *
+ * clearOcrBackends();
+ * ```
+ */
+declare function clearOcrBackends(): void;
+/**
+ * List all registered document extractors.
+ *
+ * Returns an array of names of all currently registered document extractors,
+ * including built-in extractors for PDF, Office documents, images, etc.
+ *
+ * @returns Array of document extractor names
+ *
+ * @example
+ * ```typescript
+ * import { listDocumentExtractors } from '@kreuzberg/node';
+ *
+ * const extractors = listDocumentExtractors();
+ * console.log(extractors); // ['PDFExtractor', 'ImageExtractor', ...]
+ * ```
+ */
+declare function listDocumentExtractors(): string[];
+/**
+ * Unregister a document extractor by name.
+ *
+ * Removes the specified document extractor from the registry. If the extractor
+ * doesn't exist, this operation is a no-op (does not throw an error).
+ *
+ * @param name - Name of the document extractor to unregister
+ *
+ * @example
+ * ```typescript
+ * import { unregisterDocumentExtractor } from '@kreuzberg/node';
+ *
+ * // Unregister a custom extractor
+ * unregisterDocumentExtractor('MyCustomExtractor');
+ * ```
+ */
+declare function unregisterDocumentExtractor(name: string): void;
+/**
+ * Clear all registered document extractors.
+ *
+ * Removes all document extractors from the registry, including built-in extractors.
+ * Use with caution as this will make document extraction unavailable until
+ * extractors are re-registered.
+ *
+ * @example
+ * ```typescript
+ * import { clearDocumentExtractors } from '@kreuzberg/node';
+ *
+ * clearDocumentExtractors();
+ * ```
+ */
+declare function clearDocumentExtractors(): void;
+/**
+ * ExtractionConfig namespace with static methods for loading configuration from files.
+ *
+ * Provides a factory method to load extraction configuration from TOML, YAML, or JSON files.
+ * The file format is automatically detected based on the file extension.
+ *
+ * @example
+ * ```typescript
+ * import { ExtractionConfig, extractFile } from '@kreuzberg/node';
+ *
+ * // Load configuration from file
+ * const config = ExtractionConfig.fromFile('config.toml');
+ *
+ * // Use with extraction
+ * const result = await extractFile('document.pdf', null, config);
+ * ```
+ */
+declare const ExtractionConfig: {
+    /**
+     * Load extraction configuration from a file.
+     *
+     * Automatically detects the file format based on extension:
+     * - `.toml` - TOML format
+     * - `.yaml` - YAML format
+     * - `.json` - JSON format
+     *
+     * @param filePath - Path to the configuration file (absolute or relative)
+     * @returns ExtractionConfig object loaded from the file
+     *
+     * @throws {Error} If file does not exist or is not accessible
+     * @throws {Error} If file content is not valid TOML/YAML/JSON
+     * @throws {Error} If configuration structure is invalid
+     * @throws {Error} If file extension is not supported
+     *
+     * @example
+     * ```typescript
+     * import { ExtractionConfig } from '@kreuzberg/node';
+     *
+     * // Load from TOML file
+     * const config1 = ExtractionConfig.fromFile('kreuzberg.toml');
+     *
+     * // Load from YAML file
+     * const config2 = ExtractionConfig.fromFile('./config.yaml');
+     *
+     * // Load from JSON file
+     * const config3 = ExtractionConfig.fromFile('./config.json');
+     * ```
+     */
+    fromFile(filePath: string): ExtractionConfig$1;
+    /**
+     * Discover and load configuration from current or parent directories.
+     *
+     * Searches for a `kreuzberg.toml` file starting from the current working directory
+     * and traversing up the directory tree. Returns the first configuration file found.
+     *
+     * @returns ExtractionConfig object if found, or null if no configuration file exists
+     *
+     * @example
+     * ```typescript
+     * import { ExtractionConfig } from '@kreuzberg/node';
+     *
+     * // Try to find config in current or parent directories
+     * const config = ExtractionConfig.discover();
+     * if (config) {
+     *   console.log('Found configuration');
+     *   // Use config for extraction
+     * } else {
+     *   console.log('No configuration file found, using defaults');
+     * }
+     * ```
+     */
+    discover(): ExtractionConfig$1 | null;
+};
+/**
+ * Detect MIME type from raw bytes.
+ *
+ * Uses content inspection (magic bytes) to determine MIME type.
+ * This is more accurate than extension-based detection but requires
+ * reading the file content.
+ *
+ * @param bytes - Raw file content as Buffer
+ * @returns The detected MIME type string
+ *
+ * @throws {Error} If MIME type cannot be determined from content
+ *
+ * @example
+ * ```typescript
+ * import { detectMimeType } from '@kreuzberg/node';
+ * import * as fs from 'fs';
+ *
+ * // Read file content
+ * const content = fs.readFileSync('document.pdf');
+ *
+ * // Detect MIME type from bytes
+ * const mimeType = detectMimeType(content);
+ * console.log(mimeType); // 'application/pdf'
+ * ```
+ */
+declare function detectMimeType(bytes: Buffer): string;
+/**
+ * Detect MIME type from a file path.
+ *
+ * Uses file extension to determine MIME type. Falls back to `mime_guess` crate
+ * if extension-based detection fails.
+ *
+ * @param path - Path to the file (string)
+ * @param checkExists - Whether to verify file existence (default: true)
+ * @returns The detected MIME type string
+ *
+ * @throws {Error} If file doesn't exist (when checkExists is true)
+ * @throws {Error} If MIME type cannot be determined from path/extension
+ * @throws {Error} If extension is unknown
+ *
+ * @example
+ * ```typescript
+ * import { detectMimeTypeFromPath } from '@kreuzberg/node';
+ *
+ * // Detect from existing file
+ * const mimeType = detectMimeTypeFromPath('document.pdf');
+ * console.log(mimeType); // 'application/pdf'
+ *
+ * const mimeType2 = detectMimeTypeFromPath('document.docx');
+ * console.log(mimeType2); // 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+ * ```
+ */
+declare function detectMimeTypeFromPath(path: string, checkExists?: boolean): string;
+/**
+ * Validate that a MIME type is supported by Kreuzberg.
+ *
+ * Checks if a MIME type is in the list of supported formats. Note that any
+ * `image/*` MIME type is automatically considered valid.
+ *
+ * @param mimeType - The MIME type to validate (string)
+ * @returns The validated MIME type (may be normalized)
+ *
+ * @throws {Error} If the MIME type is not supported
+ *
+ * @example
+ * ```typescript
+ * import { validateMimeType } from '@kreuzberg/node';
+ *
+ * // Validate supported type
+ * const validated = validateMimeType('application/pdf');
+ * console.log(validated); // 'application/pdf'
+ *
+ * // Validate custom image type
+ * const validated2 = validateMimeType('image/custom-format');
+ * console.log(validated2); // 'image/custom-format' (any image/* is valid)
+ *
+ * // Validate unsupported type (throws error)
+ * try {
+ *   validateMimeType('video/mp4');
+ * } catch (err) {
+ *   console.error(err); // Error: Unsupported format: video/mp4
+ * }
+ * ```
+ */
+declare function validateMimeType(mimeType: string): string;
+/**
+ * Get file extensions for a given MIME type.
+ *
+ * Returns an array of file extensions commonly associated with the specified
+ * MIME type. For example, 'application/pdf' returns ['pdf'].
+ *
+ * @param mimeType - The MIME type to look up (e.g., 'application/pdf', 'image/jpeg')
+ * @returns Array of file extensions (without leading dots)
+ *
+ * @throws {Error} If the MIME type is not recognized or supported
+ *
+ * @example
+ * ```typescript
+ * import { getExtensionsForMime } from '@kreuzberg/node';
+ *
+ * // Get extensions for PDF
+ * const pdfExts = getExtensionsForMime('application/pdf');
+ * console.log(pdfExts); // ['pdf']
+ *
+ * // Get extensions for JPEG
+ * const jpegExts = getExtensionsForMime('image/jpeg');
+ * console.log(jpegExts); // ['jpg', 'jpeg']
+ * ```
+ */
+declare function getExtensionsForMime(mimeType: string): string[];
+/**
+ * Embedding preset configuration.
+ *
+ * Contains all settings for a specific embedding model preset.
+ */
+interface EmbeddingPreset {
+    /** Name of the preset (e.g., "fast", "balanced", "quality", "multilingual") */
+    name: string;
+    /** Recommended chunk size in characters */
+    chunkSize: number;
+    /** Recommended overlap in characters */
+    overlap: number;
+    /** Model identifier (e.g., "AllMiniLML6V2Q", "BGEBaseENV15") */
+    modelName: string;
+    /** Embedding vector dimensions */
+    dimensions: number;
+    /** Human-readable description of the preset */
+    description: string;
+}
+/**
+ * List all available embedding preset names.
+ *
+ * Returns an array of preset names that can be used with `getEmbeddingPreset`.
+ *
+ * @returns Array of 4 preset names: ["fast", "balanced", "quality", "multilingual"]
+ *
+ * @example
+ * ```typescript
+ * import { listEmbeddingPresets } from '@kreuzberg/node';
+ *
+ * const presets = listEmbeddingPresets();
+ * console.log(presets); // ['fast', 'balanced', 'quality', 'multilingual']
+ * ```
+ */
+declare function listEmbeddingPresets(): string[];
+/**
+ * Get a specific embedding preset by name.
+ *
+ * Returns a preset configuration object, or null if the preset name is not found.
+ *
+ * @param name - The preset name (case-sensitive)
+ * @returns An `EmbeddingPreset` object or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * import { getEmbeddingPreset } from '@kreuzberg/node';
+ *
+ * const preset = getEmbeddingPreset('balanced');
+ * if (preset) {
+ *   console.log(`Model: ${preset.modelName}, Dims: ${preset.dimensions}`);
+ *   // Model: BGEBaseENV15, Dims: 768
+ * }
+ * ```
+ */
+declare function getEmbeddingPreset(name: string): EmbeddingPreset | null;
+/**
+ * Get the error code for the last FFI error.
+ *
+ * Returns the FFI error code as an integer. This is useful for programmatic error handling
+ * and distinguishing between different types of failures in native code.
+ *
+ * Error codes:
+ * - 0: Success (no error)
+ * - 1: GenericError
+ * - 2: Panic
+ * - 3: InvalidArgument
+ * - 4: IoError
+ * - 5: ParsingError
+ * - 6: OcrError
+ * - 7: MissingDependency
+ *
+ * @returns The integer error code
+ *
+ * @example
+ * ```typescript
+ * import { extractFile, getLastErrorCode, ErrorCode } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('document.pdf');
+ * } catch (error) {
+ *   const code = getLastErrorCode();
+ *   if (code === ErrorCode.Panic) {
+ *     console.error('Native code panic detected');
+ *   }
+ * }
+ * ```
+ */
+declare function getLastErrorCode(): number;
+/**
+ * Get panic context information if the last error was a panic.
+ *
+ * Returns detailed information about a panic in native code, or null if the last error was not a panic.
+ * This provides debugging information when native code panics.
+ *
+ * @returns A `PanicContext` object with file, line, function, message, and timestamp_secs, or null if no panic context is available
+ *
+ * @example
+ * ```typescript
+ * import { extractFile, getLastPanicContext } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('document.pdf');
+ * } catch (error) {
+ *   const context = getLastPanicContext();
+ *   if (context) {
+ *     console.error(`Panic at ${context.file}:${context.line}`);
+ *     console.error(`In function: ${context.function}`);
+ *     console.error(`Message: ${context.message}`);
+ *   }
+ * }
+ * ```
+ */
+declare function getLastPanicContext(): PanicContext | null;
+declare const __version__ = "4.0.0-rc.8";
+
+export { type EmbeddingPreset, ExtractionConfig, ExtractionResult, OcrBackendProtocol, PanicContext, PostProcessorProtocol, ValidatorProtocol, __resetBindingForTests, __setBindingForTests, __version__, batchExtractBytes, batchExtractBytesSync, batchExtractFiles, batchExtractFilesSync, clearDocumentExtractors, clearOcrBackends, clearPostProcessors, clearValidators, detectMimeType, detectMimeTypeFromPath, extractBytes, extractBytesSync, extractFile, extractFileSync, getEmbeddingPreset, getExtensionsForMime, getLastErrorCode, getLastPanicContext, listDocumentExtractors, listEmbeddingPresets, listOcrBackends, listPostProcessors, listValidators, registerOcrBackend, registerPostProcessor, registerValidator, unregisterDocumentExtractor, unregisterOcrBackend, unregisterPostProcessor, unregisterValidator, validateMimeType };