pdfdancer-client-typescript 1.0.11 → 1.0.13

package/dist/pdfdancer_v1.js

@@ -12,10 +12,97 @@ exports.PDFDancer = void 0;
 const exceptions_1 = require("./exceptions");
 const models_1 = require("./models");
 const paragraph_builder_1 = require("./paragraph-builder");
+const page_builder_1 = require("./page-builder");
 const types_1 = require("./types");
 const image_builder_1 = require("./image-builder");
+const fingerprint_1 = require("./fingerprint");
 const fs_1 = __importDefault(require("fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const DEFAULT_TOLERANCE = 0.01;
+// Debug flag - set to true to enable timing logs
+const DEBUG = (process.env.PDFDANCER_CLIENT_DEBUG ?? '').toLowerCase() === 'true' ||
+    (process.env.PDFDANCER_CLIENT_DEBUG ?? '') === '1' ||
+    (process.env.PDFDANCER_CLIENT_DEBUG ?? '').toLowerCase() === 'yes';
+/**
+ * Generate a timestamp string in the format expected by the API.
+ * Format: YYYY-MM-DDTHH:MM:SS.ffffffZ (with microseconds)
+ */
+function generateTimestamp() {
+    const now = new Date();
+    const year = now.getUTCFullYear();
+    const month = String(now.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(now.getUTCDate()).padStart(2, '0');
+    const hours = String(now.getUTCHours()).padStart(2, '0');
+    const minutes = String(now.getUTCMinutes()).padStart(2, '0');
+    const seconds = String(now.getUTCSeconds()).padStart(2, '0');
+    const milliseconds = String(now.getUTCMilliseconds()).padStart(3, '0');
+    // Add 3 more zeros for microseconds (JavaScript doesn't have microsecond precision)
+    const microseconds = milliseconds + '000';
+    return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${microseconds}Z`;
+}
+/**
+ * Parse timestamp string, handling both microseconds and nanoseconds precision.
+ * @param timestampStr Timestamp string in format YYYY-MM-DDTHH:MM:SS.fffffffZ (with 6 or 9 fractional digits)
+ */
+function parseTimestamp(timestampStr) {
+    // Remove the 'Z' suffix
+    let ts = timestampStr.replace(/Z$/, '');
+    // Handle nanoseconds (9 digits) by truncating to milliseconds (3 digits)
+    // JavaScript's Date only supports millisecond precision
+    if (ts.includes('.')) {
+        const [datePart, fracPart] = ts.split('.');
+        // Truncate to 3 digits (milliseconds)
+        const truncatedFrac = fracPart.substring(0, 3);
+        ts = `${datePart}.${truncatedFrac}`;
+    }
+    return new Date(ts + 'Z');
+}
+/**
+ * Check for X-Generated-At and X-Received-At headers and log timing information if DEBUG=true.
+ *
+ * Expected timestamp formats:
+ * - 2025-10-24T08:49:39.161945Z (microseconds - 6 digits)
+ * - 2025-10-24T08:58:45.468131265Z (nanoseconds - 9 digits)
+ */
+function logGeneratedAtHeader(response, method, path) {
+    if (!DEBUG) {
+        return;
+    }
+    const generatedAt = response.headers.get('X-Generated-At');
+    const receivedAt = response.headers.get('X-Received-At');
+    if (generatedAt || receivedAt) {
+        try {
+            const logParts = [];
+            const currentTime = new Date();
+            // Parse and log X-Received-At
+            let receivedTime = null;
+            if (receivedAt) {
+                receivedTime = parseTimestamp(receivedAt);
+                const timeSinceReceived = (currentTime.getTime() - receivedTime.getTime()) / 1000;
+                logParts.push(`X-Received-At: ${receivedAt}, time since received on backend: ${timeSinceReceived.toFixed(3)}s`);
+            }
+            // Parse and log X-Generated-At
+            let generatedTime = null;
+            if (generatedAt) {
+                generatedTime = parseTimestamp(generatedAt);
+                const timeSinceGenerated = (currentTime.getTime() - generatedTime.getTime()) / 1000;
+                logParts.push(`X-Generated-At: ${generatedAt}, time since generated on backend: ${timeSinceGenerated.toFixed(3)}s`);
+            }
+            // Calculate processing time (X-Generated-At - X-Received-At)
+            if (receivedTime && generatedTime) {
+                const processingTime = (generatedTime.getTime() - receivedTime.getTime()) / 1000;
+                logParts.push(`processing time on backend: ${processingTime.toFixed(3)}s`);
+            }
+            if (logParts.length > 0) {
+                console.log(`${Date.now() / 1000}|${method} ${path} - ${logParts.join(', ')}`);
+            }
+        }
+        catch (e) {
+            const errorMessage = e instanceof Error ? e.message : String(e);
+            console.log(`${Date.now() / 1000}|${method} ${path} - Header parse error: ${errorMessage}`);
+        }
+    }
+}
 class PageClient {
     constructor(client, pageIndex, pageRef) {
         this.type = models_1.ObjectType.PAGE;
@@ -28,8 +115,8 @@ class PageClient {
         // Cast to the internal interface to get access
         this._internals = this._client;
     }
-    async selectPathsAt(x, y) {
-        return this._internals.toPathObjects(await this._internals.findPaths(models_1.Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectPathsAt(x, y, tolerance = 0) {
+        return this._internals.toPathObjects(await this._internals.findPaths(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
     }
     async selectPaths() {
         return this._internals.toPathObjects(await this._internals.findPaths(models_1.Position.atPage(this._pageIndex)));
@@ -37,8 +124,8 @@ class PageClient {
     async selectImages() {
         return this._internals.toImageObjects(await this._internals._findImages(models_1.Position.atPage(this._pageIndex)));
     }
-    async selectImagesAt(x, y) {
-        return this._internals.toImageObjects(await this._internals._findImages(models_1.Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectImagesAt(x, y, tolerance = 0) {
+        return this._internals.toImageObjects(await this._internals._findImages(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
     }
     async delete() {
         return this._client.deletePage(this._pageIndex);
@@ -56,14 +143,14 @@ class PageClient {
     async selectForms() {
         return this._internals.toFormXObjects(await this._internals.findFormXObjects(models_1.Position.atPage(this._pageIndex)));
     }
-    async selectFormsAt(x, y) {
-        return this._internals.toFormXObjects(await this._internals.findFormXObjects(models_1.Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectFormsAt(x, y, tolerance = 0) {
+        return this._internals.toFormXObjects(await this._internals.findFormXObjects(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
     }
     async selectFormFields() {
         return this._internals.toFormFields(await this._internals.findFormFields(models_1.Position.atPage(this._pageIndex)));
     }
-    async selectFormFieldsAt(x, y) {
-        return this._internals.toFormFields(await this._internals.findFormFields(models_1.Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectFormFieldsAt(x, y, tolerance = 0) {
+        return this._internals.toFormFields(await this._internals.findFormFields(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
     }
     // noinspection JSUnusedGlobalSymbols
     async selectFormFieldsByName(fieldName) {
@@ -74,6 +161,10 @@ class PageClient {
     async selectParagraphs() {
         return this._internals.toParagraphObjects(await this._internals.findParagraphs(models_1.Position.atPage(this._pageIndex)));
     }
+    async selectElements(types) {
+        const snapshot = await this._client.getPageSnapshot(this._pageIndex, types);
+        return snapshot.elements;
+    }
     async selectParagraphsStartingWith(text) {
         let pos = models_1.Position.atPage(this._pageIndex);
         pos.textStartsWith = text;
@@ -84,8 +175,8 @@ class PageClient {
         pos.textPattern = pattern;
         return this._internals.toParagraphObjects(await this._internals.findParagraphs(pos));
     }
-    async selectParagraphsAt(x, y) {
-        return this._internals.toParagraphObjects(await this._internals.findParagraphs(models_1.Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectParagraphsAt(x, y, tolerance = DEFAULT_TOLERANCE) {
+        return this._internals.toParagraphObjects(await this._internals.findParagraphs(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
     }
     async selectTextLinesStartingWith(text) {
         let pos = models_1.Position.atPage(this._pageIndex);
@@ -95,8 +186,13 @@ class PageClient {
     /**
      * Creates a new ParagraphBuilder for fluent paragraph construction.
      */
-    newParagraph() {
-        return new paragraph_builder_1.ParagraphBuilder(this._client, this.position.pageIndex);
+    newParagraph(pageIndex) {
+        const targetIndex = pageIndex ?? this.position.pageIndex;
+        return new paragraph_builder_1.ParagraphBuilder(this._client, targetIndex);
+    }
+    newImage(pageIndex) {
+        const targetIndex = pageIndex ?? this.position.pageIndex;
+        return new image_builder_1.ImageBuilder(this._client, targetIndex);
     }
     async selectTextLines() {
         return this._internals.toTextLineObjects(await this._internals.findTextLines(models_1.Position.atPage(this._pageIndex)));
@@ -108,8 +204,15 @@ class PageClient {
         return this._internals.toTextLineObjects(await this._internals.findTextLines(pos));
     }
     // noinspection JSUnusedGlobalSymbols
-    async selectTextLinesAt(x, y) {
-        return this._internals.toTextLineObjects(await this._internals.findTextLines(models_1.Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectTextLinesAt(x, y, tolerance = DEFAULT_TOLERANCE) {
+        return this._internals.toTextLineObjects(await this._internals.findTextLines(models_1.Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
+    }
+    /**
+     * Gets a snapshot of this page, including all elements.
+     * Optionally filter by object types.
+     */
+    async getSnapshot(types) {
+        return this._client.getPageSnapshot(this._pageIndex, types);
     }
 }
 // noinspection ExceptionCaughtLocallyJS,JSUnusedLocalSymbols
@@ -126,15 +229,34 @@ class PDFDancer {
      * This constructor initializes the client, uploads the PDF data to open
      * a new session, and prepares the client for PDF manipulation operations.
      */
-    constructor(token, pdfData, baseUrl = "http://localhost:8080", readTimeout = 30000) {
+    constructor(token, pdfData, baseUrl = null, readTimeout = 30000) {
+        // Snapshot caches for optimizing find operations
+        this._documentSnapshotCache = null;
+        this._pageSnapshotCache = new Map();
+        this._pagesCache = null;
         if (!token || !token.trim()) {
             throw new exceptions_1.ValidationException("Authentication token cannot be null or empty");
         }
+        // Normalize baseUrl
+        const resolvedBaseUrl = (baseUrl && baseUrl.trim()) ||
+            process.env.PDFDANCER_BASE_URL ||
+            "https://api.pdfdancer.com";
+        // Basic validation — ensures it's a valid absolute URL
+        try {
+            new URL(resolvedBaseUrl);
+        }
+        catch {
+            throw new exceptions_1.ValidationException(`Invalid base URL: ${resolvedBaseUrl}`);
+        }
         this._token = token.trim();
-        this._baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
+        this._baseUrl = resolvedBaseUrl.replace(/\/$/, ''); // Remove trailing slash
         this._readTimeout = readTimeout;
         // Process PDF data with validation
         this._pdfBytes = this._processPdfData(pdfData);
+        // Initialize caches
+        this._documentSnapshotCache = null;
+        this._pageSnapshotCache = new Map();
+        this._pagesCache = null;
     }
     /**
      * Initialize the client by creating a session.
@@ -151,7 +273,7 @@ class PDFDancer {
             "https://api.pdfdancer.com";
         const resolvedTimeout = timeout ?? 30000;
         if (!resolvedToken) {
-            throw new Error("Missing PDFDancer token (pass it explicitly or set PDFDANCER_TOKEN in environment).");
+            throw new exceptions_1.ValidationException("Missing PDFDancer API token. Pass a token via the `token` argument or set the PDFDANCER_TOKEN environment variable.");
         }
         const client = new PDFDancer(resolvedToken, pdfData, resolvedBaseUrl, resolvedTimeout);
         return await client.init();
@@ -174,7 +296,7 @@ class PDFDancer {
             "https://api.pdfdancer.com";
         const resolvedTimeout = timeout ?? 30000;
         if (!resolvedToken) {
-            throw new Error("Missing PDFDancer token (pass it explicitly or set PDFDANCER_TOKEN in environment).");
+            throw new exceptions_1.ValidationException("Missing PDFDancer token (pass it explicitly or set PDFDANCER_TOKEN in environment).");
         }
         let createRequest;
         try {
@@ -189,16 +311,21 @@ class PDFDancer {
             const base = resolvedBaseUrl.replace(/\/+$/, '');
             const endpoint = '/session/new'.replace(/^\/+/, '');
             const url = `${base}/${endpoint}`;
+            // Generate fingerprint for this request
+            const fingerprint = await (0, fingerprint_1.generateFingerprint)();
             // Make request to create endpoint
             const response = await fetch(url, {
                 method: 'POST',
                 headers: {
                     'Authorization': `Bearer ${resolvedToken}`,
-                    'Content-Type': 'application/json'
+                    'Content-Type': 'application/json',
+                    'X-Generated-At': generateTimestamp(),
+                    'X-Fingerprint': fingerprint
                 },
                 body: JSON.stringify(createRequest.toDict()),
                 signal: resolvedTimeout > 0 ? AbortSignal.timeout(resolvedTimeout) : undefined
             });
+            logGeneratedAtHeader(response, 'POST', '/session/new');
             if (!response.ok) {
                 const errorText = await response.text();
                 throw new exceptions_1.HttpClientException(`Failed to create new PDF: ${errorText}`, response);
@@ -213,6 +340,10 @@ class PDFDancer {
             client._readTimeout = resolvedTimeout;
             client._pdfBytes = new Uint8Array();
             client._sessionId = sessionId;
+            // Initialize caches
+            client._documentSnapshotCache = null;
+            client._pageSnapshotCache = new Map();
+            client._pagesCache = null;
             return client;
         }
         catch (error) {
@@ -321,16 +452,28 @@ class PDFDancer {
                 const blob = new Blob([this._pdfBytes.buffer], { type: 'application/pdf' });
                 formData.append('pdf', blob, 'document.pdf');
             }
+            const fingerprint = await this._getFingerprint();
             const response = await fetch(this._buildUrl('/session/create'), {
                 method: 'POST',
                 headers: {
-                    'Authorization': `Bearer ${this._token}`
+                    'Authorization': `Bearer ${this._token}`,
+                    'X-Generated-At': generateTimestamp(),
+                    'X-Fingerprint': fingerprint
                 },
                 body: formData,
                 signal: this._readTimeout > 0 ? AbortSignal.timeout(this._readTimeout) : undefined
             });
+            logGeneratedAtHeader(response, 'POST', '/session/create');
             if (!response.ok) {
                 const errorMessage = await this._extractErrorMessage(response);
+                if (response.status === 401 || response.status === 403) {
+                    const defaultMessage = "Authentication with the PDFDancer API failed. Confirm that your API token is valid, has not expired, and is authorized for the requested environment.";
+                    const normalized = errorMessage?.trim() ?? "";
+                    const message = normalized && normalized !== "Unauthorized" && normalized !== "Forbidden"
+                        ? normalized
+                        : defaultMessage;
+                    throw new exceptions_1.ValidationException(message);
+                }
                 throw new exceptions_1.HttpClientException(`Failed to create session: ${errorMessage}`, response);
             }
             const sessionId = (await response.text()).trim();
@@ -340,13 +483,22 @@ class PDFDancer {
             return sessionId;
         }
         catch (error) {
-            if (error instanceof exceptions_1.HttpClientException || error instanceof exceptions_1.SessionException) {
+            if (error instanceof exceptions_1.HttpClientException || error instanceof exceptions_1.SessionException || error instanceof exceptions_1.ValidationException) {
                 throw error;
             }
             const errorMessage = error instanceof Error ? error.message : String(error);
             throw new exceptions_1.HttpClientException(`Failed to create session: ${errorMessage}`, undefined, error);
         }
     }
+    /**
+     * Get or generate the fingerprint for this client
+     */
+    async _getFingerprint() {
+        if (!this._fingerprintCache) {
+            this._fingerprintCache = await (0, fingerprint_1.generateFingerprint)(this._userId);
+        }
+        return this._fingerprintCache;
+    }
     /**
      * Make HTTP request with session headers and error handling.
      */
@@ -357,10 +509,13 @@ class PDFDancer {
                 url.searchParams.append(key, value);
             });
         }
+        const fingerprint = await this._getFingerprint();
         const headers = {
             'Authorization': `Bearer ${this._token}`,
             'X-Session-Id': this._sessionId,
-            'Content-Type': 'application/json'
+            'Content-Type': 'application/json',
+            'X-Generated-At': generateTimestamp(),
+            'X-Fingerprint': fingerprint
         };
         try {
             const response = await fetch(url.toString(), {
@@ -369,6 +524,7 @@ class PDFDancer {
                 body: data ? JSON.stringify(data) : undefined,
                 signal: this._readTimeout > 0 ? AbortSignal.timeout(this._readTimeout) : undefined
             });
+            logGeneratedAtHeader(response, method, path);
             // Handle FontNotFoundException
             if (response.status === 404) {
                 try {
@@ -403,12 +559,39 @@ class PDFDancer {
      * Searches for PDF objects matching the specified criteria.
      * This method provides flexible search capabilities across all PDF content,
      * allowing filtering by object type and position constraints.
+     *
+     * Now uses snapshot caching for better performance.
      */
     async find(objectType, position) {
-        const requestData = new models_1.FindRequest(objectType, position).toDict();
-        const response = await this._makeRequest('POST', '/pdf/find', requestData);
-        const objectsData = await response.json();
-        return objectsData.map((objData) => this._parseObjectRef(objData));
+        // Determine if we should use snapshot or fall back to HTTP
+        // For paths with coordinates, we need to use HTTP (backend requirement)
+        const isPathWithCoordinates = objectType === models_1.ObjectType.PATH &&
+            position?.shape === models_1.ShapeType.POINT;
+        if (isPathWithCoordinates) {
+            // Fall back to HTTP for path coordinate queries
+            const requestData = new models_1.FindRequest(objectType, position).toDict();
+            const response = await this._makeRequest('POST', '/pdf/find', requestData);
+            const objectsData = await response.json();
+            return objectsData.map((objData) => this._parseObjectRef(objData));
+        }
+        // Use snapshot-based search
+        let elements;
+        if (position?.pageIndex !== undefined) {
+            // Page-specific query - use page snapshot
+            const pageSnapshot = await this._getOrFetchPageSnapshot(position.pageIndex);
+            elements = pageSnapshot.elements;
+        }
+        else {
+            // Document-wide query - use document snapshot
+            const docSnapshot = await this._getOrFetchDocumentSnapshot();
+            elements = docSnapshot.getAllElements();
+        }
+        // Filter by object type
+        if (objectType) {
+            elements = elements.filter(el => el.type === objectType);
+        }
+        // Apply position-based filtering
+        return this._filterByPosition(elements, position);
     }
     /**
      * Searches for paragraph objects at the specified position.
@@ -458,36 +641,76 @@ class PDFDancer {
     /**
      * Searches for form fields at the specified position.
      * Returns FormFieldRef objects with name and value properties.
+     *
+     * Now uses snapshot caching for better performance.
      */
     async findFormFields(position) {
-        const requestData = new models_1.FindRequest(models_1.ObjectType.FORM_FIELD, position).toDict();
-        const response = await this._makeRequest('POST', '/pdf/find', requestData);
-        const objectsData = await response.json();
-        return objectsData.map((objData) => this._parseFormFieldRef(objData));
+        // Use snapshot-based search
+        let elements;
+        if (position?.pageIndex !== undefined) {
+            // Page-specific query - use page snapshot
+            const pageSnapshot = await this._getOrFetchPageSnapshot(position.pageIndex);
+            elements = pageSnapshot.elements;
+        }
+        else {
+            // Document-wide query - use document snapshot
+            const docSnapshot = await this._getOrFetchDocumentSnapshot();
+            elements = docSnapshot.getAllElements();
+        }
+        // Filter by form field types (FORM_FIELD, TEXT_FIELD, CHECKBOX, RADIO_BUTTON)
+        const formFieldTypes = [
+            models_1.ObjectType.FORM_FIELD,
+            models_1.ObjectType.TEXT_FIELD,
+            models_1.ObjectType.CHECKBOX,
+            models_1.ObjectType.RADIO_BUTTON
+        ];
+        const formFields = elements.filter(el => formFieldTypes.includes(el.type));
+        // Apply position-based filtering
+        return this._filterFormFieldsByPosition(formFields, position);
     }
     // Page Operations
     /**
      * Retrieves references to all pages in the PDF document.
+     * Now uses snapshot caching to avoid HTTP requests.
      */
     async getPages() {
-        const response = await this._makeRequest('POST', '/pdf/page/find');
-        const pagesData = await response.json();
-        return pagesData.map((pageData) => this._parsePageRef(pageData));
+        // Check if we have cached pages
+        if (this._pagesCache) {
+            return this._pagesCache;
+        }
+        // Try to get from document snapshot cache first
+        if (this._documentSnapshotCache) {
+            this._pagesCache = this._documentSnapshotCache.pages.map(p => p.pageRef);
+            return this._pagesCache;
+        }
+        // Fetch document snapshot to get pages (this will cache it)
+        const docSnapshot = await this._getOrFetchDocumentSnapshot();
+        this._pagesCache = docSnapshot.pages.map(p => p.pageRef);
+        return this._pagesCache;
     }
     /**
      * Retrieves a reference to a specific page by its page index.
+     * Now uses snapshot caching to avoid HTTP requests.
      */
     async _getPage(pageIndex) {
         if (pageIndex < 0) {
             throw new exceptions_1.ValidationException(`Page index must be >= 0, got ${pageIndex}`);
         }
-        const params = { pageIndex: pageIndex.toString() };
-        const response = await this._makeRequest('POST', '/pdf/page/find', undefined, params);
-        const pagesData = await response.json();
-        if (!pagesData || pagesData.length === 0) {
-            return null;
+        // Try page snapshot cache first
+        if (this._pageSnapshotCache.has(pageIndex)) {
+            return this._pageSnapshotCache.get(pageIndex).pageRef;
+        }
+        // Try document snapshot cache
+        if (this._documentSnapshotCache) {
+            const pageSnapshot = this._documentSnapshotCache.getPageSnapshot(pageIndex);
+            if (pageSnapshot) {
+                return pageSnapshot.pageRef;
+            }
         }
-        return this._parsePageRef(pagesData[0]);
+        // Fetch document snapshot to get page (this will cache it)
+        const docSnapshot = await this._getOrFetchDocumentSnapshot();
+        const pageSnapshot = docSnapshot.getPageSnapshot(pageIndex);
+        return pageSnapshot?.pageRef ?? null;
     }
     /**
      * Moves an existing page to a new index.
@@ -503,6 +726,8 @@ class PDFDancer {
         if (!success) {
             throw new exceptions_1.HttpClientException(`Failed to move page from ${pageIndex} to ${targetPageIndex}`, response);
         }
+        // Invalidate cache after mutation
+        this._invalidateCache();
         // Fetch the page again at its new position for up-to-date metadata
         return await this._requirePageRef(targetPageIndex);
     }
@@ -512,7 +737,10 @@ class PDFDancer {
     async deletePage(pageIndex) {
         this._validatePageIndex(pageIndex, 'pageIndex');
         const pageRef = await this._requirePageRef(pageIndex);
-        return this._deletePage(pageRef);
+        const result = await this._deletePage(pageRef);
+        // Invalidate cache after mutation
+        this._invalidateCache();
+        return result;
     }
     _validatePageIndex(pageIndex, fieldName) {
         if (!Number.isInteger(pageIndex)) {
@@ -540,6 +768,164 @@ class PDFDancer {
         const response = await this._makeRequest('DELETE', '/pdf/page/delete', requestData);
         return await response.json();
     }
+    // Snapshot Operations
+    /**
+     * Gets a snapshot of the entire PDF document.
+     * Returns page count, fonts, and snapshots of all pages with their elements.
+     *
+     * @param types Optional array of ObjectType to filter elements by type
+     * @returns DocumentSnapshot containing all document information
+     */
+    async getDocumentSnapshot(types) {
+        const params = {};
+        if (types && types.length > 0) {
+            params.types = types.join(',');
+        }
+        const response = await this._makeRequest('GET', '/pdf/document/snapshot', undefined, params);
+        const data = await response.json();
+        return this._parseDocumentSnapshot(data);
+    }
+    /**
+     * Gets a snapshot of a specific page.
+     * Returns the page reference and all elements on that page.
+     *
+     * @param pageIndex Zero-based page index
+     * @param types Optional array of ObjectType to filter elements by type
+     * @returns PageSnapshot containing page information and elements
+     */
+    async getPageSnapshot(pageIndex, types) {
+        this._validatePageIndex(pageIndex, 'pageIndex');
+        const params = {};
+        if (types && types.length > 0) {
+            params.types = types.join(',');
+        }
+        const response = await this._makeRequest('GET', `/pdf/page/${pageIndex}/snapshot`, undefined, params);
+        const data = await response.json();
+        return this._parsePageSnapshot(data);
+    }
+    // Cache Management
+    /**
+     * Gets a page snapshot from cache or fetches it.
+     * First checks page cache, then document cache, then fetches from server.
+     */
+    async _getOrFetchPageSnapshot(pageIndex) {
+        // Check page cache first
+        if (this._pageSnapshotCache.has(pageIndex)) {
+            return this._pageSnapshotCache.get(pageIndex);
+        }
+        // Check if we have document snapshot and can extract the page
+        if (this._documentSnapshotCache) {
+            const pageSnapshot = this._documentSnapshotCache.getPageSnapshot(pageIndex);
+            if (pageSnapshot) {
+                // Cache it for future use
+                this._pageSnapshotCache.set(pageIndex, pageSnapshot);
+                return pageSnapshot;
+            }
+        }
+        // Fetch page snapshot from server
+        const pageSnapshot = await this.getPageSnapshot(pageIndex);
+        this._pageSnapshotCache.set(pageIndex, pageSnapshot);
+        return pageSnapshot;
+    }
+    /**
+     * Gets the document snapshot from cache or fetches it.
+     */
+    async _getOrFetchDocumentSnapshot() {
+        if (!this._documentSnapshotCache) {
+            this._documentSnapshotCache = await this.getDocumentSnapshot();
+        }
+        return this._documentSnapshotCache;
+    }
+    /**
+     * Invalidates all snapshot caches.
+     * Called after any mutation operation.
+     */
+    _invalidateCache() {
+        this._documentSnapshotCache = null;
+        this._pageSnapshotCache.clear();
+        this._pagesCache = null;
+    }
+    /**
+     * Filters snapshot elements by Position criteria.
+     * Handles coordinates, text matching, and field name filtering.
+     */
+    _filterByPosition(elements, position) {
+        if (!position) {
+            return elements;
+        }
+        let filtered = elements;
+        // Filter by page index
+        if (position.pageIndex !== undefined) {
+            filtered = filtered.filter(el => el.position.pageIndex === position.pageIndex);
+        }
+        // Filter by coordinates (point containment with tolerance)
+        if (position.boundingRect && position.shape === models_1.ShapeType.POINT) {
+            const x = position.boundingRect.x;
+            const y = position.boundingRect.y;
+            const tolerance = position.tolerance || 0;
+            filtered = filtered.filter(el => {
+                const rect = el.position.boundingRect;
+                if (!rect)
+                    return false;
+                return x >= rect.x - tolerance && x <= rect.x + rect.width + tolerance &&
+                    y >= rect.y - tolerance && y <= rect.y + rect.height + tolerance;
+            });
+        }
+        // Filter by text starts with
+        if (position.textStartsWith && filtered.length > 0) {
+            const textLower = position.textStartsWith.toLowerCase();
+            filtered = filtered.filter(el => {
+                const textObj = el;
+                return textObj.text && textObj.text.toLowerCase().startsWith(textLower);
+            });
+        }
+        // Filter by text pattern (regex)
+        if (position.textPattern && filtered.length > 0) {
+            const regex = this._compileTextPattern(position.textPattern);
+            filtered = filtered.filter(el => {
+                const textObj = el;
+                return textObj.text && regex.test(textObj.text);
+            });
+        }
+        // Filter by name (for form fields)
+        if (position.name && filtered.length > 0) {
+            filtered = filtered.filter(el => {
+                const formField = el;
+                return formField.name === position.name;
+            });
+        }
+        return filtered;
+    }
+    /**
+     * Filters FormFieldRef elements by Position criteria.
+     */
+    _filterFormFieldsByPosition(elements, position) {
+        return this._filterByPosition(elements, position);
+    }
+    _compileTextPattern(pattern) {
+        try {
+            return new RegExp(pattern);
+        }
+        catch {
+            const inlineMatch = pattern.match(/^\(\?([a-z]+)\)/i);
+            if (inlineMatch) {
+                const supportedFlags = inlineMatch[1]
+                    .toLowerCase()
+                    .split('')
+                    .filter(flag => 'gimsuy'.includes(flag));
+                const flags = Array.from(new Set(supportedFlags)).join('');
+                const source = pattern.slice(inlineMatch[0].length);
+                try {
+                    return new RegExp(source, flags);
+                }
+                catch {
+                    // fall through to literal fallback
+                }
+            }
+            const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            return new RegExp(escaped);
+        }
+    }
     // Manipulation Operations
     /**
      * Deletes the specified PDF object from the document.
@@ -550,7 +936,10 @@ class PDFDancer {
         }
         const requestData = new models_1.DeleteRequest(objectRef).toDict();
         const response = await this._makeRequest('DELETE', '/pdf/delete', requestData);
-        return await response.json();
+        const result = await response.json();
+        // Invalidate cache after mutation
+        this._invalidateCache();
+        return result;
     }
     /**
      * Moves a PDF object to a new position within the document.
@@ -564,7 +953,10 @@ class PDFDancer {
         }
         const requestData = new models_1.MoveRequest(objectRef, position).toDict();
         const response = await this._makeRequest('PUT', '/pdf/move', requestData);
-        return await response.json();
+        const result = await response.json();
+        // Invalidate cache after mutation
+        this._invalidateCache();
+        return result;
     }
     /**
      * Changes the value of a form field.
@@ -575,7 +967,10 @@ class PDFDancer {
         }
         const requestData = new models_1.ChangeFormFieldRequest(formFieldRef, newValue).toDict();
         const response = await this._makeRequest('PUT', '/pdf/modify/formField', requestData);
-        return await response.json();
+        const result = await response.json();
+        // Invalidate cache after mutation
+        this._invalidateCache();
+        return result;
     }
     // Add Operations
     /**
@@ -611,13 +1006,28 @@ class PDFDancer {
         }
         return this._addObject(paragraph);
     }
+    /**
+     * Adds a page to the PDF document.
+     */
+    async addPage(request) {
+        const payload = request ? request.toDict() : {};
+        const data = Object.keys(payload).length > 0 ? payload : undefined;
+        const response = await this._makeRequest('POST', '/pdf/page/add', data);
+        const result = await response.json();
+        const pageRef = this._parsePageRef(result);
+        this._invalidateCache();
+        return pageRef;
+    }
     /**
      * Internal method to add any PDF object.
      */
     async _addObject(pdfObject) {
         const requestData = new models_1.AddRequest(pdfObject).toDict();
         const response = await this._makeRequest('POST', '/pdf/add', requestData);
-        return await response.json();
+        const result = await response.json();
+        // Invalidate cache after mutation
+        this._invalidateCache();
+        return result;
     }
     // Modify Operations
     /**
@@ -630,18 +1040,22 @@ class PDFDancer {
         if (newParagraph === null || newParagraph === undefined) {
             return models_1.CommandResult.empty("ModifyParagraph", objectRef.internalId);
         }
+        let result;
         if (typeof newParagraph === 'string') {
             // Text modification - returns CommandResult
             const requestData = new models_1.ModifyTextRequest(objectRef, newParagraph).toDict();
             const response = await this._makeRequest('PUT', '/pdf/text/paragraph', requestData);
-            return models_1.CommandResult.fromDict(await response.json());
+            result = models_1.CommandResult.fromDict(await response.json());
         }
         else {
             // Object modification
             const requestData = new models_1.ModifyRequest(objectRef, newParagraph).toDict();
             const response = await this._makeRequest('PUT', '/pdf/modify', requestData);
-            return models_1.CommandResult.fromDict(await response.json());
+            result = models_1.CommandResult.fromDict(await response.json());
         }
+        // Invalidate cache after mutation
+        this._invalidateCache();
+        return result;
     }
     /**
      * Modifies a text line object.
@@ -655,7 +1069,10 @@ class PDFDancer {
         }
         const requestData = new models_1.ModifyTextRequest(objectRef, newText).toDict();
         const response = await this._makeRequest('PUT', '/pdf/text/line', requestData);
-        return models_1.CommandResult.fromDict(await response.json());
+        const result = models_1.CommandResult.fromDict(await response.json());
+        // Invalidate cache after mutation
+        this._invalidateCache();
+        return result;
     }
     // Font Operations
     /**
@@ -711,15 +1128,19 @@ class PDFDancer {
             const formData = new FormData();
             const blob = new Blob([fontData.buffer], { type: 'font/ttf' });
             formData.append('ttfFile', blob, filename);
+            const fingerprint = await this._getFingerprint();
             const response = await fetch(this._buildUrl('/font/register'), {
                 method: 'POST',
                 headers: {
                     'Authorization': `Bearer ${this._token}`,
-                    'X-Session-Id': this._sessionId
+                    'X-Session-Id': this._sessionId,
+                    'X-Generated-At': generateTimestamp(),
+                    'X-Fingerprint': fingerprint
                 },
                 body: formData,
                 signal: AbortSignal.timeout(30000)
             });
+            logGeneratedAtHeader(response, 'POST', '/font/register');
             if (!response.ok) {
                 const errorMessage = await this._extractErrorMessage(response);
                 throw new exceptions_1.HttpClientException(`Font registration failed: ${errorMessage}`, response);
@@ -773,11 +1194,22 @@ class PDFDancer {
         if (this._isTextObjectData(objData, objectType)) {
             return this._parseTextObjectRef(objData);
         }
+        // Check if this is a form field type
+        const formFieldTypes = [
+            models_1.ObjectType.FORM_FIELD,
+            models_1.ObjectType.TEXT_FIELD,
+            models_1.ObjectType.CHECKBOX,
+            models_1.ObjectType.RADIO_BUTTON
+        ];
+        if (formFieldTypes.includes(objectType)) {
+            return this._parseFormFieldRef(objData);
+        }
         return new models_1.ObjectRef(objData.internalId, position, objectType);
     }
     _isTextObjectData(objData, objectType) {
         return objectType === models_1.ObjectType.PARAGRAPH ||
             objectType === models_1.ObjectType.TEXT_LINE ||
+            objectType === models_1.ObjectType.TEXT_ELEMENT ||
             typeof objData.text === 'string' ||
             typeof objData.fontName === 'string' ||
             Array.isArray(objData.children);
@@ -806,10 +1238,16 @@ class PDFDancer {
         }
         const textObject = new models_1.TextObjectRef(internalId, position, objectType, typeof objData.text === 'string' ? objData.text : undefined, typeof objData.fontName === 'string' ? objData.fontName : undefined, typeof objData.fontSize === 'number' ? objData.fontSize : undefined, lineSpacings, undefined, this._parseColor(objData.color), status);
         if (Array.isArray(objData.children) && objData.children.length > 0) {
-            textObject.children = objData.children.map((childData, index) => {
-                const childFallbackId = `${internalId || 'child'}-${index}`;
-                return this._parseTextObjectRef(childData, childFallbackId);
-            });
+            try {
+                textObject.children = objData.children.map((childData, index) => {
+                    const childFallbackId = `${internalId || 'child'}-${index}`;
+                    return this._parseTextObjectRef(childData, childFallbackId);
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`Failed to parse children of ${internalId}: ${message}`);
+            }
         }
         return textObject;
     }
@@ -887,6 +1325,47 @@ class PDFDancer {
         }
         return position;
     }
+    /**
+     * Parse JSON data into DocumentSnapshot instance.
+     */
+    _parseDocumentSnapshot(data) {
+        const pageCount = typeof data.pageCount === 'number' ? data.pageCount : 0;
+        // Parse fonts
+        const fonts = [];
+        if (Array.isArray(data.fonts)) {
+            for (const fontData of data.fonts) {
+                if (fontData && typeof fontData === 'object') {
+                    const fontName = fontData.fontName || '';
+                    const fontType = fontData.fontType || models_1.FontType.SYSTEM;
+                    const similarityScore = typeof fontData.similarityScore === 'number' ? fontData.similarityScore : 0;
+                    fonts.push(new models_1.FontRecommendation(fontName, fontType, similarityScore));
+                }
+            }
+        }
+        // Parse pages
+        const pages = [];
+        if (Array.isArray(data.pages)) {
+            for (const pageData of data.pages) {
+                pages.push(this._parsePageSnapshot(pageData));
+            }
+        }
+        return new models_1.DocumentSnapshot(pageCount, fonts, pages);
+    }
+    /**
+     * Parse JSON data into PageSnapshot instance.
+     */
+    _parsePageSnapshot(data) {
+        // Parse page reference
+        const pageRef = this._parsePageRef(data.pageRef || {});
+        // Parse elements
+        const elements = [];
+        if (Array.isArray(data.elements)) {
+            for (const elementData of data.elements) {
+                elements.push(this._parseObjectRef(elementData));
+            }
+        }
+        return new models_1.PageSnapshot(pageRef, elements);
+    }
     // Builder Pattern Support
     toPathObjects(objectRefs) {
         return objectRefs.map(ref => types_1.PathObject.fromRef(this, ref));
@@ -897,8 +1376,14 @@ class PDFDancer {
     toImageObjects(objectRefs) {
         return objectRefs.map(ref => types_1.ImageObject.fromRef(this, ref));
     }
-    newImage() {
-        return new image_builder_1.ImageBuilder(this);
+    newImage(pageIndex) {
+        return new image_builder_1.ImageBuilder(this, pageIndex);
+    }
+    newParagraph(pageIndex) {
+        return new paragraph_builder_1.ParagraphBuilder(this, pageIndex);
+    }
+    newPage() {
+        return new page_builder_1.PageBuilder(this);
     }
     page(pageIndex) {
         if (pageIndex < 0) {
@@ -913,18 +1398,37 @@ class PDFDancer {
     toFormFields(objectRefs) {
         return objectRefs.map(ref => types_1.FormFieldObject.fromRef(this, ref));
     }
+    async selectElements(types) {
+        const snapshot = await this.getDocumentSnapshot(types);
+        const elements = [];
+        for (const pageSnapshot of snapshot.pages) {
+            elements.push(...pageSnapshot.elements);
+        }
+        return elements;
+    }
     async selectParagraphs() {
         return this.toParagraphObjects(await this.findParagraphs());
     }
+    async selectParagraphsMatching(pattern) {
+        if (!pattern) {
+            throw new exceptions_1.ValidationException('Pattern cannot be empty');
+        }
+        const position = new models_1.Position();
+        position.textPattern = pattern;
+        return this.toParagraphObjects(await this.findParagraphs(position));
+    }
     toParagraphObjects(objectRefs) {
         return objectRefs.map(ref => types_1.ParagraphObject.fromRef(this, ref));
     }
     toTextLineObjects(objectRefs) {
         return objectRefs.map(ref => types_1.TextLineObject.fromRef(this, ref));
     }
-    async selectLines() {
+    async selectTextLines() {
         return this.toTextLineObjects(await this.findTextLines());
     }
+    async selectLines() {
+        return this.selectTextLines();
+    }
 }
 exports.PDFDancer = PDFDancer;
 //# sourceMappingURL=pdfdancer_v1.js.map