pdf-oxide-fips 0.3.47

package/lib/types/manager-types.d.ts

@@ -0,0 +1,179 @@
+/**
+ * TypeScript type definitions for all PDF Oxide managers
+ *
+ * Provides comprehensive type safety for Node.js and TypeScript consumers
+ * with full FFI integration and proper error handling.
+ */
+import { EventEmitter } from 'events';
+export interface PdfDocumentHandle {
+    readonly handle: unknown;
+    readonly pageCount: () => Promise<number>;
+    readonly extractText: (pageIndex: number) => Promise<string>;
+    readonly extractFormFields: () => Promise<FormField[]>;
+    readonly getMetadata: () => Promise<Record<string, string>>;
+}
+export declare enum OcrLanguage {
+    ENGLISH = "en",
+    CHINESE = "zh",
+    JAPANESE = "ja",
+    SPANISH = "es",
+    FRENCH = "fr",
+    PORTUGUESE = "pt",
+    RUSSIAN = "ru",
+    ARABIC = "ar",
+    KOREAN = "ko",
+    VIETNAMESE = "vi"
+}
+export interface TextRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface OcrResult {
+    readonly pageIndex: number;
+    readonly text: string;
+    readonly confidence: number;
+    readonly regionCount: number;
+}
+export interface OcrBatchResult {
+    readonly startPage: number;
+    readonly endPage: number;
+    readonly totalPages: number;
+    readonly totalSpans: number;
+    readonly averageConfidence: number;
+    readonly skippedPages: number;
+}
+export declare enum ComplianceType {
+    PDF_A_1B = "pdf_a_1b",
+    PDF_A_2B = "pdf_a_2b",
+    PDF_A_3B = "pdf_a_3b",
+    PDF_X_1A = "pdf_x_1a",
+    PDF_X_3 = "pdf_x_3",
+    PDF_UA = "pdf_ua"
+}
+export interface ComplianceResult {
+    readonly type: string;
+    readonly valid: boolean;
+    readonly issues: readonly string[];
+    readonly severity: 'none' | 'low' | 'medium' | 'high' | 'critical';
+}
+export interface ComplianceReport {
+    readonly timestamp: number;
+    readonly results: ComplianceResult[];
+    readonly isFullyCompliant: boolean;
+}
+export interface CacheEntry<T> {
+    readonly key: string;
+    readonly value: T;
+    readonly timestamp: number;
+    readonly ttl?: number;
+}
+export interface CacheStats {
+    readonly cacheCount: number;
+    readonly totalEntries: number;
+    readonly totalSize: number;
+    readonly entriesByCache: Map<string, number>;
+    readonly hitRate: number;
+    readonly missRate: number;
+}
+export declare enum FormFieldType {
+    TEXT = "text",
+    CHECKBOX = "checkbox",
+    RADIO = "radio",
+    COMBOBOX = "combobox",
+    LISTBOX = "listbox",
+    SIGNATURE = "signature",
+    DATE = "date"
+}
+export interface FormField {
+    readonly name: string;
+    readonly type: FormFieldType;
+    readonly value: string;
+    readonly pageIndex: number;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly required?: boolean;
+    readonly readonly?: boolean;
+}
+export interface ManagerOptions {
+    readonly enableCache?: boolean;
+    readonly cacheSize?: number;
+    readonly enableEvents?: boolean;
+    readonly enableLogging?: boolean;
+}
+export interface ManagerState {
+    readonly initialized: boolean;
+    readonly hasDocument: boolean;
+    readonly operationCount: number;
+    readonly errorCount: number;
+}
+export interface ManagerEvent<T = Record<string, unknown>> {
+    readonly eventType: string;
+    readonly timestamp: number;
+    readonly data: T;
+    readonly manager: string;
+}
+export interface ErrorEvent extends ManagerEvent<{
+    error: Error;
+    operation: string;
+}> {
+}
+export interface BatchOptions {
+    readonly pageSize?: number;
+    readonly parallelism?: number;
+    readonly timeout?: number;
+    readonly retryOnError?: boolean;
+    readonly maxRetries?: number;
+}
+export interface BatchProgress {
+    readonly processed: number;
+    readonly total: number;
+    readonly percentage: number;
+    readonly status: 'pending' | 'running' | 'completed' | 'failed';
+}
+export interface BatchResult<T> {
+    readonly data: T[];
+    readonly progress: BatchProgress;
+    readonly startTime: number;
+    readonly endTime: number;
+    readonly duration: number;
+    readonly errors: Error[];
+}
+export interface PdfMetadata {
+    readonly title?: string;
+    readonly author?: string;
+    readonly subject?: string;
+    readonly keywords?: string;
+    readonly creator?: string;
+    readonly producer?: string;
+    readonly creationDate?: Date;
+    readonly modificationDate?: Date;
+    readonly pageCount: number;
+    readonly format?: string;
+}
+export interface IManager extends EventEmitter {
+    readonly initialized: boolean;
+    destroy(): Promise<void>;
+    getState(): ManagerState;
+}
+export declare abstract class BaseManager<T extends PdfDocumentHandle = PdfDocumentHandle> extends EventEmitter implements IManager {
+    protected options: ManagerOptions;
+    private _initialized;
+    get initialized(): boolean;
+    protected set initialized(value: boolean);
+    protected document: T;
+    protected cache: Map<string, unknown>;
+    protected operationCount: number;
+    protected errorCount: number;
+    constructor(document: T, options?: ManagerOptions);
+    abstract destroy(): Promise<void>;
+    getState(): ManagerState;
+    protected recordOperation(): void;
+    protected recordError(error: Error): void;
+    protected getCached<V>(key: string): V | undefined;
+    protected setCached<V>(key: string, value: V): void;
+    protected invalidateCache(pattern?: string): void;
+}

