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

package/dist/esm/core/phone-auth/strategies/link.js

@@ -1,3 +1,8 @@
+/**
+ * Link Strategy Handler
+ * Handles authentication via app links (iOS and Android)
+ * Opens authentication app while keeping user on current page
+ */
 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) {
@@ -13,6 +18,10 @@ export class LinkHandler {
         this.isCancelled = false;
         this.isPollingInProgress = false;
     }
+    /**
+     * Invoke link-based authentication
+     * Opens authentication app while keeping user on current page
+     */
     invoke(data, options) {
         return __awaiter(this, void 0, void 0, function* () {
             console.log('[Link Auth] 🔗 invoke() called with data:', JSON.stringify(data, null, 2));
@@ -21,6 +30,7 @@ export class LinkHandler {
                 maxPollingAttempts: options.maxPollingAttempts,
                 pollingEndpoint: options.pollingEndpoint
             }) : 'none');
+            // Extract link data from prepare response
             const linkData = data.data;
             if (!linkData || !linkData.url) {
                 throw new Error('Invalid link data: missing URL');
@@ -28,23 +38,36 @@ export class LinkHandler {
             const sessionKey = data.session.session_key;
             console.log('[Link Auth] Session key:', sessionKey);
             console.log('[Link Auth] Link URL:', linkData.url);
+            // Open authentication app without navigating away from current page
             this.openAuthenticationLink(linkData.url);
+            // Notify that link was opened
             if (options === null || options === void 0 ? void 0 : options.onLinkOpened) {
                 options.onLinkOpened();
             }
+            // Start polling for authentication status
+            // Use constant interval (no exponential backoff)
             return this.startPolling(sessionKey, linkData, options);
         });
     }
+    /**
+     * Open authentication link without navigating away
+     */
     openAuthenticationLink(url) {
+        // Always use window.open - Works best for App Clips and Android deep links
+        // Must be called in direct response to user action to avoid popup blocker
         const newWindow = window.open(url, '_blank');
         if (!newWindow || newWindow.closed || typeof newWindow.closed === 'undefined') {
+            // Popup was blocked - this can happen if not called from user gesture
             console.warn('[LinkHandler] Failed to open app link - popup may have been blocked');
         }
     }
+    /**
+     * Start polling for authentication status with constant interval
+     */
     startPolling(sessionKey, linkData, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const interval = (options === null || options === void 0 ? void 0 : options.pollingInterval) || 2000;
-            const maxAttempts = (options === null || options === void 0 ? void 0 : options.maxPollingAttempts) || 30;
+            const interval = (options === null || options === void 0 ? void 0 : options.pollingInterval) || 2000; // Fixed 2 second interval
+            const maxAttempts = (options === null || options === void 0 ? void 0 : options.maxPollingAttempts) || 30; // 1 minute with 2s interval
             let attempts = 0;
             console.log('[Link Auth] 🚀 Starting polling:', {
                 sessionKey,
@@ -54,22 +77,25 @@ export class LinkHandler {
             });
             return new Promise((resolve, reject) => {
                 this.isPollingActive = true;
-                this.pollingReject = reject;
+                this.pollingReject = reject; // Store reject function for cancel()
                 const poll = () => __awaiter(this, void 0, void 0, function* () {
                     if (!this.isPollingActive) {
-                        return;
+                        return; // Polling was stopped
                     }
+                    // Skip if another poll is already in progress
                     if (this.isPollingInProgress) {
                         return;
                     }
-                    let statusUrl = '';
+                    let statusUrl = ''; // Declare at function scope for catch block access
                     try {
                         this.isPollingInProgress = true;
+                        // Check max attempts before making the request
                         if (attempts >= maxAttempts) {
                             this.stopPolling();
                             if (options === null || options === void 0 ? void 0 : options.onTimeout) {
                                 options.onTimeout();
                             }
+                            // Calculate actual timeout duration
                             const timeoutSeconds = Math.round((maxAttempts * interval) / 1000);
                             const timeoutMessage = timeoutSeconds >= 60
                                 ? `${Math.floor(timeoutSeconds / 60)} minute${Math.floor(timeoutSeconds / 60) > 1 ? 's' : ''}`
@@ -83,6 +109,11 @@ export class LinkHandler {
                             reject(new Error(`Authentication timeout after ${timeoutMessage}`));
                             return;
                         }
+                        // Build public status endpoint URL
+                        // Use the same priority logic as Desktop strategy:
+                        // 1. options?.pollingEndpoint (already contains invoke options OR client config from client.ts)
+                        // 2. Backend-provided status_url from linkData
+                        // 3. Hardcoded fallback to API server
                         let endpoint = options === null || options === void 0 ? void 0 : options.pollingEndpoint;
                         let endpointSource = 'options';
                         if (!endpoint && linkData.status_url) {
@@ -93,11 +124,14 @@ export class LinkHandler {
                         console.log('  - options?.pollingEndpoint:', options === null || options === void 0 ? void 0 : options.pollingEndpoint);
                         console.log('  - linkData.status_url:', linkData.status_url);
                         console.log('  - selected endpoint:', endpoint, 'from source:', endpointSource);
+                        // Build the status URL based on endpoint format (same as Desktop)
                         if (endpoint && (endpoint.startsWith('http://') || endpoint.startsWith('https://'))) {
+                            // Full URL provided
                             if (endpoint.includes('{{session_id}}')) {
                                 statusUrl = endpoint.replace('{{session_id}}', sessionKey);
                             }
                             else if (!endpoint.includes(sessionKey)) {
+                                // If it doesn't already contain the session ID, check if it's a base URL
                                 const url = new URL(endpoint);
                                 statusUrl = `${url.protocol}//${url.host}/public/public/status/${sessionKey}`;
                             }
@@ -106,34 +140,49 @@ export class LinkHandler {
                             }
                         }
                         else if (endpoint && endpoint !== '') {
+                            // Relative path provided (e.g. '/api/phone-auth/status')
                             const origin = typeof window !== 'undefined' ? window.location.origin : '';
                             if (endpoint.includes('{{session_id}}')) {
                                 statusUrl = origin + endpoint.replace('{{session_id}}', sessionKey);
                             }
                             else {
+                                // Append session ID to the provided endpoint
                                 statusUrl = origin + endpoint + '/' + sessionKey;
                             }
                         }
                         else {
+                            // No endpoint provided - use hardcoded fallback
                             statusUrl = `https://api.glideidentity.app/public/public/status/${sessionKey}`;
                             endpointSource = 'fallback';
                         }
                         console.log(`[Link Auth] Using ${endpointSource} endpoint: ${statusUrl}`);
+                        // Poll public status endpoint - no authentication required
                         console.log(`[Link Auth] Polling status (attempt ${attempts}/${maxAttempts}): ${statusUrl}`);
+                        // Build headers
+                        const headers = {
+                            'Accept': 'application/json'
+                        };
+                        // Add developer header if devEnv is set
+                        if (options === null || options === void 0 ? void 0 : options.devEnv) {
+                            headers['developer'] = options.devEnv;
+                            console.log(`[Link Auth] Adding developer header: ${options.devEnv}`);
+                        }
                         const response = yield fetch(statusUrl, {
                             method: 'GET',
-                            headers: {
-                                'Accept': 'application/json'
-                            }
+                            headers
                         });
                         console.log(`[Link Auth] Poll response - Status: ${response.status}, OK: ${response.ok}`);
+                        // Handle based on HTTP status code
                         if (response.status === 200) {
+                            // Session is active (pending or completed)
                             const result = yield response.json();
                             console.log('[Link Auth] Poll response data:', JSON.stringify(result, null, 2));
                             if (result.status === 'completed') {
+                                // Authentication completed successfully
                                 console.log('[Link Auth] ✅ Authentication COMPLETED! Session:', sessionKey);
                                 console.log('[Link Auth] Full completion result:', JSON.stringify(result, null, 2));
                                 this.stopPolling();
+                                // Authentication completed successfully
                                 if (options === null || options === void 0 ? void 0 : options.onStatusUpdate) {
                                     options.onStatusUpdate({
                                         status: 'authenticated',
@@ -141,7 +190,8 @@ export class LinkHandler {
                                         data: result
                                     });
                                 }
-                                this.pollingReject = undefined;
+                                // Return the authentication result
+                                this.pollingReject = undefined; // Clear reject function on success
                                 resolve({
                                     authenticated: true,
                                     credential: result.credential || sessionKey,
@@ -155,8 +205,9 @@ export class LinkHandler {
                                 });
                             }
                             else if (result.status === 'pending') {
+                                // Continue polling
                                 console.log('[Link Auth] Status still pending, continuing to poll...');
-                                attempts++;
+                                attempts++; // Increment attempts after successful poll
                                 if (options === null || options === void 0 ? void 0 : options.onStatusUpdate) {
                                     options.onStatusUpdate({
                                         status: 'pending',
@@ -165,11 +216,13 @@ export class LinkHandler {
                                 }
                             }
                             else {
+                                // Unexpected status value
                                 console.log('[Link Auth] ⚠️ Unexpected status value:', result.status, 'Full result:', JSON.stringify(result, null, 2));
-                                attempts++;
+                                attempts++; // Increment for unexpected status too
                             }
                         }
                         else if (response.status === 410) {
+                            // Session expired
                             console.log('[Link Auth] ❌ Session expired (410)');
                             this.stopPolling();
                             const errorData = yield response.json().catch(() => ({ message: 'Session expired' }));
@@ -185,6 +238,7 @@ export class LinkHandler {
                             reject(new Error(errorData.message || 'Session expired'));
                         }
                         else if (response.status === 422) {
+                            // Authentication failed
                             console.log('[Link Auth] ❌ Authentication failed (422)');
                             this.stopPolling();
                             const errorData = yield response.json().catch(() => ({ message: 'Authentication failed' }));
@@ -193,6 +247,7 @@ export class LinkHandler {
                             const errorMsg = isUserCancelled
                                 ? 'User cancelled authentication'
                                 : (errorData.message || 'Verification failed');
+                            // Authentication failed
                             if (options === null || options === void 0 ? void 0 : options.onStatusUpdate) {
                                 options.onStatusUpdate({
                                     status: 'error',
@@ -202,6 +257,7 @@ export class LinkHandler {
                             reject(new Error(errorMsg));
                         }
                         else if (response.status === 404) {
+                            // Session not found
                             console.log('[Link Auth] ❌ Session not found (404)');
                             this.stopPolling();
                             if (options === null || options === void 0 ? void 0 : options.onStatusUpdate) {
@@ -213,6 +269,7 @@ export class LinkHandler {
                             reject(new Error('Session not found'));
                         }
                         else if (response.status === 400) {
+                            // Invalid session key
                             console.log('[Link Auth] ❌ Invalid session key (400)');
                             this.stopPolling();
                             const errorData = yield response.json().catch(() => ({ message: 'Invalid session key' }));
@@ -220,8 +277,9 @@ export class LinkHandler {
                             reject(new Error(errorData.message || 'Invalid session key'));
                         }
                         else {
+                            // Unexpected status - continue polling
                             console.log('[Link Auth] ⚠️ Unexpected HTTP status:', response.status, 'continuing to poll...');
-                            attempts++;
+                            attempts++; // Increment for unexpected HTTP status
                             try {
                                 const body = yield response.text();
                                 console.log('[Link Auth] Response body:', body);
@@ -232,8 +290,9 @@ export class LinkHandler {
                         }
                     }
                     catch (error) {
+                        // Network or other error - continue polling
                         console.error('[Link Auth] 🔴 Polling error:', error.message || error);
-                        attempts++;
+                        attempts++; // Increment for error case
                         console.error('[Link Auth] Error details:', {
                             name: error.name,
                             message: error.message,
@@ -242,6 +301,7 @@ export class LinkHandler {
                             attempt: attempts,
                             error: error
                         });
+                        // Check if it's a CORS error (common on mobile)
                         if (error.message && error.message.toLowerCase().includes('failed')) {
                             console.error('[Link Auth] ⚠️ Possible CORS issue. Status URL:', statusUrl);
                             console.error('[Link Auth] Make sure the API endpoint allows CORS from your ngrok domain');
@@ -254,14 +314,20 @@ export class LinkHandler {
                         }
                     }
                     finally {
+                        // Always clear the polling flag when done
                         this.isPollingInProgress = false;
                     }
                 });
+                // Start initial poll immediately
                 poll();
+                // Set up constant interval polling (no backoff)
                 this.pollingInterval = setInterval(poll, interval);
             });
         });
     }
+    /**
+     * Stop polling
+     */
     stopPolling() {
         console.log('[Link Auth] 🏁 Stopping polling');
         this.isPollingActive = false;
@@ -271,6 +337,9 @@ export class LinkHandler {
             this.pollingInterval = undefined;
         }
     }
+    /**
+     * Format response for backend processing
+     */
     formatResponse(response) {
         if (!response.authenticated || !response.credential) {
             throw new Error('Authentication not completed');
@@ -281,25 +350,40 @@ export class LinkHandler {
             type: 'link'
         };
     }
+    /**
+     * Check if link strategy is supported
+     * Returns true for mobile devices (iOS and Android)
+     */
     isSupported() {
+        // Link strategy is supported on mobile devices
         const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
         return isMobile;
     }
+    /**
+     * Clean up resources (stop polling if active)
+     */
     cleanup() {
         this.stopPolling();
         this.isCancelled = false;
         this.onCancel = undefined;
         this.pollingReject = undefined;
     }
+    /**
+     * Check if polling is currently active
+     */
     isPolling() {
         return this.pollingInterval !== undefined;
     }
+    /**
+     * Cancel the ongoing authentication
+     */
     cancel() {
         var _a;
         console.log('[Link Auth] Cancelling authentication');
         this.isCancelled = true;
         this.stopPolling();
         (_a = this.onCancel) === null || _a === void 0 ? void 0 : _a.call(this);
+        // Immediately reject the polling promise
         if (this.pollingReject) {
             this.pollingReject({
                 code: 'USER_DENIED',

package/dist/esm/core/phone-auth/strategies/ts43.d.ts

@@ -1,9 +1,28 @@
+/**
+ * TS-43 Strategy Handler
+ * Handles Digital Credentials API authentication for Android/Chromium
+ * Properly manages session objects with session_key, nonce, and enc_key
+ */
 import type { StrategyHandler } from './types';
 import type { PrepareResponse } from '../types';
 export declare class TS43Handler implements StrategyHandler {
+    /**
+     * Invoke TS-43 authentication using Digital Credentials API
+     * The data structure from backend is already in the correct format for navigator.credentials.get
+     */
     invoke(data: PrepareResponse): Promise<any>;
+    /**
+     * Format the credential response for backend processing
+     * Include the session key so backend can retrieve the full session
+     */
     formatResponse(response: any): any;
+    /**
+     * Check if Digital Credentials API is supported
+     */
     isSupported(): boolean;
+    /**
+     * Get browser support information
+     */
     getBrowserSupportInfo(): {
         supported: boolean;
         browser: string;

package/dist/esm/core/phone-auth/strategies/ts43.js

@@ -1,3 +1,8 @@
+/**
+ * TS-43 Strategy Handler
+ * Handles Digital Credentials API authentication for Android/Chromium
+ * Properly manages session objects with session_key, nonce, and enc_key
+ */
 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) {
@@ -8,31 +13,43 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 export class TS43Handler {
+    /**
+     * Invoke TS-43 authentication using Digital Credentials API
+     * The data structure from backend is already in the correct format for navigator.credentials.get
+     */
     invoke(data) {
         return __awaiter(this, void 0, void 0, function* () {
+            // Validate session structure - only session_key is actually required
             if (!data.session || !data.session.session_key) {
                 throw new Error('Invalid TS43 session: missing required session_key');
             }
+            // Check if Digital Credentials API is available
             if (!this.isSupported()) {
                 throw new Error('Digital Credentials API not supported in this browser');
             }
+            // Extract TS43 data from the prepare response
             const ts43Data = data.data;
+            // The data is already in the correct format from backend
+            // Just pass it through to navigator.credentials.get
             const credentialRequest = {
                 digital: {
                     requests: [{
-                            protocol: ts43Data.protocol,
-                            data: ts43Data.data
+                            protocol: ts43Data.protocol, // e.g., "openid4vp-v1-unsigned"
+                            data: ts43Data.data // Pass the entire data object as-is
                         }]
                 }
             };
             try {
+                // @ts-ignore - Digital Credentials API types not yet in TypeScript
                 const credential = yield navigator.credentials.get(credentialRequest);
                 if (!credential) {
                     throw new Error('No credential received from Digital Credentials API');
                 }
+                // @ts-ignore - credential.data is not typed yet
                 return credential;
             }
             catch (error) {
+                // Handle browser-specific errors
                 if (error instanceof Error) {
                     if (error.name === 'NotAllowedError') {
                         throw new Error('User denied the authentication request');
@@ -48,8 +65,13 @@ export class TS43Handler {
             }
         });
     }
+    /**
+     * Format the credential response for backend processing
+     * Include the session key so backend can retrieve the full session
+     */
     formatResponse(response) {
         var _a;
+        // Extract vp_token from the response
         const vpToken = (_a = response.data) === null || _a === void 0 ? void 0 : _a.vp_token;
         if (!vpToken) {
             throw new Error('Invalid TS43 response: missing vp_token');
@@ -59,12 +81,20 @@ export class TS43Handler {
             type: 'ts43'
         };
     }
+    /**
+     * Check if Digital Credentials API is supported
+     */
     isSupported() {
         if (typeof window === 'undefined') {
             return false;
         }
+        // Check for DigitalCredential constructor
+        // @ts-ignore - DigitalCredential not yet in TypeScript
         return 'DigitalCredential' in window;
     }
+    /**
+     * Get browser support information
+     */
     getBrowserSupportInfo() {
         if (typeof window === 'undefined') {
             return {
@@ -84,6 +114,7 @@ export class TS43Handler {
                 browser: isChrome ? 'Chrome' : isEdge ? 'Edge' : 'Chromium'
             };
         }
+        // Provide specific guidance based on browser
         if ((isChrome || isEdge) && isAndroid) {
             return {
                 supported: false,

package/dist/esm/core/phone-auth/strategies/types.d.ts

@@ -1,5 +1,18 @@
+/**
+ * Strategy Handler Interface
+ * Defines the contract for authentication strategy implementations
+ */
 export interface StrategyHandler {
+    /**
+     * Invoke authentication using strategy-specific data
+     */
     invoke(data: any): Promise<any>;
+    /**
+     * Format response for backend processing
+     */
     formatResponse(response: any): any;
+    /**
+     * Check if this strategy is supported in the current environment
+     */
     isSupported(): boolean;
 }

package/dist/esm/core/phone-auth/strategies/types.js

@@ -1 +1,5 @@
+/**
+ * Strategy Handler Interface
+ * Defines the contract for authentication strategy implementations
+ */
 export {};

package/dist/esm/core/phone-auth/type-guards.d.ts

@@ -1,15 +1,143 @@
+/**
+ * Type Guards and Helper Functions for Phone Authentication
+ *
+ * These utilities help developers work with the SDK responses in a type-safe way
+ * without having to write their own type checking logic.
+ */
 import type { AnyExtendedResponse, DesktopExtendedResponse, LinkExtendedResponse, TS43ExtendedResponse, AuthCredential } from './api-types';
+/**
+ * Type guard to check if the result is an ExtendedResponse (extended mode)
+ * or a Credential (standard mode).
+ *
+ * @example
+ * ```typescript
+ * const result = await invokeSecurePrompt(sdkRequest, { executionMode: 'extended' });
+ *
+ * if (isExtendedResponse(result)) {
+ *   // TypeScript knows this is ExtendedResponse
+ *   console.log(result.strategy);
+ *   await result.cancel();
+ * } else {
+ *   // TypeScript knows this is a Credential
+ *   const processedResult = await verifyPhoneNumberCredential(result, session);
+ * }
+ * ```
+ */
 export declare function isExtendedResponse(result: any): result is AnyExtendedResponse;
+/**
+ * Type guard to check if the result is a Credential (standard mode response).
+ * A credential is either a string token or an object without ExtendedResponse properties.
+ *
+ * @example
+ * ```typescript
+ * if (isCredential(result)) {
+ *   // Process the credential directly
+ *   const verified = await verifyPhoneNumberCredential(result, session);
+ * }
+ * ```
+ */
 export declare function isCredential(result: any): result is string | {
     [aggregator_id: string]: string | string[];
 };
+/**
+ * Type guard to check if the result is an AuthCredential object.
+ *
+ * @example
+ * ```typescript
+ * if (isAuthCredential(result)) {
+ *   console.log(result.credential);
+ *   console.log(result.authenticated);
+ * }
+ * ```
+ */
 export declare function isAuthCredential(result: any): result is AuthCredential;
+/**
+ * Type guard to check if an ExtendedResponse is using the Link strategy.
+ * Link strategy involves opening an app link (App Clip on iOS, app on Android).
+ *
+ * @example
+ * ```typescript
+ * if (isExtendedResponse(result) && isLinkStrategy(result)) {
+ *   // Re-trigger app opening if needed
+ *   result.trigger();
+ *   await result.credential;
+ * }
+ * ```
+ */
 export declare function isLinkStrategy(result: AnyExtendedResponse): result is LinkExtendedResponse;
+/**
+ * Type guard to check if an ExtendedResponse is using the TS43 strategy.
+ * TS43 strategy uses the browser's Digital Credentials API.
+ *
+ * @example
+ * ```typescript
+ * if (isExtendedResponse(result) && isTS43Strategy(result)) {
+ *   // Re-trigger credential request if needed
+ *   await result.trigger();
+ * }
+ * ```
+ */
 export declare function isTS43Strategy(result: AnyExtendedResponse): result is TS43ExtendedResponse;
+/**
+ * Type guard to check if an ExtendedResponse is using the Desktop strategy.
+ * Desktop strategy involves QR codes for cross-device authentication.
+ *
+ * @example
+ * ```typescript
+ * if (isExtendedResponse(result) && isDesktopStrategy(result)) {
+ *   // Show custom QR code UI
+ *   displayQRCode(result.qr_code_data);
+ *   await result.start_polling();
+ * }
+ * ```
+ */
 export declare function isDesktopStrategy(result: AnyExtendedResponse): result is DesktopExtendedResponse;
+/**
+ * Helper function to safely get the authentication strategy from any result.
+ * Returns undefined if the result is not an ExtendedResponse.
+ *
+ * @example
+ * ```typescript
+ * const strategy = getStrategy(result);
+ * if (strategy === 'link') {
+ *   // Handle link strategy
+ * }
+ * ```
+ */
 export declare function getStrategy(result: any): 'link' | 'ts43' | 'desktop' | undefined;
+/**
+ * Helper function to determine if a result has polling controls.
+ * Link and Desktop strategies have polling controls in extended mode.
+ *
+ * @example
+ * ```typescript
+ * if (hasPollingControls(result)) {
+ *   await result.start_polling();
+ * }
+ * ```
+ */
 export declare function hasPollingControls(result: any): boolean;
+/**
+ * Helper function to determine if a result has a trigger method.
+ * Link and TS43 strategies have trigger methods in extended mode.
+ *
+ * @example
+ * ```typescript
+ * if (hasTrigger(result)) {
+ *   result.trigger();
+ * }
+ * ```
+ */
 export declare function hasTrigger(result: any): boolean;
+/**
+ * @deprecated Use isExtendedResponse instead
+ */
 export declare const isHeadlessResult: typeof isExtendedResponse;
+/**
+ * @deprecated Use hasPollingControls instead
+ */
 export declare const requiresPolling: typeof hasPollingControls;
+/**
+ * @deprecated This function is no longer needed as extended mode handles user actions differently
+ */
 export declare const requiresUserAction: (result: any) => boolean;