pdfdancer-client-typescript 1.0.12 → 1.0.13

package/src/fingerprint.ts

@@ -0,0 +1,169 @@
+/**
+ * Fingerprint generation for PDFDancer client
+ * Generates a unique fingerprint hash to identify client requests
+ */
+
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+/**
+ * Get the install salt from localStorage (browser) or file storage (Node.js)
+ * This creates a persistent identifier for this client installation
+ */
+function getInstallSalt(): string {
+    const storageKey = 'pdfdancer_install_salt';
+
+    // Check if we're in a browser environment
+    if (typeof localStorage !== 'undefined') {
+        let salt = localStorage.getItem(storageKey);
+        if (!salt) {
+            salt = crypto.randomBytes(16).toString('hex');
+            localStorage.setItem(storageKey, salt);
+        }
+        return salt;
+    }
+
+    // Node.js environment - use file storage
+    try {
+        const saltDir = path.join(os.homedir(), '.pdfdancer');
+        const saltFile = path.join(saltDir, 'install_salt');
+
+        // Create directory if it doesn't exist
+        if (!fs.existsSync(saltDir)) {
+            fs.mkdirSync(saltDir, { recursive: true, mode: 0o700 });
+        }
+
+        // Read existing salt or generate new one
+        if (fs.existsSync(saltFile)) {
+            return fs.readFileSync(saltFile, 'utf8').trim();
+        } else {
+            const salt = crypto.randomBytes(16).toString('hex');
+            fs.writeFileSync(saltFile, salt, { mode: 0o600 });
+            return salt;
+        }
+    } catch (error) {
+        // Fallback to generating a new salt if file operations fail
+        return crypto.randomBytes(16).toString('hex');
+    }
+}
+
+/**
+ * Attempt to get the client's IP address
+ * Note: This is limited on the client side and may not always be accurate
+ */
+async function getClientIP(): Promise<string> {
+    try {
+        // In browser, we can't reliably get the real IP
+        // Return a placeholder that will be consistent per session
+        return 'client-unknown';
+    } catch {
+        return 'client-unknown';
+    }
+}
+
+/**
+ * Get the OS type
+ */
+function getOSType(): string {
+    // Check if we're in Node.js
+    if (typeof process !== 'undefined' && process.platform) {
+        return process.platform;
+    }
+
+    // Browser environment
+    if (typeof navigator !== 'undefined') {
+        const userAgent = navigator.userAgent.toLowerCase();
+        if (userAgent.includes('win')) return 'windows';
+        if (userAgent.includes('mac')) return 'macos';
+        if (userAgent.includes('linux')) return 'linux';
+        if (userAgent.includes('android')) return 'android';
+        if (userAgent.includes('iphone') || userAgent.includes('ipad')) return 'ios';
+    }
+
+    return 'unknown';
+}
+
+/**
+ * Get the current hostname
+ */
+function getHostname(): string {
+    // Node.js environment
+    if (typeof process !== 'undefined') {
+        try {
+            return os.hostname();
+        } catch {
+            // Fall through to browser logic
+        }
+    }
+
+    // Browser environment
+    if (typeof window !== 'undefined' && window.location) {
+        return window.location.hostname;
+    }
+
+    return 'unknown';
+}
+
+/**
+ * Get the timezone
+ */
+function getTimezone(): string {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    } catch {
+        return 'unknown';
+    }
+}
+
+/**
+ * Get the locale
+ */
+function getLocale(): string {
+    try {
+        if (typeof navigator !== 'undefined' && navigator.language) {
+            return navigator.language;
+        }
+        return Intl.DateTimeFormat().resolvedOptions().locale;
+    } catch {
+        return 'unknown';
+    }
+}
+
+/**
+ * Generate a fingerprint hash from client data points
+ *
+ * @param userId Optional user ID to include in the fingerprint
+ * @returns SHA256 hash of fingerprint components
+ */
+export async function generateFingerprint(userId?: string): Promise<string> {
+    const ip = await getClientIP();
+    const uid = userId || 'unknown';
+    const osType = getOSType();
+    const sdkLanguage = 'typescript';
+    const timezone = getTimezone();
+    const locale = getLocale();
+    const domain = getHostname();
+    const installSalt = getInstallSalt();
+
+    // Hash individual components
+    const ipHash = crypto.createHash('sha256').update(ip).digest('hex');
+    const uidHash = crypto.createHash('sha256').update(uid).digest('hex');
+    const domainHash = crypto.createHash('sha256').update(domain).digest('hex');
+
+    // Concatenate all components and hash
+    const fingerprintData =
+        ipHash +
+        uidHash +
+        osType +
+        sdkLanguage +
+        timezone +
+        locale +
+        domainHash +
+        installSalt;
+
+    const fingerprintHash = crypto.createHash('sha256').update(fingerprintData).digest('hex');
+
+    return fingerprintHash;
+}

