pdfdancer-client-typescript 1.0.14 → 1.0.16

package/src/pdfdancer_v1.ts

@@ -61,6 +61,213 @@ const DEBUG =
     (process.env.PDFDANCER_CLIENT_DEBUG ?? '') === '1' ||
     (process.env.PDFDANCER_CLIENT_DEBUG ?? '').toLowerCase() === 'yes';
 
+/**
+ * Configuration for retry mechanism on REST API calls.
+ */
+export interface RetryConfig {
+    /**
+     * Maximum number of retry attempts (default: 3)
+     */
+    maxRetries?: number;
+
+    /**
+     * Initial delay in milliseconds before first retry (default: 1000)
+     * Subsequent delays use exponential backoff
+     */
+    initialDelay?: number;
+
+    /**
+     * Maximum delay in milliseconds between retries (default: 10000)
+     */
+    maxDelay?: number;
+
+    /**
+     * HTTP status codes that should trigger a retry (default: [429, 500, 502, 503, 504])
+     */
+    retryableStatusCodes?: number[];
+
+    /**
+     * Whether to retry on network errors (connection failures, timeouts) (default: true)
+     */
+    retryOnNetworkError?: boolean;
+
+    /**
+     * Exponential backoff multiplier (default: 2)
+     */
+    backoffMultiplier?: number;
+
+    /**
+     * Whether to add random jitter to retry delays to prevent thundering herd (default: true)
+     */
+    useJitter?: boolean;
+
+    /**
+     * Whether to respect Retry-After headers from server responses (default: true)
+     * When enabled, the client will use the server-specified delay instead of exponential backoff
+     * for responses that include a Retry-After header (typically 429 or 503 responses)
+     */
+    respectRetryAfter?: boolean;
+}
+
+/**
+ * Default retry configuration
+ */
+const DEFAULT_RETRY_CONFIG: Required<RetryConfig> = {
+    maxRetries: 3,
+    initialDelay: 1000,
+    maxDelay: 10000,
+    retryableStatusCodes: [429, 500, 502, 503, 504],
+    retryOnNetworkError: true,
+    backoffMultiplier: 2,
+    useJitter: true,
+    respectRetryAfter: 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: string,
+    // eslint-disable-next-line no-undef
+    options: RequestInit,
+    retryConfig: Required<RetryConfig>,
+    context: string = 'request'
+): Promise<Response> {
+    let lastError: Error | null = null;
+    let lastResponse: Response | null = 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) {
+                    let delay: number;
+                    let delaySource = 'exponential backoff';
+
+                    // Check for Retry-After header if configured
+                    if (retryConfig.respectRetryAfter) {
+                        const retryAfterDelay = parseRetryAfter(response);
+                        if (retryAfterDelay !== null) {
+                            // Use Retry-After header value, but cap at maxDelay
+                            delay = Math.min(retryAfterDelay, retryConfig.maxDelay);
+                            delaySource = 'Retry-After header';
+                        } else {
+                            // Fall back to exponential backoff
+                            delay = calculateRetryDelay(attempt, retryConfig);
+                        }
+                    } else {
+                        // Use exponential backoff
+                        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}, source: ${delaySource})`);
+                    }
+                    await sleep(delay);
+                    continue;
+                }
+            }
+
+            // Request succeeded or non-retryable error
+            return response;
+
+        } catch (error) {
+            lastError = error as 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');
+}
+
+/**
+ * Parses the Retry-After header from a response.
+ * Supports both delay-seconds (integer) and HTTP-date formats.
+ * Returns the delay in milliseconds, or null if the header is invalid or missing.
+ */
+function parseRetryAfter(response: Response): number | null {
+    const retryAfter = response.headers.get('Retry-After');
+    if (!retryAfter) {
+        return null;
+    }
+
+    // Try parsing as delay-seconds (integer)
+    const delaySeconds = parseInt(retryAfter, 10);
+    if (!isNaN(delaySeconds) && delaySeconds >= 0) {
+        return delaySeconds * 1000; // Convert to milliseconds
+    }
+
+    // Try parsing as HTTP-date
+    try {
+        const retryDate = new Date(retryAfter);
+        if (!isNaN(retryDate.getTime())) {
+            const now = Date.now();
+            const delay = retryDate.getTime() - now;
+            // Only return positive delays
+            return delay > 0 ? delay : 0;
+        }
+    } catch {
+        // Invalid date format
+    }
+
+    return null;
+}
+
+/**
+ * Calculates the delay for the next retry attempt using exponential backoff.
+ */
+function calculateRetryDelay(attemptNumber: number, retryConfig: Required<RetryConfig>): number {
+    // 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: number): Promise<void> {
+    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)
@@ -326,6 +533,93 @@ class PageClient {
     async getSnapshot(types?: ObjectType[]): Promise<PageSnapshot> {
         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: number, y: number, tolerance: number = 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: number, y: number, tolerance: number = 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: number, y: number, tolerance: number = 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: number, y: number, tolerance: number = 0) {
+        const fields = await this.selectFormFieldsAt(x, y, tolerance);
+        return fields.length > 0 ? fields[0] : null;
+    }
+
+    async selectFormFieldByName(fieldName: string) {
+        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: string) {
+        const paragraphs = await this.selectParagraphsStartingWith(text);
+        return paragraphs.length > 0 ? paragraphs[0] : null;
+    }
+
+    async selectParagraphMatching(pattern: string) {
+        const paragraphs = await this.selectParagraphsMatching(pattern);
+        return paragraphs.length > 0 ? paragraphs[0] : null;
+    }
+
+    async selectParagraphAt(x: number, y: number, tolerance: number = 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: string) {
+        const lines = await this.selectTextLinesStartingWith(text);
+        return lines.length > 0 ? lines[0] : null;
+    }
+
+    async selectTextLineMatching(pattern: string) {
+        const lines = await this.selectTextLinesMatching(pattern);
+        return lines.length > 0 ? lines[0] : null;
+    }
+
+    async selectTextLineAt(x: number, y: number, tolerance: number = DEFAULT_TOLERANCE) {
+        const lines = await this.selectTextLinesAt(x, y, tolerance);
+        return lines.length > 0 ? lines[0] : null;
+    }
 }
 
 // noinspection ExceptionCaughtLocallyJS,JSUnusedLocalSymbols
@@ -344,6 +638,7 @@ export class PDFDancer {
     private _sessionId!: string;
     private _userId?: string;
     private _fingerprintCache?: string;
+    private _retryConfig: Required<RetryConfig>;
 
     // Snapshot caches for optimizing find operations
     private _documentSnapshotCache: DocumentSnapshot | null = null;
@@ -357,9 +652,10 @@ export class PDFDancer {
      */
     private constructor(
         token: string,
-        pdfData: Uint8Array | File | ArrayBuffer,
+        pdfData: Uint8Array | File | ArrayBuffer | string,
         baseUrl: string | null = null,
-        readTimeout: number = 60000
+        readTimeout: number = 60000,
+        retryConfig?: RetryConfig
     ) {
 
         if (!token || !token.trim()) {
@@ -384,6 +680,12 @@ export class PDFDancer {
         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);
 
@@ -402,7 +704,13 @@ export class PDFDancer {
         return this;
     }
 
-    static async open(pdfData: Uint8Array, token?: string, baseUrl?: string, timeout?: number): Promise<PDFDancer> {
+    static async open(
+        pdfData: Uint8Array,
+        token?: string,
+        baseUrl?: string,
+        timeout?: number,
+        retryConfig?: RetryConfig
+    ): Promise<PDFDancer> {
         const resolvedBaseUrl =
             baseUrl ??
             process.env.PDFDANCER_BASE_URL ??
@@ -414,7 +722,7 @@ export class PDFDancer {
             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();
     }
 
@@ -428,6 +736,7 @@ export class PDFDancer {
      * @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: 60000)
+     * @param retryConfig Retry configuration (optional, uses defaults if not specified)
      */
     static async new(
         options?: {
@@ -437,7 +746,8 @@ export class PDFDancer {
         },
         token?: string,
         baseUrl?: string,
-        timeout?: number
+        timeout?: number,
+        retryConfig?: RetryConfig
     ): Promise<PDFDancer> {
         const resolvedBaseUrl =
             baseUrl ??
@@ -471,18 +781,23 @@ export class PDFDancer {
             // Generate fingerprint for this request
             const fingerprint = await generateFingerprint();
 
-            // Make request to create endpoint
-            const response = await fetch(url, {
-                method: 'POST',
-                headers: {
-                    'Authorization': `Bearer ${resolvedToken}`,
-                    'Content-Type': 'application/json',
-                    'X-Generated-At': generateTimestamp(),
-                    'X-Fingerprint': fingerprint
+            // Make request to create endpoint with retry logic
+            const response = await fetchWithRetry(
+                url,
+                {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${resolvedToken}`,
+                        'Content-Type': 'application/json',
+                        'X-Generated-At': generateTimestamp(),
+                        'X-Fingerprint': fingerprint
+                    },
+                    body: JSON.stringify(createRequest.toDict()),
+                    signal: resolvedTimeout > 0 ? AbortSignal.timeout(resolvedTimeout) : undefined
                 },
