pdfdancer-client-typescript 1.0.13 → 1.0.15

package/dist/pdfdancer_v1.js

@@ -23,6 +23,93 @@ const DEFAULT_TOLERANCE = 0.01;
 const DEBUG = (process.env.PDFDANCER_CLIENT_DEBUG ?? '').toLowerCase() === 'true' ||
     (process.env.PDFDANCER_CLIENT_DEBUG ?? '') === '1' ||
     (process.env.PDFDANCER_CLIENT_DEBUG ?? '').toLowerCase() === 'yes';
+/**
+ * Default retry configuration
+ */
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    initialDelay: 1000,
+    maxDelay: 10000,
+    retryableStatusCodes: [429, 500, 502, 503, 504],
+    retryOnNetworkError: true,
+    backoffMultiplier: 2,
+    useJitter: true
+};
+/**
+ * Static helper function for retry logic with exponential backoff.
+ * Used by static methods that don't have access to instance retry config.
+ */
+async function fetchWithRetry(url, 
+// eslint-disable-next-line no-undef
+options, retryConfig, context = 'request') {
+    let lastError = null;
+    let lastResponse = null;
+    for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
+        try {
+            const response = await fetch(url, options);
+            // Check if we should retry based on status code
+            if (!response.ok && retryConfig.retryableStatusCodes.includes(response.status)) {
+                lastResponse = response;
+                // If this is not the last attempt, wait and retry
+                if (attempt < retryConfig.maxRetries) {
+                    const delay = calculateRetryDelay(attempt, retryConfig);
+                    if (DEBUG) {
+                        console.log(`${Date.now() / 1000}|Retry attempt ${attempt + 1}/${retryConfig.maxRetries} for ${context} after ${delay}ms (status: ${response.status})`);
+                    }
+                    await sleep(delay);
+                    continue;
+                }
+            }
+            // Request succeeded or non-retryable error
+            return response;
+        }
+        catch (error) {
+            lastError = error;
+            // Check if this is a network error and we should retry
+            if (retryConfig.retryOnNetworkError && attempt < retryConfig.maxRetries) {
+                const delay = calculateRetryDelay(attempt, retryConfig);
+                if (DEBUG) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    console.log(`${Date.now() / 1000}|Retry attempt ${attempt + 1}/${retryConfig.maxRetries} for ${context} after ${delay}ms (error: ${errorMessage})`);
+                }
+                await sleep(delay);
+                continue;
+            }
+            // Non-retryable error or last attempt
+            throw error;
+        }
+    }
+    // If we exhausted all retries due to retryable status codes, return the last response
+    if (lastResponse) {
+        return lastResponse;
+    }
+    // If we exhausted all retries due to network errors, throw the last error
+    if (lastError) {
+        throw lastError;
+    }
+    // This should never happen, but just in case
+    throw new Error('Unexpected retry exhaustion');
+}
+/**
+ * Calculates the delay for the next retry attempt using exponential backoff.
+ */
+function calculateRetryDelay(attemptNumber, retryConfig) {
+    // Calculate base delay: initialDelay * (backoffMultiplier ^ attemptNumber)
+    let delay = retryConfig.initialDelay * Math.pow(retryConfig.backoffMultiplier, attemptNumber);
+    // Cap at maxDelay
+    delay = Math.min(delay, retryConfig.maxDelay);
+    // Add jitter if enabled (randomize between 50% and 100% of calculated delay)
+    if (retryConfig.useJitter) {
+        delay = delay * (0.5 + Math.random() * 0.5);
+    }
+    return Math.floor(delay);
+}
+/**
+ * Sleep for the specified number of milliseconds.
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
 /**
  * Generate a timestamp string in the format expected by the API.
  * Format: YYYY-MM-DDTHH:MM:SS.ffffffZ (with microseconds)
@@ -214,6 +301,75 @@ class PageClient {
     async getSnapshot(types) {
         return this._client.getPageSnapshot(this._pageIndex, types);
     }
+    // Singular convenience methods - return the first element or null
+    async selectPath() {
+        const paths = await this.selectPaths();
+        return paths.length > 0 ? paths[0] : null;
+    }
+    async selectPathAt(x, y, tolerance = 0) {
+        const paths = await this.selectPathsAt(x, y, tolerance);
+        return paths.length > 0 ? paths[0] : null;
+    }
+    async selectImage() {
+        const images = await this.selectImages();
+        return images.length > 0 ? images[0] : null;
+    }
+    async selectImageAt(x, y, tolerance = 0) {
+        const images = await this.selectImagesAt(x, y, tolerance);
+        return images.length > 0 ? images[0] : null;
+    }
+    async selectForm() {
+        const forms = await this.selectForms();
+        return forms.length > 0 ? forms[0] : null;
+    }
+    async selectFormAt(x, y, tolerance = 0) {
+        const forms = await this.selectFormsAt(x, y, tolerance);
+        return forms.length > 0 ? forms[0] : null;
+    }
+    async selectFormField() {
+        const fields = await this.selectFormFields();
+        return fields.length > 0 ? fields[0] : null;
+    }
+    async selectFormFieldAt(x, y, tolerance = 0) {
+        const fields = await this.selectFormFieldsAt(x, y, tolerance);
+        return fields.length > 0 ? fields[0] : null;
+    }
+    async selectFormFieldByName(fieldName) {
+        const fields = await this.selectFormFieldsByName(fieldName);
+        return fields.length > 0 ? fields[0] : null;
+    }
+    async selectParagraph() {
+        const paragraphs = await this.selectParagraphs();
+        return paragraphs.length > 0 ? paragraphs[0] : null;
+    }
+    async selectParagraphStartingWith(text) {
+        const paragraphs = await this.selectParagraphsStartingWith(text);
+        return paragraphs.length > 0 ? paragraphs[0] : null;
+    }
+    async selectParagraphMatching(pattern) {
+        const paragraphs = await this.selectParagraphsMatching(pattern);
+        return paragraphs.length > 0 ? paragraphs[0] : null;
+    }
+    async selectParagraphAt(x, y, tolerance = DEFAULT_TOLERANCE) {
+        const paragraphs = await this.selectParagraphsAt(x, y, tolerance);
+        return paragraphs.length > 0 ? paragraphs[0] : null;
+    }
+    async selectTextLine() {
+        const lines = await this.selectTextLines();
+        return lines.length > 0 ? lines[0] : null;
+    }
+    async selectTextLineStartingWith(text) {
+        const lines = await this.selectTextLinesStartingWith(text);
+        return lines.length > 0 ? lines[0] : null;
+    }
+    async selectTextLineMatching(pattern) {
+        const lines = await this.selectTextLinesMatching(pattern);
+        return lines.length > 0 ? lines[0] : null;
+    }
+    async selectTextLineAt(x, y, tolerance = DEFAULT_TOLERANCE) {
+        const lines = await this.selectTextLinesAt(x, y, tolerance);
+        return lines.length > 0 ? lines[0] : null;
+    }
 }
 // noinspection ExceptionCaughtLocallyJS,JSUnusedLocalSymbols
 /**
@@ -229,7 +385,7 @@ 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 = null, readTimeout = 30000) {
+    constructor(token, pdfData, baseUrl = null, readTimeout = 60000, retryConfig) {
         // Snapshot caches for optimizing find operations
         this._documentSnapshotCache = null;
         this._pageSnapshotCache = new Map();
@@ -251,6 +407,11 @@ class PDFDancer {
         this._token = token.trim();
         this._baseUrl = resolvedBaseUrl.replace(/\/$/, ''); // Remove trailing slash
         this._readTimeout = readTimeout;
+        // Merge retry config with defaults
+        this._retryConfig = {
+            ...DEFAULT_RETRY_CONFIG,
+            ...retryConfig
+        };
         // Process PDF data with validation
         this._pdfBytes = this._processPdfData(pdfData);
         // Initialize caches
@@ -266,16 +427,16 @@ class PDFDancer {
         this._sessionId = await this._createSession();
         return this;
     }
-    static async open(pdfData, token, baseUrl, timeout) {
-        const resolvedToken = token ?? process.env.PDFDANCER_TOKEN;
+    static async open(pdfData, token, baseUrl, timeout, retryConfig) {
         const resolvedBaseUrl = baseUrl ??
             process.env.PDFDANCER_BASE_URL ??
             "https://api.pdfdancer.com";
-        const resolvedTimeout = timeout ?? 30000;
+        const resolvedTimeout = timeout ?? 60000;
+        let resolvedToken = token?.trim() ?? process.env.PDFDANCER_TOKEN?.trim() ?? null;
         if (!resolvedToken) {
-            throw new exceptions_1.ValidationException("Missing PDFDancer API token. Pass a token via the `token` argument or set the PDFDANCER_TOKEN environment variable.");
+            resolvedToken = await PDFDancer._obtainAnonymousToken(resolvedBaseUrl, resolvedTimeout);
         }
-        const client = new PDFDancer(resolvedToken, pdfData, resolvedBaseUrl, resolvedTimeout);
+        const client = new PDFDancer(resolvedToken, pdfData, resolvedBaseUrl, resolvedTimeout, retryConfig);
         return await client.init();
     }
     /**
@@ -287,16 +448,17 @@ class PDFDancer {
      * @param options.initialPageCount Number of initial pages (default: 1)
      * @param token Authentication token (optional, can use PDFDANCER_TOKEN env var)
      * @param baseUrl Base URL for the PDFDancer API (optional)
-     * @param timeout Request timeout in milliseconds (default: 30000)
+     * @param timeout Request timeout in milliseconds (default: 60000)
+     * @param retryConfig Retry configuration (optional, uses defaults if not specified)
      */
