@kreuzberg/node 4.0.0-rc.15 → 4.0.0-rc.16

package/index.d.ts

@@ -125,6 +125,8 @@ export declare function batchExtractFiles(paths: Array<string>, config?: JsExtra
  */
 export declare function batchExtractFilesSync(paths: Array<string>, config?: JsExtractionConfig | undefined | null): Array<JsExtractionResult>
 
+export declare function classifyError(errorMessage: string): ErrorClassification
+
 /**
  * Clear all registered document extractors.
  *
@@ -165,6 +167,56 @@ export declare function clearPostProcessors(): void
 /** Clear all registered validators */
 export declare function clearValidators(): 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
+
 /**
  * Detect MIME type from raw bytes.
  *
@@ -285,6 +337,53 @@ export interface EmbeddingPreset {
   description: string
 }
 
+/**
+ * Classifies an error message string into an error code category.
+ *
+ * This function analyzes the error message content and returns the most likely
+ * error code (0-7) based on keyword patterns. Used to programmatically classify
+ * errors for handling purposes.
+ *
+ * # Arguments
+ *
+ * * `error_message` - The error message string to classify
+ *
+ * # Returns
+ *
+ * An object with:
+ * - `code`: The numeric error code (0-7)
+ * - `name`: The error code name string
+ * - `description`: Brief description of the error type
+ * - `confidence`: Confidence score (0.0-1.0) of the classification
+ *
+ * # Classification Rules
+ *
+ * - **Validation (0)**: Keywords: invalid, validation, invalid_argument, schema, required, unexpected field
+ * - **Parsing (1)**: Keywords: parsing, parse_error, corrupted, malformed, invalid format, decode, encoding
+ * - **Ocr (2)**: Keywords: ocr, optical, character, recognition, tesseract, language, model
+ * - **MissingDependency (3)**: Keywords: not found, not installed, missing, dependency, require, unavailable
+ * - **Io (4)**: Keywords: io, file, disk, read, write, permission, access, path
+ * - **Plugin (5)**: Keywords: plugin, register, extension, handler, processor
+ * - **UnsupportedFormat (6)**: Keywords: unsupported, format, mime, type, codec
+ * - **Internal (7)**: Keywords: internal, bug, panic, unexpected, invariant
+ *
+ * # Examples
+ *
+ * ```typescript
+ * const result = classifyError("PDF file is corrupted");
+ * // Returns: { code: 1, name: "parsing", confidence: 0.95 }
+ *
+ * const result = classifyError("Tesseract not found");
+ * // Returns: { code: 3, name: "missing_dependency", confidence: 0.9 }
+ * ```
+ */
+export interface ErrorClassification {
+  code: number
+  name: string
+  description: string
+  confidence: number
+}
+
 /**
  * Extract content from bytes (asynchronous).
  *
@@ -473,6 +572,52 @@ export declare function extractFileSync(filePath: string, mimeType?: string | un
  */
 export declare function getEmbeddingPreset(name: string): EmbeddingPreset | null
 
+/**
+ * Returns the description for an error code.
+ *
+ * Maps to FFI function kreuzberg_error_code_description().
+ *
+ * # Arguments
+ *
+ * * `code` - Numeric error code (0-7)
+ *
+ * # Returns
+ *
+ * A string containing a brief description of the error
+ *
+ * # Examples
+ *
+ * ```typescript
+ * const desc = getErrorCodeDescription(0);  // returns "Input validation error"
+ * const desc = getErrorCodeDescription(4);  // returns "File system I/O error"
+ * const desc = getErrorCodeDescription(99); // returns "Unknown error code"
+ * ```
+ */
+export declare function getErrorCodeDescription(code: number): string
+
+/**
+ * Returns the human-readable name for an error code.
+ *
+ * Maps to FFI function kreuzberg_error_code_name().
+ *
+ * # Arguments
+ *
+ * * `code` - Numeric error code (0-7)
+ *
+ * # Returns
+ *
+ * A string containing the error code name (e.g., "validation", "ocr", "unknown")
+ *
+ * # Examples
+ *
+ * ```typescript
+ * const name = getErrorCodeName(0);  // returns "validation"
+ * const name = getErrorCodeName(2);  // returns "ocr"
+ * const name = getErrorCodeName(99); // returns "unknown"
+ * ```
+ */
+export declare function getErrorCodeName(code: number): string
+
 /**
  * Get file extensions for a given MIME type.
  *
@@ -580,6 +725,86 @@ export declare function getLastErrorCode(): number
  */
 export declare function getLastPanicContext(): any | null
 
+/**
+ * Get valid binarization methods.
+ *
+ * Returns a list of all valid binarization method values.
+ *
+ * # Returns
+ *
+ * Array of valid binarization methods: ["otsu", "adaptive", "sauvola"]
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { getValidBinarizationMethods } from '@kreuzberg/node';
+ *
+ * const methods = getValidBinarizationMethods();
+ * console.log(methods); // ['otsu', 'adaptive', 'sauvola']
+ * ```
+ */
+export declare function getValidBinarizationMethods(): Array<string>
+
+/**
+ * Get valid language codes.
+ *
+ * Returns a list of all valid language codes in ISO 639-1 and 639-3 formats.
+ *
+ * # Returns
+ *
+ * Array of valid language codes (both 2-letter and 3-letter codes)
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { getValidLanguageCodes } from '@kreuzberg/node';
+ *
+ * const codes = getValidLanguageCodes();
+ * console.log(codes); // ['en', 'de', 'fr', ..., 'eng', 'deu', 'fra', ...]
+ * ```
+ */
+export declare function getValidLanguageCodes(): Array<string>
+
+/**
+ * Get valid OCR backends.
+ *
+ * Returns a list of all valid OCR backend values.
+ *
+ * # Returns
+ *
+ * Array of valid OCR backends: ["tesseract", "easyocr", "paddleocr"]
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { getValidOcrBackends } from '@kreuzberg/node';
+ *
+ * const backends = getValidOcrBackends();
+ * console.log(backends); // ['tesseract', 'easyocr', 'paddleocr']
+ * ```
+ */
+export declare function getValidOcrBackends(): Array<string>
+
+/**
+ * Get valid token reduction levels.
+ *
+ * Returns a list of all valid token reduction level values.
+ *
+ * # Returns
+ *
+ * Array of valid levels: ["off", "light", "moderate", "aggressive", "maximum"]
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { getValidTokenReductionLevels } from '@kreuzberg/node';
+ *
+ * const levels = getValidTokenReductionLevels();
+ * console.log(levels); // ['off', 'light', 'moderate', 'aggressive', 'maximum']
+ * ```
+ */
+export declare function getValidTokenReductionLevels(): Array<string>
+
 export interface JsChunk {
   content: string
   embedding?: number[] | undefined
@@ -1076,6 +1301,134 @@ export declare function unregisterPostProcessor(name: string): void
 /** Unregister a validator by name */
 export declare function unregisterValidator(name: string): void
 
+/**
+ * Validates a binarization method string.
+ *
+ * Valid methods: "otsu", "adaptive", "sauvola"
+ *
+ * # Arguments
+ *
+ * * `method` - The binarization method to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateBinarizationMethod } from '@kreuzberg/node';
+ *
+ * if (validateBinarizationMethod('otsu')) {
+ *   console.log('Valid method');
+ * } else {
+ *   console.log('Invalid method');
+ * }
+ * ```
+ */
+export declare function validateBinarizationMethod(method: string): boolean
+
+/**
+ * Validates chunking parameters.
+ *
+ * Checks that `maxChars > 0` and `maxOverlap < maxChars`.
+ *
+ * # Arguments
+ *
+ * * `max_chars` - Maximum characters per chunk
+ * * `max_overlap` - Maximum overlap between chunks
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateChunkingParams } from '@kreuzberg/node';
+ *
+ * if (validateChunkingParams(1000, 200)) {
+ *   console.log('Valid chunking parameters');
+ * }
+ * ```
+ */
+export declare function validateChunkingParams(maxChars: number, maxOverlap: number): boolean
+
+/**
+ * Validates a confidence threshold value.
+ *
+ * Valid range: 0.0 to 1.0 (inclusive)
+ *
+ * # Arguments
+ *
+ * * `confidence` - The confidence threshold to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateConfidence } from '@kreuzberg/node';
+ *
+ * if (validateConfidence(0.75)) {
+ *   console.log('Valid confidence threshold');
+ * }
+ * ```
+ */
+export declare function validateConfidence(confidence: number): boolean
+
+/**
+ * Validates a DPI (dots per inch) value.
+ *
+ * Valid range: 1-2400
+ *
+ * # Arguments
+ *
+ * * `dpi` - The DPI value to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateDpi } from '@kreuzberg/node';
+ *
+ * if (validateDpi(300)) {
+ *   console.log('Valid DPI');
+ * }
+ * ```
+ */
+export declare function validateDpi(dpi: number): boolean
+
+/**
+ * Validates a language code (ISO 639-1 or 639-3 format).
+ *
+ * Accepts both 2-letter codes (e.g., "en", "de") and 3-letter codes (e.g., "eng", "deu").
+ *
+ * # Arguments
+ *
+ * * `code` - The language code to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateLanguageCode } from '@kreuzberg/node';
+ *
+ * if (validateLanguageCode('en')) {
+ *   console.log('Valid language code');
+ * }
+ * ```
+ */
+export declare function validateLanguageCode(code: string): boolean
+
 /**
  * Validate that a MIME type is supported by Kreuzberg.
  *
@@ -1116,3 +1469,128 @@ export declare function unregisterValidator(name: string): void
  * ```
  */
 export declare function validateMimeType(mimeType: string): string
+
+/**
+ * Validates an OCR backend string.
+ *
+ * Valid backends: "tesseract", "easyocr", "paddleocr"
+ *
+ * # Arguments
+ *
+ * * `backend` - The OCR backend to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateOcrBackend } from '@kreuzberg/node';
+ *
+ * if (validateOcrBackend('tesseract')) {
+ *   console.log('Valid backend');
+ * }
+ * ```
+ */
+export declare function validateOcrBackend(backend: string): boolean
+
+/**
+ * Validates a tesseract output format string.
+ *
+ * Valid formats: "text", "markdown"
+ *
+ * # Arguments
+ *
+ * * `format` - The output format to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateOutputFormat } from '@kreuzberg/node';
+ *
+ * if (validateOutputFormat('markdown')) {
+ *   console.log('Valid output format');
+ * }
+ * ```
+ */
+export declare function validateOutputFormat(format: string): boolean
+
+/**
+ * Validates a Tesseract OCR Engine Mode (OEM) value.
+ *
+ * Valid range: 0-3
+ *
+ * # Arguments
+ *
+ * * `oem` - The OEM value to validate
+ *
+ * # Returns
+ *
+ * `true` if valid (0-3), `false` otherwise.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateTesseractOem } from '@kreuzberg/node';
+ *
+ * if (validateTesseractOem(1)) {
+ *   console.log('Valid OEM');
+ * }
+ * ```
+ */
+export declare function validateTesseractOem(oem: number): boolean
+
+/**
+ * Validates a Tesseract Page Segmentation Mode (PSM) value.
+ *
+ * Valid range: 0-13
+ *
+ * # Arguments
+ *
+ * * `psm` - The PSM value to validate
+ *
+ * # Returns
+ *
+ * `true` if valid (0-13), `false` otherwise.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateTesseractPsm } from '@kreuzberg/node';
+ *
+ * if (validateTesseractPsm(3)) {
+ *   console.log('Valid PSM');
+ * }
+ * ```
+ */
+export declare function validateTesseractPsm(psm: number): boolean
+
+/**
+ * Validates a token reduction level string.
+ *
+ * Valid levels: "off", "light", "moderate", "aggressive", "maximum"
+ *
+ * # Arguments
+ *
+ * * `level` - The token reduction level to validate
+ *
+ * # Returns
+ *
+ * `true` if valid, `false` if invalid.
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { validateTokenReductionLevel } from '@kreuzberg/node';
+ *
+ * if (validateTokenReductionLevel('moderate')) {
+ *   console.log('Valid token reduction level');
+ * }
+ * ```
+ */
+export declare function validateTokenReductionLevel(level: string): boolean