pdfdancer-client-typescript 1.0.13 → 1.0.15

package/src/pdfdancer_v1.ts

@@ -23,7 +23,7 @@ import {
     DocumentSnapshot,
     FindRequest,
     Font,
-    FontRecommendation,
+    DocumentFontInfo,
     FontType,
     FormFieldRef,
     Image,
@@ -61,6 +61,154 @@ 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;
+}
+
+/**
+ * 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
+};
+
+/**
+ * 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) {
+                    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 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');
+}
+
+/**
+ * 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 +474,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 +579,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 +593,10 @@ export class PDFDancer {
      */
     private constructor(
         token: string,
-        pdfData: Uint8Array | File | ArrayBuffer,
+        pdfData: Uint8Array | File | ArrayBuffer | string,
         baseUrl: string | null = null,
-        readTimeout: number = 30000
+        readTimeout: number = 60000,
+        retryConfig?: RetryConfig
     ) {
 
         if (!token || !token.trim()) {
@@ -384,6 +621,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,19 +645,25 @@ export class PDFDancer {
         return this;
     }
 
-    static async open(pdfData: Uint8Array, token?: string, baseUrl?: string, timeout?: number): Promise<PDFDancer> {
-        const resolvedToken = token ?? process.env.PDFDANCER_TOKEN;
+    static async open(
+        pdfData: Uint8Array,
+        token?: string,
+        baseUrl?: string,
+        timeout?: number,
+        retryConfig?: RetryConfig
+    ): Promise<PDFDancer> {
         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 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();
     }
 
@@ -427,7 +676,8 @@ export 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?: {
@@ -437,17 +687,18 @@ export class PDFDancer {
         },
         token?: string,
         baseUrl?: string,
-        timeout?: number
+        timeout?: number,
+        retryConfig?: RetryConfig
     ): Promise<PDFDancer> {
-        const resolvedToken = token ?? process.env.PDFDANCER_TOKEN;
         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 ValidationException("Missing PDFDancer token (pass it explicitly or set PDFDANCER_TOKEN in environment).");
+            resolvedToken = await PDFDancer._obtainAnonymousToken(resolvedBaseUrl, resolvedTimeout);
         }
 
         let createRequest: CreatePdfRequest;
@@ -471,18 +722,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 +759,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();
@@ -517,10 +778,56 @@ export class PDFDancer {
         }
     }
 
+    private static async _obtainAnonymousToken(baseUrl: string, timeout: number = 60000): Promise<string> {
+        const normalizedBaseUrl = (baseUrl || "https://api.pdfdancer.com").replace(/\/+$/, '');
+        const url = `${normalizedBaseUrl}/keys/anon`;
+
+        try {
+            const fingerprint = await 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 HttpClientException(
+                    `Failed to obtain anonymous token: ${errorText || `HTTP ${response.status}`}`,
+                    response
+                );
+            }
+
+            const tokenPayload: any = await response.json().catch(() => null);
+            const tokenValue = typeof tokenPayload?.token === 'string' ? tokenPayload.token.trim() : '';
+
+            if (!tokenValue) {
+                throw new HttpClientException("Invalid anonymous token response format", response);
+            }
+
+            return tokenValue;
+        } catch (error) {
+            if (error instanceof HttpClientException) {
+                throw error;
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new HttpClientException(`Failed to obtain anonymous token: ${errorMessage}`, undefined, error as Error);
+        }
+    }
+
     /**
      * 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");
         }
@@ -540,6 +847,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}`);
             }
@@ -621,16 +938,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');
 
@@ -675,6 +996,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.
      */
@@ -702,12 +1036,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);
 
@@ -1419,17 +1757,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(30000)
-            });
+                'POST /font/register'
+            );
 
             logGeneratedAtHeader(response, 'POST', '/font/register');
 
@@ -1534,25 +1876,30 @@ export class PDFDancer {
         let status: TextStatus | undefined;
         const statusData = objData.status;
         if (statusData && typeof statusData === 'object') {
-            // Parse font recommendation
-            const fontRecData = statusData.fontRecommendation;
-            let fontRec: FontRecommendation;
-            if (fontRecData && typeof fontRecData === 'object') {
-                fontRec = new FontRecommendation(
-                    fontRecData.fontName || '',
-                    (fontRecData.fontType as FontType) || FontType.SYSTEM,
-                    fontRecData.similarityScore || 0.0
-                );
-            } else {
-                // Create empty font recommendation if not provided
-                fontRec = new FontRecommendation('', FontType.SYSTEM, 0.0);
+            const fontInfoSource = statusData.fontInfoDto ?? statusData.fontRecommendation;
+            let fontInfo: DocumentFontInfo | undefined;
+            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 DocumentFontInfo(documentFontName, systemFontName);
             }
 
+            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(FontType) as string[]).includes(statusData.fontType)
+                ? statusData.fontType as FontType
+                : FontType.SYSTEM;
+
             status = new TextStatus(
-                statusData.modified || false,
-                statusData.encodable !== undefined ? statusData.encodable : true,
-                (statusData.fontType as FontType) || FontType.SYSTEM,
-                fontRec
+                modified,
+                encodable,
+                fontTypeValue,
+                fontInfo
             );
         }
 
@@ -1704,14 +2051,17 @@ export class PDFDancer {
         const pageCount = typeof data.pageCount === 'number' ? data.pageCount : 0;
 
         // Parse fonts
-        const fonts: FontRecommendation[] = [];
+        const fonts: DocumentFontInfo[] = [];
         if (Array.isArray(data.fonts)) {
             for (const fontData of data.fonts) {
                 if (fontData && typeof fontData === 'object') {
-                    const fontName = fontData.fontName || '';
-                    const fontType = fontData.fontType as FontType || FontType.SYSTEM;
-                    const similarityScore = typeof fontData.similarityScore === 'number' ? fontData.similarityScore : 0;
-                    fonts.push(new 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 DocumentFontInfo(documentFontName, systemFontName));
                 }
             }
         }
@@ -1825,4 +2175,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();
+    }
 }