package/src/image-builder.ts

@@ -8,13 +8,11 @@ interface PDFDancerInternals {
 }
 
 export class ImageBuilder {
-    private _client: PDFDancer;
     private _imageData: Uint8Array<ArrayBuffer> | undefined;
     private _position: Position | undefined;
-    private _internals: PDFDancerInternals;
+    private readonly _internals: PDFDancerInternals;
 
-    constructor(_client: PDFDancer) {
-        this._client = _client;
+    constructor(private _client: PDFDancer, private readonly _defaultPageIndex?: number) {
         // Cast to the internal interface to get access
         this._internals = this._client as unknown as PDFDancerInternals;
     }
@@ -33,8 +31,17 @@ export class ImageBuilder {
         return this;
     }
 
-    at(pageIndex: number, x: number, y: number) {
-        this._position = Position.atPageCoordinates(pageIndex, x, y);
+    at(x: number, y: number): this;
+    at(pageIndex: number, x: number, y: number): this;
+    at(pageIndexOrX: number, xOrY: number, maybeY?: number): this {
+        if (maybeY === undefined) {
+            if (this._defaultPageIndex === undefined) {
+                throw new Error('Page index must be provided when adding an image');
+            }
+            this._position = Position.atPageCoordinates(this._defaultPageIndex, pageIndexOrX, xOrY);
+        } else {
+            this._position = Position.atPageCoordinates(pageIndexOrX, xOrY, maybeY);
+        }
         return this;
     }
 

package/src/index.ts

@@ -6,6 +6,7 @@
 
 export { PDFDancer } from './pdfdancer_v1';
 export { ParagraphBuilder } from './paragraph-builder';
+export { PageBuilder } from './page-builder';
 
 export {
   PdfDancerException,
@@ -28,15 +29,19 @@ export {
   Image,
   BoundingRect,
   Paragraph,
+  TextLine,
   PositionMode,
   ShapeType,
   Point,
   StandardFonts,
+  STANDARD_PAGE_SIZES,
   Orientation,
   CommandResult,
   TextStatus,
   FontRecommendation,
-  FontType
+  FontType,
+  DocumentSnapshot,
+  PageSnapshot
 } from './models';
 
 export const VERSION = "1.0.0";

package/src/models.ts

@@ -8,13 +8,16 @@ export enum ObjectType {
     PATH = "PATH",
     PARAGRAPH = "PARAGRAPH",
     TEXT_LINE = "TEXT_LINE",
+    TEXT_ELEMENT = "TEXT_ELEMENT",
     PAGE = "PAGE",
     FORM_FIELD = "FORM_FIELD",
     TEXT_FIELD = "TEXT_FIELD",
-    CHECK_BOX = "CHECK_BOX",
+    CHECKBOX = "CHECKBOX",
     RADIO_BUTTON = "RADIO_BUTTON"
 }
 
+const DEFAULT_LINE_SPACING = 1.2;
+
 /**
  * Defines how position matching should be performed when searching for objects.
  */
@@ -82,6 +85,7 @@ class PositioningError extends Error {
  */
 export class Position {
     public name?: string;
+    public tolerance?: number;
 
     constructor(
         public pageIndex?: number,
@@ -102,9 +106,12 @@ export class Position {
 
     /**
      * Creates a position specification for specific coordinates on a page.
+     * @param tolerance Optional tolerance in points for coordinate matching (default: 0)
      */
-    static atPageCoordinates(pageIndex: number, x: number, y: number): Position {
-        return Position.atPage(pageIndex).atCoordinates({x, y});
+    static atPageCoordinates(pageIndex: number, x: number, y: number, tolerance: number = 0): Position {
+        const pos = Position.atPage(pageIndex).atCoordinates({x, y});
+        pos.tolerance = tolerance;
+        return pos;
     }
 
     static atPageWithText(pageIndex: number, text: string) {
@@ -480,10 +487,60 @@ export class Image {
 export class Paragraph {
     constructor(
         public position?: Position,
-        public textLines?: string[],
+        public textLines?: Array<TextLine | string>,
+        public font?: Font,
+        public color?: Color,
+        public lineSpacing: number = DEFAULT_LINE_SPACING,
+        public lineSpacings?: number[] | null
+    ) {
+    }
+
+    getPosition(): Position | undefined {
+        return this.position;
+    }
+
+    setPosition(position: Position): void {
+        this.position = position;
+    }
+
+    clearLines(): void {
+        this.textLines = [];
+    }
+
+    addLine(textLine: TextLine | string): void {
+        if (!this.textLines) {
+            this.textLines = [];
+        }
+        this.textLines.push(textLine);
+    }
+
+    getLines(): Array<TextLine | string> {
+        if (!this.textLines) {
+            this.textLines = [];
+        }
+        return this.textLines;
+    }
+
+    setLines(lines: Array<TextLine | string>): void {
+        this.textLines = [...lines];
+    }
+
+    setLineSpacings(spacings?: number[] | null): void {
+        this.lineSpacings = spacings ? [...spacings] : spacings ?? null;
+    }
+
+    getLineSpacings(): number[] | null | undefined {
+        return this.lineSpacings ? [...this.lineSpacings] : this.lineSpacings;
+    }
+}
+
+export class TextLine {
+    constructor(
+        public position?: Position,
         public font?: Font,
         public color?: Color,
-        public lineSpacing: number = 1.2
+        public lineSpacing: number = DEFAULT_LINE_SPACING,
+        public text: string = ""
     ) {
     }
 
@@ -587,38 +644,76 @@ export class AddRequest {
                 data: dataB64
             };
         } else if (obj instanceof Paragraph) {
+            const fontToDict = (font?: Font | null) => {
+                if (!font) {
+                    return null;
+                }
+                return {name: font.name, size: font.size};
+            };
+
+            const colorToDict = (color?: Color | null) => {
+                if (!color) {
+                    return null;
+                }
+                return {red: color.r, green: color.g, blue: color.b, alpha: color.a};
+            };
+
             const lines: any[] = [];
             if (obj.textLines) {
                 for (const line of obj.textLines) {
+                    let text: string;
+                    let font = obj.font;
+                    let color = obj.color;
+                    let position = obj.position;
+                    let spacing = obj.lineSpacing;
+
+                    if (line instanceof TextLine) {
+                        text = line.text;
+                        font = line.font ?? font;
+                        color = line.color ?? color;
+                        position = line.position ?? position;
+                        spacing = line.lineSpacing ?? spacing;
+                    } else {
+                        text = line;
+                    }
+
                     const textElement = {
-                        text: line,
-                        font: obj.font ? {name: obj.font.name, size: obj.font.size} : null,
-                        color: obj.color ? {red: obj.color.r, green: obj.color.g, blue: obj.color.b, alpha: obj.color.a} : null,
-                        position: obj.position ? positionToDict(obj.position) : null
+                        text,
+                        font: fontToDict(font),
+                        color: colorToDict(color),
+                        position: position ? positionToDict(position) : null
                     };
 
                     const textLine: any = {
                         textElements: [textElement]
                     };
 
-                    if (obj.color) {
-                        textLine.color = {red: obj.color.r, green: obj.color.g, blue: obj.color.b, alpha: obj.color.a};
+                    if (color) {
+                        textLine.color = colorToDict(color);
+                    }
+                    if (position) {
+                        textLine.position = positionToDict(position);
                     }
-                    if (obj.position) {
-                        textLine.position = positionToDict(obj.position);
+                    if (spacing !== undefined && spacing !== null) {
+                        textLine.lineSpacing = spacing;
                     }
+
                     lines.push(textLine);
                 }
             }
 
-            const lineSpacings = obj.lineSpacing !== undefined ? [obj.lineSpacing] : null;
+            const lineSpacings = obj.lineSpacings
+                ? [...obj.lineSpacings]
+                : (obj.lineSpacing !== undefined && obj.lineSpacing !== null
+                    ? [obj.lineSpacing]
+                    : null);
 
             return {
                 type: "PARAGRAPH",
                 position: obj.position ? positionToDict(obj.position) : null,
-                lines,
+                lines: lines.length ? lines : null,
                 lineSpacings,
-                font: obj.font ? {name: obj.font.name, size: obj.font.size} : null
+                font: fontToDict(obj.font)
             };
         } else {
             throw new Error(`Unsupported object type: ${typeof obj}`);
@@ -775,18 +870,35 @@ export class CreatePdfRequest {
  */
 export class AddPageRequest {
     constructor(
-        public pageIndex: number,
-        public pageSize?: string,
-        public orientation?: string
+        public pageIndex?: number,
+        public pageSize?: PageSize,
+        public orientation?: Orientation | string
     ) {
     }
 
     toDict(): Record<string, any> {
-        return {
-            pageIndex: this.pageIndex,
-            pageSize: this.pageSize,
-            orientation: this.orientation
-        };
+        const payload: Record<string, any> = {};
+
+        if (this.pageIndex !== undefined) {
+            payload.pageIndex = this.pageIndex;
+        }
+
+        if (this.orientation !== undefined && this.orientation !== null) {
+            const value = typeof this.orientation === 'string'
+                ? this.orientation.trim().toUpperCase()
+                : this.orientation;
+            payload.orientation = typeof value === 'string' ? value : value;
+        }
+
+        if (this.pageSize) {
+            payload.pageSize = {
+                name: this.pageSize.name,
+                width: this.pageSize.width,
+                height: this.pageSize.height
+            };
+        }
+
+        return payload;
     }
 }
 
@@ -835,6 +947,78 @@ export class CommandResult {
     }
 }
 
+/**
+ * Represents a snapshot of a single page in a PDF document.
+ * Contains the page reference and all elements on that page.
+ */
+export class PageSnapshot {
+    constructor(
+        public pageRef: PageRef,
+        public elements: ObjectRef[]
+    ) {}
+
+    /**
+     * Filters elements by object type.
+     */
+    getElementsByType(type: ObjectType): ObjectRef[] {
+        return this.elements.filter(el => el.type === type);
+    }
+
+    /**
+     * Gets the page index from the page reference.
+     */
+    getPageIndex(): number | undefined {
+        return this.pageRef.position.pageIndex;
+    }
+
+    /**
+     * Returns the number of elements on this page.
+     */
+    getElementCount(): number {
+        return this.elements.length;
+    }
+}
+
+/**
+ * Represents a complete snapshot of a PDF document.
+ * Contains page count, font information, and snapshots of all pages.
+ */
+export class DocumentSnapshot {
+    constructor(
+        public pageCount: number,
+        public fonts: FontRecommendation[],
+        public pages: PageSnapshot[]
+    ) {}
+
+    /**
+     * Gets the snapshot for a specific page by index.
+     */
+    getPageSnapshot(pageIndex: number): PageSnapshot | undefined {
+        return this.pages.find(page => page.getPageIndex() === pageIndex);
+    }
+
+    /**
+     * Gets all elements across all pages.
+     */
+    getAllElements(): ObjectRef[] {
+        return this.pages.flatMap(page => page.elements);
+    }
+
+    /**
+     * Gets all elements of a specific type across all pages.
+     */
+    getElementsByType(type: ObjectType): ObjectRef[] {
+        return this.getAllElements().filter(el => el.type === type);
+    }
+
+    /**
+     * Returns the total number of elements across all pages.
+     */
+    getTotalElementCount(): number {
+        return this.pages.reduce((sum, page) => sum + page.getElementCount(), 0);
+    }
+}
+
 // Helper function to convert Position to dictionary for JSON serialization
 function positionToDict(position: Position): Record<string, any> {
     const result: Record<string, any> = {

package/src/page-builder.ts

@@ -0,0 +1,130 @@
+import {PDFDancer} from './pdfdancer_v1';
+import {AddPageRequest, Orientation, PageRef, PageSize, STANDARD_PAGE_SIZES} from './models';
+import {ValidationException} from './exceptions';
+
+interface PDFDancerInternals {
+    addPage(request?: AddPageRequest | null): Promise<PageRef>;
+}
+
+const normalizeOrientation = (value: Orientation | string): Orientation => {
+    if (typeof value === 'string') {
+        const normalized = value.trim().toUpperCase();
+        if (!(normalized in Orientation)) {
+            throw new ValidationException(`Invalid orientation: ${value}`);
+        }
+        return Orientation[normalized as keyof typeof Orientation];
+    }
+    return value;
+};
+
+const normalizePageSize = (value: PageSize | string): PageSize => {
+    if (typeof value === 'string') {
+        const normalized = value.trim().toUpperCase();
+        const standard = STANDARD_PAGE_SIZES[normalized];
+        if (!standard) {
+            throw new ValidationException(`Unknown page size: ${value}`);
+        }
+        return {name: normalized, width: standard.width, height: standard.height};
+    }
+
+    const width = value.width;
+    const height = value.height;
+    if (width === undefined || height === undefined) {
+        throw new ValidationException('Custom page size must include width and height');
+    }
+    if (width <= 0 || height <= 0) {
+        throw new ValidationException('Page size width and height must be positive numbers');
+    }
+    return {
+        name: value.name?.toUpperCase(),
+        width,
+        height
+    };
+};
+
+export class PageBuilder {
+    private readonly _client: PDFDancer;
+    private readonly _internals: PDFDancerInternals;
+    private _pageIndex?: number;
+    private _orientation?: Orientation;
+    private _pageSize?: PageSize;
+
+    constructor(client: PDFDancer) {
+        if (!client) {
+            throw new ValidationException('Client cannot be null');
+        }
+        this._client = client;
+        this._internals = this._client as unknown as PDFDancerInternals;
+    }
+
+    atIndex(pageIndex: number): this {
+        if (pageIndex === null || pageIndex === undefined) {
+            throw new ValidationException('Page index cannot be null');
+        }
+        if (!Number.isInteger(pageIndex) || pageIndex < 0) {
+            throw new ValidationException('Page index must be a non-negative integer');
+        }
+        this._pageIndex = pageIndex;
+        return this;
+    }
+
+    orientation(orientation: Orientation | string): this {
+        this._orientation = normalizeOrientation(orientation);
+        return this;
+    }
+
+    portrait(): this {
+        this._orientation = Orientation.PORTRAIT;
+        return this;
+    }
+
+    landscape(): this {
+        this._orientation = Orientation.LANDSCAPE;
+        return this;
+    }
+
+    pageSize(pageSize: PageSize | string): this {
+        this._pageSize = normalizePageSize(pageSize);
+        return this;
+    }
+
+    a4(): this {
+        return this.pageSize('A4');
+    }
+
+    letter(): this {
+        return this.pageSize('LETTER');
+    }
+
+    a3(): this {
+        return this.pageSize('A3');
+    }
+
+    a5(): this {
+        return this.pageSize('A5');
+    }
+
+    legal(): this {
+        return this.pageSize('LEGAL');
+    }
+
+    customSize(width: number, height: number): this {
+        if (width <= 0 || height <= 0) {
+            throw new ValidationException('Custom page size dimensions must be positive');
+        }
+        this._pageSize = {width, height};
+        return this;
+    }
+
+    async add(): Promise<PageRef> {
+        const request = this._buildRequest();
+        return this._internals.addPage(request);
+    }
+
+    private _buildRequest(): AddPageRequest | null {
+        if (this._pageIndex === undefined && this._orientation === undefined && this._pageSize === undefined) {
+            return null;
+        }
+        return new AddPageRequest(this._pageIndex, this._pageSize, this._orientation);
+    }
+}