-    static async new(options, token, baseUrl, timeout) {
-        const resolvedToken = token ?? process.env.PDFDANCER_TOKEN;
+    static async new(options, token, baseUrl, timeout, retryConfig) {
         const resolvedBaseUrl = baseUrl ??
             process.env.PDFDANCER_BASE_URL ??
             "https://api.pdfdancer.com";
-        const resolvedTimeout = timeout ?? 30000;
+        const resolvedTimeout = timeout ?? 60000;
+        let resolvedToken = token?.trim() ?? process.env.PDFDANCER_TOKEN?.trim() ?? null;
         if (!resolvedToken) {
-            throw new exceptions_1.ValidationException("Missing PDFDancer token (pass it explicitly or set PDFDANCER_TOKEN in environment).");
+            resolvedToken = await PDFDancer._obtainAnonymousToken(resolvedBaseUrl, resolvedTimeout);
         }
         let createRequest;
         try {
@@ -313,8 +475,8 @@ class PDFDancer {
             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, {
+            // Make request to create endpoint with retry logic
+            const response = await fetchWithRetry(url, {
                 method: 'POST',
                 headers: {
                     'Authorization': `Bearer ${resolvedToken}`,
@@ -324,7 +486,7 @@ class PDFDancer {
                 },
                 body: JSON.stringify(createRequest.toDict()),
                 signal: resolvedTimeout > 0 ? AbortSignal.timeout(resolvedTimeout) : undefined
-            });
+            }, DEFAULT_RETRY_CONFIG, 'POST /session/new');
             logGeneratedAtHeader(response, 'POST', '/session/new');
             if (!response.ok) {
                 const errorText = await response.text();
@@ -340,6 +502,11 @@ class PDFDancer {
             client._readTimeout = resolvedTimeout;
             client._pdfBytes = new Uint8Array();
             client._sessionId = sessionId;
+            // Initialize retry config
+            client._retryConfig = {
+                ...DEFAULT_RETRY_CONFIG,
+                ...retryConfig
+            };
             // Initialize caches
             client._documentSnapshotCache = null;
             client._pageSnapshotCache = new Map();
@@ -354,6 +521,39 @@ class PDFDancer {
             throw new exceptions_1.HttpClientException(`Failed to create new PDF: ${errorMessage}`, undefined, error);
         }
     }
+    static async _obtainAnonymousToken(baseUrl, timeout = 60000) {
+        const normalizedBaseUrl = (baseUrl || "https://api.pdfdancer.com").replace(/\/+$/, '');
+        const url = `${normalizedBaseUrl}/keys/anon`;
+        try {
+            const fingerprint = await (0, fingerprint_1.generateFingerprint)();
+            const response = await fetchWithRetry(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Fingerprint': fingerprint,
+                    'X-Generated-At': generateTimestamp()
+                },
+                signal: timeout > 0 ? AbortSignal.timeout(timeout) : undefined
+            }, DEFAULT_RETRY_CONFIG, 'POST /keys/anon');
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => '');
+                throw new exceptions_1.HttpClientException(`Failed to obtain anonymous token: ${errorText || `HTTP ${response.status}`}`, response);
+            }
+            const tokenPayload = await response.json().catch(() => null);
+            const tokenValue = typeof tokenPayload?.token === 'string' ? tokenPayload.token.trim() : '';
+            if (!tokenValue) {
+                throw new exceptions_1.HttpClientException("Invalid anonymous token response format", response);
+            }
+            return tokenValue;
+        }
+        catch (error) {
+            if (error instanceof exceptions_1.HttpClientException) {
+                throw error;
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new exceptions_1.HttpClientException(`Failed to obtain anonymous token: ${errorMessage}`, undefined, error);
+        }
+    }
     /**
      * Process PDF data from various input types with strict validation.
      */
@@ -379,6 +579,17 @@ class PDFDancer {
                 // Note: File reading will be handled asynchronously in the session creation
                 return new Uint8Array(); // Placeholder, will be replaced in _createSession
             }
+            else if (typeof pdfData === 'string') {
+                // Handle string as filepath
+                if (!fs_1.default.existsSync(pdfData)) {
+                    throw new exceptions_1.ValidationException(`PDF file not found: ${pdfData}`);
+                }
+                const fileData = new Uint8Array(fs_1.default.readFileSync(pdfData));
+                if (fileData.length === 0) {
+                    throw new exceptions_1.ValidationException("PDF file is empty");
+                }
+                return fileData;
+            }
             else {
                 throw new exceptions_1.ValidationException(`Unsupported PDF data type: ${typeof pdfData}`);
             }
@@ -453,7 +664,7 @@ class PDFDancer {
                 formData.append('pdf', blob, 'document.pdf');
             }
             const fingerprint = await this._getFingerprint();
-            const response = await fetch(this._buildUrl('/session/create'), {
+            const response = await this._fetchWithRetry(this._buildUrl('/session/create'), {
                 method: 'POST',
                 headers: {
                     'Authorization': `Bearer ${this._token}`,
@@ -462,7 +673,7 @@ class PDFDancer {
                 },
                 body: formData,
                 signal: this._readTimeout > 0 ? AbortSignal.timeout(this._readTimeout) : undefined
-            });
+            }, 'POST /session/create');
             logGeneratedAtHeader(response, 'POST', '/session/create');
             if (!response.ok) {
                 const errorMessage = await this._extractErrorMessage(response);
@@ -499,6 +710,15 @@ class PDFDancer {
         }
         return this._fingerprintCache;
     }
+    /**
+     * Executes a fetch request with retry logic based on the configured retry policy.
+     * Implements exponential backoff with optional jitter.
+     */
+    async _fetchWithRetry(url, 
+    // eslint-disable-next-line no-undef
+    options, context = 'request') {
+        return fetchWithRetry(url, options, this._retryConfig, context);
+    }
     /**
      * Make HTTP request with session headers and error handling.
      */
@@ -518,12 +738,12 @@ class PDFDancer {
             'X-Fingerprint': fingerprint
         };
         try {
-            const response = await fetch(url.toString(), {
+            const response = await this._fetchWithRetry(url.toString(), {
                 method,
                 headers,
                 body: data ? JSON.stringify(data) : undefined,
                 signal: this._readTimeout > 0 ? AbortSignal.timeout(this._readTimeout) : undefined
-            });
+            }, `${method} ${path}`);
             logGeneratedAtHeader(response, method, path);
             // Handle FontNotFoundException
             if (response.status === 404) {
@@ -1129,7 +1349,7 @@ class PDFDancer {
             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'), {
+            const response = await this._fetchWithRetry(this._buildUrl('/font/register'), {
                 method: 'POST',
                 headers: {
                     'Authorization': `Bearer ${this._token}`,
@@ -1138,8 +1358,8 @@ class PDFDancer {
                     'X-Fingerprint': fingerprint
                 },
                 body: formData,
-                signal: AbortSignal.timeout(30000)
-            });
+                signal: AbortSignal.timeout(60000)
+            }, 'POST /font/register');
             logGeneratedAtHeader(response, 'POST', '/font/register');
             if (!response.ok) {
                 const errorMessage = await this._extractErrorMessage(response);
@@ -1224,17 +1444,24 @@ class PDFDancer {
         let status;
         const statusData = objData.status;
         if (statusData && typeof statusData === 'object') {
-            // Parse font recommendation
-            const fontRecData = statusData.fontRecommendation;
-            let fontRec;
-            if (fontRecData && typeof fontRecData === 'object') {
-                fontRec = new models_1.FontRecommendation(fontRecData.fontName || '', fontRecData.fontType || models_1.FontType.SYSTEM, fontRecData.similarityScore || 0.0);
-            }
-            else {
-                // Create empty font recommendation if not provided
-                fontRec = new models_1.FontRecommendation('', models_1.FontType.SYSTEM, 0.0);
+            const fontInfoSource = statusData.fontInfoDto ?? statusData.fontRecommendation;
+            let fontInfo;
+            if (fontInfoSource && typeof fontInfoSource === 'object') {
+                const documentFontName = typeof fontInfoSource.documentFontName === 'string'
+                    ? fontInfoSource.documentFontName
+                    : (typeof fontInfoSource.fontName === 'string' ? fontInfoSource.fontName : '');
+                const systemFontName = typeof fontInfoSource.systemFontName === 'string'
+                    ? fontInfoSource.systemFontName
+                    : (typeof fontInfoSource.fontName === 'string' ? fontInfoSource.fontName : '');
+                fontInfo = new models_1.DocumentFontInfo(documentFontName, systemFontName);
             }
-            status = new models_1.TextStatus(statusData.modified || false, statusData.encodable !== undefined ? statusData.encodable : true, statusData.fontType || models_1.FontType.SYSTEM, fontRec);
+            const modified = statusData.modified !== undefined ? Boolean(statusData.modified) : false;
+            const encodable = statusData.encodable !== undefined ? Boolean(statusData.encodable) : true;
+            const fontTypeValue = typeof statusData.fontType === 'string'
+                && Object.values(models_1.FontType).includes(statusData.fontType)
+                ? statusData.fontType
+                : models_1.FontType.SYSTEM;
+            status = new models_1.TextStatus(modified, encodable, fontTypeValue, fontInfo);
         }
         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) {
@@ -1335,10 +1562,13 @@ class PDFDancer {
         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));
+                    const documentFontName = typeof fontData.documentFontName === 'string'
+                        ? fontData.documentFontName
+                        : (typeof fontData.fontName === 'string' ? fontData.fontName : '');
+                    const systemFontName = typeof fontData.systemFontName === 'string'
+                        ? fontData.systemFontName
+                        : (typeof fontData.fontName === 'string' ? fontData.fontName : '');
+                    fonts.push(new models_1.DocumentFontInfo(documentFontName, systemFontName));
                 }
             }
         }
@@ -1429,6 +1659,42 @@ class PDFDancer {
     async selectLines() {
         return this.selectTextLines();
     }
+    // Singular convenience methods - return the first element or null
+    async selectImage() {
+        const images = await this.selectImages();
+        return images.length > 0 ? images[0] : null;
+    }
+    async selectPath() {
+        const paths = await this.selectPaths();
+        return paths.length > 0 ? paths[0] : null;
+    }
+    async selectForm() {
+        const forms = await this.selectForms();
+        return forms.length > 0 ? forms[0] : null;
+    }
+    async selectFormField() {
+        const fields = await this.selectFormFields();
+        return fields.length > 0 ? fields[0] : null;
+    }
+    async selectFieldByName(fieldName) {
+        const fields = await this.selectFieldsByName(fieldName);
+        return fields.length > 0 ? fields[0] : null;
+    }
+    async selectParagraph() {
+        const paragraphs = await this.selectParagraphs();
+        return paragraphs.length > 0 ? paragraphs[0] : null;
+    }
+    async selectParagraphMatching(pattern) {
+        const paragraphs = await this.selectParagraphsMatching(pattern);
+        return paragraphs.length > 0 ? paragraphs[0] : null;
+    }
+    async selectTextLine() {
+        const lines = await this.selectTextLines();
+        return lines.length > 0 ? lines[0] : null;
+    }
+    async selectLine() {
+        return this.selectTextLine();
+    }
 }
 exports.PDFDancer = PDFDancer;
 //# sourceMappingURL=pdfdancer_v1.js.map