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

package/dist/esm/core/phone-auth/type-guards.js

@@ -1,3 +1,27 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function isExtendedResponse(result) {
     return result &&
         typeof result === 'object' &&
@@ -6,16 +30,41 @@ export function isExtendedResponse(result) {
         'cancel' in result &&
         typeof result.cancel === 'function';
 }
+/**
+ * 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 function isCredential(result) {
     if (!result)
         return false;
+    // String credentials are valid
     if (typeof result === 'string')
         return true;
+    // Object credentials should NOT have ExtendedResponse properties
     if (typeof result === 'object') {
         return !('strategy' in result) && !('credential' in result) && !('cancel' in result);
     }
     return false;
 }
+/**
+ * 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 function isAuthCredential(result) {
     return result &&
         typeof result === 'object' &&
@@ -23,32 +72,114 @@ export function isAuthCredential(result) {
         'authenticated' in result &&
         'session' in result;
 }
+/**
+ * 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 function isLinkStrategy(result) {
     return result.strategy === 'link';
 }
+/**
+ * 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 function isTS43Strategy(result) {
     return result.strategy === 'ts43';
 }
+/**
+ * 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 function isDesktopStrategy(result) {
     return result.strategy === 'desktop';
 }
+/**
+ * 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 function getStrategy(result) {
     if (isExtendedResponse(result)) {
         return result.strategy;
     }
     return 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 function hasPollingControls(result) {
     if (!isExtendedResponse(result))
         return false;
     return (result.strategy === 'link' && 'start_polling' in result) ||
         (result.strategy === 'desktop' && 'start_polling' in result);
 }
+/**
+ * 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 function hasTrigger(result) {
     if (!isExtendedResponse(result))
         return false;
     return 'trigger' in result && typeof result.trigger === 'function';
 }
+// Export legacy function names as deprecated aliases for backward compatibility
+/**
+ * @deprecated Use isExtendedResponse instead
+ */
 export const isHeadlessResult = isExtendedResponse;
+/**
+ * @deprecated Use hasPollingControls instead
+ */
 export const requiresPolling = hasPollingControls;
+/**
+ * @deprecated This function is no longer needed as extended mode handles user actions differently
+ */
 export const requiresUserAction = (result) => false;

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

@@ -1,33 +1,105 @@
+/**
+ * Phone Authentication Types
+ *
+ * This file exports the types used by the Phone Auth SDK.
+ * All API types are imported from api-types.ts to ensure consistency.
+ * No backward compatibility - using clean API specification only.
+ */
 export * from './api-types';
 import type { PrepareRequest as APIPrepareRequest, GetPhoneNumberResponse, VerifyPhoneNumberResponse, UseCase as APIUseCase, AuthenticationStrategy as APIAuthStrategy } from './api-types';
 export type PhoneAuthOptions = APIPrepareRequest;
 export type PhoneAuthResult = GetPhoneNumberResponse | VerifyPhoneNumberResponse;
 export type UseCaseType = APIUseCase;
 export type AuthenticationStrategyType = APIAuthStrategy;
+/**
+ * SDK-specific error codes from error-utils
+ */
 import type { PhoneAuthErrorCode as ErrorCodeFromUtils } from './error-utils';
 export type PhoneAuthErrorCode = ErrorCodeFromUtils;
+/**
+ * SDK configuration callbacks
+ */
 export interface PhoneAuthCallbacks {
+    /**
+     * Called when cross-device authentication is detected (e.g., QR code shown)
+     */
     onCrossDeviceDetected?: () => void;
+    /**
+     * Called when a retry attempt is made
+     * @param attempt Current attempt number
+     * @param maxAttempts Maximum number of attempts
+     */
     onRetryAttempt?: (attempt: number, maxAttempts: number) => void;
+    /**
+     * Called when authentication times out
+     */
     onTimeout?: () => void;
+    /**
+     * Called when user cancels authentication
+     */
     onCancel?: () => void;
+    /**
+     * Called when polling starts
+     */
     onPollingStart?: () => void;
+    /**
+     * Called when polling stops
+     */
     onPollingStop?: () => void;
 }
+/**
+ * SDK configuration options
+ */
 export interface AuthConfig extends PhoneAuthCallbacks {
+    /**
+     * Custom endpoints for authentication flow
+     */
     endpoints?: {
         prepare?: string;
         process?: string;
+        /** Desktop authentication status polling endpoint */
         polling?: string;
     };
+    /**
+     * Timeout for API calls in milliseconds
+     * @default 30000
+     */
     timeout?: number;
+    /**
+     * Polling interval in milliseconds for status checks
+     * @default 2000
+     */
     pollingInterval?: number;
+    /**
+     * Maximum polling attempts before timeout
+     * @default 30 (1 minute with 2s interval)
+     */
     maxPollingAttempts?: number;
+    /**
+     * Enable debug logging
+     * @default false
+     */
     debug?: boolean;
+    /**
+     * Developer environment for testing (e.g., 'dev1', 'dev2')
+     * When set, adds a 'developer' header to polling requests
+     */
+    devEnv?: string;
+    /**
+     * Developer tools configuration for debugging
+     */
     devtools?: {
+        /**
+         * Show mobile console overlay for on-device debugging
+         * Displays all console logs at the bottom of the screen
+         * @default false
+         */
         showMobileConsole?: boolean;
     };
 }
+/**
+ * SDK-enhanced error type with additional context
+ */
 export interface AuthError {
     code: PhoneAuthErrorCode;
     message: string;
@@ -54,7 +126,13 @@ export interface AuthError {
         [key: string]: any;
     };
 }
+/**
+ * SDK authentication flow steps
+ */
 export type AuthStep = 'idle' | 'requesting' | 'authenticating' | 'processing' | 'complete';
+/**
+ * Browser error names
+ */
 export declare const BrowserError: {
     readonly NOT_ALLOWED: "NotAllowedError";
     readonly NETWORK: "NetworkError";
@@ -72,6 +150,9 @@ export declare const BrowserError: {
     readonly SYNTAX: "SyntaxError";
 };
 export type BrowserErrorType = typeof BrowserError[keyof typeof BrowserError];
+/**
+ * Browser error codes
+ */
 export declare const BrowserErrorCode: {
     readonly USER_CANCELLED_DC_API: 19;
     readonly PERMISSION_DENIED: 1;
@@ -83,6 +164,9 @@ export declare const BrowserErrorCode: {
     readonly SECURITY: 18;
 };
 export type BrowserErrorCodeType = typeof BrowserErrorCode[keyof typeof BrowserErrorCode];
+/**
+ * Browser names for detection
+ */
 export declare const BrowserName: {
     readonly CHROME: "Chrome";
     readonly EDGE: "Edge";
@@ -93,6 +177,9 @@ export declare const BrowserName: {
     readonly OTHER: "other";
 };
 export type BrowserNameType = typeof BrowserName[keyof typeof BrowserName];
+/**
+ * Browser Digital Credential type (extends standard Credential)
+ */
 export interface DigitalCredential extends Credential {
     data: {
         vp_token: {
@@ -100,6 +187,9 @@ export interface DigitalCredential extends Credential {
         };
     };
 }
+/**
+ * Browser credential request structure
+ */
 export interface SecureCredentialRequest {
     digital: {
         requests: Array<{
@@ -108,17 +198,40 @@ export interface SecureCredentialRequest {
         }>;
     };
 }
+/**
+ * Authentication status constants
+ * Maps to both client-side states and backend responses
+ */
 export declare const AuthStatus: {
+    /** Authentication in progress */
     readonly PENDING: "pending";
+    /** Authentication completed successfully */
     readonly COMPLETED: "completed";
+    /** User cancelled authentication */
     readonly CANCELLED: "cancelled";
+    /** Authentication failed or expired */
     readonly FAILED: "failed";
+    /** Session expired (backend returns 410 Gone) */
     readonly EXPIRED: "expired";
+    /** Session not found (backend returns 404) */
     readonly NOT_FOUND: "not_found";
 };
 export type AuthStatusType = typeof AuthStatus[keyof typeof AuthStatus];
+/**
+ * Controller for managing authentication sessions
+ * Allows cancellation and cleanup of ongoing authentication
+ */
 export interface AuthController {
+    /**
+     * Cancel the ongoing authentication
+     */
     cancel(): void;
+    /**
+     * The authentication promise
+     */
     promise: Promise<any>;
+    /**
+     * Current status of the authentication
+     */
     status: AuthStatusType;
 }

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

@@ -1,4 +1,20 @@
+/**
+ * Phone Authentication Types
+ *
+ * This file exports the types used by the Phone Auth SDK.
+ * All API types are imported from api-types.ts to ensure consistency.
+ * No backward compatibility - using clean API specification only.
+ */
+// ============================================================================
+// RE-EXPORT ALL API TYPES
+// ============================================================================
 export * from './api-types';
+// ============================================================================
+// BROWSER-SPECIFIC TYPES
+// ============================================================================
+/**
+ * Browser error names
+ */
 export const BrowserError = {
     NOT_ALLOWED: 'NotAllowedError',
     NETWORK: 'NetworkError',
@@ -15,6 +31,9 @@ export const BrowserError = {
     RANGE: 'RangeError',
     SYNTAX: 'SyntaxError'
 };
+/**
+ * Browser error codes
+ */
 export const BrowserErrorCode = {
     USER_CANCELLED_DC_API: 19,
     PERMISSION_DENIED: 1,
@@ -25,6 +44,9 @@ export const BrowserErrorCode = {
     NETWORK: 19,
     SECURITY: 18
 };
+/**
+ * Browser names for detection
+ */
 export const BrowserName = {
     CHROME: 'Chrome',
     EDGE: 'Edge',
@@ -34,11 +56,21 @@ export const BrowserName = {
     BRAVE: 'Brave',
     OTHER: 'other'
 };
+/**
+ * Authentication status constants
+ * Maps to both client-side states and backend responses
+ */
 export const AuthStatus = {
+    /** Authentication in progress */
     PENDING: 'pending',
+    /** Authentication completed successfully */
     COMPLETED: 'completed',
+    /** User cancelled authentication */
     CANCELLED: 'cancelled',
+    /** Authentication failed or expired */
     FAILED: 'failed',
+    /** Session expired (backend returns 410 Gone) */
     EXPIRED: 'expired',
+    /** Session not found (backend returns 404) */
     NOT_FOUND: 'not_found'
 };

package/dist/esm/core/phone-auth/ui/mobile-debug-console.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Mobile Debug Console
+ * A lightweight console overlay for debugging on mobile devices where dev tools aren't available
+ */
 export declare class MobileDebugConsole {
     private static instance;
     private logs;

package/dist/esm/core/phone-auth/ui/mobile-debug-console.js

@@ -1,3 +1,7 @@
+/**
+ * Mobile Debug Console
+ * A lightweight console overlay for debugging on mobile devices where dev tools aren't available
+ */
 export class MobileDebugConsole {
     constructor() {
         this.logs = [];
@@ -32,13 +36,15 @@ export class MobileDebugConsole {
         ['log', 'error', 'warn', 'debug', 'info'].forEach(method => {
             const originalMethod = this.originalConsole[method];
             console[method] = (...args) => {
+                // Call original
                 originalMethod.apply(console, args);
+                // Add to our display
                 this.addLog(method, args);
             };
         });
     }
     addLog(type, args) {
-        const timestamp = new Date().toTimeString().split(' ')[0];
+        const timestamp = new Date().toTimeString().split(' ')[0]; // HH:MM:SS
         const content = args.map(arg => {
             if (typeof arg === 'object') {
                 try {
@@ -50,6 +56,7 @@ export class MobileDebugConsole {
             }
             return String(arg);
         }).join(' ');
+        // Create colored log entry
         const colors = {
             log: '#fff',
             error: '#ff6b6b',
@@ -65,6 +72,7 @@ export class MobileDebugConsole {
       </div>
     `;
         this.logs.push(logHtml);
+        // Keep only last 500 logs
         if (this.logs.length > 500) {
             this.logs.shift();
         }
@@ -73,13 +81,17 @@ export class MobileDebugConsole {
     updateDisplay() {
         if (!this.logsContainer || !this.isVisible)
             return;
+        // Check if scrolled to bottom before update
         this.isAtBottom = this.logsContainer.scrollHeight - this.logsContainer.scrollTop <= this.logsContainer.clientHeight + 50;
+        // Update content
         this.logsContainer.innerHTML = this.logs.join('');
+        // Auto-scroll only if was at bottom
         if (this.isAtBottom) {
             this.logsContainer.scrollTop = this.logsContainer.scrollHeight;
         }
     }
     createUI() {
+        // Create styles
         const style = document.createElement('style');
         style.textContent = `
       #mobile-debug-console {
@@ -172,11 +184,13 @@ export class MobileDebugConsole {
       }
     `;
         document.head.appendChild(style);
+        // Create container
         this.container = document.createElement('div');
         this.container.id = 'mobile-debug-console';
         if (!this.isVisible) {
             this.container.className = 'hidden';
         }
+        // Create header
         const header = document.createElement('div');
         header.id = 'debug-header';
         const title = document.createElement('div');
@@ -184,12 +198,15 @@ export class MobileDebugConsole {
         title.textContent = '📱 Mobile Debug Console';
         const buttons = document.createElement('div');
         buttons.id = 'debug-buttons';
+        // Clear button
         const clearBtn = document.createElement('button');
         clearBtn.textContent = 'Clear';
         clearBtn.onclick = () => this.clear();
+        // Show/Hide button
         const toggleBtn = document.createElement('button');
         toggleBtn.textContent = 'Hide';
         toggleBtn.onclick = () => this.toggle();
+        // Close button
         const closeBtn = document.createElement('button');
         closeBtn.textContent = '✕';
         closeBtn.style.color = '#ff6b6b';
@@ -199,20 +216,25 @@ export class MobileDebugConsole {
         buttons.appendChild(closeBtn);
         header.appendChild(title);
         header.appendChild(buttons);
+        // Create logs container
         this.logsContainer = document.createElement('div');
         this.logsContainer.id = 'debug-logs';
+        // Track scroll position
         this.logsContainer.addEventListener('scroll', () => {
             this.isAtBottom = this.logsContainer.scrollHeight - this.logsContainer.scrollTop <= this.logsContainer.clientHeight + 50;
         });
+        // Assemble
         this.container.appendChild(header);
         this.container.appendChild(this.logsContainer);
         document.body.appendChild(this.container);
+        // Create floating toggle button
         this.floatingToggle = document.createElement('button');
         this.floatingToggle.id = 'debug-floating-toggle';
-        this.floatingToggle.innerHTML = '🖥️';
+        this.floatingToggle.innerHTML = '🖥️'; // Console icon
         this.floatingToggle.title = 'Show Debug Console';
         this.floatingToggle.onclick = () => this.toggle();
         document.body.appendChild(this.floatingToggle);
+        // Store reference for toggle button
         window.__debugToggleBtn = toggleBtn;
     }
     escapeHtml(text) {
@@ -243,15 +265,19 @@ export class MobileDebugConsole {
         }
     }
     cleanup() {
+        // Restore original console
         Object.keys(this.originalConsole).forEach(method => {
             console[method] = this.originalConsole[method];
         });
+        // Remove UI
         if (this.container) {
             this.container.remove();
         }
+        // Remove floating toggle
         if (this.floatingToggle) {
             this.floatingToggle.remove();
         }
+        // Clean up references
         delete window.__debugToggleBtn;
     }
 }

package/dist/esm/core/phone-auth/ui/modal.d.ts

@@ -1,11 +1,22 @@
+/**
+ * Modal UI Component for Phone Authentication
+ *
+ * This file creates the UI components (modals, buttons) that are shown
+ * when the SDK is NOT in headless mode. Think of it like a popup window
+ * that handles the authentication flow for you.
+ */
 import type { InvokeOptions } from '../api-types';
 import type { QRCodeData } from '../strategies/desktop';
-export type ModalViewMode = 'toggle' | 'dual' | 'pre-step';
-export type ModalTheme = 'dark' | 'light' | 'auto';
-export type AuthModalOptions = NonNullable<InvokeOptions['modalOptions']> & {
-    viewMode?: ModalViewMode;
-    theme?: ModalTheme;
-};
+/**
+ * Creates and manages a modal dialog for authentication
+ *
+ * @example
+ * const modal = new AuthModal({
+ *   title: "Verify Your Phone",
+ *   description: "Complete authentication to continue"
+ * });
+ * modal.show();
+ */
 export declare class AuthModal {
     private container;
     private backdrop;
@@ -13,35 +24,65 @@ export declare class AuthModal {
     private options;
     private callbacks;
     private closeCallback?;
-    private theme;
-    private currentStep;
-    private qrCodeData;
-    private statusMessage;
-    private originalBodyOverflow;
-    private isClosing;
-    private readonly iconApple;
-    private readonly iconAndroid;
-    private readonly iconBack;
-    constructor(options?: AuthModalOptions, callbacks?: InvokeOptions['callbacks']);
-    private shouldUseDarkMode;
+    constructor(options?: InvokeOptions['modalOptions'], callbacks?: InvokeOptions['callbacks']);
     private handleEscapeKey;
+    /**
+     * Escape HTML to prevent XSS attacks
+     */
     private escapeHtml;
+    /**
+     * Shows the modal with a QR code for desktop authentication
+     * Supports both single QR code (legacy) and dual-platform QR codes (iOS + Android)
+     */
     showQRCode(qrCodeData: string | QRCodeData, statusMessage?: string): void;
-    updateStatus(status: string, isError?: boolean): void;
+    /**
+     * Creates a modal with iOS/Android platform toggle
+     */
+    private createDualPlatformQRModal;
+    /**
+     * Sets a callback to be called when the modal is cancelled/closed
+     */
     setCloseCallback(callback: () => void): void;
-    private renderToggleMode;
-    private renderDualMode;
-    private renderPreStepMode;
-    private setupPreStepListeners;
-    private updatePreStepUI;
-    private setupBackButton;
+    /**
+     * Shows the modal with a button for Link authentication (App Clips)
+     * IMPORTANT: The button click is required for iOS to recognize the app link
+     */
+    showLinkButton(url: string, buttonText?: string): Promise<void>;
+    /**
+     * Shows the modal with a button for TS43 authentication
+     * IMPORTANT: The button click is required for Digital Credentials API (transient activation)
+     */
+    showTS43Button(onAuthenticate: () => Promise<any>): Promise<any>;
+    /**
+     * Updates the status message in the modal
+     */
+    updateStatus(message: string, isError?: boolean): void;
+    /**
+     * Creates the modal HTML structure
+     */
     private createModal;
-    private setupHelpInteraction;
+    /**
+     * Injects CSS styles for the modal
+     */
     private injectStyles;
+    /**
+     * Shows the modal with animation
+     */
     show(): void;
+    /**
+     * Setup click handlers for iOS/Android platform toggle
+     */
     private setupPlatformToggles;
-    private lockBodyScroll;
-    private unlockBodyScroll;
+    /**
+     * Closes the modal with animation
+     */
     close(): void;
+    /**
+     * Removes modal elements from DOM
+     */
     private cleanup;
+    /**
+     * Check if modal is currently open
+     */
+    isModalOpen(): boolean;
 }