package/lib/types/manager-types.js

@@ -0,0 +1,100 @@
+/**
+ * TypeScript type definitions for all PDF Oxide managers
+ *
+ * Provides comprehensive type safety for Node.js and TypeScript consumers
+ * with full FFI integration and proper error handling.
+ */
+import { EventEmitter } from 'events';
+// ============================================================
+// OCR Types
+// ============================================================
+export var OcrLanguage;
+(function (OcrLanguage) {
+    OcrLanguage["ENGLISH"] = "en";
+    OcrLanguage["CHINESE"] = "zh";
+    OcrLanguage["JAPANESE"] = "ja";
+    OcrLanguage["SPANISH"] = "es";
+    OcrLanguage["FRENCH"] = "fr";
+    OcrLanguage["PORTUGUESE"] = "pt";
+    OcrLanguage["RUSSIAN"] = "ru";
+    OcrLanguage["ARABIC"] = "ar";
+    OcrLanguage["KOREAN"] = "ko";
+    OcrLanguage["VIETNAMESE"] = "vi";
+})(OcrLanguage || (OcrLanguage = {}));
+// ============================================================
+// Compliance Types
+// ============================================================
+export var ComplianceType;
+(function (ComplianceType) {
+    ComplianceType["PDF_A_1B"] = "pdf_a_1b";
+    ComplianceType["PDF_A_2B"] = "pdf_a_2b";
+    ComplianceType["PDF_A_3B"] = "pdf_a_3b";
+    ComplianceType["PDF_X_1A"] = "pdf_x_1a";
+    ComplianceType["PDF_X_3"] = "pdf_x_3";
+    ComplianceType["PDF_UA"] = "pdf_ua";
+})(ComplianceType || (ComplianceType = {}));
+// ============================================================
+// Form Field Types
+// ============================================================
+export var FormFieldType;
+(function (FormFieldType) {
+    FormFieldType["TEXT"] = "text";
+    FormFieldType["CHECKBOX"] = "checkbox";
+    FormFieldType["RADIO"] = "radio";
+    FormFieldType["COMBOBOX"] = "combobox";
+    FormFieldType["LISTBOX"] = "listbox";
+    FormFieldType["SIGNATURE"] = "signature";
+    FormFieldType["DATE"] = "date";
+})(FormFieldType || (FormFieldType = {}));
+export class BaseManager extends EventEmitter {
+    get initialized() {
+        return this._initialized;
+    }
+    set initialized(value) {
+        this._initialized = value;
+    }
+    constructor(document, options = {}) {
+        super();
+        this.options = options;
+        this._initialized = false;
+        this.cache = new Map();
+        this.operationCount = 0;
+        this.errorCount = 0;
+        this.document = document;
+        this.initialized = true;
+    }
+    getState() {
+        return {
+            initialized: this.initialized,
+            hasDocument: !!this.document,
+            operationCount: this.operationCount,
+            errorCount: this.errorCount,
+        };
+    }
+    recordOperation() {
+        this.operationCount++;
+    }
+    recordError(error) {
+        this.errorCount++;
+        this.emit('error', { error, timestamp: Date.now() });
+    }
+    getCached(key) {
+        return this.cache.get(key);
+    }
+    setCached(key, value) {
+        if (this.options.enableCache !== false) {
+            this.cache.set(key, value);
+        }
+    }
+    invalidateCache(pattern) {
+        if (pattern) {
+            const keys = Array.from(this.cache.keys()).filter((k) => k.includes(pattern));
+            keys.forEach((k) => {
+                this.cache.delete(k);
+            });
+        }
+        else {
+            this.cache.clear();
+        }
+    }
+}

