/* auto-generated by NAPI-RS */
/* eslint-disable */
/**
 * Lazy PDF page iterator. A more memory-efficient alternative to
 * `iteratePdfPagesSync`/`iteratePdfPages` when memory is a concern or when
 * pages should be processed as they are rendered (e.g., sending each page to
 * a vision model for OCR).
 *
 * Renders one page at a time via the `.next()` method. Callers must call
 * `.close()` when done to free native resources.
 *
 * # Example
 *
 * ```javascript
 * const iter = new PdfPageIterator("doc.pdf", 150);
 * let result;
 * while ((result = iter.next()) !== null) {
 *     const { pageIndex, data } = result;
 *     // process page...
 * }
 * iter.close();
 * ```
 */
export declare class JsPdfPageIterator {
  /**
   * Create a new PDF page iterator.
   *
   * # Parameters
   *
   * * `file_path` - Path to the PDF file
   * * `dpi` - Optional DPI (default 150)
   */
  constructor(filePath: string, dpi?: number | undefined | null)
  /**
   * Advance the iterator and return the next page.
   *
   * Returns `{ pageIndex, data }` or `null` when exhausted.
   */
  next(): PdfPageResult | null
  /** Total number of pages in the PDF. */
  pageCount(): number
  /** Free native resources. Safe to call multiple times. */
  close(): void
}

/** Opaque handle to a worker pool */
export declare class JsWorkerPool {

}

/**
 * Batch extract from multiple byte arrays (asynchronous).
 *
 * Asynchronously processes multiple in-memory buffers in parallel. Non-blocking
 * alternative to `batchExtractBytesSync`.
 *
 * # Parameters
 *
 * * `data_list` - Array of buffers to extract
 * * `mime_types` - Array of MIME types (must match data_list length)
 * * `config` - Optional extraction configuration
 * * `file_configs` - Optional per-item extraction configs (must match data_list length if provided)
 *
 * # Returns
 *
 * Promise resolving to array of `ExtractionResult`.
 *
 * # Example
 *
 * ```typescript
 * import { batchExtractBytes } from '@kreuzberg/node';
 *
 * const responses = await Promise.all([
 *   fetch('https://example.com/doc1.pdf'),
 *   fetch('https://example.com/doc2.pdf')
 * ]);
 * const buffers = await Promise.all(
 *   responses.map(r => r.arrayBuffer().then(b => Buffer.from(b)))
 * );
 * const results = await batchExtractBytes(
 *   buffers,
 *   ['application/pdf', 'application/pdf'],
 *   null
 * );
 * ```
 */
export declare function batchExtractBytes(dataList: Array<Buffer>, mimeTypes: Array<string>, config?: JsExtractionConfig | undefined | null, fileConfigs?: Array<JsFileExtractionConfig | undefined | null> | undefined | null): Promise<Array<JsExtractionResult>>

/**
 * Batch extract from multiple byte arrays (synchronous).
 *
 * Synchronously processes multiple in-memory buffers in parallel. Requires
 * corresponding MIME types for each buffer.
 *
 * # Parameters
 *
 * * `data_list` - Array of buffers to extract
 * * `mime_types` - Array of MIME types (must match data_list length)
 * * `config` - Optional extraction configuration
 * * `file_configs` - Optional per-item extraction configs (must match data_list length if provided)
 *
 * # Returns
 *
 * Array of `ExtractionResult` in the same order as inputs.
 *
 * # Errors
 *
 * Throws if data_list and mime_types lengths don't match.
 *
 * # Example
 *
 * ```typescript
 * import { batchExtractBytesSync } from '@kreuzberg/node';
 *
 * const buffers = [buffer1, buffer2, buffer3];
 * const mimeTypes = ['application/pdf', 'image/png', 'text/plain'];
 * const results = batchExtractBytesSync(buffers, mimeTypes, null);
 * ```
 */
export declare function batchExtractBytesSync(dataList: Array<Buffer>, mimeTypes: Array<string>, config?: JsExtractionConfig | undefined | null, fileConfigs?: Array<JsFileExtractionConfig | undefined | null> | undefined | null): Array<JsExtractionResult>

/**
 * Batch extract from multiple files (asynchronous).
 *
 * Asynchronously processes multiple files in parallel. Non-blocking alternative
 * to `batchExtractFilesSync` with same performance benefits.
 *
 * # Parameters
 *
 * * `paths` - Array of file paths to extract
 * * `config` - Optional extraction configuration (applied to all files)
 * * `file_configs` - Optional per-file extraction configs (must match paths length if provided)
 *
 * # Returns
 *
 * Promise resolving to array of `ExtractionResult`.
 *
 * # Example
 *
 * ```typescript
 * import { batchExtractFiles } from '@kreuzberg/node';
 *
 * const files = ['report1.pdf', 'report2.pdf', 'report3.pdf'];
 * const results = await batchExtractFiles(files, null);
 * console.log(`Processed ${results.length} files`);
 * ```
 */
