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

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

@@ -1,3 +1,8 @@
+/**
+ * Desktop Strategy Handler
+ * Handles QR code-based authentication for desktop browsers
+ * Manages QR code display and polling for authentication status
+ */
 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,33 +18,49 @@ export class DesktopHandler {
         this.isCancelled = false;
         this.isPollingInProgress = false;
     }
+    /**
+     * Maps backend HTTP status codes to client status
+     * @param httpStatus HTTP status code from backend
+     * @param bodyStatus Optional status from response body (for 200 OK responses)
+     * @returns Mapped status string for client use
+     */
     mapBackendStatus(httpStatus, bodyStatus) {
         switch (httpStatus) {
             case 200:
+                // For 200 OK, check the body status
                 return bodyStatus === 'completed' ? 'authenticated' : 'pending';
             case 410:
                 return 'expired';
             case 422:
-                return 'error';
+                return 'error'; // Failed or cancelled
             case 404:
-                return 'error';
+                return 'error'; // Session not found
             case 400:
-                return 'error';
+                return 'error'; // Invalid session key
             default:
                 return 'error';
         }
     }
+    /**
+     * Invoke desktop authentication with QR code
+     * Returns QR code data for display and starts polling if endpoint is provided
+     */
     invoke(data, options) {
         return __awaiter(this, void 0, void 0, function* () {
             const desktopData = data.data;
+            // Extract QR code from nested or flat structure, checking multiple field names
             let qrCode;
             let sessionId;
             let pollingEndpoint;
             let pollingInterval;
             let expiresIn;
+            // Check nested structure first (data.data.qr_code_image or data.data.qr_code)
             if (desktopData && desktopData.data && typeof desktopData.data === 'object') {
                 const innerData = desktopData.data;
+                // Try to extract from inner data
+                // Support both single QR (qr_code_image) and dual-platform QR (ios/android)
                 if (innerData.ios_qr_image && innerData.android_qr_image) {
+                    // Dual-platform QR format - both must be present
                     qrCode = {
                         iosQRCode: innerData.ios_qr_image,
                         androidQRCode: innerData.android_qr_image,
@@ -48,9 +69,11 @@ export class DesktopHandler {
                     };
                 }
                 else if (innerData.ios_qr_image || innerData.android_qr_image) {
+                    // Only one platform QR - use as single QR format
                     qrCode = innerData.ios_qr_image || innerData.android_qr_image;
                 }
                 else {
+                    // Single QR format (legacy)
                     qrCode = innerData.qr_code_image || innerData.qr_code;
                 }
                 sessionId = innerData.session_id;
@@ -58,6 +81,7 @@ export class DesktopHandler {
                 pollingInterval = innerData.polling_interval;
                 expiresIn = innerData.expires_in;
             }
+            // Fall back to flat structure if no QR code found
             if (!qrCode && desktopData) {
                 qrCode = desktopData.qr_code_image || desktopData.qr_code;
                 sessionId = sessionId || desktopData.session_id;
@@ -65,47 +89,65 @@ export class DesktopHandler {
                 pollingInterval = pollingInterval || desktopData.polling_interval;
                 expiresIn = expiresIn || desktopData.expires_in;
             }
+            // Validate QR code exists
             if (!qrCode) {
                 throw new Error('Invalid desktop authentication data: missing QR code');
             }
+            // Validate session ID exists
             if (!sessionId) {
                 throw new Error('Invalid desktop authentication data: missing session ID');
             }
+            // Notify that QR code is ready
             if (options === null || options === void 0 ? void 0 : options.onQRCodeReady) {
                 options.onQRCodeReady(qrCode);
             }
+            // Use polling endpoint with this priority:
+            // 1. Developer-provided endpoint from options (highest priority)
+            // 2. Backend-provided endpoint
+            // 3. Hardcoded fallback
             console.log('[Desktop QR] Polling endpoint selection:');
             console.log('  - options?.pollingEndpoint:', options === null || options === void 0 ? void 0 : options.pollingEndpoint);
             console.log('  - backend pollingEndpoint:', pollingEndpoint);
             let finalPollingEndpoint = options === null || options === void 0 ? void 0 : options.pollingEndpoint;
             let endpointSource = 'options';
             if (!finalPollingEndpoint) {
-                finalPollingEndpoint = pollingEndpoint;
+                finalPollingEndpoint = pollingEndpoint; // Backend-provided status_url
                 endpointSource = 'backend';
             }
             if (!finalPollingEndpoint) {
+                // Use hardcoded fallback - this will be constructed in the polling function
                 console.log('[Desktop QR] No polling endpoint provided, will use hardcoded fallback');
                 endpointSource = 'fallback';
             }
             console.log('[Desktop QR] Selected endpoint:', finalPollingEndpoint, 'from source:', endpointSource);
+            // Start polling for authentication status
             const finalPollingInterval = (options === null || options === void 0 ? void 0 : options.pollingInterval) || pollingInterval || 2000;
-            const maxAttempts = (options === null || options === void 0 ? void 0 : options.maxPollingAttempts) || 30;
+            const maxAttempts = (options === null || options === void 0 ? void 0 : options.maxPollingAttempts) || 30; // Default to 1 minute
             console.log(`[Desktop QR] Starting polling - endpoint source: ${endpointSource}, interval: ${finalPollingInterval}ms, max attempts: ${maxAttempts}`);
-            return this.startPolling(finalPollingEndpoint || '', sessionId, finalPollingInterval, maxAttempts, expiresIn || 300, options, endpointSource);
+            return this.startPolling(finalPollingEndpoint || '', // Pass empty string if undefined, will use fallback
+            sessionId, finalPollingInterval, maxAttempts, expiresIn || 300, // Default 5 minutes expiry
+            options, endpointSource // Pass the endpoint source for logging
+            );
         });
     }
+    /**
+     * Start polling for authentication status
+     */
     startPolling(endpoint_1, sessionId_1, interval_1, maxAttempts_1, expiresIn_1, options_1) {
         return __awaiter(this, arguments, void 0, function* (endpoint, sessionId, interval, maxAttempts, expiresIn, options, endpointSource = 'unknown') {
             const startTime = Date.now();
             const expiryTime = startTime + (expiresIn * 1000);
             return new Promise((resolve, reject) => {
+                // Store the reject function so we can call it from cancel()
                 this.pollingReject = reject;
                 const poll = () => __awaiter(this, void 0, void 0, function* () {
+                    // Skip if another poll is already in progress
                     if (this.isPollingInProgress) {
                         return;
                     }
                     try {
                         this.isPollingInProgress = true;
+                        // Check if cancelled
                         if (this.isCancelled) {
                             this.stopPolling();
                             if (options === null || options === void 0 ? void 0 : options.onCancel) {
@@ -117,12 +159,14 @@ export class DesktopHandler {
                                     message: 'Authentication cancelled'
                                 });
                             }
+                            // Reject the promise with a cancellation error
                             reject({
                                 code: 'USER_DENIED',
                                 message: 'Authentication cancelled by user'
                             });
                             return;
                         }
+                        // Check if expired
                         if (Date.now() > expiryTime) {
                             this.stopPolling();
                             if (options === null || options === void 0 ? void 0 : options.onExpired) {
@@ -140,6 +184,7 @@ export class DesktopHandler {
                             });
                             return;
                         }
+                        // Check max attempts
                         if (this.pollingAttempts >= maxAttempts) {
                             this.stopPolling();
                             if (options === null || options === void 0 ? void 0 : options.onTimeout) {
@@ -157,35 +202,58 @@ export class DesktopHandler {
                             });
                             return;
                         }
+                        // Build public status endpoint URL - use relative path for proxied requests
                         let statusUrl;
+                        // Extract base URL and construct public endpoint
                         if (endpoint && (endpoint.startsWith('http://') || endpoint.startsWith('https://'))) {
-                            const url = new URL(endpoint);
-                            statusUrl = `${url.protocol}//${url.host}/public/public/status/${sessionId}`;
+                            // Full URL provided - use as is
+                            statusUrl = endpoint;
                         }
                         else if (endpoint && endpoint !== '') {
+                            // Relative path provided (e.g. '/api/phone-auth/status')
+                            // Append session ID to the provided endpoint
                             statusUrl = `${endpoint}/${sessionId}`;
                         }
                         else {
+                            // No endpoint provided - use hardcoded fallback
+                            // This ensures it goes through the same domain and uses the app's API configuration
                             statusUrl = `/api/phone-auth/status/${sessionId}`;
                         }
+                        // Poll the public endpoint - no authentication required
                         console.log(`[Desktop QR] Polling status (attempt ${this.pollingAttempts}/${maxAttempts})`);
                         console.log(`[Desktop QR] Using ${endpointSource} endpoint: ${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(`[Desktop QR] Adding developer header: ${options.devEnv}`);
+                        }
                         const response = yield fetch(statusUrl, {
                             method: 'GET',
-                            headers: {
-                                'Accept': 'application/json'
-                            }
+                            headers
                         });
                         console.log(`[Desktop QR] Status response: ${response.status} ${response.statusText}`);
+                        // Backend Status Code Mapping:
+                        // - 200 OK: Session exists (body has 'pending' or 'completed' status)
+                        // - 410 Gone: Session expired after timeout
+                        // - 422 Unprocessable Entity: Authentication failed or cancelled
+                        // - 404 Not Found: Session doesn't exist
+                        // - 400 Bad Request: Invalid session key format
+                        // Handle response based on HTTP status code
                         if (response.status === 200) {
                             const result = yield response.json();
                             if (result.status === 'completed') {
+                                // Authentication completed successfully
                                 this.stopPolling();
+                                // Close the modal if it exists
                                 const modal = document.querySelector('[style*="position: fixed"]');
                                 if (modal && modal.querySelector('#desktop-auth-status')) {
                                     setTimeout(() => {
                                         modal.remove();
-                                    }, 500);
+                                    }, 500); // Brief delay to show success message
                                 }
                                 if (options === null || options === void 0 ? void 0 : options.onStatusUpdate) {
                                     options.onStatusUpdate({
@@ -194,7 +262,8 @@ export class DesktopHandler {
                                         data: result
                                     });
                                 }
-                                this.pollingReject = undefined;
+                                // Return the session data for next steps
+                                this.pollingReject = undefined; // Clear the reject function on success
                                 resolve({
                                     authenticated: true,
                                     credential: result.credential || result.session_key || sessionId,
@@ -208,6 +277,7 @@ export class DesktopHandler {
                                 });
                             }
                             else if (result.status === 'pending') {
+                                // Continue polling
                                 this.pollingAttempts++;
                                 if (options === null || options === void 0 ? void 0 : options.onStatusUpdate) {
                                     options.onStatusUpdate({
@@ -218,8 +288,10 @@ export class DesktopHandler {
                             }
                         }
                         else if (response.status === 410) {
+                            // Session expired
                             this.stopPolling();
                             const errorData = yield response.json().catch(() => ({ message: 'Session expired' }));
+                            // Close the modal on error
                             const modal = document.querySelector('[style*="position: fixed"]');
                             if (modal && modal.querySelector('#desktop-auth-status')) {
                                 setTimeout(() => {
@@ -241,8 +313,10 @@ export class DesktopHandler {
                             });
                         }
                         else if (response.status === 422) {
+                            // Authentication failed
                             this.stopPolling();
                             const errorData = yield response.json().catch(() => ({ message: 'Authentication failed' }));
+                            // Close the modal on error
                             const modal = document.querySelector('[style*="position: fixed"]');
                             if (modal && modal.querySelector('#desktop-auth-status')) {
                                 setTimeout(() => {
@@ -264,6 +338,7 @@ export class DesktopHandler {
                             });
                         }
                         else if (response.status === 404) {
+                            // Session not found
                             this.stopPolling();
                             if (options === null || options === void 0 ? void 0 : options.onStatusUpdate) {
                                 options.onStatusUpdate({
@@ -277,6 +352,7 @@ export class DesktopHandler {
                             });
                         }
                         else if (response.status === 400) {
+                            // Invalid session key
                             this.stopPolling();
                             const errorData = yield response.json().catch(() => ({ message: 'Invalid session key' }));
                             resolve({
@@ -285,10 +361,12 @@ export class DesktopHandler {
                             });
                         }
                         else {
+                            // Unexpected status - continue polling
                             this.pollingAttempts++;
                         }
                     }
                     catch (error) {
+                        // Network or other error - continue polling
                         this.pollingAttempts++;
                         if (options === null || options === void 0 ? void 0 : options.onStatusUpdate) {
                             options.onStatusUpdate({
@@ -298,14 +376,20 @@ export class DesktopHandler {
                         }
                     }
                     finally {
+                        // Always clear the polling flag when done
                         this.isPollingInProgress = false;
                     }
                 });
+                // Start initial poll
                 poll();
+                // Set up interval for subsequent polls
                 this.pollingIntervalId = setInterval(poll, interval);
             });
         });
     }
+    /**
+     * Stop polling
+     */
     stopPolling() {
         if (this.pollingIntervalId) {
             console.log('[Desktop QR] Stopping polling');
@@ -314,10 +398,18 @@ export class DesktopHandler {
         }
         this.pollingAttempts = 0;
         this.isPollingInProgress = false;
+        // Don't clear pollingReject here - it's needed by cancel()
     }
+    /**
+     * Check if polling is currently active
+     */
     isPolling() {
         return this.pollingIntervalId !== undefined;
     }
+    /**
+     * Format response for backend processing
+     * Desktop strategy typically returns the credential from mobile authentication
+     */
     formatResponse(response) {
         if (!response.authenticated || !response.credential) {
             throw new Error('Authentication not completed');
@@ -327,23 +419,35 @@ export class DesktopHandler {
             session: response.session
         };
     }
+    /**
+     * Check if desktop authentication is supported
+     * Desktop auth with QR codes works in any modern browser
+     */
     isSupported() {
+        // Check for required browser APIs
         return typeof window !== 'undefined' &&
             typeof fetch !== 'undefined' &&
             typeof Promise !== 'undefined';
     }
+    /**
+     * Clean up resources (stop polling if active)
+     */
     cleanup() {
         this.stopPolling();
         this.isCancelled = false;
         this.onCancel = undefined;
         this.pollingReject = undefined;
     }
+    /**
+     * Cancel the ongoing authentication
+     */
     cancel() {
         var _a;
         console.log('[Desktop QR] 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',
@@ -353,14 +457,20 @@ export class DesktopHandler {
         }
     }
 }
+/**
+ * Helper function to display QR code in a modal or inline
+ */
 export function createQRCodeDisplay(qrCodeData, options) {
     const container = (options === null || options === void 0 ? void 0 : options.container) || document.createElement('div');
     container.className = 'phone-auth-qr-container';
+    // Determine QR code to display
     let qrCodeSrc;
     if (typeof qrCodeData === 'string') {
+        // Simple string QR code
         qrCodeSrc = qrCodeData;
     }
     else if (qrCodeData && typeof qrCodeData === 'object') {
+        // QRCodeData object - prefer iOS QR if available
         if (qrCodeData.iosQRCode) {
             qrCodeSrc = qrCodeData.iosQRCode;
         }
@@ -374,6 +484,7 @@ export function createQRCodeDisplay(qrCodeData, options) {
     else {
         throw new Error('Invalid qrCodeData: must be string or QRCodeData object');
     }
+    // Create QR code image
     const img = document.createElement('img');
     img.src = qrCodeSrc;
     img.alt = 'QR Code for authentication';
@@ -381,6 +492,7 @@ export function createQRCodeDisplay(qrCodeData, options) {
     img.style.height = `${(options === null || options === void 0 ? void 0 : options.size) || 256}px`;
     img.style.display = 'block';
     img.style.margin = '0 auto';
+    // Add title if provided
     if (options === null || options === void 0 ? void 0 : options.title) {
         const title = document.createElement('h3');
         title.textContent = options.title;
@@ -389,6 +501,7 @@ export function createQRCodeDisplay(qrCodeData, options) {
         container.appendChild(title);
     }
     container.appendChild(img);
+    // Add description if provided
     if (options === null || options === void 0 ? void 0 : options.description) {
         const desc = document.createElement('p');
         desc.textContent = options.description;
@@ -399,7 +512,12 @@ export function createQRCodeDisplay(qrCodeData, options) {
     }
     return container;
 }
+/**
+ * Helper function to create a modal for QR code display
+ * Supports both string QR codes and QRCodeData objects for dual-platform support
+ */
 export function showQRCodeModal(qrCodeData, options) {
+    // Create modal overlay
     const overlay = document.createElement('div');
     overlay.style.cssText = `
     position: fixed;
@@ -413,6 +531,7 @@ export function showQRCodeModal(qrCodeData, options) {
     justify-content: center;
     z-index: 9999;
   `;
+    // Create modal content
     const modal = document.createElement('div');
     modal.style.cssText = `
     background: white;
@@ -421,6 +540,7 @@ export function showQRCodeModal(qrCodeData, options) {
     max-width: 400px;
     position: relative;
   `;
+    // Add close button
     const closeBtn = document.createElement('button');
     closeBtn.textContent = '×';
     closeBtn.style.cssText = `
@@ -440,11 +560,13 @@ export function showQRCodeModal(qrCodeData, options) {
         }
     };
     modal.appendChild(closeBtn);
+    // Add QR code display
     const qrDisplay = createQRCodeDisplay(qrCodeData, {
         title: (options === null || options === void 0 ? void 0 : options.title) || 'Scan QR Code to Authenticate',
         description: (options === null || options === void 0 ? void 0 : options.description) || 'Use your mobile device to scan this QR code'
     });
     modal.appendChild(qrDisplay);
+    // Add loading spinner placeholder
     const statusDiv = document.createElement('div');
     statusDiv.id = 'desktop-auth-status';
     statusDiv.style.cssText = `
@@ -456,6 +578,7 @@ export function showQRCodeModal(qrCodeData, options) {
     modal.appendChild(statusDiv);
     overlay.appendChild(modal);
     document.body.appendChild(overlay);
+    // Close modal on overlay click
     overlay.onclick = (e) => {
         if (e.target === overlay) {
             document.body.removeChild(overlay);

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

@@ -1,3 +1,7 @@
+/**
+ * Strategy Handlers Export
+ * Provides implementations for TS43, Link, and Desktop authentication strategies
+ */
 export type { StrategyHandler } from './types';
 export { TS43Handler } from './ts43';
 export { LinkHandler } from './link';

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

@@ -1,3 +1,7 @@
+/**
+ * Strategy Handlers Export
+ * Provides implementations for TS43, Link, and Desktop authentication strategies
+ */
 export { TS43Handler } from './ts43';
 export { LinkHandler } from './link';
 export { DesktopHandler, createQRCodeDisplay, showQRCodeModal } from './desktop';

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

@@ -1,23 +1,44 @@
+/**
+ * Link Strategy Handler
+ * Handles authentication via app links (iOS and Android)
+ * Opens authentication app while keeping user on current page
+ */
 import type { StrategyHandler } from './types';
 import type { PrepareResponse } from '../types';
 export interface LinkAuthOptions {
+    /** Fixed polling interval in milliseconds (default: 2000) */
     pollingInterval?: number;
+    /** Maximum polling attempts before timeout (default: 30 = 1 minute with 2s interval) */
     maxPollingAttempts?: number;
+    /** Custom polling endpoint (overrides backend-provided or configured endpoint) */
     pollingEndpoint?: string;
+    /** Developer environment (adds 'developer' header to requests) */
+    devEnv?: string;
+    /** Callback when link is opened */
     onLinkOpened?: () => void;
+    /** Callback for polling status updates */
     onStatusUpdate?: (status: PollingStatus) => void;
+    /** Callback when authentication times out */
     onTimeout?: () => void;
+    /** Callback when authentication is cancelled by user */
     onCancel?: () => void;
 }
 export interface PollingStatus {
+    /** Current status of the authentication */
     status: 'pending' | 'authenticated' | 'expired' | 'cancelled' | 'error';
+    /** Optional message */
     message?: string;
+    /** Authentication result data if status is 'authenticated' */
     data?: any;
 }
 export interface LinkAuthResult {
+    /** Whether authentication was successful */
     authenticated: boolean;
+    /** Authentication credential if successful */
     credential?: string;
+    /** Session info for subsequent requests */
     session?: any;
+    /** Error message if authentication failed */
     error?: string;
 }
 export declare class LinkHandler implements StrategyHandler {
@@ -27,13 +48,42 @@ export declare class LinkHandler implements StrategyHandler {
     private onCancel?;
     private pollingReject?;
     private isPollingInProgress;
+    /**
+     * Invoke link-based authentication
+     * Opens authentication app while keeping user on current page
+     */
     invoke(data: PrepareResponse, options?: LinkAuthOptions): Promise<LinkAuthResult>;
+    /**
+     * Open authentication link without navigating away
+     */
     private openAuthenticationLink;
+    /**
+     * Start polling for authentication status with constant interval
+     */
     private startPolling;
+    /**
+     * Stop polling
+     */
     private stopPolling;
+    /**
+     * Format response for backend processing
+     */
     formatResponse(response: LinkAuthResult): any;
+    /**
+     * Check if link strategy is supported
+     * Returns true for mobile devices (iOS and Android)
+     */
     isSupported(): boolean;
+    /**
+     * Clean up resources (stop polling if active)
+     */
     cleanup(): void;
+    /**
+     * Check if polling is currently active
+     */
     isPolling(): boolean;
+    /**
+     * Cancel the ongoing authentication
+     */
     cancel(): void;
 }