pdf-oxide-fips 0.3.47

package/lib/builders/annotation-builder.js

@@ -0,0 +1,317 @@
+/**
+ * Builder for creating PDF annotations
+ *
+ * Configures annotation properties like content, appearance, author, and behavior.
+ *
+ * @example
+ * ```typescript
+ * import { AnnotationBuilder } from 'pdf_oxide';
+ *
+ * const annotation = AnnotationBuilder.create()
+ *   .type('highlight')
+ *   .content('Important section')
+ *   .author('Reviewer')
+ *   .color([1, 1, 0]) // Yellow
+ *   .build();
+ *
+ * pdf.addAnnotation(annotation);
+ * ```
+ */
+export class AnnotationBuilder {
+    /**
+     * Creates a new AnnotationBuilder instance
+     * @private
+     */
+    constructor() {
+        this._type = 'text';
+        this._content = '';
+        this._color = [1, 0, 0]; // Default: red (RGB normalized 0-1)
+        this._opacity = 1.0;
+        this._creationDate = new Date();
+        this._modificationDate = new Date();
+        this._flags = 0;
+    }
+    /**
+     * Creates a new AnnotationBuilder instance
+     * @returns New builder instance
+     */
+    static create() {
+        return new AnnotationBuilder();
+    }
+    /**
+     * Creates a text annotation (comment/note)
+     * @returns This builder for chaining
+     */
+    asText() {
+        this._type = 'text';
+        return this;
+    }
+    /**
+     * Creates a highlight annotation
+     * @returns This builder for chaining
+     */
+    asHighlight() {
+        this._type = 'highlight';
+        return this;
+    }
+    /**
+     * Creates an underline annotation
+     * @returns This builder for chaining
+     */
+    asUnderline() {
+        this._type = 'underline';
+        return this;
+    }
+    /**
+     * Creates a strikeout annotation
+     * @returns This builder for chaining
+     */
+    asStrikeout() {
+        this._type = 'strikeout';
+        return this;
+    }
+    /**
+     * Creates a squiggly (wavy underline) annotation
+     * @returns This builder for chaining
+     */
+    asSquiggly() {
+        this._type = 'squiggly';
+        return this;
+    }
+    /**
+     * Sets the annotation type
+     * @param type - Annotation type ('text', 'highlight', 'underline', 'strikeout', 'squiggly')
+     * @returns This builder for chaining
+     */
+    type(type) {
+        const validTypes = ['text', 'highlight', 'underline', 'strikeout', 'squiggly', 'note'];
+        if (!validTypes.includes(type)) {
+            throw new Error(`Invalid annotation type. Must be one of: ${validTypes.join(', ')}`);
+        }
+        this._type = type;
+        return this;
+    }
+    /**
+     * Sets the annotation content/text
+     * @param content - The annotation content
+     * @returns This builder for chaining
+     */
+    content(content) {
+        if (typeof content !== 'string') {
+            throw new Error('Content must be a string');
+        }
+        this._content = content;
+        return this;
+    }
+    /**
+     * Sets the author of the annotation
+     * @param author - The author name
+     * @returns This builder for chaining
+     */
+    author(author) {
+        if (typeof author !== 'string') {
+            throw new Error('Author must be a string');
+        }
+        this._author = author.length > 0 ? author : undefined;
+        return this;
+    }
+    /**
+     * Sets the subject/title of the annotation
+     * @param subject - The annotation subject
+     * @returns This builder for chaining
+     */
+    subject(subject) {
+        if (typeof subject !== 'string') {
+            throw new Error('Subject must be a string');
+        }
+        this._subject = subject.length > 0 ? subject : undefined;
+        return this;
+    }
+    /**
+     * Sets the color of the annotation (RGB, normalized 0-1)
+     * @param rgb - RGB color array [r, g, b] with values 0-1
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.color([1, 1, 0]); // Yellow
+     * builder.color([1, 0, 0]); // Red
+     * builder.color([0, 1, 0]); // Green
+     * ```
+     */
+    color(rgb) {
+        if (!Array.isArray(rgb) || rgb.length !== 3) {
+            throw new Error('Color must be an array of 3 RGB values [r, g, b]');
+        }
+        if (!rgb.every((c) => typeof c === 'number' && c >= 0 && c <= 1)) {
+            throw new Error('RGB values must be numbers between 0 and 1');
+        }
+        this._color = [...rgb];
+        return this;
+    }
+    /**
+     * Sets the color using common color names
+     * @param colorName - Color name (e.g., 'red', 'yellow', 'green', 'blue')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.colorName('yellow');
+     * builder.colorName('red');
+     * ```
+     */
+    colorName(colorName) {
+        const colors = {
+            red: [1, 0, 0],
+            green: [0, 1, 0],
+            blue: [0, 0, 1],
+            yellow: [1, 1, 0],
+            cyan: [0, 1, 1],
+            magenta: [1, 0, 1],
+            white: [1, 1, 1],
+            black: [0, 0, 0],
+            gray: [0.5, 0.5, 0.5],
+            orange: [1, 0.5, 0],
+            purple: [0.5, 0, 0.5],
+        };
+        const lowerColorName = colorName.toLowerCase();
+        if (!colors[lowerColorName]) {
+            const available = Object.keys(colors).join(', ');
+            throw new Error(`Unknown color. Available colors: ${available}`);
+        }
+        this._color = [...colors[lowerColorName]];
+        return this;
+    }
+    /**
+     * Sets the opacity/transparency (0-1)
+     * @param opacity - Opacity value (0=transparent, 1=opaque)
+     * @returns This builder for chaining
+     */
+    opacity(opacity) {
+        if (typeof opacity !== 'number' || opacity < 0 || opacity > 1) {
+            throw new Error('Opacity must be a number between 0 and 1');
+        }
+        this._opacity = opacity;
+        return this;
+    }
+    /**
+     * Sets the bounding box for the annotation
+     * @param bounds - Bounding box {x, y, width, height}
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.bounds({x: 100, y: 200, width: 150, height: 30});
+     * ```
+     */
+    bounds(bounds) {
+        if (typeof bounds !== 'object' || bounds === null) {
+            throw new Error('Bounds must be an object');
+        }
+        const { x, y, width, height } = bounds;
+        if (![x, y, width, height].every((v) => typeof v === 'number' && v >= 0)) {
+            throw new Error('Bounds must have numeric x, y, width, height values >= 0');
+        }
+        this._bounds = { x, y, width, height };
+        return this;
+    }
+    /**
+     * Sets the creation date
+     * @param date - The creation date
+     * @returns This builder for chaining
+     */
+    creationDate(date) {
+        if (!(date instanceof Date)) {
+            throw new Error('creationDate must be a Date object');
+        }
+        this._creationDate = new Date(date);
+        return this;
+    }
+    /**
+     * Sets the modification date
+     * @param date - The modification date
+     * @returns This builder for chaining
+     */
+    modificationDate(date) {
+        if (!(date instanceof Date)) {
+            throw new Error('modificationDate must be a Date object');
+        }
+        this._modificationDate = new Date(date);
+        return this;
+    }
+    /**
+     * Sets the annotation to be printed
+     * @returns This builder for chaining
+     */
+    printable() {
+        this._flags |= 4; // Print flag
+        return this;
+    }
+    /**
+     * Sets the annotation to NOT be printed
+     * @returns This builder for chaining
+     */
+    notPrintable() {
+        this._flags &= ~4; // Clear print flag
+        return this;
+    }
+    /**
+     * Sets whether the annotation is locked (read-only)
+     * @param locked - Whether to lock the annotation
+     * @returns This builder for chaining
+     */
+    locked(locked) {
+        if (typeof locked !== 'boolean') {
+            throw new Error('locked must be a boolean');
+        }
+        if (locked) {
+            this._flags |= 128; // Locked flag
+        }
+        else {
+            this._flags &= ~128;
+        }
+        return this;
+    }
+    /**
+     * Sets a reply to this annotation
+     * @param replyContent - Content of the reply
+     * @returns This builder for chaining
+     */
+    reply(replyContent) {
+        if (typeof replyContent !== 'string') {
+            throw new Error('Reply content must be a string');
+        }
+        this._reply = replyContent;
+        return this;
+    }
+    /**
+     * Builds and returns the annotation object
+     * @returns Immutable annotation object
+     */
+    build() {
+        if (!this._bounds && this._type !== 'text') {
+            throw new Error(`Annotation type "${this._type}" requires bounds to be set`);
+        }
+        return {
+            type: this._type,
+            content: this._content,
+            author: this._author,
+            subject: this._subject,
+            color: [...this._color],
+            opacity: this._opacity,
+            bounds: this._bounds ? { ...this._bounds } : undefined,
+            creationDate: new Date(this._creationDate),
+            modificationDate: new Date(this._modificationDate),
+            flags: this._flags,
+            reply: this._reply,
+        };
+    }
+}
+/**
+ * Create a new AnnotationBuilder with static factory
+ * @deprecated Use AnnotationBuilder.create() instead
+ * @returns New builder instance
+ */
+export function createAnnotationBuilder() {
+    return AnnotationBuilder.create();
+}

