@glideidentity/web-client-sdk 5.0.1 → 5.1.1-beta.1

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

@@ -7,10 +7,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         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, validateNonce } from './validation-utils';
+import { validatePhoneNumber, validatePlmn } from './validation-utils';
 import { LoggerFactory } from '../logger';
 import { DesktopHandler } from './strategies/desktop';
 import { LinkHandler } from './strategies/link';
@@ -21,31 +22,41 @@ export class PhoneAuthClient {
         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',
-                polling: (_c = config.endpoints) === null || _c === void 0 ? void 0 : _c.polling
+                polling: (_c = config.endpoints) === null || _c === void 0 ? void 0 : _c.polling // Pass through the polling endpoint
             },
             timeout: config.timeout || 30000,
-            pollingInterval: config.pollingInterval || 2000,
-            maxPollingAttempts: config.maxPollingAttempts || 30,
+            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',
+            devEnv: config.devEnv,
             devtools: config.devtools
         };
         this.debug = this.config.debug;
+        // Log initialization with devEnv if set
+        if (config.devEnv) {
+            console.log(`[PhoneAuth] Initialized with devEnv: ${config.devEnv}`);
+        }
+        // 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 (((_d = config.devtools) === null || _d === void 0 ? void 0 : _d.showMobileConsole) && typeof window !== 'undefined') {
             import('./ui/mobile-debug-console').then(({ MobileDebugConsole }) => {
                 MobileDebugConsole.init();
@@ -54,21 +65,32 @@ export class PhoneAuthClient {
                 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,
@@ -77,11 +99,20 @@ export class PhoneAuthClient {
             });
         }
     }
+    /**
+     * 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 {
@@ -100,6 +131,7 @@ export class PhoneAuthClient {
                 browser: isChrome ? BrowserName.CHROME : isEdge ? BrowserName.EDGE : BrowserName.OTHER
             };
         }
+        // Provide specific guidance based on browser
         if (isChrome || isEdge) {
             return {
                 supported: false,
@@ -116,11 +148,16 @@ export class PhoneAuthClient {
             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;
+            const maxRetries = 2; // Default max retries
+            // Try verification with silent retries
             return this.verifyWithRetry(options, maxRetries);
         });
     }
@@ -128,38 +165,55 @@ export class PhoneAuthClient {
         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;
+                // Validate use_case is provided for endpoint selection
                 if (!options.use_case) {
                     throw this.createError(PhoneAuthErrorCode.MISSING_PARAMETERS, 'use_case is required', { field: 'use_case' });
                 }
                 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})`);
                     }
-                    yield this.delay(Math.min(1000 * Math.pow(2, this.retryCount - 1), 5000));
+                    // 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,
@@ -168,11 +222,15 @@ export class PhoneAuthClient {
                     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,
@@ -197,35 +255,60 @@ export class PhoneAuthClient {
             }
         });
     }
+    /**
+     * 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* () {
             var _a, _b, _c;
+            // 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 use_case is provided (unless only parent_session_id is given)
             if (!options.use_case && !(((_a = options.options) === null || _a === void 0 ? void 0 : _a.parent_session_id) && !options.phone_number && !options.plmn)) {
                 throw this.createError(PhoneAuthErrorCode.MISSING_PARAMETERS, 'use_case is required', { field: 'use_case' });
             }
+            // Validate required parameters based on use case
             if (!options.phone_number && !options.plmn && !((_b = options.options) === null || _b === void 0 ? void 0 : _b.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' });
                 }
@@ -233,36 +316,39 @@ export class PhoneAuthClient {
                     throw this.createError(PhoneAuthErrorCode.MISSING_PARAMETERS, 'Phone number is required for VerifyPhoneNumber', { field: 'phoneNumber', useCase: 'VerifyPhoneNumber' });
                 }
                 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' });
                 }
             }
+            // Log parent session usage
             if (((_c = options.options) === null || _c === void 0 ? void 0 : _c.parent_session_id) && !options.phone_number && !options.plmn) {
                 if (this.debug) {
                     console.log('[PhoneAuth] Using parent_session_id: %s, use_case: %s', options.options.parent_session_id, options.use_case || 'not provided');
                 }
             }
             const requestId = `web-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
-            const nonce = btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(32))))
-                .replace(/\+/g, '-')
-                .replace(/\//g, '_')
-                .replace(/=/g, '');
-            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
+            // Be permissive - backend will ignore extra fields if not needed
             const requestBody = {
+                // Include use_case if provided (optional when parent_session_id is given)
                 use_case: options.use_case,
+                // Include phone_number if provided (backend ignores if not needed)
                 phone_number: options.phone_number,
+                // Include PLMN if provided
                 plmn: options.plmn ? {
                     mcc: options.plmn.mcc,
                     mnc: options.plmn.mnc
                 } : undefined,
-                nonce: nonce,
+                // Auto-generated request ID
                 id: requestId,
+                // Optional fields
                 client_info: {
                     user_agent: navigator.userAgent,
-                    platform: navigator.platform
+                    platform: navigator.platform,
+                    // user_agent: "Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36",
+                    // platform: "Android"
                 },
+                // Advanced options (for desktop-mobile binding and future features)
                 options: options.options
             };
             this.log('Preparing phone verification request', requestBody);
@@ -273,15 +359,20 @@ export class PhoneAuthClient {
                     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 (_d) {
+                        // 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,
@@ -289,6 +380,7 @@ export class PhoneAuthClient {
                         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;
                 }
@@ -297,12 +389,16 @@ export class PhoneAuthClient {
                 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: {
@@ -316,16 +412,68 @@ export class PhoneAuthClient {
             }
         });
     }
+    /**
+     * 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 Extended Mode (returns control methods)
+     * ```typescript
+     * // Get control methods for custom implementation
+     * const result = await phoneAuth.invokeSecurePrompt(prepareResult, {
+     *   executionMode: 'extended',
+     *   preventDefaultUI: true  // Desktop: no modal
+     * });
+     *
+     * if (result.strategy === 'desktop') {
+     *   // Show custom QR UI
+     *   showCustomQR(result.qr_code_data);
+     *   // Start polling
+     *   await result.start_polling();
+     * }
+     * ```
+     *
+     * @param prepareResponse - Response from prepare() with strategy and data
+     * @param options - Control UI behavior and response type
+     * @returns Credential or ExtendedResponse based on executionMode
+     */
     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, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+            // 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);
                 }
