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

package/README.md

@@ -1,26 +1,36 @@
-# Kreuzberg for Node.js
+# Kreuzberg
+
+[![Rust](https://img.shields.io/crates/v/kreuzberg?label=Rust)](https://crates.io/crates/kreuzberg)
+[![Python](https://img.shields.io/pypi/v/kreuzberg?label=Python)](https://pypi.org/project/kreuzberg/)
+[![TypeScript](https://img.shields.io/npm/v/@kreuzberg/node?label=TypeScript)](https://www.npmjs.com/package/@kreuzberg/node)
+[![WASM](https://img.shields.io/npm/v/@kreuzberg/wasm?label=WASM)](https://www.npmjs.com/package/@kreuzberg/wasm)
+[![Ruby](https://img.shields.io/gem/v/kreuzberg?label=Ruby)](https://rubygems.org/gems/kreuzberg)
+[![Java](https://img.shields.io/maven-central/v/dev.kreuzberg/kreuzberg?label=Java)](https://central.sonatype.com/artifact/dev.kreuzberg/kreuzberg)
+[![Go](https://img.shields.io/github/v/tag/kreuzberg-dev/kreuzberg?label=Go)](https://pkg.go.dev/github.com/kreuzberg-dev/kreuzberg)
+[![C#](https://img.shields.io/nuget/v/Goldziher.Kreuzberg?label=C%23)](https://www.nuget.org/packages/Goldziher.Kreuzberg/)
 
-[![npm](https://img.shields.io/npm/v/kreuzberg)](https://www.npmjs.com/package/kreuzberg)
-[![Crates.io](https://img.shields.io/crates/v/kreuzberg)](https://crates.io/crates/kreuzberg)
-[![PyPI](https://img.shields.io/pypi/v/kreuzberg)](https://pypi.org/project/kreuzberg/)
-[![RubyGems](https://img.shields.io/gem/v/kreuzberg)](https://rubygems.org/gems/kreuzberg)
-[![Node Version](https://img.shields.io/node/v/kreuzberg)](https://www.npmjs.com/package/kreuzberg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Documentation](https://img.shields.io/badge/docs-kreuzberg.dev-blue)](https://kreuzberg.dev)
+[![Documentation](https://img.shields.io/badge/docs-kreuzberg.dev-blue)](https://kreuzberg.dev/)
+[![Discord](https://img.shields.io/badge/Discord-Join%20our%20community-7289da)](https://discord.gg/pXxagNK2zN)
 
 High-performance document intelligence for Node.js and TypeScript, powered by Rust.
 
-Extract text, tables, images, and metadata from 50+ file formats including PDF, DOCX, PPTX, XLSX, images, and more.
+Extract text, tables, images, and metadata from 56 file formats including PDF, DOCX, PPTX, XLSX, images, and more.
+
+> **Recommended for Node.js and Bun** - Native NAPI-RS bindings provide the best performance (2-3x faster than WASM).
+>
+> For browser, Deno, or Cloudflare Workers, use [@kreuzberg/wasm](../kreuzberg-wasm/) instead.
 
-> **🚀 Version 4.0.0 Release Candidate**
+> **Version 4.0.0 Release Candidate**
 > This is a pre-release version. We invite you to test the library and [report any issues](https://github.com/kreuzberg-dev/kreuzberg/issues) you encounter.
 
 ## Features
 
-- **50+ File Formats**: PDF, DOCX, PPTX, XLSX, images, HTML, Markdown, XML, JSON, and more
+- **56 File Formats**: PDF, DOCX, PPTX, XLSX, images, HTML, Markdown, XML, JSON, and more
 - **OCR Support**: Built-in Tesseract, EasyOCR, and PaddleOCR backends for scanned documents
 - **Table Extraction**: Advanced table detection and structured data extraction
-- **High Performance**: Native Rust core provides 10-50x performance improvements over pure JavaScript
+- **Native Performance**: 2-3x faster than WASM; 10-50x faster than pure JavaScript
+- **Zero-Copy Operations**: Direct system calls and minimal data copying
 - **Type-Safe**: Full TypeScript definitions for all methods, configurations, and return types
 - **Async/Sync APIs**: Both asynchronous and synchronous extraction methods
 - **Batch Processing**: Process multiple documents in parallel with optimized concurrency
@@ -29,6 +39,27 @@ Extract text, tables, images, and metadata from 50+ file formats including PDF,
 - **Caching**: Built-in result caching for faster repeated extractions
 - **Zero Configuration**: Works out of the box with sensible defaults
 
+## Why Use This Package?
+
+Choose `@kreuzberg/node` if you're building with:
+
+- **Node.js 18+** - Native bindings provide direct access to system resources
+- **Bun** - Full compatibility with Bun's Node.js API
+- **Performance-critical applications** - Processing large document batches or real-time extraction
+- **Server-side extraction** - APIs, microservices, document processing pipelines
+
+### Comparison with @kreuzberg/wasm
+
+| Aspect | `@kreuzberg/node` | `@kreuzberg/wasm` |
+|--------|------------------|-------------------|
+| **Performance** | 2-3x faster (native) | Standard baseline |
+| **Environment** | Node.js, Bun | Browser, Deno, Workers, Node.js |
+| **Bundle Size** | 10-15 MB (prebuilt binary) | 2-4 MB (WASM module) |
+| **System Access** | Direct system calls | Sandboxed via WASM |
+| **Best For** | Server-side, batch processing | Client-side, edge computing |
+
+Use `@kreuzberg/wasm` for browser applications, Cloudflare Workers, Deno, or when you need a smaller bundle size.
+
 ## Requirements
 
 - Node.js 18 or higher
@@ -537,7 +568,7 @@ Processing 100 mixed documents (PDF, DOCX, XLSX):
 If you encounter errors about missing native modules:
 
 ```bash
-npm rebuild kreuzberg
+npm rebuild @kreuzberg/node
 ```
 
 ### OCR Not Working
@@ -653,7 +684,7 @@ For comprehensive documentation, visit [https://kreuzberg.dev](https://kreuzberg
 
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](https://github.com/kreuzberg-dev/kreuzberg/blob/main/docs/contributing.md) for details.
+We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
 
 ## License
 
@@ -666,4 +697,4 @@ MIT
 - [GitHub](https://github.com/kreuzberg-dev/kreuzberg)
 - [Issue Tracker](https://github.com/kreuzberg-dev/kreuzberg/issues)
 - [Changelog](https://github.com/kreuzberg-dev/kreuzberg/blob/main/CHANGELOG.md)
-- [npm Package](https://www.npmjs.com/package/kreuzberg)
+- [npm Package](https://www.npmjs.com/package/@kreuzberg/node)

package/dist/cli.d.mts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Proxy entry point that forwards to the Rust-based Kreuzberg CLI.
+ *
+ * This keeps `npx kreuzberg` working without shipping an additional TypeScript CLI implementation.
+ */
+declare function main(argv: string[]): number;
+
+export { main };

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Proxy entry point that forwards to the Rust-based Kreuzberg CLI.
+ *
+ * This keeps `npx kreuzberg` working without shipping an additional TypeScript CLI implementation.
+ */
+declare function main(argv: string[]): number;
+
+export { main };

package/dist/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var cli_exports = {};
+__export(cli_exports, {
+  main: () => main
+});
+module.exports = __toCommonJS(cli_exports);
+var import_node_child_process = require("node:child_process");
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var import_node_url = require("node:url");
+var import_which = __toESM(require("which"));
+const import_meta = {};
+function main(argv) {
+  const args = argv.slice(2);
+  let cliPath;
+  try {
+    cliPath = import_which.default.sync("kreuzberg-cli");
+  } catch {
+  }
+  if (!cliPath) {
+    const __dirname = typeof __filename !== "undefined" ? (0, import_node_path.dirname)(__filename) : (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+    const devBinary = (0, import_node_path.join)(__dirname, "..", "..", "..", "target", "release", "kreuzberg");
+    if ((0, import_node_fs.existsSync)(devBinary)) {
+      cliPath = devBinary;
+    }
+  }
+  if (!cliPath) {
+    console.error(
+      "The embedded Kreuzberg CLI binary could not be located. This indicates a packaging issue; please open an issue at https://github.com/kreuzberg-dev/kreuzberg/issues so we can investigate."
+    );
+    return 1;
+  }
+  const result = (0, import_node_child_process.spawnSync)(cliPath, args, {
+    stdio: "inherit",
+    shell: false
+  });
+  if (result.error) {
+    console.error(`Failed to execute kreuzberg-cli: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../typescript/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * Proxy entry point that forwards to the Rust-based Kreuzberg CLI.\n *\n * This keeps `npx kreuzberg` working without shipping an additional TypeScript CLI implementation.\n */\n\nimport { spawnSync } from \"node:child_process\";\nimport { existsSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport which from \"which\";\n\nfunction main(argv: string[]): number {\n\tconst args = argv.slice(2);\n\n\tlet cliPath: string | undefined;\n\ttry {\n\t\tcliPath = which.sync(\"kreuzberg-cli\");\n\t} catch {}\n\n\tif (!cliPath) {\n\t\tconst __dirname = typeof __filename !== \"undefined\" ? dirname(__filename) : dirname(fileURLToPath(import.meta.url));\n\t\tconst devBinary = join(__dirname, \"..\", \"..\", \"..\", \"target\", \"release\", \"kreuzberg\");\n\t\tif (existsSync(devBinary)) {\n\t\t\tcliPath = devBinary;\n\t\t}\n\t}\n\n\tif (!cliPath) {\n\t\tconsole.error(\n\t\t\t\"The embedded Kreuzberg CLI binary could not be located. \" +\n\t\t\t\t\"This indicates a packaging issue; please open an issue at \" +\n\t\t\t\t\"https://github.com/kreuzberg-dev/kreuzberg/issues so we can investigate.\",\n\t\t);\n\t\treturn 1;\n\t}\n\n\tconst result = spawnSync(cliPath, args, {\n\t\tstdio: \"inherit\",\n\t\tshell: false,\n\t});\n\n\tif (result.error) {\n\t\tconsole.error(`Failed to execute kreuzberg-cli: ${result.error.message}`);\n\t\treturn 1;\n\t}\n\n\treturn result.status ?? 1;\n}\n\nif (require.main === module) {\n\tprocess.exit(main(process.argv));\n}\n\nexport { main };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,gCAA0B;AAC1B,qBAA2B;AAC3B,uBAA8B;AAC9B,sBAA8B;AAC9B,mBAAkB;AAZlB;AAcA,SAAS,KAAK,MAAwB;AACrC,QAAM,OAAO,KAAK,MAAM,CAAC;AAEzB,MAAI;AACJ,MAAI;AACH,cAAU,aAAAA,QAAM,KAAK,eAAe;AAAA,EACrC,QAAQ;AAAA,EAAC;AAET,MAAI,CAAC,SAAS;AACb,UAAM,YAAY,OAAO,eAAe,kBAAc,0BAAQ,UAAU,QAAI,8BAAQ,+BAAc,YAAY,GAAG,CAAC;AAClH,UAAM,gBAAY,uBAAK,WAAW,MAAM,MAAM,MAAM,UAAU,WAAW,WAAW;AACpF,YAAI,2BAAW,SAAS,GAAG;AAC1B,gBAAU;AAAA,IACX;AAAA,EACD;AAEA,MAAI,CAAC,SAAS;AACb,YAAQ;AAAA,MACP;AAAA,IAGD;AACA,WAAO;AAAA,EACR;AAEA,QAAM,aAAS,qCAAU,SAAS,MAAM;AAAA,IACvC,OAAO;AAAA,IACP,OAAO;AAAA,EACR,CAAC;AAED,MAAI,OAAO,OAAO;AACjB,YAAQ,MAAM,oCAAoC,OAAO,MAAM,OAAO,EAAE;AACxE,WAAO;AAAA,EACR;AAEA,SAAO,OAAO,UAAU;AACzB;AAEA,IAAI,QAAQ,SAAS,QAAQ;AAC5B,UAAQ,KAAK,KAAK,QAAQ,IAAI,CAAC;AAChC;","names":["which"]}

package/dist/cli.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import which from "which";
+function main(argv) {
+  const args = argv.slice(2);
+  let cliPath;
+  try {
+    cliPath = which.sync("kreuzberg-cli");
+  } catch {
+  }
+  if (!cliPath) {
+    const __dirname = typeof __filename !== "undefined" ? dirname(__filename) : dirname(fileURLToPath(import.meta.url));
+    const devBinary = join(__dirname, "..", "..", "..", "target", "release", "kreuzberg");
+    if (existsSync(devBinary)) {
+      cliPath = devBinary;
+    }
+  }
+  if (!cliPath) {
+    console.error(
+      "The embedded Kreuzberg CLI binary could not be located. This indicates a packaging issue; please open an issue at https://github.com/kreuzberg-dev/kreuzberg/issues so we can investigate."
+    );
+    return 1;
+  }
+  const result = spawnSync(cliPath, args, {
+    stdio: "inherit",
+    shell: false
+  });
+  if (result.error) {
+    console.error(`Failed to execute kreuzberg-cli: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+export {
+  main
+};
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../typescript/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * Proxy entry point that forwards to the Rust-based Kreuzberg CLI.\n *\n * This keeps `npx kreuzberg` working without shipping an additional TypeScript CLI implementation.\n */\n\nimport { spawnSync } from \"node:child_process\";\nimport { existsSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport which from \"which\";\n\nfunction main(argv: string[]): number {\n\tconst args = argv.slice(2);\n\n\tlet cliPath: string | undefined;\n\ttry {\n\t\tcliPath = which.sync(\"kreuzberg-cli\");\n\t} catch {}\n\n\tif (!cliPath) {\n\t\tconst __dirname = typeof __filename !== \"undefined\" ? dirname(__filename) : dirname(fileURLToPath(import.meta.url));\n\t\tconst devBinary = join(__dirname, \"..\", \"..\", \"..\", \"target\", \"release\", \"kreuzberg\");\n\t\tif (existsSync(devBinary)) {\n\t\t\tcliPath = devBinary;\n\t\t}\n\t}\n\n\tif (!cliPath) {\n\t\tconsole.error(\n\t\t\t\"The embedded Kreuzberg CLI binary could not be located. \" +\n\t\t\t\t\"This indicates a packaging issue; please open an issue at \" +\n\t\t\t\t\"https://github.com/kreuzberg-dev/kreuzberg/issues so we can investigate.\",\n\t\t);\n\t\treturn 1;\n\t}\n\n\tconst result = spawnSync(cliPath, args, {\n\t\tstdio: \"inherit\",\n\t\tshell: false,\n\t});\n\n\tif (result.error) {\n\t\tconsole.error(`Failed to execute kreuzberg-cli: ${result.error.message}`);\n\t\treturn 1;\n\t}\n\n\treturn result.status ?? 1;\n}\n\nif (require.main === module) {\n\tprocess.exit(main(process.argv));\n}\n\nexport { main };\n"],"mappings":";AAQA,SAAS,iBAAiB;AAC1B,SAAS,kBAAkB;AAC3B,SAAS,SAAS,YAAY;AAC9B,SAAS,qBAAqB;AAC9B,OAAO,WAAW;AAElB,SAAS,KAAK,MAAwB;AACrC,QAAM,OAAO,KAAK,MAAM,CAAC;AAEzB,MAAI;AACJ,MAAI;AACH,cAAU,MAAM,KAAK,eAAe;AAAA,EACrC,QAAQ;AAAA,EAAC;AAET,MAAI,CAAC,SAAS;AACb,UAAM,YAAY,OAAO,eAAe,cAAc,QAAQ,UAAU,IAAI,QAAQ,cAAc,YAAY,GAAG,CAAC;AAClH,UAAM,YAAY,KAAK,WAAW,MAAM,MAAM,MAAM,UAAU,WAAW,WAAW;AACpF,QAAI,WAAW,SAAS,GAAG;AAC1B,gBAAU;AAAA,IACX;AAAA,EACD;AAEA,MAAI,CAAC,SAAS;AACb,YAAQ;AAAA,MACP;AAAA,IAGD;AACA,WAAO;AAAA,EACR;AAEA,QAAM,SAAS,UAAU,SAAS,MAAM;AAAA,IACvC,OAAO;AAAA,IACP,OAAO;AAAA,EACR,CAAC;AAED,MAAI,OAAO,OAAO;AACjB,YAAQ,MAAM,oCAAoC,OAAO,MAAM,OAAO,EAAE;AACxE,WAAO;AAAA,EACR;AAEA,SAAO,OAAO,UAAU;AACzB;AAEA,IAAI,QAAQ,SAAS,QAAQ;AAC5B,UAAQ,KAAK,KAAK,QAAQ,IAAI,CAAC;AAChC;","names":[]}

package/dist/errors.d.mts

@@ -0,0 +1,358 @@
+/**
+ * Error types for Kreuzberg document intelligence framework.
+ *
+ * These error classes mirror the Rust core error types and provide
+ * type-safe error handling for TypeScript consumers.
+ *
+ * ## Error Hierarchy
+ *
+ * ```
+ * Error (JavaScript built-in)
+ *   └── KreuzbergError (base class)
+ *       ├── ValidationError
+ *       ├── ParsingError
+ *       ├── OcrError
+ *       ├── CacheError
+ *       ├── ImageProcessingError
+ *       ├── PluginError
+ *       ├── MissingDependencyError
+ *       └── ... (other error types)
+ * ```
+ *
+ * @module errors
+ */
+/**
+ * FFI error codes matching kreuzberg-ffi C library error types.
+ *
+ * @example
+ * ```typescript
+ * import { ErrorCode, getLastErrorCode } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('document.pdf');
+ * } catch (error) {
+ *   const code = getLastErrorCode();
+ *   if (code === ErrorCode.Panic) {
+ *     console.error('A panic occurred in the native library');
+ *   }
+ * }
+ * ```
+ */
+declare enum ErrorCode {
+    /**
+     * No error (success)
+     */
+    Success = 0,
+    /**
+     * Generic error
+     */
+    GenericError = 1,
+    /**
+     * Panic occurred in native code
+     */
+    Panic = 2,
+    /**
+     * Invalid argument provided
+     */
+    InvalidArgument = 3,
+    /**
+     * I/O error (file system, network, etc.)
+     */
+    IoError = 4,
+    /**
+     * Error parsing document content
+     */
+    ParsingError = 5,
+    /**
+     * Error in OCR processing
+     */
+    OcrError = 6,
+    /**
+     * Required system dependency is missing
+     */
+    MissingDependency = 7
+}
+/**
+ * Context information for panics in native code.
+ *
+ * Contains file location, line number, function name, panic message,
+ * and timestamp for debugging native library issues.
+ *
+ * @example
+ * ```typescript
+ * import { KreuzbergError } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('document.pdf');
+ * } catch (error) {
+ *   if (error instanceof KreuzbergError && error.panicContext) {
+ *     console.error('Panic occurred:');
+ *     console.error(`File: ${error.panicContext.file}`);
+ *     console.error(`Line: ${error.panicContext.line}`);
+ *     console.error(`Function: ${error.panicContext.function}`);
+ *     console.error(`Message: ${error.panicContext.message}`);
+ *   }
+ * }
+ * ```
+ */
+interface PanicContext {
+    /**
+     * Source file where panic occurred
+     */
+    file: string;
+    /**
+     * Line number in source file
+     */
+    line: number;
+    /**
+     * Function name where panic occurred
+     */
+    function: string;
+    /**
+     * Panic message
+     */
+    message: string;
+    /**
+     * Unix timestamp (seconds since epoch)
+     */
+    timestamp_secs: number;
+}
+/**
+ * Base error class for all Kreuzberg errors.
+ *
+ * All error types thrown by Kreuzberg extend this class, allowing
+ * consumers to catch all Kreuzberg-specific errors with a single catch block.
+ *
+ * @example
+ * ```typescript
+ * import { extractFile, KreuzbergError } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('document.pdf');
+ * } catch (error) {
+ *   if (error instanceof KreuzbergError) {
+ *     console.error('Kreuzberg error:', error.message);
+ *     if (error.panicContext) {
+ *       console.error('Panic at:', error.panicContext.file + ':' + error.panicContext.line);
+ *     }
+ *   } else {
+ *     throw error; // Re-throw non-Kreuzberg errors
+ *   }
+ * }
+ * ```
+ */
+declare class KreuzbergError extends Error {
+    /**
+     * Panic context if error was caused by a panic in native code.
+     * Will be null for non-panic errors.
+     */
+    readonly panicContext: PanicContext | null;
+    constructor(message: string, panicContext?: PanicContext | null);
+    toJSON(): {
+        name: string;
+        message: string;
+        panicContext: PanicContext | null;
+        stack: string | undefined;
+    };
+}
+/**
+ * Error thrown when document validation fails.
+ *
+ * Validation errors occur when a document doesn't meet specified criteria,
+ * such as minimum content length, required metadata fields, or quality thresholds.
+ *
+ * @example
+ * ```typescript
+ * import { extractFile, ValidationError } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('document.pdf');
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error('Document validation failed:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class ValidationError extends KreuzbergError {
+    constructor(message: string, panicContext?: PanicContext | null);
+}
+/**
+ * Error thrown when document parsing fails.
+ *
+ * Parsing errors occur when a document is corrupted, malformed, or cannot
+ * be processed by the extraction engine. This includes issues like:
+ * - Corrupted PDF files
+ * - Invalid XML/JSON syntax
+ * - Unsupported file format versions
+ * - Encrypted documents without valid passwords
+ *
+ * @example
+ * ```typescript
+ * import { extractFile, ParsingError } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('corrupted.pdf');
+ * } catch (error) {
+ *   if (error instanceof ParsingError) {
+ *     console.error('Failed to parse document:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class ParsingError extends KreuzbergError {
+    constructor(message: string, panicContext?: PanicContext | null);
+}
+/**
+ * Error thrown when OCR processing fails.
+ *
+ * OCR errors occur during optical character recognition, such as:
+ * - OCR backend initialization failures
+ * - Image preprocessing errors
+ * - Language model loading issues
+ * - OCR engine crashes
+ *
+ * @example
+ * ```typescript
+ * import { extractFile, OcrError } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('scanned.pdf', null, {
+ *     ocr: { backend: 'tesseract', language: 'eng' }
+ *   });
+ * } catch (error) {
+ *   if (error instanceof OcrError) {
+ *     console.error('OCR processing failed:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class OcrError extends KreuzbergError {
+    constructor(message: string, panicContext?: PanicContext | null);
+}
+/**
+ * Error thrown when cache operations fail.
+ *
+ * Cache errors are typically non-fatal and occur during caching operations, such as:
+ * - Cache directory creation failures
+ * - Disk write errors
+ * - Cache entry corruption
+ * - Insufficient disk space
+ *
+ * These errors are usually logged but don't prevent extraction from completing.
+ *
+ * @example
+ * ```typescript
+ * import { extractFile, CacheError } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('document.pdf', null, {
+ *     useCache: true
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CacheError) {
+ *     console.warn('Cache operation failed, continuing without cache:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class CacheError extends KreuzbergError {
+    constructor(message: string, panicContext?: PanicContext | null);
+}
+/**
+ * Error thrown when image processing operations fail.
+ *
+ * Image processing errors occur during image manipulation, such as:
+ * - Image decoding failures
+ * - Unsupported image formats
+ * - Image resizing/scaling errors
+ * - DPI adjustment failures
+ * - Color space conversion issues
+ *
+ * @example
+ * ```typescript
+ * import { extractFile, ImageProcessingError } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('document.pdf', null, {
+ *     images: {
+ *       extractImages: true,
+ *       targetDpi: 300
+ *     }
+ *   });
+ * } catch (error) {
+ *   if (error instanceof ImageProcessingError) {
+ *     console.error('Image processing failed:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class ImageProcessingError extends KreuzbergError {
+    constructor(message: string, panicContext?: PanicContext | null);
+}
+/**
+ * Error thrown when a plugin operation fails.
+ *
+ * Plugin errors occur in custom plugins (postprocessors, validators, OCR backends), such as:
+ * - Plugin initialization failures
+ * - Plugin processing errors
+ * - Plugin crashes or timeouts
+ * - Invalid plugin configuration
+ *
+ * The error message includes the plugin name to help identify which plugin failed.
+ *
+ * @example
+ * ```typescript
+ * import { extractFile, PluginError } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('document.pdf');
+ * } catch (error) {
+ *   if (error instanceof PluginError) {
+ *     console.error(`Plugin '${error.pluginName}' failed:`, error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class PluginError extends KreuzbergError {
+    /**
+     * Name of the plugin that threw the error.
+     */
+    readonly pluginName: string;
+    constructor(message: string, pluginName: string, panicContext?: PanicContext | null);
+    toJSON(): {
+        name: string;
+        message: string;
+        pluginName: string;
+        panicContext: PanicContext | null;
+        stack: string | undefined;
+    };
+}
+/**
+ * Error thrown when a required system dependency is missing.
+ *
+ * Missing dependency errors occur when external tools or libraries are not available, such as:
+ * - LibreOffice (for DOC/PPT/XLS files)
+ * - Tesseract OCR (for OCR processing)
+ * - ImageMagick (for image processing)
+ * - Poppler (for PDF rendering)
+ *
+ * @example
+ * ```typescript
+ * import { extractFile, MissingDependencyError } from '@kreuzberg/node';
+ *
+ * try {
+ *   const result = await extractFile('document.doc');
+ * } catch (error) {
+ *   if (error instanceof MissingDependencyError) {
+ *     console.error('Missing dependency:', error.message);
+ *     console.log('Please install LibreOffice to process DOC files');
+ *   }
+ * }
+ * ```
+ */
+declare class MissingDependencyError extends KreuzbergError {
+    constructor(message: string, panicContext?: PanicContext | null);
+}
+
+export { CacheError, ErrorCode, ImageProcessingError, KreuzbergError, MissingDependencyError, OcrError, type PanicContext, ParsingError, PluginError, ValidationError };