package/lib/types/native-bindings.d.ts

@@ -0,0 +1,439 @@
+/**
+ * Type definitions for PDF Oxide native bindings (C++ module via NAPI)
+ *
+ * These interfaces describe the structure of objects returned from the native module.
+ * They are used for type checking and IDE auto-completion when working with the binding layer.
+ */
+/**
+ * Represents a rectangular area with coordinates and dimensions
+ */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Represents a 2D point coordinate
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * Represents an RGB color value
+ */
+export interface Color {
+    red: number;
+    green: number;
+    blue: number;
+    alpha?: number;
+}
+/**
+ * Document metadata and properties
+ */
+export interface DocumentInfo {
+    title?: string;
+    author?: string;
+    subject?: string;
+    keywords?: string[];
+    creator?: string;
+    producer?: string;
+    creationDate?: Date;
+    modificationDate?: Date;
+    encrypted?: boolean;
+    pages?: number;
+}
+/**
+ * PDF document metadata
+ */
+export interface Metadata {
+    [key: string]: string | number | boolean | Date | undefined;
+}
+/**
+ * Embedded file information
+ */
+export interface EmbeddedFile {
+    filename: string;
+    mimeType?: string;
+    size?: number;
+    data?: Buffer;
+}
+/**
+ * Result of a text search operation
+ */
+export interface SearchResult {
+    pageIndex: number;
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    confidence?: number;
+}
+/**
+ * Options for text search operations
+ */
+export interface SearchOptions {
+    caseSensitive?: boolean;
+    wholeWords?: boolean;
+    regex?: boolean;
+    startPage?: number;
+    endPage?: number;
+    maxResults?: number;
+}
+/**
+ * Options for document conversion
+ */
+export interface ConversionOptions {
+    format?: 'markdown' | 'text' | 'html';
+    includeImages?: boolean;
+    includeMetadata?: boolean;
+    preserveLayout?: boolean;
+    encoding?: string;
+}
+/**
+ * Base class for PDF elements (text, images, paths, etc.)
+ */
+export interface PdfElement {
+    type: string;
+    bounds: Rect;
+    rotation?: number;
+    opacity?: number;
+    blendMode?: string;
+}
+/**
+ * Text element extracted from PDF
+ */
+export interface PdfText extends PdfElement {
+    type: 'text';
+    content: string;
+    fontSize?: number;
+    fontName?: string;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    color?: Color;
+}
+/**
+ * Image element from PDF
+ */
+export interface PdfImage extends PdfElement {
+    type: 'image';
+    width: number;
+    height: number;
+    colorSpace?: string;
+    bitsPerComponent?: number;
+    data?: Buffer;
+}
+/**
+ * Vector path (graphics)
+ */
+export interface PdfPath extends PdfElement {
+    type: 'path';
+    points: Point[];
+    strokeColor?: Color;
+    fillColor?: Color;
+    lineWidth?: number;
+}
+/**
+ * Table extracted from PDF
+ */
+export interface PdfTable extends PdfElement {
+    type: 'table';
+    rows: number;
+    columns: number;
+    cells: PdfTableCell[][];
+}
+/**
+ * Individual table cell
+ */
+export interface PdfTableCell {
+    text: string;
+    rowSpan?: number;
+    colSpan?: number;
+    backgroundColor?: Color;
+    borderColor?: Color;
+}
+/**
+ * Base annotation interface
+ */
+export interface Annotation {
+    type: string;
+    page: number;
+    bounds: Rect;
+    author?: string;
+    content?: string;
+    creationDate?: Date;
+    modificationDate?: Date;
+    flags?: number;
+}
+/**
+ * Text annotation (sticky note style)
+ */
+export interface TextAnnotation extends Annotation {
+    type: 'text';
+    icon?: string;
+    color?: Color;
+}
+/**
+ * Highlight annotation
+ */
+export interface HighlightAnnotation extends Annotation {
+    type: 'highlight';
+    color?: Color;
+    quadPoints?: Point[][];
+}
+/**
+ * Link annotation
+ */
+export interface LinkAnnotation extends Annotation {
+    type: 'link';
+    url?: string;
+    destination?: {
+        page: number;
+        x?: number;
+        y?: number;
+        zoom?: number;
+    };
+    action?: string;
+}
+/**
+ * Ink annotation (drawing/handwriting)
+ */
+export interface InkAnnotation extends Annotation {
+    type: 'ink';
+    strokes: Point[][];
+    color?: Color;
+    thickness?: number;
+}
+/**
+ * Square annotation
+ */
+export interface SquareAnnotation extends Annotation {
+    type: 'square';
+    fillColor?: Color;
+    strokeColor?: Color;
+    lineWidth?: number;
+}
+/**
+ * Circle annotation
+ */
+export interface CircleAnnotation extends Annotation {
+    type: 'circle';
+    fillColor?: Color;
+    strokeColor?: Color;
+    lineWidth?: number;
+}
+/**
+ * Line annotation
+ */
+export interface LineAnnotation extends Annotation {
+    type: 'line';
+    startPoint: Point;
+    endPoint: Point;
+    color?: Color;
+    lineWidth?: number;
+    startLineStyle?: string;
+    endLineStyle?: string;
+}
+/**
+ * Polygon annotation
+ */
+export interface PolygonAnnotation extends Annotation {
+    type: 'polygon';
+    vertices: Point[];
+    fillColor?: Color;
+    strokeColor?: Color;
+    lineWidth?: number;
+}
+/**
+ * Native PdfDocument class interface
+ */
+export interface NativePdfDocument {
+    getVersion(): string;
+    getPdfOxideVersion(): string;
+    getPageCount(): number;
+    getTitle(): string | null;
+    getAuthor(): string | null;
+    getSubject(): string | null;
+    getKeywords(): string[] | null;
+    getCreationDate(): Date | null;
+    getModificationDate(): Date | null;
+    isEncrypted(): boolean;
+    isLinearized(): boolean;
+    getMetadata(): Metadata;
+    setMetadata(metadata: Metadata): void;
+    getDocumentInfo(): DocumentInfo;
+    extractText(pageIndex: number): string;
+    extractTextAsync(pageIndex: number): Promise<string>;
+    toMarkdown(): string;
+    toMarkdownAsync(): Promise<string>;
+    toHtml(): string;
+    search(text: string, options?: SearchOptions): SearchResult[];
+    hasText(text: string, caseSensitive?: boolean): boolean;
+    getPage(pageIndex: number): NativePdfPage;
+    getPages(): NativePdfPage[];
+    saveToPath(path: string): void;
+    saveToPdf(format?: string): Buffer;
+    save_async(path: string): Promise<void>;
+    saveToStream(stream: NodeJS.WritableStream): void;
+    getForms(): any;
+    fillForms(values: Record<string, string>): void;
+    getEmbeddedFiles(): EmbeddedFile[];
+    extractEmbeddedFile(filename: string): Buffer;
+    encrypt(userPassword: string, ownerPassword?: string, permissions?: number): void;
+    decrypt(password: string): boolean;
+    setPermissions(permissions: number): void;
+    getOutline(): any[];
+    setOutline(outline: any[]): void;
+    getStructure(): any;
+    getPageLabels(): string[];
+    setPageLabels(labels: string[]): void;
+    getLayers(): any[];
+    setLayerVisibility(layerId: string, visible: boolean): void;
+    close(): void;
+}
+/**
+ * Native Pdf class interface (represents a PDF file)
+ */
+export interface NativePdf {
+    getPageCount(): number;
+    getPageSizes(): Array<{
+        width: number;
+        height: number;
+    }>;
+    getPageSize(pageIndex: number): {
+        width: number;
+        height: number;
+    };
+    getPage(pageIndex: number): NativePdfPage;
+    renderPage(pageIndex: number, options?: any): Buffer;
+    renderPageToCanvas(pageIndex: number, canvas: any): void;
+    addPage(width: number, height: number): NativePdfPage;
+    removePage(pageIndex: number): void;
+    insertPage(pageIndex: number, width: number, height: number): NativePdfPage;
+    rotatePage(pageIndex: number, rotation: number): void;
+    save_async(path: string): Promise<void>;
+    saveToBuffer(): Buffer;
+    close(): void;
+}
+/**
+ * Native PdfPage class interface
+ */
+export interface NativePdfPage {
+    getIndex(): number;
+    getWidth(): number;
+    getHeight(): number;
+    getRotation(): number;
+    getMediaBox(): Rect;
+    getCropBox(): Rect;
+    extractText(): string;
+    extractElements(): PdfElement[];
+    getImages(): PdfImage[];
+    getTables(): PdfTable[];
+    render(options?: any): Buffer;
+    renderToCanvas(canvas: any): void;
+    getAnnotations(): Annotation[];
+    addAnnotation(annotation: Annotation): void;
+    removeAnnotation(annotationIndex: number): void;
+    setMediaBox(rect: Rect): void;
+    setCropBox(rect: Rect): void;
+    rotate(rotation: number): void;
+    drawText(text: string, x: number, y: number, options?: any): void;
+    drawImage(image: Buffer, x: number, y: number, width: number, height: number): void;
+    drawPath(points: Point[], options?: any): void;
+    searchText(text: string, options?: SearchOptions): SearchResult[];
+    close(): void;
+}
+/**
+ * Native builder class interface
+ */
+export interface NativePdfBuilder {
+    title(title: string): NativePdfBuilder;
+    author(author: string): NativePdfBuilder;
+    subject(subject: string): NativePdfBuilder;
+    keywords(keywords: string[]): NativePdfBuilder;
+    creator(creator: string): NativePdfBuilder;
+    producer(producer: string): NativePdfBuilder;
+    build(): NativePdf;
+}
+/**
+ * Native text searcher interface
+ */
+export interface NativeTextSearcher {
+    search(text: string, options?: SearchOptions): SearchResult[];
+    replaceAll(searchText: string, replaceText: string): number;
+    getMatches(text: string): SearchResult[];
+}
+/**
+ * Page size constants
+ */
+export interface PageSizeConstants {
+    A0: {
+        width: number;
+        height: number;
+    };
+    A1: {
+        width: number;
+        height: number;
+    };
+    A2: {
+        width: number;
+        height: number;
+    };
+    A3: {
+        width: number;
+        height: number;
+    };
+    A4: {
+        width: number;
+        height: number;
+    };
+    A5: {
+        width: number;
+        height: number;
+    };
+    Letter: {
+        width: number;
+        height: number;
+    };
+    Legal: {
+        width: number;
+        height: number;
+    };
+    Tabloid: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Complete native module interface
+ */
+export interface NativeModule {
+    getVersion(): string;
+    getPdfOxideVersion(): string;
+    PdfDocument: new (...args: any[]) => NativePdfDocument;
+    Pdf: new (...args: any[]) => NativePdf;
+    PdfPage: new (...args: any[]) => NativePdfPage;
+    PdfBuilder: new (...args: any[]) => NativePdfBuilder;
+    TextSearcher: new (...args: any[]) => NativeTextSearcher;
+    PdfElement: new (...args: any[]) => PdfElement;
+    PdfText: new (...args: any[]) => PdfText;
+    PdfImage: new (...args: any[]) => PdfImage;
+    PdfPath: new (...args: any[]) => PdfPath;
+    PdfTable: new (...args: any[]) => PdfTable;
+    PdfStructure: new (...args: any[]) => any;
+    Annotation: new (...args: any[]) => Annotation;
+    TextAnnotation: new (...args: any[]) => TextAnnotation;
+    HighlightAnnotation: new (...args: any[]) => HighlightAnnotation;
+    LinkAnnotation: new (...args: any[]) => LinkAnnotation;
+    PageSize: PageSizeConstants;
+    Rect: new (x: number, y: number, width: number, height: number) => Rect;
+    Point: new (x: number, y: number) => Point;
+    Color: new (red: number, green: number, blue: number, alpha?: number) => Color;
+    ConversionOptions: new (...args: any[]) => ConversionOptions;
+    SearchOptions: new (...args: any[]) => SearchOptions;
+    SearchResult: new (...args: any[]) => SearchResult;
+    [key: string]: any;
+}