package/lib/builders/conversion-options-builder.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Builder for conversion options when converting PDF to other formats
+ *
+ * Configures how PDFs are converted to Markdown, HTML, or other text formats
+ * with options for formatting, image handling, and content extraction.
+ *
+ * @example
+ * ```typescript
+ * import { ConversionOptionsBuilder } from 'pdf_oxide';
+ *
+ * const options = ConversionOptionsBuilder.create()
+ *   .preserveFormatting(true)
+ *   .includeImages(true)
+ *   .detectHeadings(true)
+ *   .detectTables(true)
+ *   .build();
+ *
+ * const doc = PdfDocument.open('file.pdf');
+ * const markdown = doc.toMarkdown(0, options);
+ * ```
+ */
+interface PageRangeOptions {
+    start: number;
+    end: number;
+}
+export interface ConversionOptions {
+    preserveFormatting: boolean;
+    detectHeadings: boolean;
+    detectTables: boolean;
+    detectLists: boolean;
+    includeImages: boolean;
+    imageFormat: string;
+    imageQuality: number;
+    maxImageDimension: number;
+    outputEncoding: string;
+    normalizeWhitespace: boolean;
+    extractAnnotations: boolean;
+    useStructureTree: boolean;
+    pageRange?: PageRangeOptions;
+}
+export declare class ConversionOptionsBuilder {
+    private _preserveFormatting;
+    private _detectHeadings;
+    private _detectTables;
+    private _detectLists;
+    private _includeImages;
+    private _imageFormat;
+    private _imageQuality;
+    private _maxImageDimension;
+    private _outputEncoding;
+    private _normalizeWhitespace;
+    private _extractAnnotations;
+    private _useStructureTree;
+    private _pageRange?;
+    /**
+     * Creates a new ConversionOptionsBuilder instance
+     * @private
+     */
+    private constructor();
+    /**
+     * Creates a new ConversionOptionsBuilder instance
+     * @returns New builder instance
+     */
+    static create(): ConversionOptionsBuilder;
+    /**
+     * Creates options with default settings optimized for readability
+     * @returns Conversion options with default preset
+     */
+    static default(): ConversionOptions;
+    /**
+     * Creates options optimized for text-only extraction
+     * @returns Conversion options with text-only preset
+     */
+    static textOnly(): ConversionOptions;
+    /**
+     * Creates options optimized for maximum quality and detail preservation
+     * @returns Conversion options with high-quality preset
+     */
+    static highQuality(): ConversionOptions;
+    /**
+     * Creates options for fast, basic conversion
+     * @returns Conversion options with fast preset
+     */
+    static fast(): ConversionOptions;
+    preserveFormatting(preserve: boolean): this;
+    detectHeadings(detect: boolean): this;
+    detectTables(detect: boolean): this;
+    detectLists(detect: boolean): this;
+    includeImages(include: boolean): this;
+    imageFormat(format: string): this;
+    imageQuality(quality: number): this;
+    maxImageDimension(maxDimension: number): this;
+    outputEncoding(encoding: string): this;
+    normalizeWhitespace(normalize: boolean): this;
+    extractAnnotations(extract: boolean): this;
+    useStructureTree(use: boolean): this;
+    pageRange(start: number, end: number): this;
+    build(): ConversionOptions;
+}
+/**
+ * Create a new ConversionOptionsBuilder with static factory
+ * @deprecated Use ConversionOptionsBuilder.create() instead
+ * @returns New builder instance
+ */
+export declare function createConversionOptionsBuilder(): ConversionOptionsBuilder;
+export {};