export declare function batchExtractFiles(paths: Array<string>, config?: JsExtractionConfig | undefined | null, fileConfigs?: Array<JsFileExtractionConfig | undefined | null> | 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>>

export declare function batchExtractFilesSync(paths: Array<string>, config?: JsExtractionConfig | undefined | null, fileConfigs?: Array<JsFileExtractionConfig | undefined | null> | undefined | null): Array<JsExtractionResult>

export declare function classifyError(errorMessage: string): ErrorClassification

/**
 * 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';
 *
 * clearDocumentExtractors();
 * ```
 */
export declare function clearDocumentExtractors(): void

/** Clear all registered OCR backends */
export declare function clearOcrBackends(): void

/** Clear all registered postprocessors */
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.
 *
 * Uses content inspection (magic bytes) to determine MIME type.
 * This is more accurate than extension-based detection but requires
 * reading the file content.
 *
 * # Parameters
 *
 * * `bytes` - Raw file content as Buffer
 *
 * # Returns
 *
 * The detected MIME type string.
 *
 * # Errors
 *
 * Throws an error if MIME type cannot be determined from content.
 *
 * # Example
 *
 * ```typescript
 * import { detectMimeTypeFromBytes } from 'kreuzberg';
 * import * as fs from 'fs';
 *
 * // Read file content
 * const content = fs.readFileSync('document.pdf');
 *
 * // Detect MIME type from bytes
 * const mimeType = detectMimeTypeFromBytes(content);
 * ```
 */
export declare function detectMimeTypeFromBytes(bytes: Buffer): string

/**
 * Detect MIME type from a file path.
 *
 * Determines the MIME type based on the file extension in the provided path.
 * By default, checks if the file exists; can be disabled with check_exists parameter.
 *
 * # Parameters
 *
 * * `path` - The file path to detect MIME type from (e.g., 'document.pdf')
 * * `check_exists` - Whether to verify the file exists (default: true)
 *
 * # Returns
 *
 * The detected MIME type as a string (e.g., 'application/pdf').
 *
 * # Errors
 *
 * Throws an error if MIME type cannot be determined from the file extension,
 * or if check_exists is true and the file does not exist.
 *
 * # Example
 *
 * ```typescript
 * import { detectMimeTypeFromPath } from 'kreuzberg';
 *
 * // Detect MIME type from existing file
 * const mimeType = detectMimeTypeFromPath('/path/to/document.pdf');
 *
 * // Detect without checking file existence
 * const mimeType2 = detectMimeTypeFromPath('document.docx', false);
 * ```
 */
export declare function detectMimeTypeFromPath(path: string, checkExists?: boolean | undefined | null): string

/**
 * Discover extraction configuration file in current directory or parent directories.
 *
 * Searches for configuration files in the following order:
 * 1. `kreuzberg.toml`
 * 2. `kreuzberg.yaml` / `kreuzberg.yml`
 * 3. `kreuzberg.json`
 * 4. Searches parent directories up to the filesystem root
 *
 * Returns the first configuration file found or throws an error if none found.
 *
 * # Returns
 *
 * `JsExtractionConfig` object with discovered configuration.
 *
 * # Errors
 *
 * Throws an error if no configuration file is found.
 *
 * # Example
 *
 * ```typescript
 * import { discoverExtractionConfig } from 'kreuzberg';
 *
 * // Automatically finds kreuzberg.toml or kreuzberg.yaml in current or parent directories
 * const config = discoverExtractionConfig();
 * const result = await extractFile('document.pdf', null, config);
 * ```
 */
export declare function discoverExtractionConfig(): JsExtractionConfig | null

/**
 * Generate embeddings from a list of text strings (asynchronous).
 *
 * # Arguments
 *
 * * `texts` - List of strings to embed
 * * `config` - Optional embedding configuration (model, batch size, normalization)
 *
 * # Returns
 *
 * `Promise<number[][]>` — one embedding vector per input text
 *
 * # Example
 *
 * ```typescript
 * import { embed } from '@kreuzberg/node';
 *
 * const embeddings = await embed(['Hello, world!'], { model: { type: 'preset', name: 'balanced' } });
 * console.log(embeddings.length); // 1
 * ```
 */
export declare function embed(texts: Array<string>, config?: JsEmbeddingConfig | undefined | null): Promise<Array<Array<number>>>

export 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
}

/**
 * Embedding preset configuration for TypeScript bindings.
 *
 * Contains all settings for a specific embedding model preset.
 */
export 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
}

/**
 * Generate embeddings from a list of text strings (synchronous).
 *
 * # Arguments
 *
 * * `texts` - List of strings to embed
 * * `config` - Optional embedding configuration (model, batch size, normalization)
 *
 * # Returns
 *
 * `number[][]` — one embedding vector per input text
 *
 * # Example
 *
 * ```typescript
 * import { embedSync } from '@kreuzberg/node';
 *
 * const embeddings = embedSync(['Hello, world!'], { model: { type: 'preset', name: 'balanced' } });
 * console.log(embeddings.length); // 1
 * ```
 */
export declare function embedSync(texts: Array<string>, config?: JsEmbeddingConfig | undefined | null): Array<Array<number>>

/**
 * 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
 * - **Embedding (8)**: Keywords: embed, embedding, vector, inference, model
 *
 * # 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).
 *
 * Asynchronously extracts content from a byte buffer. Non-blocking alternative
 * to `extractBytesSync` for processing in-memory data.
 *
 * # Parameters
 *
 * * `data` - Buffer containing the document bytes
 * * `mime_type` - MIME type of the data
 * * `config` - Optional extraction configuration
 *
 * # Returns
 *
 * Promise resolving to `ExtractionResult`.
 *
 * # Example
 *
 * ```typescript
 * import { extractBytes } from '@kreuzberg/node';
 *
 * const response = await fetch('https://example.com/document.pdf');
 * const buffer = Buffer.from(await response.arrayBuffer());
 * const result = await extractBytes(buffer, 'application/pdf', null);
 * ```
 */
export declare function extractBytes(data: Buffer, mimeType: string, config?: JsExtractionConfig | undefined | null): Promise<JsExtractionResult>

/**
 * Extract content from bytes (synchronous).
 *
 * Synchronously extracts content from a byte buffer without requiring a file path.
 * Useful for processing in-memory data, network streams, or database BLOBs.
 *
 * # Parameters
 *
 * * `data` - Buffer containing the document bytes
 * * `mime_type` - MIME type of the data (e.g., "application/pdf", "image/png")
 * * `config` - Optional extraction configuration
 *
 * # Returns
 *
 * `ExtractionResult` with extracted content and metadata.
 *
 * # Errors
 *
 * Throws an error if data is malformed or MIME type is unsupported.
 *
 * # Example
 *
 * ```typescript
 * import { extractBytesSync } from '@kreuzberg/node';
 * import fs from 'fs';
 *
 * const buffer = fs.readFileSync('document.pdf');
 * const result = extractBytesSync(buffer, 'application/pdf', null);
 * console.log(result.content);
 * ```
 */
