pdf-oxide 0.3.24 → 0.3.29

package/lib/errors.js

@@ -0,0 +1,1117 @@
+/**
+ * Unified Error Handling for PDF Oxide
+ *
+ * Provides comprehensive exception hierarchy consistent across all language bindings.
+ * Uses 4-digit error codes organized by category (1000-9999).
+ *
+ * Error Code System:
+ * - 1000-1999: Parse errors
+ * - 2000-2999: I/O errors
+ * - 3000-3999: Encryption errors
+ * - 4000-4999: State errors
+ * - 5000-5999: Unsupported feature errors
+ * - 6000-6999: Validation errors
+ * - 7000-7999: Rendering errors
+ * - 8000-8999: Search errors
+ * - 9000-9999: Other errors (compliance, OCR, etc.)
+ */
+/**
+ * Error categories for classification and handling
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    ErrorCategory["VALIDATION"] = "validation";
+    ErrorCategory["IO"] = "io";
+    ErrorCategory["ENCRYPTION"] = "encryption";
+    ErrorCategory["PARSING"] = "parsing";
+    ErrorCategory["RENDERING"] = "rendering";
+    ErrorCategory["SEARCH"] = "search";
+    ErrorCategory["PERMISSION"] = "permission";
+    ErrorCategory["RESOURCE"] = "resource";
+    ErrorCategory["STATE"] = "state";
+    ErrorCategory["UNSUPPORTED"] = "unsupported";
+    ErrorCategory["COMPLIANCE"] = "compliance";
+    ErrorCategory["OCR"] = "ocr";
+    ErrorCategory["SIGNATURE"] = "signature";
+    ErrorCategory["REDACTION"] = "redaction";
+    ErrorCategory["UNKNOWN"] = "unknown";
+})(ErrorCategory || (ErrorCategory = {}));
+/**
+ * Error severity levels for prioritization and monitoring
+ */
+export var ErrorSeverity;
+(function (ErrorSeverity) {
+    ErrorSeverity["LOW"] = "low";
+    ErrorSeverity["MEDIUM"] = "medium";
+    ErrorSeverity["HIGH"] = "high";
+    ErrorSeverity["CRITICAL"] = "critical";
+})(ErrorSeverity || (ErrorSeverity = {}));
+/**
+ * Base class for all PDF Oxide errors.
+ *
+ * @class PdfException
+ * @extends {Error}
+ * @property {string} code - 4-digit error code (XXXX format)
+ * @property {string} message - Human-readable error message
+ * @property {PdfErrorDetails} details - Additional context information
+ *
+ * @example
+ * try {
+ *   // PDF operation
+ * } catch (err) {
+ *   if (err instanceof PdfException) {
+ *     console.log(`[${err.code}] ${err.message}`);
+ *     console.log('Context:', err.details);
+ *   }
+ * }
+ */
+export class PdfException extends Error {
+    /**
+     * Creates a new PdfException.
+     *
+     * @param code - 4-digit error code
+     * @param message - Human-readable error message
+     * @param category - Error category for classification
+     * @param severity - Error severity level
+     * @param details - Additional context information
+     * @param recovery - Recovery information
+     */
+    constructor(code, message, category = ErrorCategory.UNKNOWN, severity = ErrorSeverity.HIGH, details = {}, recovery = {}) {
+        if (!code || code.length !== 4 || !/^\d{4}$/.test(code)) {
+            throw new Error('Code must be 4 digits');
+        }
+        super(`[${code}] ${message}`);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.message = message;
+        this.category = category;
+        this.severity = severity;
+        this.details = {
+            timestamp: new Date().toISOString(),
+            ...details,
+        };
+        this.recovery = {
+            canRetry: false,
+            suggestions: [],
+            ...recovery,
+        };
+        // Maintain proper stack trace for where our error was thrown
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Adds operational context to this exception for better diagnostics.
+     *
+     * @param operation - Name of the operation that failed
+     * @param context - Additional context key-value pairs
+     * @returns This exception for method chaining
+     *
+     * @example
+     * throw new FileNotFound('Not found')
+     *   .withContext('openFile', { path: '/tmp/doc.pdf' });
+     */
+    withContext(operation, context = {}) {
+        this.details.operation = operation;
+        this.details.context = { ...this.details.context, ...context };
+        return this;
+    }
+    /**
+     * Get a comprehensive error message with all details
+     * @returns Formatted error message with context and suggestions
+     */
+    getFullMessage() {
+        const parts = [
+            `[${this.code}] ${this.message}`,
+            `Category: ${this.category} | Severity: ${this.severity}`,
+        ];
+        if (this.details.operation) {
+            parts.push(`Operation: ${this.details.operation}`);
+        }
+        if (this.details.context && Object.keys(this.details.context).length > 0) {
+            const contextStr = Object.entries(this.details.context)
+                .map(([key, value]) => `  ${key}: ${JSON.stringify(value)}`)
+                .join('\n');
+            parts.push(`Context:\n${contextStr}`);
+        }
+        if (this.recovery.suggestions.length > 0) {
+            const suggestionsStr = this.recovery.suggestions
+                .map((s) => `  • ${s}`)
+                .join('\n');
+            parts.push(`Recovery Suggestions:\n${suggestionsStr}`);
+        }
+        if (this.recovery.alternativeApproach) {
+            parts.push(`Alternative Approach: ${this.recovery.alternativeApproach}`);
+        }
+        if (this.recovery.canRetry) {
+            const retryMsg = this.recovery.retryAfterMs
+                ? `retry after ${this.recovery.retryAfterMs}ms`
+                : 'retry';
+            parts.push(`Status: Retryable (${retryMsg})`);
+        }
+        return parts.join('\n');
+    }
+    /**
+     * Convert error to JSON for logging/monitoring
+     * @returns JSON representation of the error
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            category: this.category,
+            severity: this.severity,
+            details: this.details,
+            recovery: this.recovery,
+            stack: this.stack,
+        };
+    }
+}
+// ===== Parse Errors (1000-1999) =====
+export class ParseException extends PdfException {
+    constructor(message, details = {}) {
+        super('1000', message, ErrorCategory.PARSING, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'Verify the PDF file is not corrupted',
+                'Try opening the file with Adobe Reader',
+                'Check that the file is a valid PDF',
+            ],
+        });
+    }
+}
+export class InvalidStructure extends PdfException {
+    constructor(message, details = {}) {
+        super('1101', message, ErrorCategory.PARSING, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'The PDF structure is invalid or incomplete',
+                'Try re-saving the PDF with a PDF tool',
+                'Contact the PDF creator for a corrected version',
+            ],
+        });
+    }
+}
+export class CorruptedData extends PdfException {
+    constructor(message, details = {}) {
+        super('1200', message, ErrorCategory.PARSING, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'PDF file may be corrupted or damaged',
+                'Try opening the file with Adobe Reader',
+                'Attempt to recover the file using a PDF recovery tool',
+            ],
+        });
+    }
+}
+export class UnsupportedVersion extends PdfException {
+    constructor(message, details = {}) {
+        super('1300', message, ErrorCategory.UNSUPPORTED, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'This PDF version is not supported',
+                'Try converting the PDF to a standard format',
+                'Update your PDF library to a newer version',
+            ],
+            alternativeApproach: 'Use a PDF converter tool to convert to standard PDF format',
+        });
+    }
+}
+// ===== I/O Errors (2000-2999) =====
+export class IoException extends PdfException {
+    constructor(message, details = {}) {
+        super('2000', message, ErrorCategory.IO, ErrorSeverity.HIGH, details, {
+            canRetry: true,
+            retryAfterMs: 1000,
+            suggestions: [
+                'Check file permissions (readable)',
+                'Verify file path exists',
+                'Ensure disk space available',
+                'Check file is not locked by another process',
+            ],
+        });
+    }
+}
+export class FileNotFound extends PdfException {
+    constructor(message, details = {}) {
+        super('2100', message, ErrorCategory.IO, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'Verify the file path is correct',
+                'Check that the file exists',
+                'Ensure the path is absolute or properly resolved',
+            ],
+        });
+    }
+}
+export class PermissionDenied extends PdfException {
+    constructor(message, details = {}) {
+        super('2200', message, ErrorCategory.PERMISSION, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'Check file permissions using chmod/ls -l',
+                'Ensure the process has read permissions',
+                'Try running with appropriate permissions',
+            ],
+            alternativeApproach: 'Copy the file to a location with proper permissions',
+        });
+    }
+}
+export class DiskFull extends PdfException {
+    constructor(message, details = {}) {
+        super('2300', message, ErrorCategory.RESOURCE, ErrorSeverity.CRITICAL, details, {
+            canRetry: true,
+            retryAfterMs: 2000,
+            suggestions: [
+                'Free up disk space',
+                'Delete unnecessary files',
+                'Archive old files to external storage',
+            ],
+            alternativeApproach: 'Process the PDF on a device with more available storage',
+        });
+    }
+}
+export class NetworkError extends PdfException {
+    constructor(message, details = {}) {
+        super('2400', message, ErrorCategory.IO, ErrorSeverity.MEDIUM, details, {
+            canRetry: true,
+            retryAfterMs: 2000,
+            suggestions: [
+                'Check network connectivity',
+                'Verify the remote server is reachable',
+                'Check firewall and proxy settings',
+            ],
+        });
+    }
+}
+// ===== Encryption Errors (3000-3999) =====
+export class EncryptionException extends PdfException {
+    constructor(message, details = {}) {
+        super('3000', message, ErrorCategory.ENCRYPTION, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'Check if PDF requires password',
+                'Verify encryption credentials',
+                'Try opening PDF in Adobe Reader to verify',
+            ],
+        });
+    }
+}
+export class InvalidPassword extends PdfException {
+    constructor(message, details = {}) {
+        super('3100', message, ErrorCategory.ENCRYPTION, ErrorSeverity.MEDIUM, details, {
+            canRetry: true,
+            retryAfterMs: 1000,
+            suggestions: [
+                'Verify the password is correct',
+                'Check for leading/trailing spaces',
+                'Ensure correct keyboard layout is selected',
+                'Try password with different case',
+            ],
+        });
+    }
+}
+export class DecryptionFailed extends PdfException {
+    constructor(message, details = {}) {
+        super('3200', message, ErrorCategory.ENCRYPTION, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'File may be corrupted',
+                'Encryption method may be unsupported',
+                'Try opening with different PDF reader',
+            ],
+        });
+    }
+}
+export class UnsupportedAlgorithm extends PdfException {
+    constructor(message, details = {}) {
+        super('3300', message, ErrorCategory.ENCRYPTION, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'This encryption algorithm is not supported',
+                'Convert PDF with different encryption algorithm',
+                'Contact PDF creator for unencrypted version',
+            ],
+            alternativeApproach: 'Use Adobe Acrobat to re-save with supported encryption',
+        });
+    }
+}
+// ===== State Errors (4000-4999) =====
+export class InvalidStateException extends PdfException {
+    constructor(message, details = {}) {
+        super('4000', message, ErrorCategory.STATE, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'Ensure the document is in the correct state for this operation',
+                'Check that required initialization steps were completed',
+                'Verify operation order and dependencies',
+            ],
+        });
+    }
+}
+export class DocumentClosed extends PdfException {
+    constructor(message, details = {}) {
+        super('4100', message, ErrorCategory.STATE, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'The document has been closed and cannot be used',
+                'Create a new document instance or reopen the file',
+                'Check that the document is not being used after closure',
+            ],
+        });
+    }
+}
+export class OperationNotAllowed extends PdfException {
+    constructor(message, details = {}) {
+        super('4200', message, ErrorCategory.STATE, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'This operation is not allowed in the current document state',
+                'Check document permissions and security settings',
+                'Ensure document is writable (not read-only)',
+            ],
+        });
+    }
+}
+export class InvalidOperation extends PdfException {
+    constructor(message, details = {}) {
+        super('4300', message, ErrorCategory.STATE, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'This operation cannot be performed on this document',
+                'Verify the document format and content type',
+                'Check operation prerequisites are met',
+            ],
+        });
+    }
+}
+// ===== Unsupported Feature Errors (5000-5999) =====
+export class UnsupportedFeatureException extends PdfException {
+    constructor(message, details = {}) {
+        super('5000', message, ErrorCategory.UNSUPPORTED, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'This PDF feature is not supported',
+                'Check the documentation for supported features',
+                'Consider using a different PDF tool for this operation',
+            ],
+        });
+    }
+}
+export class FeatureNotImplemented extends PdfException {
+    constructor(message, details = {}) {
+        super('5100', message, ErrorCategory.UNSUPPORTED, ErrorSeverity.LOW, details, {
+            canRetry: false,
+            suggestions: [
+                'This feature is not yet implemented',
+                'Check the library changelog for planned features',
+                'File a feature request if this is important for your use case',
+            ],
+        });
+    }
+}
+export class FormatNotSupported extends PdfException {
+    constructor(message, details = {}) {
+        super('5200', message, ErrorCategory.UNSUPPORTED, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'The document format is not supported',
+                'Try converting to a standard format first',
+                'Check documentation for supported formats',
+            ],
+            alternativeApproach: 'Convert the document using a format converter',
+        });
+    }
+}
+export class EncodingNotSupported extends PdfException {
+    constructor(message, details = {}) {
+        super('5300', message, ErrorCategory.UNSUPPORTED, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'The character encoding is not supported',
+                'Try using a different character encoding',
+                'Check that the PDF text is properly encoded',
+            ],
+        });
+    }
+}
+// ===== Validation Errors (6000-6999) =====
+export class ValidationException extends PdfException {
+    constructor(message, details = {}) {
+        super('6000', message, ErrorCategory.VALIDATION, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'Verify all parameters are valid and properly formatted',
+                'Check the API documentation for parameter requirements',
+                'Ensure all required fields are provided',
+            ],
+        });
+    }
+}
+export class InvalidParameter extends PdfException {
+    constructor(message, details = {}) {
+        super('6100', message, ErrorCategory.VALIDATION, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'Check that all parameters are valid',
+                'Review the function signature and parameter types',
+                'Ensure parameter values are within valid ranges',
+            ],
+        });
+    }
+}
+export class InvalidValue extends PdfException {
+    constructor(message, details = {}) {
+        super('6200', message, ErrorCategory.VALIDATION, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'Verify the value is correct and properly formatted',
+                'Check acceptable value ranges in the documentation',
+                'Ensure the value type matches the expected type',
+            ],
+        });
+    }
+}
+export class MissingRequired extends PdfException {
+    constructor(message, details = {}) {
+        super('6300', message, ErrorCategory.VALIDATION, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'Provide the required parameter or field',
+                'Check the API documentation for required fields',
+                'Ensure no required parameters are omitted',
+            ],
+        });
+    }
+}
+export class TypeMismatch extends PdfException {
+    constructor(message, details = {}) {
+        super('6400', message, ErrorCategory.VALIDATION, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'Verify the parameter type matches the expected type',
+                'Convert the value to the correct type',
+                'Check the function signature in the documentation',
+            ],
+        });
+    }
+}
+// ===== Rendering Errors (7000-7999) =====
+export class RenderingException extends PdfException {
+    constructor(message, details = {}) {
+        super('7000', message, ErrorCategory.RENDERING, ErrorSeverity.HIGH, details, {
+            canRetry: true,
+            retryAfterMs: 1000,
+            suggestions: [
+                'Check that the PDF content is valid',
+                'Verify rendering parameters are correct',
+                'Try rendering a different page to isolate the issue',
+            ],
+        });
+    }
+}
+export class RenderFailed extends PdfException {
+    constructor(message, details = {}) {
+        super('7100', message, ErrorCategory.RENDERING, ErrorSeverity.HIGH, details, {
+            canRetry: true,
+            retryAfterMs: 1000,
+            suggestions: [
+                'The rendering operation failed',
+                'Check available system resources',
+                'Try rendering with lower quality settings',
+            ],
+        });
+    }
+}
+export class UnsupportedRenderFormat extends PdfException {
+    constructor(message, details = {}) {
+        super('7200', message, ErrorCategory.RENDERING, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'The render format is not supported',
+                'Use a supported format (PNG, JPG, PDF, SVG)',
+                'Check documentation for supported rendering formats',
+            ],
+        });
+    }
+}
+export class InsufficientMemory extends PdfException {
+    constructor(message, details = {}) {
+        super('7300', message, ErrorCategory.RESOURCE, ErrorSeverity.CRITICAL, details, {
+            canRetry: true,
+            retryAfterMs: 2000,
+            suggestions: [
+                'Free up system memory',
+                'Close other applications to reduce memory usage',
+                'Reduce render resolution or quality',
+            ],
+            alternativeApproach: 'Process the document on a system with more available memory',
+        });
+    }
+}
+// ===== Search Errors (8000-8999) =====
+export class SearchException extends PdfException {
+    constructor(message, details = {}) {
+        super('8000', message, ErrorCategory.SEARCH, ErrorSeverity.MEDIUM, details, {
+            canRetry: true,
+            retryAfterMs: 500,
+            suggestions: [
+                'Verify the search term is valid',
+                'Check that the document contains searchable text',
+                'Try a simpler search pattern',
+            ],
+        });
+    }
+}
+export class SearchFailed extends PdfException {
+    constructor(message, details = {}) {
+        super('8100', message, ErrorCategory.SEARCH, ErrorSeverity.MEDIUM, details, {
+            canRetry: true,
+            retryAfterMs: 500,
+            suggestions: [
+                'The search operation failed',
+                'Verify the document is not corrupted',
+                'Check that the search parameters are valid',
+            ],
+        });
+    }
+}
+export class InvalidPattern extends PdfException {
+    constructor(message, details = {}) {
+        super('8200', message, ErrorCategory.VALIDATION, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'The search pattern is invalid',
+                'Check the regular expression syntax',
+                'Escape special characters if needed',
+            ],
+        });
+    }
+}
+export class IndexCorrupted extends PdfException {
+    constructor(message, details = {}) {
+        super('8300', message, ErrorCategory.SEARCH, ErrorSeverity.HIGH, details, {
+            canRetry: true,
+            retryAfterMs: 1000,
+            suggestions: [
+                'The search index may be corrupted',
+                'Try rebuilding the search index',
+                'Verify the PDF document is valid',
+            ],
+        });
+    }
+}
+// ===== Signature Errors (8500-8599) =====
+export class SignatureException extends PdfException {
+    constructor(message, details = {}) {
+        super('8500', message, ErrorCategory.SIGNATURE, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'Verify the certificate file path and password are correct',
+                'Ensure the certificate contains a valid private key for signing',
+                'Check that the PDF data is valid and not corrupted',
+                'Confirm the signing algorithm is supported',
+            ],
+        });
+    }
+}
+export class CertificateLoadFailed extends PdfException {
+    constructor(message, details = {}) {
+        super('8501', message, ErrorCategory.SIGNATURE, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'Verify the certificate file exists and is readable',
+                'Check the password for PKCS#12 files',
+                'Ensure the PEM files are properly formatted',
+                'Confirm the certificate and key match',
+            ],
+        });
+    }
+}
+export class SigningFailed extends PdfException {
+    constructor(message, details = {}) {
+        super('8502', message, ErrorCategory.SIGNATURE, ErrorSeverity.HIGH, details, {
+            canRetry: true,
+            retryAfterMs: 1000,
+            suggestions: [
+                'Verify the credentials have a valid private key',
+                'Check that the PDF data is not corrupted',
+                'Ensure the signing algorithm is compatible with the certificate',
+                'Try a different signature subfilter',
+            ],
+        });
+    }
+}
+// ===== Redaction Errors (8600-8699) =====
+export class RedactionException extends PdfException {
+    constructor(message, details = {}) {
+        super('8600', message, ErrorCategory.REDACTION, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'Verify the redaction area coordinates are valid',
+                'Ensure the document is opened for editing',
+                'Check that the page index is within range',
+                'Confirm the document is not read-only or encrypted',
+            ],
+        });
+    }
+}
+// ===== Accessibility Errors (9500-9599) =====
+export class AccessibilityException extends PdfException {
+    constructor(message, details = {}) {
+        super('9500', message, ErrorCategory.VALIDATION, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'Check the document structure and tagging',
+                'Verify alt text is set for images and figures',
+                'Ensure document language and title are specified',
+                'Run accessibility validation to identify issues',
+            ],
+        });
+    }
+}
+// ===== Optimization Errors (9600-9699) =====
+export class OptimizationException extends PdfException {
+    constructor(message, details = {}) {
+        super('9600', message, ErrorCategory.RESOURCE, ErrorSeverity.MEDIUM, details, {
+            canRetry: true,
+            retryAfterMs: 1000,
+            suggestions: [
+                'Check that the document is not corrupted',
+                'Verify sufficient disk space for optimization',
+                'Try optimizing with different settings (DPI, quality)',
+                'Ensure document is not encrypted or read-only',
+            ],
+        });
+    }
+}
+// ===== Compliance Errors (9000-9100) =====
+export class ComplianceException extends PdfException {
+    constructor(message, details = {}) {
+        super('9000', message, ErrorCategory.COMPLIANCE, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'Check PDF compliance level requirements',
+                'Verify document meets compliance standards',
+                'Review compliance validation report',
+            ],
+        });
+    }
+}
+export class InvalidCompliance extends PdfException {
+    constructor(message, details = {}) {
+        super('9100', message, ErrorCategory.COMPLIANCE, ErrorSeverity.HIGH, details, {
+            canRetry: false,
+            suggestions: [
+                'The document does not meet compliance requirements',
+                'Fix the compliance issues identified',
+                'Convert the document to a compliant format',
+            ],
+        });
+    }
+}
+export class ValidationFailed extends PdfException {
+    constructor(message, details = {}) {
+        super('9150', message, ErrorCategory.COMPLIANCE, ErrorSeverity.MEDIUM, details, {
+            canRetry: true,
+            retryAfterMs: 1000,
+            suggestions: [
+                'Validation failed for this document',
+                'Check the validation error details',
+                'Fix the identified issues and retry',
+            ],
+        });
+    }
+}
+// ===== OCR Errors (9200-9300) =====
+export class OcrException extends PdfException {
+    constructor(message, details = {}) {
+        super('9200', message, ErrorCategory.OCR, ErrorSeverity.MEDIUM, details, {
+            canRetry: true,
+            retryAfterMs: 2000,
+            suggestions: [
+                'OCR processing failed',
+                'Verify the image quality is sufficient',
+                'Check that the document language is supported',
+            ],
+        });
+    }
+}
+export class RecognitionFailed extends PdfException {
+    constructor(message, details = {}) {
+        super('9201', message, ErrorCategory.OCR, ErrorSeverity.MEDIUM, details, {
+            canRetry: true,
+            retryAfterMs: 2000,
+            suggestions: [
+                'Text recognition failed',
+                'Try improving the image quality',
+                'Ensure the document language is set correctly',
+            ],
+        });
+    }
+}
+export class LanguageNotSupported extends PdfException {
+    constructor(message, details = {}) {
+        super('9202', message, ErrorCategory.OCR, ErrorSeverity.MEDIUM, details, {
+            canRetry: false,
+            suggestions: [
+                'The document language is not supported for OCR',
+                'Check available language packs',
+                'Install language support if available',
+            ],
+        });
+    }
+}
+export class ImageProcessingFailed extends PdfException {
+    constructor(message, details = {}) {
+        super('9203', message, ErrorCategory.OCR, ErrorSeverity.MEDIUM, details, {
+            canRetry: true,
+            retryAfterMs: 2000,
+            suggestions: [
+                'Image processing failed',
+                'Verify image format and encoding',
+                'Try with a higher quality image',
+            ],
+        });
+    }
+}
+// ===== Other Errors (9900-9999) =====
+export class UnknownError extends PdfException {
+    constructor(message, details = {}) {
+        super('9900', message, ErrorCategory.UNKNOWN, ErrorSeverity.HIGH, details, {
+            canRetry: true,
+            retryAfterMs: 1000,
+            suggestions: [
+                'An unknown error occurred',
+                'Check the error message for details',
+                'Try the operation again',
+                'File a bug report if the problem persists',
+            ],
+        });
+    }
+}
+export class InternalError extends PdfException {
+    constructor(message, details = {}) {
+        super('9901', message, ErrorCategory.UNKNOWN, ErrorSeverity.CRITICAL, details, {
+            canRetry: true,
+            retryAfterMs: 2000,
+            suggestions: [
+                'An internal error occurred',
+                'Please restart the application',
+                'Check system resources',
+                'File a bug report with error details',
+            ],
+        });
+    }
+}
+// ===== Error Mapping from Rust FFI =====
+/**
+ * Maps Rust error type names to JavaScript exception types.
+ */
+export const ERROR_MAP = {
+    // Parse errors
+    InvalidStructure,
+    CorruptedData,
+    UnsupportedVersion,
+    // I/O errors
+    FileNotFound,
+    PermissionDenied,
+    DiskFull,
+    NetworkError,
+    // Encryption errors
+    InvalidPassword,
+    DecryptionFailed,
+    UnsupportedAlgorithm,
+    // State errors
+    DocumentClosed,
+    OperationNotAllowed,
+    InvalidOperation,
+    // Unsupported features
+    FeatureNotImplemented,
+    FormatNotSupported,
+    EncodingNotSupported,
+    // Validation errors
+    InvalidParameter,
+    InvalidValue,
+    MissingRequired,
+    TypeMismatch,
+    // Rendering errors
+    RenderFailed,
+    UnsupportedRenderFormat,
+    InsufficientMemory,
+    // Search errors
+    SearchFailed,
+    InvalidPattern,
+    IndexCorrupted,
+    // Signature errors
+    SignatureException,
+    CertificateLoadFailed,
+    SigningFailed,
+    // Redaction errors
+    RedactionException,
+    // Accessibility errors
+    AccessibilityException,
+    // Optimization errors
+    OptimizationException,
+    // Other errors
+    ComplianceException,
+    OcrException,
+    UnknownError,
+};
+/**
+ * Maps a Rust error type to a JavaScript exception.
+ *
+ * @param rustErrorType - Rust error type name
+ * @param message - Error message
+ * @param details - Additional context
+ * @returns Appropriate error instance
+ *
+ * @example
+ * try {
+ *   // Native call
+ * } catch (err) {
+ *   const jsErr = mapError('FileNotFound', 'File does not exist', { path: '/tmp/doc.pdf' });
+ *   throw jsErr;
+ * }
+ */
+export function mapError(rustErrorType, message, details = {}) {
+    const ErrorClass = ERROR_MAP[rustErrorType] || UnknownError;
+    return new ErrorClass(message, details);
+}
+/**
+ * Maps a numeric FFI error code from the Rust layer to a JavaScript exception.
+ *
+ * FFI Error Codes:
+ * - 0: Success (no error)
+ * - 1: I/O error
+ * - 2: Parse error
+ * - 3: Encryption error
+ * - 4: Invalid state error
+ * - 5: Rendering unsupported
+ * - 6: OCR unsupported
+ * - 7: Invalid argument
+ * - 8: Signature error
+ * - 100: Internal/generic error
+ *
+ * @param errorCode - Numeric FFI error code from native layer
+ * @param message - Optional error message override
+ * @returns Appropriate error instance
+ *
+ * @example
+ * const errorCode = nativeCall();
+ * if (errorCode !== 0) {
+ *   throw mapFfiErrorCode(errorCode, 'Operation failed');
+ * }
+ */
+export function mapFfiErrorCode(errorCode, message) {
+    switch (errorCode) {
+        case 0:
+            return new UnknownError(message ?? 'Success (no error)');
+        case 1:
+            return new IoException(message ?? 'I/O error: File not found, permission denied, or read/write failed');
+        case 2:
+            return new ParseException(message ?? 'Parse error: Invalid PDF structure or content stream');
+        case 3:
+            return new EncryptionException(message ?? 'Encryption error: Incorrect password or unsupported encryption');
+        case 4:
+            return new InvalidStateException(message ?? 'Invalid state: Operation not allowed in current document state');
+        case 5:
+            return new UnsupportedFeatureException(message ?? 'Feature not enabled: Rendering support not compiled in');
+        case 6:
+            return new UnsupportedFeatureException(message ?? 'Feature not enabled: OCR support not compiled in');
+        case 7:
+            return new InvalidParameter(message ?? 'Invalid argument: Null pointer or invalid parameter passed');
+        case 8:
+            return new SignatureException(message ?? 'Signature error: Certificate loading, signing, or verification failed');
+        case 9:
+            return new RedactionException(message ?? 'Redaction error: Content redaction or metadata scrubbing failed');
+        case 10:
+            return new ComplianceException(message ?? 'Compliance error: PDF/A, PDF/X, or PDF/UA conversion or validation failed');
+        case 11:
+            return new AccessibilityException(message ?? 'Accessibility error: Tagging, structure tree, or alt text operation failed');
+        case 12:
+            return new OptimizationException(message ?? 'Optimization error: Font subsetting, image downsampling, or deduplication failed');
+        default:
+            return new UnknownError(message ?? `Unknown error (code: ${errorCode})`);
+    }
+}
+/**
+ * Creates an error with optional context.
+ *
+ * @param code - 4-digit error code
+ * @param message - Error message
+ * @param options - Configuration options
+ * @returns Created exception
+ *
+ * @example
+ * const err = createError('7100', 'Rendering failed', {
+ *   operation: 'renderPage',
+ *   context: { page: 0, format: 'png' }
+ * });
+ */
+export function createError(code, message, options = {}) {
+    // Map code to appropriate error class
+    const codeMap = {
+        '1101': InvalidStructure,
+        '1200': CorruptedData,
+        '1300': UnsupportedVersion,
+        '2100': FileNotFound,
+        '2200': PermissionDenied,
+        '2300': DiskFull,
+        '2400': NetworkError,
+        '3100': InvalidPassword,
+        '3200': DecryptionFailed,
+        '3300': UnsupportedAlgorithm,
+        '4100': DocumentClosed,
+        '4200': OperationNotAllowed,
+        '4300': InvalidOperation,
+        '5100': FeatureNotImplemented,
+        '5200': FormatNotSupported,
+        '5300': EncodingNotSupported,
+        '6100': InvalidParameter,
+        '6200': InvalidValue,
+        '6300': MissingRequired,
+        '6400': TypeMismatch,
+        '7100': RenderFailed,
+        '7200': UnsupportedRenderFormat,
+        '7300': InsufficientMemory,
+        '8100': SearchFailed,
+        '8200': InvalidPattern,
+        '8300': IndexCorrupted,
+        '8500': SignatureException,
+        '8501': CertificateLoadFailed,
+        '8502': SigningFailed,
+        '8600': RedactionException,
+        '9500': AccessibilityException,
+        '9600': OptimizationException,
+        '9100': InvalidCompliance,
+        '9150': ValidationFailed,
+        '9200': OcrException,
+        '9201': RecognitionFailed,
+        '9202': LanguageNotSupported,
+        '9203': ImageProcessingFailed,
+    };
+    const ErrorClass = codeMap[code];
+    const context = options.context || {};
+    let err;
+    if (ErrorClass) {
+        err = new ErrorClass(message, context);
+    }
+    else {
+        err = new PdfException(code, message, ErrorCategory.UNKNOWN, ErrorSeverity.HIGH, context);
+    }
+    if (options.operation) {
+        err.withContext(options.operation, context);
+    }
+    return err;
+}
+/**
+ * Maps native error to appropriate PDF exception.
+ *
+ * @param error - The error to wrap
+ * @returns Wrapped exception
+ *
+ * @example
+ * try {
+ *   // Native call
+ * } catch (err) {
+ *   const wrapped = wrapError(err);
+ *   console.log(wrapped.code); // e.g., "2100"
+ * }
+ */
+export function wrapError(error) {
+    // If already a PdfException, return as-is
+    if (error instanceof PdfException) {
+        return error;
+    }
+    let code = '9900';
+    let message = 'Unknown error occurred';
+    let details = {};
+    // Handle Error objects
+    if (error instanceof Error) {
+        message = error.message;
+        // Try to extract code from message format: [XXXX] message
+        const codeMatch = message.match(/^\[(\d{4})\]/);
+        if (codeMatch && codeMatch[1]) {
+            code = codeMatch[1];
+            message = message.replace(/^\[\d{4}\]\s*/, '');
+        }
+        // Copy additional properties
+        const props = Object.getOwnPropertyNames(error);
+        for (const prop of props) {
+            if (prop !== 'message' && prop !== 'name' && prop !== 'stack') {
+                details[prop] = error[prop];
+            }
+        }
+    }
+    // Handle plain objects
+    else if (error && typeof error === 'object') {
+        const obj = error;
+        if (obj.code) {
+            code = String(obj.code);
+            // Convert string codes to 4-digit if needed
+            if (!/^\d{4}$/.test(code)) {
+                code = '9900';
+            }
+        }
+        if (obj.message && typeof obj.message === 'string') {
+            message = obj.message;
+        }
+        details = obj;
+    }
+    // Handle strings
+    else if (typeof error === 'string') {
+        message = error;
+    }
+    try {
+        return new PdfException(code, message, ErrorCategory.UNKNOWN, ErrorSeverity.HIGH, details);
+    }
+    catch {
+        // If code validation fails, use generic error
+        return new UnknownError(message, details);
+    }
+}
+/**
+ * Creates a method wrapper that catches native errors and converts them.
+ *
+ * @param fn - The method to wrap
+ * @param thisArg - The context (this) to bind
+ * @returns Wrapped function with error conversion
+ *
+ * @example
+ * const wrapped = wrapMethod(nativeMethod, this);
+ * const result = wrapped(arg1, arg2); // Throws PdfException on error
+ */
+export function wrapMethod(fn, thisArg = null) {
+    return function (...args) {
+        try {
+            return fn.apply(thisArg || this, args);
+        }
+        catch (nativeErr) {
+            throw wrapError(nativeErr);
+        }
+    };
+}
+/**
+ * Creates an async method wrapper that catches native errors.
+ *
+ * @param fn - The async method to wrap
+ * @param thisArg - The context (this) to bind
+ * @returns Wrapped async function with error conversion
+ *
+ * @example
+ * const wrapped = wrapAsyncMethod(nativeAsyncMethod, this);
+ * const result = await wrapped(arg1, arg2); // Throws PdfException on error
+ */
+export function wrapAsyncMethod(fn, thisArg = null) {
+    return async function (...args) {
+        try {
+            return await fn.apply(thisArg || this, args);
+        }
+        catch (nativeErr) {
+            throw wrapError(nativeErr);
+        }
+    };
+}
+//# sourceMappingURL=errors.js.map