-                body: JSON.stringify(createRequest.toDict()),
-                signal: resolvedTimeout > 0 ? AbortSignal.timeout(resolvedTimeout) : undefined
-            });
+                DEFAULT_RETRY_CONFIG,
+                'POST /session/new'
+            );
 
             logGeneratedAtHeader(response, 'POST', '/session/new');
 
@@ -503,6 +818,11 @@ export 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();
@@ -523,15 +843,20 @@ export class PDFDancer {
 
         try {
             const fingerprint = await generateFingerprint();
-            const response = await fetch(url, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'X-Fingerprint': fingerprint,
-                    'X-Generated-At': generateTimestamp()
+            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
                 },
-                signal: timeout > 0 ? AbortSignal.timeout(timeout) : undefined
-            });
+                DEFAULT_RETRY_CONFIG,
+                'POST /keys/anon'
+            );
 
             if (!response.ok) {
                 const errorText = await response.text().catch(() => '');
@@ -561,7 +886,7 @@ export class PDFDancer {
     /**
      * Process PDF data from various input types with strict validation.
      */
-    private _processPdfData(pdfData: Uint8Array | File | ArrayBuffer): Uint8Array {
+    private _processPdfData(pdfData: Uint8Array | File | ArrayBuffer | string): Uint8Array {
         if (!pdfData) {
             throw new ValidationException("PDF data cannot be null");
         }
@@ -581,6 +906,16 @@ export class PDFDancer {
             } else if (pdfData instanceof File) {
                 // 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.existsSync(pdfData)) {
+                    throw new ValidationException(`PDF file not found: ${pdfData}`);
+                }
+                const fileData = new Uint8Array(fs.readFileSync(pdfData));
+                if (fileData.length === 0) {
+                    throw new ValidationException("PDF file is empty");
+                }
+                return fileData;
             } else {
                 throw new ValidationException(`Unsupported PDF data type: ${typeof pdfData}`);
             }
@@ -662,16 +997,20 @@ export class PDFDancer {
 
             const fingerprint = await this._getFingerprint();
 
-            const response = await fetch(this._buildUrl('/session/create'), {
-                method: 'POST',
-                headers: {
-                    'Authorization': `Bearer ${this._token}`,
-                    'X-Generated-At': generateTimestamp(),
-                    'X-Fingerprint': fingerprint
+            const response = await this._fetchWithRetry(
+                this._buildUrl('/session/create'),
+                {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${this._token}`,
+                        'X-Generated-At': generateTimestamp(),
+                        'X-Fingerprint': fingerprint
+                    },
+                    body: formData,
+                    signal: this._readTimeout > 0 ? AbortSignal.timeout(this._readTimeout) : undefined
                 },
-                body: formData,
-                signal: this._readTimeout > 0 ? AbortSignal.timeout(this._readTimeout) : undefined
-            });
+                'POST /session/create'
+            );
 
             logGeneratedAtHeader(response, 'POST', '/session/create');
 
@@ -716,6 +1055,19 @@ export class PDFDancer {
         return this._fingerprintCache;
     }
 
+    /**
+     * Executes a fetch request with retry logic based on the configured retry policy.
+     * Implements exponential backoff with optional jitter.
+     */
+    private async _fetchWithRetry(
+        url: string,
+        // eslint-disable-next-line no-undef
+        options: RequestInit,
+        context: string = 'request'
+    ): Promise<Response> {
+        return fetchWithRetry(url, options, this._retryConfig, context);
+    }
+
     /**
      * Make HTTP request with session headers and error handling.
      */
@@ -743,12 +1095,16 @@ export class PDFDancer {
         };
 
         try {
-            const response = await fetch(url.toString(), {
-                method,
-                headers,
-                body: data ? JSON.stringify(data) : undefined,
-                signal: this._readTimeout > 0 ? AbortSignal.timeout(this._readTimeout) : undefined
-            });
+            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);
 
@@ -1460,17 +1816,21 @@ export class PDFDancer {
 
             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-Generated-At': generateTimestamp(),
-                    'X-Fingerprint': fingerprint
+            const response = await this._fetchWithRetry(
+                this._buildUrl('/font/register'),
+                {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${this._token}`,
+                        'X-Session-Id': this._sessionId,
+                        'X-Generated-At': generateTimestamp(),
+                        'X-Fingerprint': fingerprint
+                    },
+                    body: formData,
+                    signal: AbortSignal.timeout(60000)
                 },
-                body: formData,
-                signal: AbortSignal.timeout(60000)
-            });
+                'POST /font/register'
+            );
 
             logGeneratedAtHeader(response, 'POST', '/font/register');
 
@@ -1874,4 +2234,50 @@ export 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: string) {
+        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: string) {
+        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();
+    }
 }