export declare function extractBytesSync(data: Buffer, mimeType: string, config?: JsExtractionConfig | undefined | null): JsExtractionResult

/**
 * Extract content from a file (asynchronous).
 *
 * Asynchronously extracts text, tables, images, and metadata from a document file.
 * Non-blocking alternative to `extractFileSync` for use in async/await contexts.
 *
 * # Parameters
 *
 * * `file_path` - Path to the file to extract (absolute or relative)
 * * `mime_type` - Optional MIME type hint (auto-detected if omitted)
 * * `config` - Optional extraction configuration (OCR, chunking, etc.)
 *
 * # Returns
 *
 * Promise resolving to `ExtractionResult` with extracted content and metadata.
 *
 * # Errors
 *
 * Rejects if file processing fails (see `extractFileSync` for error conditions).
 *
 * # Example
 *
 * ```typescript
 * import { extractFile } from '@kreuzberg/node';
 *
 * // Async/await usage
 * const result = await extractFile('document.pdf', null, null);
 * console.log(result.content);
 *
 * // Promise usage
 * extractFile('report.docx', null, null)
 *   .then(result => console.log(result.content))
 *   .catch(err => console.error(err));
 * ```
 */
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, mimeType?: string | undefined | null, config?: JsExtractionConfig | undefined | null): Promise<JsExtractionResult>

export declare function extractFileSync(filePath: string, mimeType?: string | undefined | null, config?: JsExtractionConfig | undefined | null): JsExtractionResult

/**
 * Get a specific embedding preset by name.
 *
 * Returns a preset configuration object, or null if the preset name is not found.
 *
 * # Arguments
 *
 * * `name` - The preset name (case-sensitive)
 *
 * # Returns
 *
 * An `EmbeddingPreset` object with the following properties:
 * - `name`: string - Preset name
 * - `chunkSize`: number - Recommended chunk size in characters
 * - `overlap`: number - Recommended overlap in characters
 * - `modelName`: string - Model identifier
 * - `dimensions`: number - Embedding vector dimensions
 * - `description`: string - Human-readable description
 *
 * Returns `null` if preset name is not found.
 *
 * # Example
 *
 * ```typescript
 * import { getEmbeddingPreset } from 'kreuzberg';
 *
 * const preset = getEmbeddingPreset('balanced');
 * if (preset) {
 *   console.log(`Model: ${preset.modelName}, Dims: ${preset.dimensions}`);
 *   // Model: BGEBaseENV15, Dims: 768
 * }
 * ```
 */
export declare function getEmbeddingPreset(name: string): EmbeddingPreset | null

/**
 * Get a specific embedding preset by name.
 *
 * Returns a preset configuration object, or null if the preset name is not found.
 *
 * # Arguments
 *
 * * `name` - The preset name (case-sensitive)
 *
 * # Returns
 *
 * An `EmbeddingPreset` object with the following properties:
 * - `name`: string - Preset name
 * - `chunkSize`: number - Recommended chunk size in characters
 * - `overlap`: number - Recommended overlap in characters
 * - `modelName`: string - Model identifier
 * - `dimensions`: number - Embedding vector dimensions
 * - `description`: string - Human-readable description
 *
 * Returns `null` if preset name is not found.
 *
 * # Example
 *
 * ```typescript
 * import { getEmbeddingPreset } from 'kreuzberg';
 *
 * const preset = getEmbeddingPreset('balanced');
 * if (preset) {
 *   console.log(`Model: ${preset.modelName}, Dims: ${preset.dimensions}`);
 *   // Model: BGEBaseENV15, Dims: 768
 * }
 * ```
 */
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.
 *
 * Returns an array of file extensions commonly associated with the specified
 * MIME type. For example, 'application/pdf' returns ['pdf'].
 *
 * # Parameters
 *
 * * `mime_type` - The MIME type to look up (e.g., 'application/pdf', 'image/jpeg')
 *
 * # Returns
 *
 * Array of file extensions (without leading dots).
 *
 * # Errors
 *
 * Throws an error if the MIME type is not recognized or supported.
 *
 * # Example
 *
 * ```typescript
 * import { getExtensionsForMime } from 'kreuzberg';
 *
 * // 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']
 * ```
 */
export declare function getExtensionsForMime(mimeType: string): Array<string>

/**
 * Get the error code for the last FFI error.
 *
 * Returns the FFI error code as an integer. Error codes are:
 * - 0: Success (no error)
 * - 1: GenericError
 * - 2: Panic
 * - 3: InvalidArgument
 * - 4: IoError
 * - 5: ParsingError
 * - 6: OcrError
 * - 7: MissingDependency
 *
 * This is useful for programmatic error handling and distinguishing
 * between different types of failures in native code.
 *
 * # 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');
 *   }
 * }
 * ```
 */
