@glideidentity/web-client-sdk 4.4.8-beta.1

package/dist/esm/core/phone-auth/client.js

@@ -0,0 +1,1316 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+// Import API types for API communication
+import * as API from './api-types';
+import { BrowserError, BrowserErrorCode, BrowserName } from './types';
+import { PhoneAuthErrorCode, isPhoneAuthError, parseBackendError, getUserMessage, isUserError, serializeError, createErrorBreadcrumb } from './error-utils';
+import { validatePhoneNumber, validatePlmn, validateConsentData, validateNonce } from './validation-utils';
+import { LoggerFactory } from '../logger';
+import { DesktopHandler } from './strategies/desktop';
+import { LinkHandler } from './strategies/link';
+import { AuthModal } from './ui/modal';
+export class PhoneAuthClient {
+    constructor(config = {}) {
+        var _a, _b, _c;
+        this.crossDeviceActive = false;
+        this.retryCount = 0;
+        this.sessionCache = new Map();
+        // Store base timeout for normal operations
+        this.baseTimeout = config.timeout || 30000;
+        // Default configuration with cross-device support
+        this.config = {
+            endpoints: {
+                prepare: ((_a = config.endpoints) === null || _a === void 0 ? void 0 : _a.prepare) || '/api/magic-auth/prepare',
+                process: ((_b = config.endpoints) === null || _b === void 0 ? void 0 : _b.process) || '/api/magic-auth/process'
+            },
+            timeout: config.timeout || 30000,
+            pollingInterval: config.pollingInterval || 2000, // Default 2 seconds
+            maxPollingAttempts: config.maxPollingAttempts || 30, // Changed from 150 to 30 (1 minute total)
+            debug: config.debug || false,
+            aggregatorId: config.aggregatorId || 'default',
+            devtools: config.devtools
+        };
+        this.debug = this.config.debug;
+        // Store callbacks
+        this.callbacks = {
+            onCrossDeviceDetected: config.onCrossDeviceDetected,
+            onRetryAttempt: config.onRetryAttempt
+        };
+        // Initialize logger based on config
+        this.logger = LoggerFactory.create({
+            level: config.logLevel,
+            prefix: '[PhoneAuth]',
+            remote: config.remoteLogging,
+            custom: config.logger
+        });
+        // Initialize developer tools if configured
+        if (((_c = config.devtools) === null || _c === void 0 ? void 0 : _c.showMobileConsole) && typeof window !== 'undefined') {
+            import('./ui/mobile-debug-console').then(({ MobileDebugConsole }) => {
+                MobileDebugConsole.init();
+                console.log('[PhoneAuth] Mobile debug console enabled');
+            }).catch(err => {
+                console.error('[PhoneAuth] Failed to load mobile debug console:', err);
+            });
+        }
+        // Set up session cache cleanup
+        this.setupCacheCleanup();
+    }
+    /**
+     * Get user-friendly error message using error utilities
+     */
+    getUserFriendlyMessage(error) {
+        if (typeof error === 'string') {
+            // For legacy string error codes
+            return getUserMessage({ code: error });
+        }
+        return getUserMessage(error);
+    }
+    /**
+     * Log error with proper context and sanitization
+     */
+    logError(error, context) {
+        // Create breadcrumb for error tracking
+        const breadcrumb = createErrorBreadcrumb(error);
+        // Serialize error for logging (sanitized)
+        const serialized = serializeError(error);
+        if (this.debug || !isUserError(error)) {
+            console.error('[PhoneAuth] Error:', Object.assign(Object.assign({}, serialized), { breadcrumb,
+                context }));
+        }
+        // Log trace context for distributed tracing (if available)
+        if (error.traceId) {
+            console.debug('[PhoneAuth] Trace Context:', {
+                traceId: error.traceId,
+                spanId: error.spanId,
+                requestId: error.requestId
+            });
+        }
+    }
+    /**
+     * Check if the browser supports secure phone authentication
+     */
+    isSupported() {
+        // Only check on client side
+        if (typeof window === 'undefined')
+            return false;
+        // Check for the DigitalCredential constructor specifically
+        // This is more accurate than checking credentials.get which exists for other credential types
+        return 'DigitalCredential' in window;
+    }
+    /**
+     * Get detailed browser support information
+     */
+    getBrowserSupportInfo() {
+        if (typeof window === 'undefined') {
+            return {
+                supported: false,
+                browser: 'unknown',
+                message: 'Not running in a browser environment'
+            };
+        }
+        const userAgent = navigator.userAgent;
+        const isChrome = /Chrome/.test(userAgent) && /Google Inc/.test(navigator.vendor);
+        const isEdge = /Edg\//.test(userAgent);
+        const isSupported = this.isSupported();
+        if (isSupported) {
+            return {
+                supported: true,
+                browser: isChrome ? BrowserName.CHROME : isEdge ? BrowserName.EDGE : BrowserName.OTHER
+            };
+        }
+        // Provide specific guidance based on browser
+        if (isChrome || isEdge) {
+            return {
+                supported: false,
+                browser: isChrome ? BrowserName.CHROME : BrowserName.EDGE,
+                message: 'Digital Credentials API is not enabled. Please enable the #web-identity-digital-credentials flag.',
+                helpUrl: isChrome
+                    ? 'chrome://flags/#web-identity-digital-credentials'
+                    : 'edge://flags/#web-identity-digital-credentials'
+            };
+        }
+        return {
+            supported: false,
+            browser: 'other',
+            message: 'Your browser doesn\'t support the Digital Credentials API. Please use Chrome or Edge with the #web-identity-digital-credentials flag enabled.'
+        };
+    }
+    /**
+     * Main verification method with silent retry support
+     */
+    verify(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Reset retry count for new verification
+            this.retryCount = 0;
+            this.lastRequest = options;
+            const maxRetries = 2; // Default max retries
+            // Try verification with silent retries
+            return this.verifyWithRetry(options, maxRetries);
+        });
+    }
+    verifyWithRetry(options, maxRetries) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            try {
+                // Step 1: Prepare the phone verification request
+                const preparedRequest = yield this.preparePhoneRequest(options);
+                // Step 2: Invoke secure prompt for user consent (always in UI mode for high-level API)
+                const credentialResponse = yield this.invokeSecurePrompt(preparedRequest);
+                // Check if headless result was returned (this shouldn't happen in high-level API)
+                if (credentialResponse && typeof credentialResponse === 'object' && 'strategy' in credentialResponse) {
+                    throw this.createError(PhoneAuthErrorCode.INVALID_RESPONSE, 'Headless mode is not supported in authenticatePhoneNumber. Use preparePhoneRequest and invokeSecurePrompt directly for headless mode.');
+                }
+                // Step 3: Process the response through appropriate endpoint
+                const credential = credentialResponse;
+                const result = options.use_case === API.USE_CASE.GET_PHONE_NUMBER
+                    ? yield this.getPhoneNumber(credential, preparedRequest.session)
+                    : yield this.verifyPhoneNumber(credential, preparedRequest.session);
+                // Return the result directly - it's already the correct type
+                // Cache successful result with session info for later use
+                this.cacheSession(options, result);
+                return result;
+            }
+            catch (error) {
+                const authError = isPhoneAuthError(error) ? error : parseBackendError(error);
+                // Check if we should retry (silent retry - don't throw yet)
+                // Note: We cannot automatically retry USER_DENIED errors because the Digital Credentials API
+                // requires user interaction (transient activation). Automatic retries would fail with
+                // "The 'digital-credentials-get' feature requires transient activation" error.
+                if (this.shouldRetry(authError) && this.retryCount < maxRetries) {
+                    this.retryCount++;
+                    // Notify about retry attempt (but don't show error to user)
+                    (_b = (_a = this.callbacks).onRetryAttempt) === null || _b === void 0 ? void 0 : _b.call(_a, this.retryCount, maxRetries);
+                    if (this.debug) {
+                        console.log(`[PhoneAuth] Retrying verification (attempt ${this.retryCount + 1}/${maxRetries + 1})`);
+                    }
+                    // Wait before retry
+                    yield this.delay(Math.min(1000 * Math.pow(2, this.retryCount - 1), 5000)); // Exponential backoff
+                    // Check cache for recent successful session
+                    const cachedResult = this.getCachedSession(options);
+                    if (cachedResult) {
+                        if (this.debug)
+                            console.log('[PhoneAuth] Using cached session result');
+                        return cachedResult;
+                    }
+                    // Retry the verification
+                    return this.verifyWithRetry(options, maxRetries);
+                }
+                // All retries exhausted or non-retryable error - now throw
+                // Add context
+                authError.context = {
+                    step: 'complete',
+                    useCase: options.use_case,
+                    timestamp: new Date().toISOString(),
+                    userAgent: navigator.userAgent,
+                    attemptNumber: this.retryCount + 1,
+                    maxAttempts: maxRetries + 1
+                };
+                // Log error with proper sanitization
+                this.logError(authError, { options });
+                // Re-throw the structured error
+                if (isPhoneAuthError(error)) {
+                    // If it already has context, throw as-is
+                    if (error.context) {
+                        throw error;
+                    }
+                    // Otherwise, create a new error with context
+                    const enhancedError = {
+                        code: authError.code,
+                        message: error.message,
+                        details: error.details,
+                        status: error.status,
+                        requestId: error.requestId,
+                        timestamp: error.timestamp,
+                        retryAfter: error.retryAfter,
+                        browserError: error.browserError,
+                        context: {
+                            useCase: options.use_case,
+                            timestamp: new Date().toISOString(),
+                            userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : undefined,
+                            url: typeof window !== 'undefined' ? window.location.href : undefined,
+                            attemptNumber: this.retryCount + 1,
+                            maxAttempts: maxRetries + 1
+                        }
+                    };
+                    throw enhancedError;
+                }
+                throw this.createError(PhoneAuthErrorCode.VERIFICATION_FAILED, 'Verification failed', error);
+            }
+        });
+    }
+    /**
+     * High-level method to get phone number (complete flow)
+     * Handles prepare, credential prompt, and get phone number in one call
+     */
+    getPhoneNumberComplete(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.verify(Object.assign({ use_case: API.USE_CASE.GET_PHONE_NUMBER }, options));
+        });
+    }
+    /**
+     * High-level method to verify phone number (complete flow)
+     * Handles prepare, credential prompt, and verification in one call
+     */
+    verifyPhoneNumberComplete(phoneNumber, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.verify(Object.assign({ use_case: API.USE_CASE.VERIFY_PHONE_NUMBER, phone_number: phoneNumber }, options));
+        });
+    }
+    /**
+     * Step 1: Prepare phone verification request
+     *
+     * This method prepares a secure request for phone verification.
+     * You can use this with your own backend or the glide-sdk-node.
+     *
+     * @example
+     * ```typescript
+     * const request = await phoneAuthClient.preparePhoneRequest({ useCase: 'GetPhoneNumber' });
+     * // Handle the request with custom logic
+     * ```
+     */
+    preparePhoneRequest(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Validate use case requirements first
+            // const useCaseValidation = validateUseCaseRequirements(options.use_case, options.phone_number);
+            // if (!useCaseValidation.valid) {
+            //   throw this.createError(
+            //     PhoneAuthErrorCode.BAD_REQUEST,
+            //     useCaseValidation.error!,
+            //     { field: 'use_case' }
+            //   );
+            // }
+            var _a, _b;
+            // Validate phone number if provided
+            if (options.phone_number) {
+                const phoneValidation = validatePhoneNumber(options.phone_number);
+                if (!phoneValidation.valid) {
+                    throw this.createError(PhoneAuthErrorCode.INVALID_PHONE_NUMBER, phoneValidation.error, { field: 'phone_number' });
+                }
+            }
+            // Validate PLMN if provided
+            if (options.plmn) {
+                const plmnValidation = validatePlmn(options.plmn);
+                if (!plmnValidation.valid) {
+                    throw this.createError(PhoneAuthErrorCode.BAD_REQUEST, plmnValidation.error, { field: 'plmn' });
+                }
+            }
+            // Validate consent data if provided
+            if (options.consent_data) {
+                const consentValidation = validateConsentData(options.consent_data);
+                if (!consentValidation.valid) {
+                    throw this.createError(PhoneAuthErrorCode.BAD_REQUEST, consentValidation.error, { field: 'consent_data' });
+                }
+            }
+            // Validate required parameters based on use case
+            if (!options.phone_number && !options.plmn && !((_a = options.options) === null || _a === void 0 ? void 0 : _a.parent_session_id)) {
+                // Provide specific error message based on use case
+                if (options.use_case === API.USE_CASE.GET_PHONE_NUMBER) {
+                    throw this.createError(PhoneAuthErrorCode.MISSING_PARAMETERS, 'PLMN (MCC/MNC) is required for GetPhoneNumber. Please provide carrier network information.', { field: 'plmn', useCase: 'GetPhoneNumber' });
+                }
+                else if (options.use_case === API.USE_CASE.VERIFY_PHONE_NUMBER) {
+                    throw this.createError(PhoneAuthErrorCode.MISSING_PARAMETERS, 'Phone number is required for VerifyPhoneNumber', { field: 'phoneNumber', useCase: 'VerifyPhoneNumber' });
+                }
+                else if (!options.use_case) {
+                    // If no use case, that's an error
+                    throw this.createError(PhoneAuthErrorCode.MISSING_PARAMETERS, 'use_case is required', { field: 'use_case' });
+                }
+                else {
+                    // Fallback for other use cases
+                    throw this.createError(PhoneAuthErrorCode.MISSING_PARAMETERS, 'Either phone number or PLMN (MCC/MNC) must be provided', { field: 'phoneNumber,plmn' });
+                }
+            }
+            // If only parent_session_id is provided, use_case is optional (will be inherited)
+            if (((_b = options.options) === null || _b === void 0 ? void 0 : _b.parent_session_id) && !options.phone_number && !options.plmn && !options.use_case) {
+                if (this.debug) {
+                    console.log('[PhoneAuth] Using parent_session_id only - all fields will be inherited from parent session');
+                }
+            }
+            const requestId = `web-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+            // Generate cryptographically secure nonce
+            const nonce = btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(32))))
+                .replace(/\+/g, '-')
+                .replace(/\//g, '_')
+                .replace(/=/g, '');
+            // Validate generated nonce
+            const nonceValidation = validateNonce(nonce);
+            if (!nonceValidation.valid) {
+                throw this.createError(PhoneAuthErrorCode.INTERNAL_SERVER_ERROR, 'Failed to generate valid nonce', { field: 'nonce' });
+            }
+            // Build properly typed request body according to API specification
+            const requestBody = {
+                // Required fields
+                use_case: options.use_case,
+                // One of these is required
+                phone_number: options.phone_number,
+                plmn: options.plmn ? {
+                    mcc: options.plmn.mcc,
+                    mnc: options.plmn.mnc
+                } : undefined,
+                // Auto-generated fields (SDK always provides these)
+                nonce: nonce,
+                id: requestId,
+                // Optional fields
+                consent_data: options.consent_data,
+                client_info: {
+                    user_agent: navigator.userAgent,
+                    platform: navigator.platform
+                },
+                // Advanced options (for desktop-mobile binding and future features)
+                options: options.options
+            };
+            this.log('Preparing phone verification request', requestBody);
+            try {
+                const response = yield this.fetchWithTimeout(this.config.endpoints.prepare, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(requestBody)
+                });
+                if (!response.ok) {
+                    // Try to get error details from response body
+                    let errorDetails = null;
+                    try {
+                        errorDetails = yield response.json();
+                        // Always include the HTTP status from the response
+                        errorDetails = Object.assign(Object.assign({}, errorDetails), { status: response.status });
+                    }
+                    catch (_c) {
+                        // If JSON parsing fails, use status text
+                        errorDetails = { status: response.status, statusText: response.statusText };
+                    }
+                    // Parse the backend error response (handles both structured and unstructured errors)
+                    const parsedError = parseBackendError(errorDetails);
+                    // Enhance with additional context
+                    parsedError.context = {
+                        step: 'prepare',
+                        useCase: options.use_case,
+                        timestamp: new Date().toISOString(),
+                        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : undefined,
+                        url: typeof window !== 'undefined' ? window.location.href : undefined
+                    };
+                    // Add endpoint info
+                    parsedError.details = Object.assign(Object.assign({}, parsedError.details), { endpoint: 'prepare', status: response.status });
+                    throw parsedError;
+                }
+                const data = yield response.json();
+                this.log('Phone verification request prepared', data);
+                if (!data.authentication_strategy || !data.data || !data.session) {
+                    throw this.createError(PhoneAuthErrorCode.INVALID_RESPONSE, 'Invalid response format from backend');
+                }
+                // Return the full response as-is
+                // The invoke method will handle it based on authentication_strategy
+                return data;
+            }
+            catch (error) {
+                // If it's already an AuthError, re-throw it
+                if (this.isAuthError(error)) {
+                    throw error;
+                }
+                // Otherwise, wrap it as a network error
+                throw this.createError(PhoneAuthErrorCode.NETWORK_ERROR, 'Failed to prepare verification request', {
+                    originalError: error,
+                    context: {
+                        step: 'prepare',
+                        useCase: options.use_case,
+                        timestamp: new Date().toISOString(),
+                        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : undefined,
+                        url: typeof window !== 'undefined' ? window.location.href : undefined
+                    }
+                });
+            }
+        });
+    }
+    /**
+     * Step 2: Invoke secure prompt for user consent
+     *
+     * This method can work in two modes:
+     * 1. **UI Mode (default)**: Shows built-in UI components (modals/buttons)
+     * 2. **Headless Mode**: Returns raw data for custom UI implementation
+     *
+     * **Important**: This method automatically handles reactive objects from frameworks
+     * like Vue.js and React by deep cloning the input. This ensures compatibility with
+     * browser APIs that expect plain objects.
+     *
+     * @example UI Mode (shows modal/button)
+     * ```typescript
+     * // Shows SDK's built-in UI
+     * const credential = await phoneAuth.invokeSecurePrompt(prepareResult);
+     *
+     * // Customize the UI
+     * const credential = await phoneAuth.invokeSecurePrompt(prepareResult, {
+     *   modalOptions: {
+     *     title: 'Verify Your Identity',
+     *     buttonText: 'Continue with Verizon'
+     *   }
+     * });
+     * ```
+     *
+     * @example Headless Mode (returns data)
+     * ```typescript
+     * // Get raw data without showing UI
+     * const result = await phoneAuth.invokeSecurePrompt(prepareResult, {
+     *   headless: true
+     * });
+     *
+     * if (result.strategy === 'link') {
+     *   // Open URL yourself
+     *   window.open(result.url);
+     *   await result.pollingPromise; // Wait for completion
+     * }
+     * ```
+     *
+     * @param prepareResponse - Response from prepare() with strategy and data
+     * @param options - Control UI behavior or enable headless mode
+     * @returns Credential or HeadlessResult based on mode
+     */
+    invokeSecurePrompt(prepareResponse, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Deep clone to avoid issues with reactive objects (Vue/React)
+            // This ensures we work with plain objects for browser APIs
+            // Vue's reactivity system wraps objects in Proxies which can interfere
+            // with browser APIs like Digital Credentials API that expect plain objects
+            var _a, _b, _c;
+            // Try structuredClone first (modern browsers), but catch errors and fallback to JSON method
+            let plainResponse;
+            try {
+                // structuredClone might throw if object contains non-cloneable properties
+                plainResponse = typeof structuredClone !== 'undefined'
+                    ? structuredClone(prepareResponse)
+                    : JSON.parse(JSON.stringify(prepareResponse));
+            }
+            catch (cloneError) {
+                // Fallback to JSON method if structuredClone fails
+                if (this.debug) {
+                    console.log('[PhoneAuth] structuredClone failed, using JSON fallback:', cloneError);
+                }
+                plainResponse = JSON.parse(JSON.stringify(prepareResponse));
+            }
+            console.log('[PhoneAuth] === invokeSecurePrompt called ===');
+            console.log('[PhoneAuth] Session cache size:', this.sessionCache.size);
+            console.log('[PhoneAuth] Retry count:', this.retryCount);
+            console.log('[PhoneAuth] PrepareResponse received:', JSON.stringify(plainResponse, null, 2));
+            // Check if we're in headless mode (new InvokeOptions format)
+            // Properly detect InvokeOptions by checking for any of its properties
+            const invokeOptions = options && ('headless' in options ||
+                'theme' in options ||
+                'modalOptions' in options ||
+                'callbacks' in options) ? options : undefined;
+            // Smart defaults: Link and TS43 default to headless, Desktop defaults to UI mode
+            const strategy = plainResponse.authentication_strategy;
+            const defaultHeadless = strategy === 'link' || strategy === 'ts43' ? true : false;
+            const isHeadless = (_a = invokeOptions === null || invokeOptions === void 0 ? void 0 : invokeOptions.headless) !== null && _a !== void 0 ? _a : defaultHeadless;
+            // DesktopAuthOptions is only used if not InvokeOptions
+            const desktopOptions = options && !invokeOptions ? options : undefined;
+            // Handle based on authentication strategy
+            if (plainResponse.authentication_strategy === API.AUTHENTICATION_STRATEGY.TS43) {
+                // Check browser support for TS43 strategy which requires Digital Credentials API
+                if (!this.isSupported()) {
+                    throw this.createError(PhoneAuthErrorCode.BROWSER_NOT_SUPPORTED, 'Your browser does not support the Digital Credentials API required for TS43 authentication');
+                }
+                const ts43Data = plainResponse.data;
+                const secureCredentialRequest = {
+                    digital: {
+                        requests: [{
+                                protocol: ts43Data.protocol,
+                                data: ts43Data.data
+                            }]
+                    }
+                };
+                this.log('Invoking TS43 secure authentication prompt', secureCredentialRequest);
+                // Function to trigger TS43 authentication
+                const triggerTS43 = () => __awaiter(this, void 0, void 0, function* () {
+                    var _a, _b;
+                    try {
+                        // This is the browser API call for TS43
+                        // Cast to CredentialRequestOptions with digital field (TS43 specific)
+                        const credentialOptions = secureCredentialRequest;
+                        const credentialResponse = yield navigator.credentials.get(credentialOptions);
+                        // Type guard for Digital Credential response
+                        const digitalResponse = credentialResponse;
+                        if (!digitalResponse || !('data' in digitalResponse) || !digitalResponse.data) {
+                            // Check if this is likely due to the browser flag being disabled
+                            const supportInfo = this.getBrowserSupportInfo();
+                            if (supportInfo.browser === BrowserName.CHROME || supportInfo.browser === BrowserName.EDGE) {
+                                throw new Error(`Digital Credentials API returned no response. This usually means the browser feature flag is not enabled. Please ensure the ${supportInfo.helpUrl || '#web-identity-digital-credentials flag'} is set to "Enabled" (not "Default" or "Disabled") and restart your browser.`);
+                            }
+                            throw new Error('Digital Credentials API returned no response. Your browser may not fully support this feature.');
+                        }
+                        const credentialData = digitalResponse.data;
+                        this.log('Secure credential response received', credentialData);
+                        return credentialData.vp_token;
+                    }
+                    catch (error) {
+                        // Capture detailed browser error information
+                        const errorObj = error;
+                        const browserErrorDetails = {
+                            name: errorObj.name || 'UnknownError',
+                            message: errorObj.message || 'Unknown error occurred',
+                            stack: errorObj.stack,
+                            code: errorObj.code
+                        };
+                        const errorContext = {
+                            step: 'prompt',
+                            timestamp: new Date().toISOString(),
+                            userAgent: navigator.userAgent,
+                            url: window.location.href,
+                            // Include request details for debugging
+                            authentication_strategy: plainResponse.authentication_strategy,
+                            hasSession: !!plainResponse.session
+                        };
+                        // Handle specific browser errors
+                        if (errorObj.name === BrowserError.NOT_ALLOWED) {
+                            throw this.createError(PhoneAuthErrorCode.USER_DENIED, 'User denied the credential request or the request timed out', {
+                                originalError: error,
+                                browserError: browserErrorDetails,
+                                context: errorContext
+                            });
+                        }
+                        // NetworkError with code 19 specifically indicates user cancellation in Digital Credentials API
+                        if (errorObj.name === BrowserError.NETWORK && errorObj.code === BrowserErrorCode.USER_CANCELLED_DC_API) {
+                            throw this.createError(PhoneAuthErrorCode.USER_DENIED, 'Authentication cancelled by user', {
+                                originalError: error,
+                                browserError: browserErrorDetails,
+                                context: errorContext
+                            });
+                        }
+                        // NetworkError without code 19 is a real network error
+                        if (errorObj.name === BrowserError.NETWORK) {
+                            throw this.createError(PhoneAuthErrorCode.NETWORK_ERROR, 'Network error occurred while retrieving credentials', {
+                                originalError: error,
+                                browserError: browserErrorDetails,
+                                context: errorContext
+                            });
+                        }
+                        if (errorObj.name === BrowserError.NOT_SUPPORTED) {
+                            throw this.createError(PhoneAuthErrorCode.BROWSER_NOT_SUPPORTED, 'Your browser does not support the Digital Credentials API', {
+                                originalError: error,
+                                browserError: browserErrorDetails,
+                                context: errorContext
+                            });
+                        }
+                        if (errorObj.name === BrowserError.SECURITY) {
+                            throw this.createError(PhoneAuthErrorCode.FORBIDDEN, 'Security error: This feature requires a secure context (HTTPS)', {
+                                originalError: error,
+                                browserError: browserErrorDetails,
+                                context: errorContext
+                            });
+                        }
+                        // Check for other cancellation patterns
+                        if (errorObj.name === BrowserError.ABORT ||
+                            ((_a = browserErrorDetails.message) === null || _a === void 0 ? void 0 : _a.includes('The operation was aborted')) ||
+                            ((_b = browserErrorDetails.message) === null || _b === void 0 ? void 0 : _b.includes('User cancelled'))) {
+                            throw this.createError(PhoneAuthErrorCode.USER_DENIED, 'Authentication cancelled', {
+                                originalError: error,
+                                browserError: browserErrorDetails,
+                                context: errorContext
+                            });
+                        }
+                        // For any other errors, capture all details
+                        throw this.createError(PhoneAuthErrorCode.INTERNAL_SERVER_ERROR, `Digital Credentials API error: ${errorObj.message || 'Unknown error'}`, {
+                            originalError: error,
+                            browserError: browserErrorDetails,
+                            context: errorContext
+                        });
+                    }
+                });
+                // IMPORTANT: For TS43, we ALWAYS call the API directly without any modal
+                // The Digital Credentials API provides its own OS-level UI (drawer/bottom sheet)
+                // Adding our own modal would be redundant and confusing for users
+                // Unlike Link (which needs a button for iOS App Clips), TS43 just needs direct invocation
+                // Enhanced trigger function with callback support
+                const enhancedTriggerTS43 = () => __awaiter(this, void 0, void 0, function* () {
+                    var _a, _b;
+                    try {
+                        const result = yield triggerTS43();
+                        (_a = invokeOptions === null || invokeOptions === void 0 ? void 0 : invokeOptions.onTriggerAttempt) === null || _a === void 0 ? void 0 : _a.call(invokeOptions, {
+                            strategy: API.AUTHENTICATION_STRATEGY.TS43,
+                            success: true
+                        });
+                        return result;
+                    }
+                    catch (error) {
+                        (_b = invokeOptions === null || invokeOptions === void 0 ? void 0 : invokeOptions.onTriggerAttempt) === null || _b === void 0 ? void 0 : _b.call(invokeOptions, {
+                            strategy: API.AUTHENTICATION_STRATEGY.TS43,
+                            success: false,
+                            error
+                        });
+                        throw error;
+                    }
+                });
+                // Headless mode for TS43 still returns the trigger function for custom UI
+                // This allows developers to control WHEN to trigger, but not HOW
+                if (isHeadless) {
+                    // Auto-trigger for TS43 if enabled (may fail due to browser restrictions)
+                    if ((invokeOptions === null || invokeOptions === void 0 ? void 0 : invokeOptions.autoTrigger) !== false) {
+                        try {
+                            // Try to trigger immediately if we have user gesture context
+                            const result = yield enhancedTriggerTS43();
+                            // If successful, return the result directly
+                            return result;
+                        }
+                        catch (error) {
+                            // If auto-trigger fails, continue to return HeadlessResult with trigger
+                            if (this.debug) {
+                                console.log('[TS43] Auto-trigger failed, returning trigger function:', error);
+                            }
+                        }
+                    }
+                    // Return trigger function for developers who want to control timing
+                    return {
+                        strategy: API.AUTHENTICATION_STRATEGY.TS43,
+                        credentialRequest: secureCredentialRequest,
+                        trigger: enhancedTriggerTS43,
+                        session: plainResponse.session
+                    };
+                }
+                else {
+                    // In UI mode, directly invoke the Digital Credentials API
+                    // No modal needed - the OS provides its own UI
+                    return yield enhancedTriggerTS43();
+                }
+            }
+            else if (plainResponse.authentication_strategy === API.AUTHENTICATION_STRATEGY.DESKTOP) {
+                // Desktop strategy - QR code based authentication
+                const desktopData = plainResponse.data;
+                // Check if headless mode is requested
+                if (isHeadless) {
+                    // Return raw data for custom UI implementation
+                    const handler = new DesktopHandler();
+                    // Start polling in the background
+                    const pollingPromise = handler.invoke(plainResponse, Object.assign(Object.assign({}, desktopOptions), { 
+                        // Don't pass config.endpoints.polling - let backend-provided status_url take priority
+                        pollingInterval: this.config.pollingInterval || 2000, maxPollingAttempts: this.config.maxPollingAttempts || 150, 
+                        // No UI callbacks in headless mode
+                        onQRCodeReady: undefined, onStatusUpdate: undefined })).then(result => {
+                        if (result.authenticated && result.credential) {
+                            // Extract session ID from nested or flat structure
+                            let sessionId = 'default';
+                            // Check if desktopData has nested structure
+                            if (desktopData && typeof desktopData === 'object') {
+                                if (desktopData.data && typeof desktopData.data === 'object') {
+                                    // Nested structure: data.data.session_id
+                                    sessionId = desktopData.data.session_id || sessionId;
+                                }
+                                // Also check flat structure
+                                if (!sessionId || sessionId === 'default') {
+                                    sessionId = desktopData.session_id || sessionId;
+                                }
+                            }
+                            // Return credential in expected format for subsequent API calls
+                            return {
+                                [sessionId]: result.credential
+                            };
+                        }
+                        else {
+                            throw this.createError(PhoneAuthErrorCode.USER_DENIED, result.error || 'Desktop authentication failed');
+                        }
+                    });
+                    return {
+                        strategy: API.AUTHENTICATION_STRATEGY.DESKTOP,
+                        qrCode: (_b = desktopData.data) === null || _b === void 0 ? void 0 : _b.qr_code_image, // data.data.qr_code_image
+                        pollingPromise,
+                        session: plainResponse.session
+                    };
+                }
+                else {
+                    // UI mode - show QR code modal
+                    const handler = new DesktopHandler();
+                    const modal = new AuthModal(invokeOptions === null || invokeOptions === void 0 ? void 0 : invokeOptions.modalOptions, invokeOptions === null || invokeOptions === void 0 ? void 0 : invokeOptions.callbacks);
+                    // Default options with modal display
+                    const options = Object.assign(Object.assign({}, desktopOptions), { 
+                        // Don't pass config.endpoints.polling - let backend-provided status_url take priority
+                        // Only explicit desktopOptions.pollingEndpoint will override backend URL
+                        pollingInterval: (desktopOptions === null || desktopOptions === void 0 ? void 0 : desktopOptions.pollingInterval) || this.config.pollingInterval || 2000, maxPollingAttempts: (desktopOptions === null || desktopOptions === void 0 ? void 0 : desktopOptions.maxPollingAttempts) || this.config.maxPollingAttempts || 150, onQRCodeReady: (qrCodeData) => {
+                            // Show QR code in modal (supports both single and dual-platform)
+                            modal.showQRCode(qrCodeData, 'Scan with your mobile device');
+                        }, onStatusUpdate: (status) => {
+                            // Update status in modal
+                            if (status.status === 'pending') {
+                                modal.updateStatus('Waiting for authentication...');
+                            }
+                            else if (status.status === 'authenticated') {
+                                modal.updateStatus('Authentication successful!');
+                                setTimeout(() => modal.close(), 1500);
+                            }
+                            else if (status.status === 'expired') {
+                                modal.updateStatus('QR code expired', true);
+                            }
+                            else if (status.status === 'error') {
+                                modal.updateStatus('Authentication failed', true);
+                            }
+                        } });
+                    try {
+                        const result = yield handler.invoke(plainResponse, options);
+                        if (result.authenticated && result.credential) {
+                            // Extract session ID from nested or flat structure
+                            let sessionId = 'default';
+                            // Check if desktopData has nested structure
+                            if (desktopData && typeof desktopData === 'object') {
+                                if (desktopData.data && typeof desktopData.data === 'object') {
+                                    // Nested structure: data.data.session_id
+                                    sessionId = desktopData.data.session_id || sessionId;
+                                }
+                                // Also check flat structure
+                                if (!sessionId || sessionId === 'default') {
+                                    sessionId = desktopData.session_id || sessionId;
+                                }
+                            }
+                            // Return credential in expected format for subsequent API calls
+                            return {
+                                [sessionId]: result.credential
+                            };
+                        }
+                        else {
+                            throw this.createError(PhoneAuthErrorCode.USER_DENIED, result.error || 'Desktop authentication failed');
+                        }
+                    }
+                    catch (error) {
+                        if (error instanceof Error && error.name === 'PhoneAuthError') {
+                            throw error;
+                        }
+                        throw this.createError(PhoneAuthErrorCode.INTERNAL_SERVER_ERROR, `Desktop authentication error: ${error instanceof Error ? error.message : 'Unknown error'}`, { originalError: error });
+                    }
+                    finally {
+                        // Ensure handler cleanup
+                        handler.cleanup();
+                        modal.close();
+                    }
+                }
+            }
+            else if (plainResponse.authentication_strategy === API.AUTHENTICATION_STRATEGY.LINK) {
+                // Link strategy - app-based authentication (iOS/Android)
+                const linkData = plainResponse.data;
+                // Check if headless mode is requested
+                if (isHeadless) {
+                    // Return raw data for custom UI implementation
+                    const handler = new LinkHandler();
+                    // Create reusable trigger function that ONLY opens the App Clip
+                    // This can be called multiple times without restarting polling
+                    const triggerLink = () => {
+                        var _a, _b;
+                        try {
+                            window.open(linkData.url, '_blank');
+                            (_a = invokeOptions === null || invokeOptions === void 0 ? void 0 : invokeOptions.onTriggerAttempt) === null || _a === void 0 ? void 0 : _a.call(invokeOptions, {
+                                strategy: API.AUTHENTICATION_STRATEGY.LINK,
+                                url: linkData.url,
+                                success: true
+                            });
+                        }
+                        catch (error) {
+                            (_b = invokeOptions === null || invokeOptions === void 0 ? void 0 : invokeOptions.onTriggerAttempt) === null || _b === void 0 ? void 0 : _b.call(invokeOptions, {
+                                strategy: API.AUTHENTICATION_STRATEGY.LINK,
+                                url: linkData.url,
+                                success: false,
+                                error
+                            });
+                        }
+                    };
+                    // Auto-trigger by default for Link strategy
+                    // This opens the App Clip immediately while preserving user gesture context
+                    if ((invokeOptions === null || invokeOptions === void 0 ? void 0 : invokeOptions.autoTrigger) !== false) {
+                        triggerLink();
+                    }
+                    // Start polling in the background (independent of trigger)
+                    const pollingPromise = new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
+                        var _a;
+                        try {
+                            const result = yield handler.invoke(plainResponse, {
+                                pollingEndpoint: (_a = this.config.endpoints) === null || _a === void 0 ? void 0 : _a.polling,
+                                pollingInterval: this.config.pollingInterval || 2000,
+                                maxPollingAttempts: this.config.maxPollingAttempts || 150,
+                                // openMethod removed - always uses window.open()
+                                onLinkOpened: undefined,
+                                onStatusUpdate: undefined
+                            });
+                            if (result.authenticated && result.credential) {
+                                // Return credential in the expected format
+                                const aggregatorId = this.config.aggregatorId || 'default';
+                                resolve({ [aggregatorId]: result.credential });
+                            }
+                            else {
+                                reject(this.createError(PhoneAuthErrorCode.USER_DENIED, result.error || 'Link authentication failed'));
+                            }
+                        }
+                        catch (error) {
+                            reject(error);
+                        }
+                    }));
+                    return {
+                        strategy: API.AUTHENTICATION_STRATEGY.LINK,
+                        url: linkData.url,
+                        pollingPromise,
+                        session: plainResponse.session,
+                        // Trigger function to open App Clip (can be called multiple times)
+                        // Does NOT restart polling - just opens the URL
+                        trigger: triggerLink
+                    };
+                }
+                else {
+                    // UI mode - show button to open app link
+                    const modal = new AuthModal(invokeOptions === null || invokeOptions === void 0 ? void 0 : invokeOptions.modalOptions, invokeOptions === null || invokeOptions === void 0 ? void 0 : invokeOptions.callbacks);
+                    const handler = new LinkHandler();
+                    // Show link button in modal - user MUST click the button to open the app link
+                    // This is critical for iOS to recognize the app link (requires user interaction)
+                    yield modal.showLinkButton(linkData.url);
+                    // Link options - the app link will be opened by user clicking the modal button
+                    const options = {
+                        // Use configured polling endpoint if available
+                        pollingEndpoint: (_c = this.config.endpoints) === null || _c === void 0 ? void 0 : _c.polling,
+                        pollingInterval: this.config.pollingInterval || 2000, // Default 2 second interval
+                        maxPollingAttempts: this.config.maxPollingAttempts || 150, // Default 5 minutes total
+                        onLinkOpened: () => {
+                            this.log('Authentication app link opened');
+                            modal.updateStatus('Waiting for app authentication...');
+                        },
+                        onStatusUpdate: (status) => {
+                            this.log('Link authentication status update:', status);
+                            if (status.status === 'authenticated') {
+                                modal.updateStatus('Authentication successful!');
+                                setTimeout(() => modal.close(), 1500);
+                            }
+                            else if (status.status === 'error') {
+                                modal.updateStatus('Authentication failed', true);
+                            }
+                        },
+                        onTimeout: () => {
+                            this.log('Link authentication timed out');
+                            modal.updateStatus('Authentication timed out', true);
+                        }
+                    };
+                    try {
+                        const result = yield handler.invoke(plainResponse, options);
+                        if (result.authenticated && result.credential) {
+                            // Return the credential for further processing
+                            // The credential is typically the session key
+                            const aggregatorId = this.config.aggregatorId || 'default';
+                            modal.close();
+                            return { [aggregatorId]: result.credential };
+                        }
+                        else {
+                            throw this.createError(PhoneAuthErrorCode.VERIFICATION_FAILED, result.error || 'Link authentication failed');
+                        }
+                    }
+                    catch (error) {
+                        modal.close();
+                        if (error instanceof Error && error.name === 'PhoneAuthError') {
+                            throw error;
+                        }
+                        throw this.createError(PhoneAuthErrorCode.INTERNAL_SERVER_ERROR, `Link authentication error: ${error instanceof Error ? error.message : 'Unknown error'}`, { originalError: error });
+                    }
+                    finally {
+                        // Ensure handler cleanup
+                        handler.cleanup();
+                    }
+                }
+            }
+            else {
+                // Unknown strategy
+                throw this.createError(PhoneAuthErrorCode.UNSUPPORTED_STRATEGY, `Unknown authentication strategy: ${plainResponse.authentication_strategy}`);
+            }
+        });
+    }
+    /**
+     * Step 3A: Get phone number from credential
+     *
+     * @example
+     * ```typescript
+     * const prepareResp = await phoneAuthClient.preparePhoneRequest({ useCase: 'GetPhoneNumber', plmn: {...} });
+     * const credential = await phoneAuthClient.invokeSecurePrompt(prepareResp);
+     * const result = await phoneAuthClient.getPhoneNumber(credential, prepareResp.session);
+     * console.log(result.phone_number); // +1234567890
+     * ```
+     */
+    getPhoneNumber(credentialResponse, session) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Extract credential string
+            const credentialString = this.extractCredentialString(credentialResponse);
+            // Build request body for GetPhoneNumber
+            const requestBody = {
+                session: session,
+                credential: credentialString,
+                use_case: API.USE_CASE.GET_PHONE_NUMBER // Required for server routing
+            };
+            // Only show full details in debug mode, mask sensitive data otherwise
+            if (this.config.debug) {
+                this.log('Getting phone number from credential', {
+                    session: session,
+                    credential: credentialString ? credentialString.substring(0, 50) + '...' : 'undefined', // Show partial for debugging
+                    endpoint: this.config.endpoints.process || '/api/phone-auth/process'
+                });
+            }
+            else {
+                this.log('Getting phone number from credential');
+            }
+            try {
+                const response = yield this.fetchWithTimeout(this.config.endpoints.process || '/api/phone-auth/process', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(requestBody)
+                });
+                if (!response.ok) {
+                    const errorDetails = yield this.extractErrorDetails(response);
+                    const parsedError = parseBackendError(errorDetails);
+                    parsedError.context = {
+                        step: 'process',
+                        timestamp: new Date().toISOString(),
+                        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : undefined,
+                        url: typeof window !== 'undefined' ? window.location.href : undefined
+                    };
+                    throw parsedError;
+                }
+                const data = yield response.json();
+                this.log('Phone number retrieved', { phone_number: data.phone_number });
+                if (!data.phone_number) {
+                    throw this.createError(PhoneAuthErrorCode.VERIFICATION_FAILED, 'No phone number returned from server');
+                }
+                return data;
+            }
+            catch (error) {
+                if (this.isAuthError(error))
+                    throw error;
+                throw this.createError(PhoneAuthErrorCode.NETWORK_ERROR, 'Failed to get phone number', {
+                    originalError: error,
+                    context: {
+                        step: 'process',
+                        timestamp: new Date().toISOString()
+                    }
+                });
+            }
+        });
+    }
+    /**
+     * Step 3B: Verify phone number with credential
+     *
+     * @example
+     * ```typescript
+     * const prepareResp = await phoneAuthClient.preparePhoneRequest({
+     *   useCase: 'VerifyPhoneNumber',
+     *   phoneNumber: '+1234567890'
+     * });
+     * const credential = await phoneAuthClient.invokeSecurePrompt(prepareResp);
+     * const result = await phoneAuthClient.verifyPhoneNumber(credential, prepareResp.session);
+     * console.log(result.verified); // true
+     * ```
+     */
+    verifyPhoneNumber(credentialResponse, session) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Extract credential string
+            const credentialString = this.extractCredentialString(credentialResponse);
+            // Build request body for VerifyPhoneNumber
+            const requestBody = {
+                session: session,
+                credential: credentialString,
+                use_case: API.USE_CASE.VERIFY_PHONE_NUMBER // Required for server routing
+            };
+            // Only show full details in debug mode, mask sensitive data otherwise
+            if (this.config.debug) {
+                this.log('Verifying phone number with credential', {
+                    session: session,
+                    credential: credentialString ? credentialString.substring(0, 50) + '...' : 'undefined', // Show partial for debugging
+                    endpoint: this.config.endpoints.process || '/api/phone-auth/process'
+                });
+            }
+            else {
+                this.log('Verifying phone number');
+            }
+            try {
+                const response = yield this.fetchWithTimeout(this.config.endpoints.process || '/api/phone-auth/process', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(requestBody)
+                });
+                if (!response.ok) {
+                    const errorDetails = yield this.extractErrorDetails(response);
+                    const parsedError = parseBackendError(errorDetails);
+                    parsedError.context = {
+                        step: 'process',
+                        timestamp: new Date().toISOString(),
+                        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : undefined,
+                        url: typeof window !== 'undefined' ? window.location.href : undefined
+                    };
+                    throw parsedError;
+                }
+                const data = yield response.json();
+                this.log('Phone number verification result', {
+                    phone_number: data.phone_number,
+                    verified: data.verified
+                });
+                if (!data.phone_number) {
+                    throw this.createError(PhoneAuthErrorCode.VERIFICATION_FAILED, 'No phone number returned from server');
+                }
+                return data;
+            }
+            catch (error) {
+                if (this.isAuthError(error))
+                    throw error;
+                throw this.createError(PhoneAuthErrorCode.NETWORK_ERROR, 'Failed to verify phone number', {
+                    originalError: error,
+                    context: {
+                        step: 'process',
+                        timestamp: new Date().toISOString()
+                    }
+                });
+            }
+        });
+    }
+    /**
+     * Helper to extract credential string from various formats
+     */
+    extractCredentialString(credentialResponse) {
+        // If already a string, return it
+        if (typeof credentialResponse === 'string') {
+            return credentialResponse;
+        }
+        // Extract from vp_token object - try configured aggregatorId first, then 'glide', then 'default'
+        let credential = credentialResponse[this.config.aggregatorId || 'glide'];
+        // Fallback to 'glide' if not found
+        if (!credential && credentialResponse['glide']) {
+            credential = credentialResponse['glide'];
+        }
+        // Fallback to 'default' if still not found
+        if (!credential && credentialResponse['default']) {
+            credential = credentialResponse['default'];
+        }
+        // If still not found, try to get the first available key
+        if (!credential) {
+            const keys = Object.keys(credentialResponse);
+            if (keys.length > 0) {
+                credential = credentialResponse[keys[0]];
+            }
+        }
+        // Convert array to string if needed
+        return Array.isArray(credential) ? credential[0] : credential;
+    }
+    /**
+     * Helper to extract error details from response
+     */
+    extractErrorDetails(response) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const errorData = yield response.json();
+                // Always include the HTTP status from the response
+                return Object.assign(Object.assign({}, errorData), { status: response.status // Ensure HTTP status is included
+                 });
+            }
+            catch (_a) {
+                return { status: response.status, statusText: response.statusText };
+            }
+        });
+    }
+    /**
+     * Fetch with timeout
+     */
+    fetchWithTimeout(url, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.config.timeout);
+            try {
+                return yield fetch(url, Object.assign(Object.assign({}, options), { signal: controller.signal }));
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        });
+    }
+    /**
+     * Create an AuthError
+     */
+    createError(code, message, details) {
+        const error = {
+            code,
+            message,
+            details: (details === null || details === void 0 ? void 0 : details.originalError) ? Object.assign(Object.assign({}, details), { originalError: undefined // Remove the original error object
+             }) : details
+        };
+        // Add browser error details if present
+        if (details === null || details === void 0 ? void 0 : details.browserError) {
+            error.browserError = details.browserError;
+        }
+        // Add context if present
+        if (details === null || details === void 0 ? void 0 : details.context) {
+            error.context = details.context;
+        }
+        // Add other specific fields
+        if (details === null || details === void 0 ? void 0 : details.status) {
+            error.status = details.status;
+        }
+        if (details === null || details === void 0 ? void 0 : details.requestId) {
+            error.requestId = details.requestId;
+        }
+        if (details === null || details === void 0 ? void 0 : details.timestamp) {
+            error.timestamp = details.timestamp;
+        }
+        if (details === null || details === void 0 ? void 0 : details.retryAfter) {
+            error.retryAfter = details.retryAfter;
+        }
+        return error;
+    }
+    /**
+     * Type guard for AuthError
+     */
+    isAuthError(error) {
+        return error && typeof error.code === 'string' && typeof error.message === 'string';
+    }
+    /**
+     * Debug logging
+     */
+    log(...args) {
+        if (this.debug) {
+            console.log('[PhoneAuth]', ...args);
+        }
+    }
+    /**
+     * Determine if an error should trigger a retry
+     */
+    shouldRetry(error) {
+        var _a, _b, _c;
+        // Don't retry on 4xx client errors (these are not transient)
+        if (error.status && error.status >= 400 && error.status < 500) {
+            return false;
+        }
+        // Don't retry on explicit user denial or unsupported browser
+        // USER_DENIED cannot be retried automatically because the Digital Credentials API
+        // requires user interaction (transient activation)
+        const nonRetryableCodes = [
+            'USER_DENIED',
+            'BROWSER_NOT_SUPPORTED',
+            'INVALID_PHONE_NUMBER',
+            'INVALID_PARAMETERS',
+            'MISSING_PARAMETERS',
+            'UNPROCESSABLE_ENTITY', // 422 errors
+            'USE_CASE_MISMATCH', // Use case validation errors
+            'PHONE_NUMBER_MISMATCH', // Phone verification failures
+            'VERIFICATION_FAILED', // Verification failures
+            'INVALID_CREDENTIAL', // Bad credentials
+            'CARRIER_NOT_ELIGIBLE', // Carrier not supported
+            'SESSION_EXPIRED', // Session expired
+            'INVALID_SESSION' // Invalid session
+        ];
+        if (nonRetryableCodes.includes(error.code)) {
+            return false;
+        }
+        // Only retry on network and server errors (5xx)
+        const retryableCodes = [
+            'NETWORK_ERROR',
+            'REQUEST_TIMEOUT',
+            'GATEWAY_TIMEOUT',
+            'SERVICE_UNAVAILABLE',
+            'BAD_GATEWAY',
+            'INTERNAL_SERVER_ERROR'
+        ];
+        // Also check for cross-device error types in details
+        const isCrossDeviceError = ((_a = error.details) === null || _a === void 0 ? void 0 : _a.errorType) && [
+            'CROSS_DEVICE_TIMEOUT',
+            'CROSS_DEVICE_CONNECTION_LOST',
+            'CROSS_DEVICE_INCOMPLETE'
+        ].includes(error.details.errorType);
+        return retryableCodes.includes(error.code) ||
+            isCrossDeviceError ||
+            (((_b = error.browserError) === null || _b === void 0 ? void 0 : _b.name) === 'NetworkError' && ((_c = error.browserError) === null || _c === void 0 ? void 0 : _c.code) !== 19);
+    }
+    /**
+     * Analyze and enhance errors specific to cross-device flows
+     */
+    analyzeCrossDeviceError(error, prepareResponse) {
+        var _a;
+        const errorObj = error;
+        // Check for specific cross-device error patterns
+        const isCrossDeviceTimeout = (errorObj.name === 'AbortError' && this.crossDeviceActive) ||
+            (((_a = errorObj.message) === null || _a === void 0 ? void 0 : _a.includes('timeout')) && this.crossDeviceActive);
+        const isCrossDeviceNetworkIssue = errorObj.name === 'NetworkError' &&
+            errorObj.code !== 19 && // Not user cancellation
+            this.crossDeviceActive;
+        if (isCrossDeviceTimeout) {
+            return {
+                code: 'REQUEST_TIMEOUT',
+                message: 'Cross-device authentication timed out. The QR code may have expired or the phone connection was lost.',
+                details: {
+                    suggestion: 'Try again and complete the phone authentication within 2 minutes',
+                    originalError: errorObj.message,
+                    crossDevice: true,
+                    errorType: 'CROSS_DEVICE_TIMEOUT'
+                },
+                browserError: error.browserError
+            };
+        }
+        if (isCrossDeviceNetworkIssue) {
+            return {
+                code: 'NETWORK_ERROR',
+                message: 'Connection lost during cross-device authentication. Please ensure both devices have stable internet.',
+                details: {
+                    suggestion: 'Check your network connection on both devices and try again',
+                    originalError: errorObj.message,
+                    crossDevice: true,
+                    errorType: 'CROSS_DEVICE_CONNECTION_LOST'
+                },
+                browserError: error.browserError
+            };
+        }
+        // Return the original error if not cross-device specific
+        return error;
+    }
+    /**
+     * Cache successful session for retry scenarios
+     */
+    cacheSession(options, result) {
+        const cacheKey = this.getCacheKey(options);
+        this.sessionCache.set(cacheKey, {
+            timestamp: Date.now(),
+            data: result
+        });
+    }
+    /**
+     * Retrieve cached session if available and recent
+     */
+    getCachedSession(options) {
+        const cacheKey = this.getCacheKey(options);
+        const cached = this.sessionCache.get(cacheKey);
+        if (!cached)
+            return null;
+        // Cache valid for 5 minutes
+        const cacheValidMs = 5 * 60 * 1000;
+        if (Date.now() - cached.timestamp > cacheValidMs) {
+            this.sessionCache.delete(cacheKey);
+            return null;
+        }
+        return cached.data;
+    }
+    /**
+     * Generate cache key for session storage
+     */
+    getCacheKey(options) {
+        var _a, _b;
+        return `${options.use_case}-${options.phone_number || 'no-phone'}-${((_a = options.plmn) === null || _a === void 0 ? void 0 : _a.mcc) || ''}-${((_b = options.plmn) === null || _b === void 0 ? void 0 : _b.mnc) || ''}`;
+    }
+    /**
+     * Set up periodic cache cleanup
+     */
+    setupCacheCleanup() {
+        // Only run cleanup in browser environment (not during SSR)
+        if (typeof window === 'undefined') {
+            return;
+        }
+        // Clean up expired cache entries every minute
+        setInterval(() => {
+            const now = Date.now();
+            const cacheValidMs = 5 * 60 * 1000;
+            for (const [key, value] of this.sessionCache.entries()) {
+                if (now - value.timestamp > cacheValidMs) {
+                    this.sessionCache.delete(key);
+                }
+            }
+        }, 60000);
+    }
+    /**
+     * Utility delay function
+     */
+    delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}