pdf-oxide-fips 0.3.47

package/lib/managers/extraction-manager.js

@@ -0,0 +1,482 @@
+/**
+ * Manager for content extraction from PDF documents
+ *
+ * Caching is handled automatically at the Rust FFI layer, eliminating
+ * the need for duplicate cache implementations in the binding.
+ *
+ * @example
+ * ```typescript
+ * import { ExtractionManager, ConversionOptionsBuilder } from 'pdf_oxide';
+ *
+ * const doc = PdfDocument.open('document.pdf');
+ * const extractionManager = new ExtractionManager(doc);
+ *
+ * // Extract text from a single page
+ * const text = extractionManager.extractText(0);
+ * console.log(text);
+ *
+ * // Extract all text
+ * const allText = extractionManager.extractAllText();
+ *
+ * // Extract with custom options
+ * const options = ConversionOptionsBuilder.highQuality().build();
+ * const markdown = extractionManager.extractMarkdown(0, options);
+ * ```
+ */
+export class ExtractionManager {
+    /**
+     * Creates a new ExtractionManager for the given document
+     * @param document - The PDF document
+     * @throws Error if document is null or undefined
+     */
+    constructor(document) {
+        if (!document) {
+            throw new Error('Document is required');
+        }
+        this._document = document;
+    }
+    /**
+     * Extracts text from a single page.
+     *
+     * The native layer produces UTF-8 bytes, which Node decodes into a JS
+     * `string` (UTF-16 code units internally). As a result,
+     * `text.length` reports UTF-16 code units, not bytes — so a 648-byte
+     * UTF-8 string containing two accented letters reads as 646 in JS. Use
+     * `Buffer.byteLength(text, 'utf8')` if you need the byte count (e.g. to
+     * compare against Go's `len(string)` or Rust's `String::len()`).
+     *
+     * Results are automatically cached at the FFI layer.
+     *
+     * @param pageIndex - Zero-based page index
+     * @param options - Conversion options
+     * @returns Extracted text (UTF-16 code units)
+     * @throws Error if page index is invalid
+     *
+     * @example
+     * ```typescript
+     * const text = manager.extractText(0);
+     * console.log(`Page 1: ${text.length} UTF-16 code units`);
+     * console.log(`         ${Buffer.byteLength(text, 'utf8')} UTF-8 bytes`);
+     * ```
+     */
+    extractText(pageIndex, options) {
+        if (typeof pageIndex !== 'number' || pageIndex < 0) {
+            throw new Error('Page index must be a non-negative number');
+        }
+        if (pageIndex >= this._document.pageCount) {
+            throw new Error(`Page index ${pageIndex} out of range`);
+        }
+        try {
+            return this._document.extractText(pageIndex);
+        }
+        catch (error) {
+            throw new Error(`Failed to extract text from page ${pageIndex}: ${error.message}`);
+        }
+    }
+    /**
+     * Extracts text from all pages
+     * @param options - Conversion options
+     * @returns All extracted text concatenated
+     *
+     * @example
+     * ```typescript
+     * const allText = manager.extractAllText();
+     * console.log(`Total characters: ${allText.length}`);
+     * ```
+     */
+    extractAllText(options) {
+        try {
+            const parts = [];
+            for (let i = 0; i < this._document.pageCount; i++) {
+                parts.push(this.extractText(i, options));
+            }
+            return parts.join('\n');
+        }
+        catch (error) {
+            throw new Error(`Failed to extract all text: ${error.message}`);
+        }
+    }
+    /**
+     * Extracts text from a range of pages
+     * @param startPageIndex - Zero-based start page index
+     * @param endPageIndex - Zero-based end page index (inclusive)
+     * @param options - Conversion options
+     * @returns Extracted text from pages in range
+     *
+     * @example
+     * ```typescript
+     * const text = manager.extractTextRange(0, 10);
+     * console.log(`Text from pages 1-11: ${text}`);
+     * ```
+     */
+    extractTextRange(startPageIndex, endPageIndex, options) {
+        if (typeof startPageIndex !== 'number' || startPageIndex < 0) {
+            throw new Error('Start page index must be a non-negative number');
+        }
+        if (typeof endPageIndex !== 'number' || endPageIndex < startPageIndex) {
+            throw new Error('End page index must be >= start page index');
+        }
+        if (endPageIndex >= this._document.pageCount) {
+            throw new Error(`End page index ${endPageIndex} out of range`);
+        }
+        try {
+            const parts = [];
+            for (let i = startPageIndex; i <= endPageIndex; i++) {
+                parts.push(this.extractText(i, options));
+            }
+            return parts.join('\n');
+        }
+        catch (error) {
+            throw new Error(`Failed to extract text range: ${error.message}`);
+        }
+    }
+    /**
+     * Extracts text from specific page indices (non-contiguous)
+     * @param pageIndices - Array of zero-based page indices
+     * @param options - Conversion options
+     * @returns Extracted text from specified pages concatenated with newlines
+     * @throws Error if page indices are invalid
+     *
+     * @example
+     * ```typescript
+     * const text = manager.extractTextBatch([0, 2, 5]); // Extract pages 1, 3, 6
+     * console.log(text);
+     * ```
+     */
+    extractTextBatch(pageIndices, options) {
+        if (!Array.isArray(pageIndices)) {
+            throw new Error('Page indices must be an array');
+        }
+        if (pageIndices.length === 0) {
+            return '';
+        }
+        try {
+            const parts = [];
+            for (const pageIndex of pageIndices) {
+                if (typeof pageIndex !== 'number' ||
+                    pageIndex < 0 ||
+                    pageIndex >= this._document.pageCount) {
+                    throw new Error(`Invalid page index: ${pageIndex}`);
+                }
+                parts.push(this.extractText(pageIndex, options));
+            }
+            return parts.join('\n');
+        }
+        catch (error) {
+            throw new Error(`Failed to extract text batch: ${error.message}`);
+        }
+    }
+    /**
+     * Extracts text from pages as an array (one entry per page)
+     * @param startPageIndex - Zero-based start page index
+     * @param endPageIndex - Zero-based end page index (inclusive)
+     * @param options - Conversion options
+     * @returns Array of extracted text, one per page
+     *
+     * @example
+     * ```typescript
+     * const pages = manager.extractTextArray(0, 5);
+     * pages.forEach((text, i) => console.log(`Page ${i}: ${text.length} chars`));
+     * ```
+     */
+    extractTextArray(startPageIndex, endPageIndex, options) {
+        if (typeof startPageIndex !== 'number' || startPageIndex < 0) {
+            throw new Error('Start page index must be a non-negative number');
+        }
+        if (typeof endPageIndex !== 'number' || endPageIndex < startPageIndex) {
+            throw new Error('End page index must be >= start page index');
+        }
+        if (endPageIndex >= this._document.pageCount) {
+            throw new Error(`End page index ${endPageIndex} out of range`);
+        }
+        try {
+            const results = [];
+            for (let i = startPageIndex; i <= endPageIndex; i++) {
+                results.push(this.extractText(i, options));
+            }
+            return results;
+        }
+        catch (error) {
+            throw new Error(`Failed to extract text array: ${error.message}`);
+        }
+    }
+    /**
+     * Extracts page as Markdown.
+     * Results are automatically cached at the FFI layer.
+     * @param pageIndex - Zero-based page index
+     * @param options - Conversion options
+     * @returns Page content as Markdown
+     * @throws Error if page index is invalid
+     *
+     * @example
+     * ```typescript
+     * const markdown = manager.extractMarkdown(0);
+     * console.log(markdown); // Markdown formatted content
+     * ```
+     */
+    extractMarkdown(pageIndex, options) {
+        if (typeof pageIndex !== 'number' || pageIndex < 0) {
+            throw new Error('Page index must be a non-negative number');
+        }
+        if (pageIndex >= this._document.pageCount) {
+            throw new Error(`Page index ${pageIndex} out of range`);
+        }
+        try {
+            return this._document.toMarkdown(pageIndex, options);
+        }
+        catch (error) {
+            throw new Error(`Failed to extract markdown from page ${pageIndex}: ${error.message}`);
+        }
+    }
+    /**
+     * Extracts all pages as Markdown
+     * @param options - Conversion options
+     * @returns All pages as Markdown
+     *
+     * @example
+     * ```typescript
+     * const markdown = manager.extractAllMarkdown();
+     * // Write to file
+     * fs.writeFileSync('output.md', markdown);
+     * ```
+     */
+    extractAllMarkdown(options) {
+        try {
+            const parts = [];
+            for (let i = 0; i < this._document.pageCount; i++) {
+                const heading = `\n## Page ${i + 1}\n`;
+                const content = this.extractMarkdown(i, options);
+                parts.push(heading + content);
+            }
+            return parts.join('\n');
+        }
+        catch (error) {
+            throw new Error(`Failed to extract all markdown: ${error.message}`);
+        }
+    }
+    /**
+     * Extracts markdown from a range of pages
+     * @param startPageIndex - Zero-based start page index
+     * @param endPageIndex - Zero-based end page index (inclusive)
+     * @param options - Conversion options
+     * @returns Extracted markdown from pages in range
+     */
+    extractMarkdownRange(startPageIndex, endPageIndex, options) {
+        if (typeof startPageIndex !== 'number' || startPageIndex < 0) {
+            throw new Error('Start page index must be a non-negative number');
+        }
+        if (typeof endPageIndex !== 'number' || endPageIndex < startPageIndex) {
+            throw new Error('End page index must be >= start page index');
+        }
+        if (endPageIndex >= this._document.pageCount) {
+            throw new Error(`End page index ${endPageIndex} out of range`);
+        }
+        try {
+            const parts = [];
+            for (let i = startPageIndex; i <= endPageIndex; i++) {
+                const heading = `\n## Page ${i + 1}\n`;
+                const content = this.extractMarkdown(i, options);
+                parts.push(heading + content);
+            }
+            return parts.join('\n');
+        }
+        catch (error) {
+            throw new Error(`Failed to extract markdown range: ${error.message}`);
+        }
+    }
+    /**
+     * Gets word count for a page
+     * @param pageIndex - Zero-based page index
+     * @returns Estimated word count
+     */
+    getPageWordCount(pageIndex) {
+        const text = this.extractText(pageIndex);
+        return text.trim().split(/\s+/).length;
+    }
+    /**
+     * Gets total word count for all pages
+     * @returns Total word count across all pages
+     */
+    getTotalWordCount() {
+        const allText = this.extractAllText();
+        return allText
+            .trim()
+            .split(/\s+/)
+            .filter((word) => word.length > 0).length;
+    }
+    /**
+     * Gets character count for a page
+     * @param pageIndex - Zero-based page index
+     * @returns Character count (including whitespace)
+     */
+    getPageCharacterCount(pageIndex) {
+        const text = this.extractText(pageIndex);
+        return text.length;
+    }
+    /**
+     * Gets total character count for all pages
+     * @returns Total character count
+     */
+    getTotalCharacterCount() {
+        let total = 0;
+        for (let i = 0; i < this._document.pageCount; i++) {
+            total += this.getPageCharacterCount(i);
+        }
+        return total;
+    }
+    /**
+     * Gets line count for a page
+     * @param pageIndex - Zero-based page index
+     * @returns Estimated line count
+     */
+    getPageLineCount(pageIndex) {
+        const text = this.extractText(pageIndex);
+        return text.split('\n').length;
+    }
+    /**
+     * Gets statistics for extracted content
+     * @returns Content statistics object
+     *
+     * @example
+     * ```typescript
+     * const stats = manager.getContentStatistics();
+     * console.log(`Total pages: ${stats.pageCount}`);
+     * console.log(`Total words: ${stats.wordCount}`);
+     * console.log(`Average page length: ${stats.averagePageLength}`);
+     * ```
+     */
+    getContentStatistics() {
+        try {
+            const pageCount = this._document.pageCount;
+            const totalWords = this.getTotalWordCount();
+            const totalCharacters = this.getTotalCharacterCount();
+            return {
+                pageCount,
+                wordCount: totalWords,
+                characterCount: totalCharacters,
+                averageWordsPerPage: Math.round(totalWords / pageCount),
+                averageCharactersPerPage: Math.round(totalCharacters / pageCount),
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to get content statistics: ${error.message}`);
+        }
+    }
+    /**
+     * Searches for text across all pages and returns matching snippets
+     * @param searchText - Text to search for
+     * @param contextLength - Characters of context around match
+     * @returns Array of match objects with page and snippet
+     *
+     * @example
+     * ```typescript
+     * const matches = manager.searchContent('keyword', 50);
+     * matches.forEach(match => {
+     *   console.log(`Page ${match.pageIndex + 1}: ...${match.snippet}...`);
+     * });
+     * ```
+     */
+    searchContent(searchText, contextLength = 100) {
+        if (!searchText || typeof searchText !== 'string') {
+            throw new Error('Search text must be a non-empty string');
+        }
+        const results = [];
+        const searchRegex = new RegExp(searchText, 'gi');
+        for (let i = 0; i < this._document.pageCount; i++) {
+            try {
+                const text = this.extractText(i);
+                let match;
+                while ((match = searchRegex.exec(text)) !== null) {
+                    const start = Math.max(0, match.index - contextLength);
+                    const end = Math.min(text.length, match.index + searchText.length + contextLength);
+                    const snippet = text.substring(start, end);
+                    results.push({
+                        pageIndex: i,
+                        pageNumber: i + 1,
+                        matchIndex: match.index,
+                        snippet: snippet.replace(/\n/g, ' '),
+                        matchText: match[0],
+                    });
+                }
+                // Reset regex for next iteration
+                searchRegex.lastIndex = 0;
+            }
+            catch (e) {
+                // Skip pages that fail extraction
+            }
+        }
+        return results;
+    }
+    /**
+     * Extract text from a page in a worker thread (non-blocking)
+     * @param documentPath - Path to the PDF document
+     * @param pageIndex - Page index to extract from
+     * @param options - Optional extraction options
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to extracted text
+     */
+    async extractTextInWorker(documentPath, pageIndex, options, timeout) {
+        const { workerPool } = await import('../workers/index.js');
+        const result = await workerPool.runTask({
+            operation: 'extract',
+            documentPath,
+            params: {
+                type: 'text',
+                pageIndex,
+                options: options || {},
+            },
+        }, timeout);
+        if (!result.success) {
+            throw new Error(`Worker extraction failed: ${result.error instanceof Error ? result.error.message : String(result.error)}`);
+        }
+        return result.data;
+    }
+    /**
+     * Extract markdown from a page in a worker thread (non-blocking)
+     * @param documentPath - Path to the PDF document
+     * @param pageIndex - Page index to extract from
+     * @param options - Optional extraction options
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to extracted markdown
+     */
+    async extractMarkdownInWorker(documentPath, pageIndex, options, timeout) {
+        const { workerPool } = await import('../workers/index.js');
+        const result = await workerPool.runTask({
+            operation: 'extract',
+            documentPath,
+            params: {
+                type: 'markdown',
+                pageIndex,
+                options: options || {},
+            },
+        }, timeout);
+        if (!result.success) {
+            throw new Error(`Worker extraction failed: ${result.error instanceof Error ? result.error.message : String(result.error)}`);
+        }
+        return result.data;
+    }
+    /**
+     * Extract HTML from a page in a worker thread (non-blocking)
+     * @param documentPath - Path to the PDF document
+     * @param pageIndex - Page index to extract from
+     * @param options - Optional extraction options
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to extracted HTML
+     */
+    async extractHtmlInWorker(documentPath, pageIndex, options, timeout) {
+        const { workerPool } = await import('../workers/index.js');
+        const result = await workerPool.runTask({
+            operation: 'extract',
+            documentPath,
+            params: {
+                type: 'html',
+                pageIndex,
+                options: options || {},
+            },
+        }, timeout);
+        if (!result.success) {
+            throw new Error(`Worker extraction failed: ${result.error instanceof Error ? result.error.message : String(result.error)}`);
+        }
+        return result.data;
+    }
+}

package/lib/managers/final-utilities.d.ts

@@ -0,0 +1,127 @@
+import { EventEmitter } from 'events';
+export declare enum EventType {
+    PAGE_LOADED = "page_loaded",
+    PAGE_RENDERED = "page_rendered",
+    CONTENT_PARSED = "content_parsed",
+    SEARCH_COMPLETED = "search_completed",
+    ERROR_OCCURRED = "error_occurred",
+    PROCESSING_STARTED = "processing_started",
+    PROCESSING_COMPLETED = "processing_completed"
+}
+export declare enum EncryptionAlgorithm {
+    AES_128 = "aes_128",
+    AES_256 = "aes_256",
+    RC4_40 = "rc4_40",
+    RC4_128 = "rc4_128"
+}
+export declare enum CompressionLevel {
+    NONE = 0,
+    FAST = 3,
+    BALANCED = 6,
+    BEST = 9
+}
+export interface DocumentEvent {
+    eventType: EventType;
+    timestamp: number;
+    data: Record<string, any>;
+    pageIndex?: number;
+}
+export interface EncryptionSettings {
+    algorithm: EncryptionAlgorithm;
+    userPassword: string;
+    ownerPassword: string;
+    allowPrinting: boolean;
+    allowCopying: boolean;
+    allowModification: boolean;
+}
+export interface CompressionSettings {
+    level: CompressionLevel;
+    compressImages: boolean;
+    compressStreams: boolean;
+    compressFonts: boolean;
+    removeDuplicates: boolean;
+}
+export declare class EventManager extends EventEmitter {
+    private document;
+    private eventListeners;
+    constructor(document: any);
+    addEventListener(eventType: EventType, handler: (event: unknown) => void): Promise<boolean>;
+    removeEventListener(eventType: EventType, handler: (event: unknown) => void): Promise<boolean>;
+    emitEvent(event: DocumentEvent): Promise<boolean>;
+    hasListener(eventType: EventType): Promise<boolean>;
+    getListenerCount(eventType: EventType): Promise<number>;
+    clearListeners(eventType?: EventType): Promise<boolean>;
+    getEventHistory(): Promise<DocumentEvent[]>;
+    enableEventLogging(enabled: boolean): Promise<boolean>;
+    getEventStatistics(): Promise<Record<string, any>>;
+    waitForEvent(eventType: EventType, timeoutSec?: number): Promise<DocumentEvent | null>;
+}
+export declare class EncryptionManager extends EventEmitter {
+    private document;
+    private encryptionSettings;
+    constructor(document: any);
+    encryptDocument(settings: EncryptionSettings): Promise<boolean>;
+    decryptDocument(password: string): Promise<boolean>;
+    changeEncryption(newSettings: EncryptionSettings): Promise<boolean>;
+    getEncryptionAlgorithm(): Promise<string | null>;
+    isDocumentEncrypted(): Promise<boolean>;
+    removeEncryption(ownerPassword: string): Promise<boolean>;
+    setUserPassword(password: string): Promise<boolean>;
+    setOwnerPassword(password: string): Promise<boolean>;
+    validatePassword(password: string): Promise<boolean>;
+    getPermissions(): Promise<Record<string, boolean>>;
+    setPermissions(permissions: Record<string, boolean>): Promise<boolean>;
+    exportCertificate(outputPath: string): Promise<boolean>;
+    importCertificate(certPath: string): Promise<boolean>;
+    encryptionStatus(): Promise<Record<string, any>>;
+}
+export declare class CompressionManager extends EventEmitter {
+    private document;
+    private compressionSettings;
+    constructor(document: any);
+    compressDocument(settings: CompressionSettings): Promise<boolean>;
+    compressImages(quality?: number): Promise<boolean>;
+    compressStreams(): Promise<boolean>;
+    compressPage(pageIndex: number, settings: CompressionSettings): Promise<boolean>;
+    getCompressionRatio(): Promise<number | null>;
+    estimateCompression(settings: CompressionSettings): Promise<number | null>;
+    decompressDocument(): Promise<boolean>;
+    isCompressed(): Promise<boolean>;
+    getCompressionReport(): Promise<Record<string, any>>;
+    optimizeForWeb(): Promise<boolean>;
+    optimizeForPrint(): Promise<boolean>;
+}
+export declare class CustomAnnotationManager extends EventEmitter {
+    private document;
+    private customAnnotations;
+    constructor(document: any);
+    createCustomAnnotation(annotationType: string, properties: Record<string, any>): Promise<string | null>;
+    registerAnnotationType(typeName: string, handler: (...args: unknown[]) => unknown): Promise<boolean>;
+    modifyAnnotation(annotationId: string, properties: Record<string, any>): Promise<boolean>;
+    deleteCustomAnnotation(annotationId: string): Promise<boolean>;
+    getCustomAnnotations(pageIndex: number): Promise<Record<string, any>[]>;
+    setAnnotationVisibility(annotationId: string, visible: boolean): Promise<boolean>;
+    exportAnnotations(outputPath: string): Promise<boolean>;
+    importAnnotations(inputPath: string): Promise<boolean>;
+    applyAnnotationStyle(annotationId: string, style: Record<string, any>): Promise<boolean>;
+    getAnnotationMetadata(annotationId: string): Promise<Record<string, any> | null>;
+    replyToAnnotation(annotationId: string, replyText: string): Promise<boolean>;
+    getAnnotationReplies(annotationId: string): Promise<string[]>;
+    flattenAnnotations(): Promise<boolean>;
+    convertAnnotations(targetFormat: string): Promise<boolean>;
+}
+export declare class ContentSecurityManager extends EventEmitter {
+    private document;
+    private accessPolicies;
+    constructor(document: any);
+    setAccessControl(policyName: string, restrictions: Record<string, any>): Promise<boolean>;
+    validateAccess(userRole: string, action: string): Promise<boolean>;
+    applyDigitalRights(rights: Record<string, boolean>): Promise<boolean>;
+    sanitizeContent(removeScripts?: boolean, removeEmbedded?: boolean): Promise<boolean>;
+    detectSuspiciousContent(): Promise<Record<string, any>[]>;
+    getAccessLog(): Promise<Record<string, any>[]>;
+    setExpirationDate(expirationDate: string): Promise<boolean>;
+    enableWatermarking(watermarkText: string): Promise<boolean>;
+    trackDocumentUsage(enabled: boolean): Promise<boolean>;
+    getSecurityAudit(): Promise<Record<string, any>>;
+}