package/lib/builders/conversion-options-builder.js

@@ -0,0 +1,214 @@
+/**
+ * Builder for conversion options when converting PDF to other formats
+ *
+ * Configures how PDFs are converted to Markdown, HTML, or other text formats
+ * with options for formatting, image handling, and content extraction.
+ *
+ * @example
+ * ```typescript
+ * import { ConversionOptionsBuilder } from 'pdf_oxide';
+ *
+ * const options = ConversionOptionsBuilder.create()
+ *   .preserveFormatting(true)
+ *   .includeImages(true)
+ *   .detectHeadings(true)
+ *   .detectTables(true)
+ *   .build();
+ *
+ * const doc = PdfDocument.open('file.pdf');
+ * const markdown = doc.toMarkdown(0, options);
+ * ```
+ */
+export class ConversionOptionsBuilder {
+    /**
+     * Creates a new ConversionOptionsBuilder instance
+     * @private
+     */
+    constructor() {
+        this._preserveFormatting = true;
+        this._detectHeadings = true;
+        this._detectTables = true;
+        this._detectLists = true;
+        this._includeImages = true;
+        this._imageFormat = 'png';
+        this._imageQuality = 85;
+        this._maxImageDimension = 2048;
+        this._outputEncoding = 'utf-8';
+        this._normalizeWhitespace = true;
+        this._extractAnnotations = false;
+        this._useStructureTree = true;
+    }
+    /**
+     * Creates a new ConversionOptionsBuilder instance
+     * @returns New builder instance
+     */
+    static create() {
+        return new ConversionOptionsBuilder();
+    }
+    /**
+     * Creates options with default settings optimized for readability
+     * @returns Conversion options with default preset
+     */
+    static default() {
+        return ConversionOptionsBuilder.create().build();
+    }
+    /**
+     * Creates options optimized for text-only extraction
+     * @returns Conversion options with text-only preset
+     */
+    static textOnly() {
+        return ConversionOptionsBuilder.create()
+            .preserveFormatting(false)
+            .detectHeadings(true)
+            .detectTables(false)
+            .detectLists(false)
+            .includeImages(false)
+            .build();
+    }
+    /**
+     * Creates options optimized for maximum quality and detail preservation
+     * @returns Conversion options with high-quality preset
+     */
+    static highQuality() {
+        return ConversionOptionsBuilder.create()
+            .preserveFormatting(true)
+            .detectHeadings(true)
+            .detectTables(true)
+            .detectLists(true)
+            .includeImages(true)
+            .imageQuality(95)
+            .normalizeWhitespace(false)
+            .build();
+    }
+    /**
+     * Creates options for fast, basic conversion
+     * @returns Conversion options with fast preset
+     */
+    static fast() {
+        return ConversionOptionsBuilder.create()
+            .preserveFormatting(false)
+            .detectHeadings(false)
+            .detectTables(false)
+            .detectLists(false)
+            .includeImages(false)
+            .normalizeWhitespace(true)
+            .build();
+    }
+    preserveFormatting(preserve) {
+        if (typeof preserve !== 'boolean') {
+            throw new Error('preserveFormatting must be a boolean');
+        }
+        this._preserveFormatting = preserve;
+        return this;
+    }
+    detectHeadings(detect) {
+        if (typeof detect !== 'boolean') {
+            throw new Error('detectHeadings must be a boolean');
+        }
+        this._detectHeadings = detect;
+        return this;
+    }
+    detectTables(detect) {
+        if (typeof detect !== 'boolean') {
+            throw new Error('detectTables must be a boolean');
+        }
+        this._detectTables = detect;
+        return this;
+    }
+    detectLists(detect) {
+        if (typeof detect !== 'boolean') {
+            throw new Error('detectLists must be a boolean');
+        }
+        this._detectLists = detect;
+        return this;
+    }
+    includeImages(include) {
+        if (typeof include !== 'boolean') {
+            throw new Error('includeImages must be a boolean');
+        }
+        this._includeImages = include;
+        return this;
+    }
+    imageFormat(format) {
+        const validFormats = ['png', 'jpg', 'jpeg', 'webp'];
+        if (!validFormats.includes(format.toLowerCase())) {
+            throw new Error(`Invalid image format. Must be one of: ${validFormats.join(', ')}`);
+        }
+        this._imageFormat = format.toLowerCase();
+        return this;
+    }
+    imageQuality(quality) {
+        if (typeof quality !== 'number' || quality < 0 || quality > 100) {
+            throw new Error('imageQuality must be a number between 0 and 100');
+        }
+        this._imageQuality = quality;
+        return this;
+    }
+    maxImageDimension(maxDimension) {
+        if (typeof maxDimension !== 'number' || maxDimension <= 0) {
+            throw new Error('maxImageDimension must be a positive number');
+        }
+        this._maxImageDimension = maxDimension;
+        return this;
+    }
+    outputEncoding(encoding) {
+        if (typeof encoding !== 'string' || encoding.length === 0) {
+            throw new Error('outputEncoding must be a non-empty string');
+        }
+        this._outputEncoding = encoding;
+        return this;
+    }
+    normalizeWhitespace(normalize) {
+        if (typeof normalize !== 'boolean') {
+            throw new Error('normalizeWhitespace must be a boolean');
+        }
+        this._normalizeWhitespace = normalize;
+        return this;
+    }
+    extractAnnotations(extract) {
+        if (typeof extract !== 'boolean') {
+            throw new Error('extractAnnotations must be a boolean');
+        }
+        this._extractAnnotations = extract;
+        return this;
+    }
+    useStructureTree(use) {
+        if (typeof use !== 'boolean') {
+            throw new Error('useStructureTree must be a boolean');
+        }
+        this._useStructureTree = use;
+        return this;
+    }
+    pageRange(start, end) {
+        if (typeof start !== 'number' || typeof end !== 'number' || start < 0 || end < start) {
+            throw new Error('pageRange must have valid start and end indices');
+        }
+        this._pageRange = { start, end };
+        return this;
+    }
+    build() {
+        return {
+            preserveFormatting: this._preserveFormatting,
+            detectHeadings: this._detectHeadings,
+            detectTables: this._detectTables,
+            detectLists: this._detectLists,
+            includeImages: this._includeImages,
+            imageFormat: this._imageFormat,
+            imageQuality: this._imageQuality,
+            maxImageDimension: this._maxImageDimension,
+            outputEncoding: this._outputEncoding,
+            normalizeWhitespace: this._normalizeWhitespace,
+            extractAnnotations: this._extractAnnotations,
+            useStructureTree: this._useStructureTree,
+            pageRange: this._pageRange,
+        };
+    }
+}
+/**
+ * Create a new ConversionOptionsBuilder with static factory
+ * @deprecated Use ConversionOptionsBuilder.create() instead
+ * @returns New builder instance
+ */
+export function createConversionOptionsBuilder() {
+    return ConversionOptionsBuilder.create();
+}