@@ -335,11 +483,16 @@ export class PhoneAuthClient {
             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));
+            // Treat options as InvokeOptions (the modern format)
+            // Legacy DesktopAuthOptions properties will still work through property access
             const opts = options;
+            // Get configuration from options - access properties directly
             const strategy = plainResponse.authentication_strategy;
             const preventDefaultUI = (_a = opts === null || opts === void 0 ? void 0 : opts.preventDefaultUI) !== null && _a !== void 0 ? _a : false;
             const executionMode = (_b = opts === null || opts === void 0 ? void 0 : opts.executionMode) !== null && _b !== void 0 ? _b : 'standard';
+            // 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');
                 }
@@ -353,13 +506,18 @@ export class PhoneAuthClient {
                     }
                 };
                 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.`);
@@ -371,6 +529,7 @@ export class PhoneAuthClient {
                         return credentialData.vp_token;
                     }
                     catch (error) {
+                        // Capture detailed browser error information
                         const errorObj = error;
                         const browserErrorDetails = {
                             name: errorObj.name || 'UnknownError',
@@ -383,9 +542,11 @@ export class PhoneAuthClient {
                             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,
@@ -393,6 +554,7 @@ export class PhoneAuthClient {
                                 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,
@@ -400,6 +562,7 @@ export class PhoneAuthClient {
                                 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,
@@ -421,6 +584,7 @@ export class PhoneAuthClient {
                                 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'))) {
@@ -430,6 +594,7 @@ export class PhoneAuthClient {
                                 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,
@@ -437,6 +602,11 @@ export class PhoneAuthClient {
                         });
                     }
                 });
+                // 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 {
@@ -456,11 +626,16 @@ export class PhoneAuthClient {
                         throw error;
                     }
                 });
+                // TS43 always auto-triggers (no SDK UI ever)
+                // The Digital Credentials API provides its own OS-level UI
+                // Use a wrapper object to allow updating the promise reference
                 const credentialWrapper = {
                     promise: null
                 };
                 try {
+                    // Always try to trigger immediately
                     const vpToken = yield enhancedTriggerTS43();
+                    // Convert to AuthCredential format
                     credentialWrapper.promise = Promise.resolve({
                         credential: typeof vpToken === 'string' ? vpToken : Object.values(vpToken)[0],
                         session: plainResponse.session,
@@ -468,25 +643,34 @@ export class PhoneAuthClient {
                     });
                 }
                 catch (error) {
+                    // If auto-trigger fails, create a rejected promise
                     credentialWrapper.promise = Promise.reject(error);
                 }
+                // Handle based on execution mode
                 if (executionMode === 'extended') {
+                    // Extended mode - return control methods
                     const response = {
                         strategy: 'ts43',
                         session: plainResponse.session,
-                        credential: credentialWrapper.promise,
+                        credential: credentialWrapper.promise, // Initial value
+                        // Re-trigger credential request
                         trigger: () => __awaiter(this, void 0, void 0, function* () {
                             const vpToken = yield enhancedTriggerTS43();
+                            // Update the credential promise in the wrapper
                             credentialWrapper.promise = Promise.resolve({
                                 credential: typeof vpToken === 'string' ? vpToken : Object.values(vpToken)[0],
                                 session: plainResponse.session,
                                 authenticated: true
                             });
+                            // Return void as per interface
                         }),
                         cancel: () => {
+                            // TS43 doesn't have a way to cancel once triggered
+                            // but we can reject the promise
                             credentialWrapper.promise = Promise.reject(this.createError(PhoneAuthErrorCode.USER_DENIED, 'Authentication cancelled'));
                         }
                     };
+                    // Define credential as a getter that always returns the current promise
                     Object.defineProperty(response, 'credential', {
                         get() {
                             return credentialWrapper.promise;
@@ -497,15 +681,20 @@ export class PhoneAuthClient {
                     return response;
                 }
                 else {
+                    // Standard mode - just return credential
+                    // Wait for and return the credential
                     const credential = yield credentialWrapper.promise;
+                    // Return in standard format
                     return {
                         [plainResponse.session.session_key]: credential.credential
                     };
                 }
             }
             else if (plainResponse.authentication_strategy === API.AUTHENTICATION_STRATEGY.DESKTOP) {
+                // Desktop strategy - QR code based authentication
                 const desktopData = plainResponse.data;
                 const handler = new DesktopHandler();
+                // Extract QR code data - convert to QRCodeData format for modal
                 const qrCodeData = {
                     iosQRCode: ((_c = desktopData.data) === null || _c === void 0 ? void 0 : _c.ios_qr_image) || desktopData.ios_qr_image ||
                         ((_d = desktopData.data) === null || _d === void 0 ? void 0 : _d.qr_code_image) || desktopData.qr_code_image || desktopData.qr_code || '',
@@ -513,15 +702,18 @@ export class PhoneAuthClient {
                     iosUrl: ((_f = desktopData.data) === null || _f === void 0 ? void 0 : _f.ios_url) || desktopData.ios_url,
                     androidUrl: ((_g = desktopData.data) === null || _g === void 0 ? void 0 : _g.android_url) || desktopData.android_url
                 };
+                // Also keep snake_case format for extended response
                 const qrCodeDataSnakeCase = {
                     ios_qr_image: ((_h = desktopData.data) === null || _h === void 0 ? void 0 : _h.ios_qr_image) || desktopData.ios_qr_image,
                     android_qr_image: ((_j = desktopData.data) === null || _j === void 0 ? void 0 : _j.android_qr_image) || desktopData.android_qr_image,
                     qr_code: ((_k = desktopData.data) === null || _k === void 0 ? void 0 : _k.qr_code_image) || desktopData.qr_code_image || desktopData.qr_code,
                     challenge: (_l = desktopData.data) === null || _l === void 0 ? void 0 : _l.challenge
                 };
+                // Polling options - gather from any options format
                 const pollingEndpointToUse = (opts === null || opts === void 0 ? void 0 : opts.pollingEndpoint) ||
                     ((_m = this.config.endpoints) === null || _m === void 0 ? void 0 : _m.polling);
-                const pollingOptions = Object.assign(Object.assign({}, opts), { pollingEndpoint: pollingEndpointToUse, pollingInterval: (opts === null || opts === void 0 ? void 0 : opts.pollingInterval) || this.config.pollingInterval || 2000, maxPollingAttempts: (opts === null || opts === void 0 ? void 0 : opts.maxPollingAttempts) || this.config.maxPollingAttempts || 30, onQRCodeReady: undefined, onStatusUpdate: undefined });
+                const pollingOptions = Object.assign(Object.assign({}, opts), { pollingEndpoint: pollingEndpointToUse, pollingInterval: (opts === null || opts === void 0 ? void 0 : opts.pollingInterval) || this.config.pollingInterval || 2000, maxPollingAttempts: (opts === null || opts === void 0 ? void 0 : opts.maxPollingAttempts) || this.config.maxPollingAttempts || 30, devEnv: (opts === null || opts === void 0 ? void 0 : opts.devEnv) || this.config.devEnv, onQRCodeReady: undefined, onStatusUpdate: undefined });
+                // Decide whether to show modal based on preventDefaultUI
                 const showModal = !preventDefaultUI;
                 let modal;
                 let modalRef = undefined;
@@ -533,27 +725,40 @@ export class PhoneAuthClient {
                 });
                 if (showModal) {
                     console.log('[Desktop] Creating modal with QR data:', qrCodeData);
+                    // Create and setup modal
                     modal = new AuthModal(opts === null || opts === void 0 ? void 0 : opts.modalOptions, opts === null || opts === void 0 ? void 0 : opts.callbacks);
                     modal.setCloseCallback(() => {
                         this.log('Desktop QR modal closed by user, cancelling polling');
                         handler.cancel();
                     });
+                    // Add UI callbacks to polling options
                     pollingOptions.onQRCodeReady = (qrData) => {
                         console.log('[Desktop] onQRCodeReady callback triggered:', qrData);
                         modal.showQRCode(qrData, 'Scan with your mobile device');
                     };
                     pollingOptions.onStatusUpdate = (status) => {
-                        if (status.status === 'authenticated' ||
-                            status.status === 'error' ||
-                            status.status === 'expired') {
-                            modal.close();
+                        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);
                         }
                     };
+                    // Note: We don't show the QR code here. It will be shown by the onQRCodeReady callback
+                    // that gets triggered immediately when handler.invoke() is called
                     modalRef = modal;
                 }
                 else {
                     console.log('[Desktop] Modal not shown - preventDefaultUI is true');
                 }
+                // Create credential promise
                 const startPolling = () => handler.invoke(plainResponse, pollingOptions).then(result => {
                     if (result.authenticated && result.credential) {
                         return {
@@ -566,13 +771,22 @@ export class PhoneAuthClient {
                         throw this.createError(PhoneAuthErrorCode.USER_DENIED, result.error || 'Desktop authentication failed');
                     }
                 });
+                // Handle based on execution mode
                 if (executionMode === 'extended') {
+                    // Extended mode - return control methods
+                    // Create a promise and always start polling immediately
                     const credentialPromise = new Promise((resolve, reject) => {
+                        // Always start polling immediately in extended mode (consistent with Link)
+                        // This prevents the "unresolved promise trap" where developers might await
+                        // the credential before calling start_polling()
                         startPolling()
                             .then(resolve)
                             .catch(reject);
                     });
+                    // Create wrapped functions
                     const wrappedStartPolling = () => __awaiter(this, void 0, void 0, function* () {
+                        // Polling has already started automatically in extended mode
+                        // This method just returns the existing credential promise for consistency
                         return credentialPromise;
                     });
                     const wrappedStopPolling = () => {
@@ -585,7 +799,9 @@ export class PhoneAuthClient {
                         handler.cleanup();
                         if (modal)
                             modal.close();
+                        // The credential promise will be rejected by the handler.cancel() call
                     };
+                    // Create the response object with a getter for is_polling
                     const response = {
                         strategy: 'desktop',
                         session: plainResponse.session,
@@ -595,8 +811,10 @@ export class PhoneAuthClient {
                         start_polling: wrappedStartPolling,
                         stop_polling: wrappedStopPolling,
                         cancel: wrappedCancel,
-                        is_polling: false
+                        // This will be replaced with a getter
+                        is_polling: false // Initial value, will be overridden by getter
                     };
+                    // Define is_polling as a getter that returns current state
                     Object.defineProperty(response, 'is_polling', {
                         get() {
                             return handler.isPolling();
@@ -607,8 +825,11 @@ export class PhoneAuthClient {
                     return response;
                 }
                 else {
+                    // Standard mode - return credential when complete
+                    // Start polling and wait for result
                     try {
                         const credential = yield startPolling();
+                        // Extract session ID for compatibility
                         let sessionId = 'default';
                         if (desktopData && typeof desktopData === 'object') {
                             if (desktopData.data && typeof desktopData.data === 'object') {
@@ -628,8 +849,10 @@ export class PhoneAuthClient {
                 }
             }
             else if (plainResponse.authentication_strategy === API.AUTHENTICATION_STRATEGY.LINK) {
+                // Link strategy - app-based authentication (iOS/Android)
                 const linkData = plainResponse.data;
                 const handler = new LinkHandler();
+                // Create reusable trigger function that ONLY opens the App Clip
                 const triggerLink = () => {
                     var _a, _b;
                     try {
@@ -649,9 +872,12 @@ export class PhoneAuthClient {
                         });
                     }
                 };
+                // Link always auto-opens the app (no SDK UI by default)
+                // Open immediately to preserve user gesture context
                 if ((opts === null || opts === void 0 ? void 0 : opts.autoTrigger) !== false) {
                     triggerLink();
                 }
+                // Start polling in the background
                 console.log('[PhoneAuth Client] Link polling config:', {
                     fromOptions: opts === null || opts === void 0 ? void 0 : opts.pollingEndpoint,
                     fromClientConfig: (_o = this.config.endpoints) === null || _o === void 0 ? void 0 : _o.polling,
@@ -661,15 +887,20 @@ export class PhoneAuthClient {
                     pollingEndpoint: (opts === null || opts === void 0 ? void 0 : opts.pollingEndpoint) || ((_q = this.config.endpoints) === null || _q === void 0 ? void 0 : _q.polling),
                     pollingInterval: (opts === null || opts === void 0 ? void 0 : opts.pollingInterval) || this.config.pollingInterval || 2000,
                     maxPollingAttempts: (opts === null || opts === void 0 ? void 0 : opts.maxPollingAttempts) || this.config.maxPollingAttempts || 30,
+                    devEnv: (opts === null || opts === void 0 ? void 0 : opts.devEnv) || this.config.devEnv,
                     onLinkOpened: undefined,
                     onStatusUpdate: undefined
                 };
                 console.log('[PhoneAuth Client] Final Link polling options:', pollingOptions);
+                // Handle based on execution mode
                 if (executionMode === 'extended') {
+                    // Extended mode - return control methods and start polling immediately
                     let pollingStarted = false;
                     let pollingPromise = null;
+                    // Start polling immediately (Link always polls automatically unlike Desktop)
                     pollingPromise = handler.invoke(plainResponse, pollingOptions);
                     pollingStarted = true;
+                    // Create credential promise from the polling result
                     const credentialPromise = pollingPromise.then(result => {
                         if (result.authenticated && result.credential) {
                             return {
@@ -682,8 +913,10 @@ export class PhoneAuthClient {
                             throw this.createError(PhoneAuthErrorCode.USER_DENIED, result.error || 'Link authentication failed');
                         }
                     });
+                    // Function to restart polling (for retry scenarios)
                     const startPolling = () => __awaiter(this, void 0, void 0, function* () {
                         if (!pollingStarted) {
+                            // This is here for API consistency, but for Link it's already polling
                             pollingStarted = true;
                             if (!pollingPromise) {
                                 pollingPromise = handler.invoke(plainResponse, pollingOptions);
@@ -700,6 +933,7 @@ export class PhoneAuthClient {
                                 throw this.createError(PhoneAuthErrorCode.USER_DENIED, result.error || 'Link authentication failed');
                             }
                         }
+                        // If already polling, just return the existing promise result
                         const result = yield pollingPromise;
                         if (result.authenticated && result.credential) {
                             return {
@@ -719,15 +953,21 @@ export class PhoneAuthClient {
                         data: {
                             app_url: linkData.url
                         },
+                        // Re-open the app link
                         trigger: triggerLink,
+                        // Polling control - now prevents double polling
                         start_polling: startPolling,
                         stop_polling: () => handler.cleanup(),
                         cancel: () => {
                             handler.cancel();
                             handler.cleanup();
+                            // Note: For Link, polling is already started, so the promise 
+                            // will be rejected by the handler.cancel() call
                         },
-                        is_polling: false
+                        // This will be replaced with a getter
+                        is_polling: false // Initial value, will be overridden by getter
                     };
+                    // Define is_polling as a getter that returns current state
                     Object.defineProperty(response, 'is_polling', {
                         get() {
                             return handler.isPolling();
@@ -738,6 +978,7 @@ export class PhoneAuthClient {
                     return response;
                 }
                 else {
+                    // Standard mode - start polling immediately and wait for completion
                     const credentialPromise = handler.invoke(plainResponse, pollingOptions).then(result => {
                         if (result.authenticated && result.credential) {
                             return {
@@ -750,28 +991,44 @@ export class PhoneAuthClient {
                             throw this.createError(PhoneAuthErrorCode.USER_DENIED, result.error || 'Link authentication failed');
                         }
                     });
+                    // Wait for credential and return in standard format
                     const credential = yield credentialPromise;
                     const aggregatorId = this.config.aggregatorId || 'default';
                     return { [aggregatorId]: credential.credential };
                 }
             }
             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
+                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',
+                    credential: credentialString ? credentialString.substring(0, 50) + '...' : 'undefined', // Show partial for debugging
                     endpoint: this.config.endpoints.process || '/api/phone-auth/process'
                 });
             }
@@ -815,18 +1072,35 @@ export class PhoneAuthClient {
             }
         });
     }
+    /**
+     * 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
+                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',
+                    credential: credentialString ? credentialString.substring(0, 50) + '...' : 'undefined', // Show partial for debugging
                     endpoint: this.config.endpoints.process || '/api/phone-auth/process'
                 });
             }
@@ -873,36 +1147,53 @@ export class PhoneAuthClient {
             }
         });
     }
+    /**
+     * 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();
-                return Object.assign(Object.assign({}, errorData), { status: response.status });
+                // 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();
@@ -915,18 +1206,25 @@ export class PhoneAuthClient {
             }
         });
     }
+    /**
+     * 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 }) : details
+            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;
         }
@@ -941,37 +1239,51 @@ export class PhoneAuthClient {
         }
         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',
-            'USE_CASE_MISMATCH',
-            'PHONE_NUMBER_MISMATCH',
-            'VERIFICATION_FAILED',
-            'INVALID_CREDENTIAL',
-            'CARRIER_NOT_ELIGIBLE',
-            'SESSION_EXPIRED',
-            'INVALID_SESSION'
+            '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',
@@ -980,6 +1292,7 @@ export class PhoneAuthClient {
             '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',
@@ -989,13 +1302,17 @@ export class PhoneAuthClient {
             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 &&
+            errorObj.code !== 19 && // Not user cancellation
             this.crossDeviceActive;
         if (isCrossDeviceTimeout) {
             return {
@@ -1023,8 +1340,12 @@ export class PhoneAuthClient {
                 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, {
@@ -1032,11 +1353,15 @@ export class PhoneAuthClient {
             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);
@@ -1044,14 +1369,22 @@ export class PhoneAuthClient {
         }
         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;
@@ -1062,6 +1395,9 @@ export class PhoneAuthClient {
             }
         }, 60000);
     }
+    /**
+     * Utility delay function
+     */
     delay(ms) {
         return new Promise(resolve => setTimeout(resolve, ms));
     }