export 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.
 *
 * # Returns
 *
 * A `PanicContext` object with:
 * - `file`: string - Source file where panic occurred
 * - `line`: number - Line number
 * - `function`: string - Function name
 * - `message`: string - Panic message
 * - `timestamp_secs`: number - Unix timestamp (seconds since epoch)
 *
 * Returns `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}`);
 *   }
 * }
 * ```
 */
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

/**
 * Create a PDF page iterator and collect all pages (asynchronous).
 *
 * Non-blocking variant of `iteratePdfPagesSync`. Rendering is offloaded
 * to the worker pool.
 *
 * Note: Pages are collected eagerly into an array. For true lazy iteration,
 * use `new PdfPageIterator(filePath, dpi)` which exposes a `.next()` method
 * that renders one page at a time.
 *
 * # Parameters
 *
 * * `file_path` - Path to the PDF file
 * * `dpi` - Optional DPI (default 150)
 *
 * # Returns
 *
 * Promise resolving to an array of `PdfPageResult` objects.
 */
export declare function iteratePdfPages(filePath: string, dpi?: number | undefined | null): Promise<Array<PdfPageResult>>

/**
 * Create a PDF page iterator and collect all pages (synchronous).
 *
 * Opens the PDF once and renders pages lazily, returning an array of
 * `{ pageIndex, data }` objects. Each page is rendered one at a time so
 * only one raw image is in memory at a time.
 *
 * Note: Pages are collected eagerly into an array. For true lazy iteration,
 * use `new PdfPageIterator(filePath, dpi)` which exposes a `.next()` method
 * that renders one page at a time.
 *
 * # Parameters
 *
 * * `file_path` - Path to the PDF file
 * * `dpi` - Optional DPI (default 150)
 *
 * # Returns
 *
 * Array of `PdfPageResult` objects.
 */
export declare function iteratePdfPagesSync(filePath: string, dpi?: number | undefined | null): Array<PdfPageResult>

/**
 * Hardware acceleration configuration for ONNX Runtime inference.
 *
 * Controls which execution provider (CPU, CoreML, CUDA, TensorRT) is used
 * for layout detection and embedding generation.
 */
export interface JsAccelerationConfig {
  /** Execution provider: "auto" (default), "cpu", "coreml", "cuda", "tensorrt". */
  provider?: string
  /** GPU device ID for CUDA/TensorRT. Ignored for CPU/CoreML/Auto. */
  deviceId?: number
}

export interface JsArchiveEntry {
  path: string
  mimeType: string
  result: JsExtractionResult
}

export interface JsBoundingBox {
  x0: number
  y0: number
  x1: number
  y1: number
}

export interface JsChunk {
  content: string
  chunkType: string
  embedding?: number[] | undefined
  metadata: JsChunkMetadata
}

export interface JsChunkingConfig {
  maxChars?: number
  maxOverlap?: number
  /** Optional embedding configuration for generating embeddings */
  embedding?: JsEmbeddingConfig
  /** Optional preset name for chunking parameters */
  preset?: string
  /**
   * Chunker type: "text" (default), "markdown", "yaml", or "semantic".
   * Set to "semantic" for topic-aware chunking that works out of the box
   * with sensible defaults. No other parameters needed.
   */
  chunkerType?: string
  /** Sizing type: "characters" (default) or "tokenizer" */
  sizingType?: string
  /** HuggingFace model ID for tokenizer sizing (e.g., "Xenova/gpt-4o") */
  sizingModel?: string
  /** Optional cache directory for tokenizer files */
  sizingCacheDir?: string
  /** Prepend heading context to each chunk when using markdown chunker */
  prependHeadingContext?: boolean
  /**
   * Cosine similarity threshold for semantic topic detection (0.0-1.0).
   * Optional, defaults to 0.75. Rarely needs tuning.
   */
  topicThreshold?: number
}

export interface JsChunkMetadata {
  byteStart: number
  byteEnd: number
  tokenCount?: number
  chunkIndex: number
  totalChunks: number
  firstPage?: number
  lastPage?: number
  headingContext?: JsHeadingContext
}

/** Concurrency configuration for Node.js bindings. */
export interface JsConcurrencyConfig {
  /** Maximum number of threads for all internal thread pools. */
  maxThreads?: number
}

/**
 * Content filtering configuration for Node.js bindings.
 *
 * Controls whether "furniture" content (headers, footers, watermarks,
 * repeating text) is included in or stripped from extraction results.
 */
export interface JsContentFilterConfig {
  /** Include running headers in extraction output. Default: false. */
  includeHeaders?: boolean
  /** Include running footers in extraction output. Default: false. */
  includeFooters?: boolean
  /** Enable cross-page repeating text detection and removal. Default: true. */
  stripRepeatingText?: boolean
  /** Include watermark text in extraction output. Default: false. */
  includeWatermarks?: boolean
}

export interface JsElement {
  elementId: string
  elementType: string
  text: string
  metadata: JsElementMetadata
}

export interface JsElementMetadata {
  pageNumber?: number
  filename?: string
  coordinates?: JsBoundingBox
  elementIndex?: number
  additional?: Record<string, string> | undefined
}

/** Email extraction configuration for Node.js bindings. */
export interface JsEmailConfig {
  /**
   * Windows codepage number for MSG files with no codepage property.
   * Common values: 1250 (Central European), 1251 (Cyrillic), 1252 (Western, default),
   * 1253 (Greek), 1254 (Turkish), 932 (Japanese), 936 (Simplified Chinese).
   */
  msgFallbackCodepage?: number
}

/** Embedding generation configuration for Node.js bindings. */
export interface JsEmbeddingConfig {
  /** Embedding model configuration */
  model?: JsEmbeddingModelType
  /** Whether to normalize embeddings (L2 normalization) */
  normalize?: boolean
  /** Batch size for embedding generation */
  batchSize?: number
  /** Whether to show download progress for models */
  showDownloadProgress?: boolean
  /** Custom cache directory for model storage */
  cacheDir?: string
  /** Hardware acceleration configuration for ONNX Runtime inference */
  acceleration?: JsAccelerationConfig
}

/**
 * Embedding model type configuration for Node.js bindings.
 *
 * This struct represents different embedding model sources:
 * - `preset`: Use a named preset (e.g., "balanced", "fast", "quality", "multilingual")
 * - `custom`: Use a custom ONNX model from HuggingFace
 */
export interface JsEmbeddingModelType {
  /** Type of model: "preset" or "custom" */
  modelType: string
  /** For preset: preset name; for custom: HuggingFace model ID */
  value: string
  /** Number of dimensions (only for custom) */
  dimensions?: number
}

export interface JsExtractedImage {
  data: Buffer
  format: string
  imageIndex: number
  pageNumber?: number
  width?: number
  height?: number
  colorspace?: string
  bitsPerComponent?: number
  isMask: boolean
  description?: string
  ocrResult?: JsExtractionResult | undefined
  boundingBox?: JsBoundingBox
  sourcePath?: string
}

export interface JsExtractedKeyword {
  text: string
  score: number
  algorithm: string
  positions?: Array<number>
}

export interface JsExtractionConfig {
  useCache?: boolean
  enableQualityProcessing?: boolean
  ocr?: JsOcrConfig
  forceOcr?: boolean
  /** Disable OCR entirely — image files return empty content instead of errors */
  disableOcr?: boolean
  /** List of 1-indexed page numbers to force OCR on (None = use force_ocr setting) */
  forceOcrPages?: Array<number>
  chunking?: JsChunkingConfig
  images?: JsImageExtractionConfig
  pdfOptions?: JsPdfConfig
  tokenReduction?: JsTokenReductionConfig
  languageDetection?: JsLanguageDetectionConfig
  postprocessor?: JsPostProcessorConfig
  keywords?: JsKeywordConfig
  htmlOptions?: JsHtmlOptions
  maxConcurrentExtractions?: number
  pages?: JsPageConfig
  /** Output text format: "plain" | "markdown" | "djot" | "html" */
  outputFormat?: string
  /** Result structure format: "unified" | "element_based" */
  resultFormat?: string
  /** Include document structure in extraction result */
  includeDocumentStructure?: boolean
  /** Layout detection configuration (None = layout detection disabled) */
  layout?: JsLayoutDetectionConfig
  /** Email extraction configuration */
  email?: JsEmailConfig
  /** Hardware acceleration configuration for ONNX Runtime inference */
  acceleration?: JsAccelerationConfig
  /** Security limits to guard against DoS attacks */
  securityLimits?: JsSecurityLimits
  /** Concurrency configuration for thread pool control */
  concurrency?: JsConcurrencyConfig
  /** Cache namespace for tenant isolation */
  cacheNamespace?: string
  /** Per-request cache TTL in seconds (0 = skip cache) */
  cacheTtlSecs?: number
  /** Maximum recursion depth for archive extraction (default: 3) */
  maxArchiveDepth?: number
  /** Default per-file extraction timeout in seconds */
  extractionTimeoutSecs?: number
  /** Tree-sitter language pack configuration for code analysis */
  treeSitter?: JsTreeSitterConfig
  /** Structured extraction configuration for LLM-based data extraction */
  structuredExtraction?: JsStructuredExtractionConfig
  /** Content filtering configuration for headers/footers/watermarks */
  contentFilter?: JsContentFilterConfig
  /** HTML output configuration for styled HTML rendering */
  htmlOutput?: JsHtmlOutputConfig
}

export interface JsExtractionResult {
  content: string
  mimeType: string
  metadata: Metadata
  tables: Array<JsTable>
  detectedLanguages: Array<string>
  chunks: Array<JsChunk>
  images: Array<JsExtractedImage>
  pages: Array<JsPageContent>
  elements: Array<JsElement>
  document: DocumentStructure | null
  djotContent: DjotContent | null
  ocrElements: OcrElement[] | null
  extractedKeywords: Array<JsExtractedKeyword>
  qualityScore?: number
  processingWarnings: Array<JsProcessingWarning>
  llmUsage: Array<JsLlmUsage>
  annotations: Array<JsPdfAnnotation>
  children: Array<JsArchiveEntry>
  uris: Array<JsUri>
  /** Code intelligence results from tree-sitter processing. */
  codeIntelligence: CodeProcessResult | null
  /** Structured extraction output conforming to the provided JSON schema. */
  structuredOutput: Record<string, unknown> | null
}

export interface JsFileExtractionConfig {
  enableQualityProcessing?: boolean
  ocr?: JsOcrConfig
  forceOcr?: boolean
  /** Disable OCR entirely — image files return empty content instead of errors */
  disableOcr?: boolean
  /** List of 1-indexed page numbers to force OCR on (None = use force_ocr setting) */
  forceOcrPages?: Array<number>
  chunking?: JsChunkingConfig
  images?: JsImageExtractionConfig
  pdfOptions?: JsPdfConfig
  tokenReduction?: JsTokenReductionConfig
  languageDetection?: JsLanguageDetectionConfig
  postprocessor?: JsPostProcessorConfig
  keywords?: JsKeywordConfig
  htmlOptions?: JsHtmlOptions
  pages?: JsPageConfig
  /** Output text format: "plain" | "markdown" | "djot" | "html" */
  outputFormat?: string
  /** Result structure format: "unified" | "element_based" */
  resultFormat?: string
  /** Include document structure in extraction result */
  includeDocumentStructure?: boolean
  /** Layout detection configuration (None = layout detection disabled) */
  layout?: JsLayoutDetectionConfig
  /** Per-file extraction timeout in seconds */
  timeoutSecs?: number
  /** Tree-sitter language pack configuration for code analysis */
  treeSitter?: JsTreeSitterConfig
  /** Structured extraction configuration for LLM-based data extraction */
  structuredExtraction?: JsStructuredExtractionConfig
  /** Content filtering configuration for headers/footers/watermarks */
  contentFilter?: JsContentFilterConfig
}

export interface JsHeadingContext {
  headings: Array<JsHeadingLevel>
}

export interface JsHeadingLevel {
  level: number
  text: string
}

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 {
  headingStyle?: string
  listIndentType?: string
  listIndentWidth?: number
  bullets?: string
  strongEmSymbol?: string
  escapeAsterisks?: boolean
  escapeUnderscores?: boolean
  escapeMisc?: boolean
  escapeAscii?: boolean
  codeLanguage?: string
  autolinks?: boolean
  defaultTitle?: boolean
  brInTables?: boolean
  highlightStyle?: string
  extractMetadata?: boolean
  whitespaceMode?: string
  stripNewlines?: boolean
  wrap?: boolean
  wrapWidth?: number
  convertAsInline?: boolean
  subSymbol?: string
  supSymbol?: string
  newlineStyle?: string
  codeBlockStyle?: string
  keepInlineImagesIn?: Array<string>
  encoding?: string
  debug?: boolean
  stripTags?: Array<string>
  preserveTags?: Array<string>
  preprocessing?: JsHtmlPreprocessingOptions
}

/**
 * HTML output configuration for styled HTML rendering.
 *
 * Controls how `outputFormat: "html"` renders documents when `htmlOutput`
 * is set on the extraction config.
 */
export interface JsHtmlOutputConfig {
  /** Inline CSS string injected after the theme stylesheet. */
  css?: string
  /** Path to a CSS file loaded at renderer construction time. */
  cssFile?: string
  /** Built-in theme: "default", "github", "dark", "light", "unstyled". Default: "unstyled". */
  theme?: string
  /** CSS class prefix for emitted class names. Default: "kb-". */
  classPrefix?: string
  /** Embed resolved CSS in a `<style>` block. Default: true. */
  embedCss?: boolean
}

export interface JsHtmlPreprocessingOptions {
  enabled?: boolean
  preset?: string
  removeNavigation?: boolean
  removeForms?: boolean
}

export interface JsImageExtractionConfig {
  extractImages?: boolean
  targetDpi?: number
  maxImageDimension?: number
  injectPlaceholders?: boolean
  autoAdjustDpi?: boolean
  minDpi?: number
  maxDpi?: number
  maxImagesPerPage?: number
}

export interface JsKeywordConfig {
  algorithm?: string
  maxKeywords?: number
  minScore?: number
  ngramRange?: [number, number] | undefined
  language?: string
  yakeParams?: JsYakeParams
  rakeParams?: JsRakeParams
}

export interface JsLanguageDetectionConfig {
  enabled?: boolean
  minConfidence?: number
  detectMultiple?: boolean
}

export interface JsLayoutDetectionConfig {
  confidenceThreshold?: number
  applyHeuristics?: boolean
  tableModel?: string
  /** Hardware acceleration configuration for ONNX Runtime inference */
  acceleration?: JsAccelerationConfig
}

export interface JsLayoutRegion {
  /** Layout class name (e.g. "picture", "table", "text") */
  class: string
  /** Confidence score (0.0 to 1.0) */
  confidence: number
  /** Bounding box in document coordinate space */
  boundingBox: JsBoundingBox
  /** Fraction of page area covered (0.0 to 1.0) */
  areaFraction: number
}

/**
 * LLM provider/model configuration for Node.js bindings.
 *
 * Used for VLM OCR, VLM embeddings, and structured extraction features.
 */
export interface JsLlmConfig {
  /** Provider/model string using liter-llm routing format (e.g., "openai/gpt-4o"). */
  model: string
  /** API key for the provider. When not set, falls back to provider env var. */
  apiKey?: string
  /** Custom base URL override for the provider endpoint. */
  baseUrl?: string
  /** Request timeout in seconds. */
  timeoutSecs?: number
  /** Maximum retry attempts. */
  maxRetries?: number
  /** Sampling temperature for generation tasks. */
  temperature?: number
  /** Maximum tokens to generate. */
  maxTokens?: number
}

export interface JsLlmUsage {
  model: string
  source: string
  inputTokens?: number | undefined
  outputTokens?: number | undefined
  totalTokens?: number | undefined
  estimatedCost?: number
  finishReason?: string
}

export interface JsOcrConfig {
  enabled?: boolean
  backend: string
  language?: string
  tesseractConfig?: JsTesseractConfig
  paddleOcrConfig?: JsPaddleOcrConfig
  elementConfig?: JsOcrElementConfig
  /** VLM configuration for vision-language model OCR backend. */
  vlmConfig?: JsLlmConfig
  /** Custom prompt template for VLM OCR. */
  vlmPrompt?: string
}

export interface JsOcrElementConfig {
  includeElements?: boolean
  minLevel?: string
  minConfidence?: number
  buildHierarchy?: boolean
}

export interface JsPaddleOcrConfig {
  cacheDir?: string
  useAngleCls?: boolean
  enableTableDetection?: boolean
  detDbThresh?: number
  detDbBoxThresh?: number
  detDbUnclipRatio?: number
  detLimitSideLen?: number
  recBatchNum?: number
  minConfidence?: number
  outputFormat?: string
}

export interface JsPageConfig {
  extractPages?: boolean
  insertPageMarkers?: boolean
  markerFormat?: string
}

export interface JsPageContent {
  pageNumber: number
  content: string
  tables: Array<JsTable>
  images: Array<JsExtractedImage>
  hierarchy?: JsPageHierarchy
  isBlank?: boolean
  layoutRegions?: Array<JsLayoutRegion>
}

export interface JsPageHierarchy {
  blockCount: number
  blocks: Array<JsHierarchicalBlock>
}

export interface JsPdfAnnotation {
  annotationType: string
  content?: string
  pageNumber: number
  boundingBox?: JsBoundingBox
}

export interface JsPdfConfig {
  extractImages?: boolean
  passwords?: Array<string>
  extractMetadata?: boolean
  hierarchy?: JsHierarchyConfig
  extractAnnotations?: boolean
  topMarginFraction?: number
  bottomMarginFraction?: number
  allowSingleColumnTables?: boolean
}

export interface JsPostProcessorConfig {
  enabled?: boolean
  enabledProcessors?: Array<string>
  disabledProcessors?: Array<string>
}

export interface JsProcessingWarning {
  source: string
  message: string
}

export interface JsRakeParams {
  minWordLength?: number
  maxWordsPerPhrase?: number
}

/** Security limits to protect against DoS attacks (ZIP bombs, XML entity expansion, etc.). */
export interface JsSecurityLimits {
  /** Maximum uncompressed size for archives in bytes. */
  maxArchiveSize?: number
  /** Maximum compression ratio before flagging as potential bomb. */
  maxCompressionRatio?: number
  /** Maximum number of files in an archive. */
  maxFilesInArchive?: number
  /** Maximum nesting depth for structures. */
  maxNestingDepth?: number
  /** Maximum entity/string length. */
  maxEntityLength?: number
  /** Maximum content size in bytes. */
  maxContentSize?: number
  /** Maximum iterations per operation. */
  maxIterations?: number
  /** Maximum XML depth in levels. */
  maxXmlDepth?: number
  /** Maximum cells per table. */
  maxTableCells?: number
}

/**
 * Structured extraction configuration for Node.js bindings.
 *
 * Sends extracted document content to an LLM with a JSON schema,
 * returning structured data conforming to the schema.
 */
export interface JsStructuredExtractionConfig {
  /** JSON Schema defining the desired output structure. */
  schema: Record<string, unknown>
  /** LLM configuration for the extraction. */
  llm: JsLlmConfig
  /** Schema name passed to the LLM's structured output mode. */
  schemaName?: string
  /** Optional schema description for the LLM. */
  schemaDescription?: string
  /** Enable strict mode — output must exactly match the schema. */
  strict?: boolean
  /** Custom Jinja2 extraction prompt template. */
  prompt?: string
}

export interface JsTable {
  cells: Array<Array<string>>
  markdown: string
  pageNumber: number
  boundingBox?: JsBoundingBox
}

export interface JsTesseractConfig {
  psm?: number
  enableTableDetection?: boolean
  tesseditCharWhitelist?: string
}

export interface JsTokenReductionConfig {
  mode?: string
  preserveImportantWords?: boolean
}

/** Tree-sitter language pack configuration for Node.js bindings. */
export interface JsTreeSitterConfig {
  /** Enable code intelligence processing. Default: true. */
  enabled?: boolean
  /** Custom cache directory for downloaded grammars. */
  cacheDir?: string
  /** Languages to pre-download on init (e.g., ["python", "rust"]). */
  languages?: Array<string>
  /** Language groups to pre-download (e.g., ["web", "systems", "scripting"]). */
  groups?: Array<string>
  /** Processing options for code analysis. */
  process?: JsTreeSitterProcessConfig
}

/** Tree-sitter processing options for Node.js bindings. */
export interface JsTreeSitterProcessConfig {
  /** Extract structural items (functions, classes, structs, etc.). Default: true. */
  structure?: boolean
  /** Extract import statements. Default: true. */
  imports?: boolean
  /** Extract export statements. Default: true. */
  exports?: boolean
  /** Extract comments. Default: false. */
  comments?: boolean
  /** Extract docstrings. Default: false. */
  docstrings?: boolean
  /** Extract symbol definitions. Default: false. */
  symbols?: boolean
  /** Include parse diagnostics. Default: false. */
  diagnostics?: boolean
  /** Maximum chunk size in bytes. None disables chunking. */
  chunkMaxSize?: number
  /** Content rendering mode: "chunks" (default), "raw", or "structure". */
  contentMode?: string
}

export interface JsUri {
  url: string
  label?: string
  page?: number
  kind: string
}

export interface JsYakeParams {
  windowSize?: number
}

export declare function listDocumentExtractors(): Array<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';
 *
 * const presets = listEmbeddingPresets();
 * console.log(presets); // ['fast', 'balanced', 'quality', 'multilingual']
 * ```
 */
export declare function listEmbeddingPresets(): Array<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';
 *
 * const presets = listEmbeddingPresets();
 * console.log(presets); // ['fast', 'balanced', 'quality', 'multilingual']
 * ```
 */
export declare function listEmbeddingPresets(): Array<string>

/** List all registered OCR backends */
export declare function listOcrBackends(): Array<string>

/** List all registered post-processors */
export declare function listPostProcessors(): Array<string>

/** List all registered validators */
export declare function listValidators(): Array<string>

/**
 * Load extraction configuration from a file.
 *
 * Automatically detects the file format based on extension:
 * - `.toml` - TOML format
 * - `.yaml` - YAML format
 * - `.json` - JSON format
 *
 * # Parameters
 *
 * * `file_path` - Path to the configuration file (absolute or relative)
 *
 * # Returns
 *
 * `JsExtractionConfig` object with loaded configuration.
 *
 * # Errors
 *
 * Throws an error if:
 * - File does not exist or is not accessible
 * - File content is not valid TOML/YAML/JSON
 * - Configuration structure is invalid
 *
 * # Example
 *
 * ```typescript
 * import { loadExtractionConfigFromFile } from 'kreuzberg';
 *
 * // Load from TOML file
 * const config = loadExtractionConfigFromFile('kreuzberg.toml');
 *
 * // Load from YAML file
 * const config2 = loadExtractionConfigFromFile('./config.yaml');
 *
 * // Use with extraction
 * const result = await extractFile('document.pdf', null, config);
 * ```
 */
export declare function loadExtractionConfigFromFile(filePath: string): JsExtractionConfig

/**
 * Get the number of pages in a PDF file without rendering.
 *
 * # Parameters
 *
 * * `file_path` - Path to the PDF file
 * * `dpi` - Optional DPI (not used for counting, but validates the PDF)
 *
 * # Returns
 *
 * Number of pages in the PDF.
 */
export declare function pdfPageCount(filePath: string, dpi?: number | undefined | null): number

/** A rendered PDF page with its zero-based index and PNG data. */
export interface PdfPageResult {
  /** Zero-based page index. */
  pageIndex: number
  /** PNG image data. */
  data: Buffer
}

/**
 * Register a custom OCR backend
 *
 * Registers a JavaScript OCR backend that can process images and extract text.
 *
 * # Arguments
 *
 * * `backend` - JavaScript object with the following interface:
 *   - `name(): string` - Unique backend name
 *   - `supportedLanguages(): string[]` - Array of supported ISO 639-2/3 language codes
 *   - `processImage(imageBytes: string, language: string): Promise<result>` - Process image and return extraction result
 *
 * # Implementation Notes
 *
 * Due to NAPI ThreadsafeFunction limitations, the processImage function receives:
 * - `imageBytes` as a Base64 string (first argument)
 * - `language` as string (second argument)
 *
 * And must return a Promise resolving to a JSON-serializable object with:
 * ```typescript
 * {
 *   content: string,
 *   mime_type: string,  // default: "text/plain"
 *   metadata: object,   // default: {}
 *   tables: array       // default: []
 * }
 * ```
 *
 * # Example
 *
 * ```typescript
 * import { registerOcrBackend } from '@kreuzberg/node';
 *
 * registerOcrBackend({
 *   name: () => "my-ocr",
 *   supportedLanguages: () => ["eng", "deu", "fra"],
 *   processImage: async (imageBytes, language) => {
 *     const buffer = Buffer.from(imageBytes, "base64");
 *     const text = await myOcrLibrary.process(buffer, language);
 *     return {
 *       content: text,
 *       mime_type: "text/plain",
 *       metadata: { confidence: 0.95 },
 *       tables: []
 *     };
 *   }
 * });
 * ```
 */
export declare function registerOcrBackend(backend: object): void

/**
 * Register a custom postprocessor
 *
 * Registers a JavaScript PostProcessor that will be called after extraction.
 *
 * # Arguments
 *
 * * `processor` - JavaScript object with the following interface:
 *   - `name(): string` - Unique processor name
 *   - `process(...args): string` - Process function that receives JSON string as args\[0\]
 *   - `processingStage(): "early" | "middle" | "late"` - Optional processing stage
 *
 * # Implementation Notes
 *
 * Due to NAPI ThreadsafeFunction limitations, the process function receives the extraction
 * result as a JSON string in args\[0\] and must return a JSON string. Use the TypeScript
 * wrapper functions for a cleaner API.
 *
 * # Example
 *
 * ```typescript
 * import { registerPostProcessor } from '@kreuzberg/node';
 *
 * registerPostProcessor({
 *   name: () => "word-counter",
 *   processingStage: () => "middle",
 *   process: (...args) => {
 *     const result = JSON.parse(args[0]);
 *     const wordCount = result.content.split(/\s+/).length;
 *     result.metadata.word_count = wordCount;
 *     return JSON.stringify(result);
 *   }
 * });
 * ```
 */
export declare function registerPostProcessor(processor: object): void

/**
 * Register a custom validator
 *
 * Registers a JavaScript Validator that will be called after extraction.
 *
 * # Arguments
 *
 * * `validator` - JavaScript object with the following interface:
 *   - `name(): string` - Unique validator name
 *   - `validate(...args): Promise<string>` - Validate function that receives JSON string as args\[0\]
 *   - `priority(): number` - Optional priority (defaults to 50, higher runs first)
 *
 * # Implementation Notes
 *
 * Due to NAPI ThreadsafeFunction limitations, the validate function receives the extraction
 * result as a JSON string in args\[0\]. On success, return an empty string. On validation
 * failure, throw an error (the Promise should reject). Use the TypeScript wrapper functions
 * for a cleaner API.
 *
 * # Example
 *
 * ```typescript
 * import { registerValidator } from '@kreuzberg/node';
 *
 * registerValidator({
 *   name: () => "min-length",
 *   priority: () => 100,
 *   validate: async (...args) => {
 *     const result = JSON.parse(args[0]);
 *     if (result.content.length < 100) {
 *       throw new Error("ValidationError: Content too short");
 *     }
 *     return ""; // Success - return empty string
 *   }
 * });
 * ```
 */
export declare function registerValidator(validator: object): void

/**
 * Render a single page of a PDF file to a PNG buffer (asynchronous).
 *
 * Non-blocking alternative to `renderPdfPageSync`.
 *
 * # Parameters
 *
 * * `file_path` - Path to the PDF file
 * * `page_index` - Zero-based page index
 * * `dpi` - Optional DPI (default 150)
 *
 * # Returns
 *
 * Promise resolving to a Buffer containing PNG image data.
 */
export declare function renderPdfPage(filePath: string, pageIndex: number, dpi?: number | undefined | null): Promise<Buffer>

/**
 * Render a single page of a PDF file to a PNG buffer (synchronous).
 *
 * # Parameters
 *
 * * `file_path` - Path to the PDF file
 * * `page_index` - Zero-based page index
 * * `dpi` - Optional DPI (default 150)
 *
 * # Returns
 *
 * Buffer containing PNG image data.
 */
export declare function renderPdfPageSync(filePath: string, pageIndex: number, dpi?: number | undefined | null): Buffer

/**
 * 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).
 *
 * # Parameters
 *
 * * `name` - Name of the document extractor to unregister
 *
 * # Example
 *
 * ```typescript
 * import { unregisterDocumentExtractor } from 'kreuzberg';
 *
 * // Unregister a custom extractor
 * unregisterDocumentExtractor('MyCustomExtractor');
 * ```
 */
export declare function unregisterDocumentExtractor(name: string): void

/** Unregister an OCR backend by name */
export declare function unregisterOcrBackend(name: string): void

/** Unregister a postprocessor by name */
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(maxCharacters: number, overlap: 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.
 *
 * Checks if a MIME type is in the list of supported formats. Note that any
 * `image/*` MIME type is automatically considered valid.
 *
 * # Parameters
 *
 * * `mime_type` - The MIME type to validate (string)
 *
 * # Returns
 *
 * The validated MIME type (may be normalized).
 *
 * # Errors
 *
 * Throws an error if the MIME type is not supported.
 */
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
}