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

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

@@ -1,28 +1,61 @@
+/**
+ * Glide Phone Authentication API Types
+ *
+ * This file is copied from the master API specification at /glide-api-types.ts
+ * It defines the exact contract that ALL implementations must follow.
+ *
+ * NAMING CONVENTION:
+ * - ALL TYPES USE snake_case FOR API COMMUNICATION
+ * - Frontend SDKs should use snake_case throughout for consistency
+ * - This eliminates conversion errors and makes debugging easier
+ * - While not idiomatic JavaScript, it matches the API exactly
+ */
+// ============================================================================
+// USE CASES
+// ============================================================================
 export const USE_CASE = {
     GET_PHONE_NUMBER: 'GetPhoneNumber',
     VERIFY_PHONE_NUMBER: 'VerifyPhoneNumber'
 };
+// ============================================================================
+// AUTHENTICATION STRATEGIES
+// ============================================================================
 export const AUTHENTICATION_STRATEGY = {
     TS43: 'ts43',
     LINK: 'link',
     DESKTOP: 'desktop'
 };
+// ============================================================================
+// ERROR HANDLING
+// ============================================================================
+/**
+ * Error codes - MUST match server implementation
+ */
 export const ERROR_CODE = {
+    // 400 Bad Request
     INVALID_PHONE_NUMBER: 'INVALID_PHONE_NUMBER',
     MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD',
     INVALID_USE_CASE: 'INVALID_USE_CASE',
+    // 404 Not Found
     INVALID_SESSION: 'INVALID_SESSION',
     SESSION_EXPIRED: 'SESSION_EXPIRED',
+    // 422 Unprocessable Entity
     CARRIER_NOT_ELIGIBLE: 'CARRIER_NOT_ELIGIBLE',
     UNSUPPORTED_PLATFORM: 'UNSUPPORTED_PLATFORM',
     PHONE_NUMBER_MISMATCH: 'PHONE_NUMBER_MISMATCH',
     INVALID_CREDENTIAL: 'INVALID_CREDENTIAL',
     VERIFICATION_FAILED: 'VERIFICATION_FAILED',
     USE_CASE_MISMATCH: 'USE_CASE_MISMATCH',
+    // 429 Too Many Requests
     RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
+    // 500 Internal Server Error
     INTERNAL_SERVER_ERROR: 'INTERNAL_SERVER_ERROR',
+    // 503 Service Unavailable
     SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE'
 };
+/**
+ * Error messages - User-friendly messages for each error code
+ */
 export const ERROR_MESSAGES = {
     [ERROR_CODE.INVALID_PHONE_NUMBER]: "Phone number must be in E.164 format",
     [ERROR_CODE.MISSING_REQUIRED_FIELD]: "Required field is missing",
@@ -39,6 +72,9 @@ export const ERROR_MESSAGES = {
     [ERROR_CODE.INTERNAL_SERVER_ERROR]: "An unexpected error occurred",
     [ERROR_CODE.SERVICE_UNAVAILABLE]: "Service temporarily unavailable"
 };
+/**
+ * HTTP status codes for each error
+ */
 export const ERROR_STATUS_CODES = {
     [ERROR_CODE.INVALID_PHONE_NUMBER]: 400,
     [ERROR_CODE.MISSING_REQUIRED_FIELD]: 400,
@@ -55,26 +91,50 @@ export const ERROR_STATUS_CODES = {
     [ERROR_CODE.INTERNAL_SERVER_ERROR]: 500,
     [ERROR_CODE.SERVICE_UNAVAILABLE]: 503
 };
+// ============================================================================
+// VALIDATION HELPERS
+// ============================================================================
+/**
+ * E.164 phone number validation regex
+ */
 export const E164_REGEX = /^\+[1-9]\d{1,14}$/;
+/**
+ * Validate phone number format
+ */
 export function validatePhoneNumber(phone) {
     return E164_REGEX.test(phone);
 }
+/**
+ * Validate PLMN format
+ */
 export function validatePLMN(plmn) {
+    // MCC: exactly 3 digits
     if (!/^\d{3}$/.test(plmn.mcc))
         return false;
+    // MNC: 2 or 3 digits
     if (!/^\d{2,3}$/.test(plmn.mnc))
         return false;
     return true;
 }
+/**
+ * Validate session info
+ */
 export function validateSession(session) {
     if (!session.session_key || session.session_key.length < 16)
         return false;
+    // nonce and enc_key are optional and stored in metadata if needed
     return true;
 }
+/**
+ * Validate use case
+ */
 export function validateUseCase(useCase) {
     return useCase === USE_CASE.GET_PHONE_NUMBER ||
         useCase === USE_CASE.VERIFY_PHONE_NUMBER;
 }
+/**
+ * Create error response helper
+ */
 export function createErrorResponse(code, details, requestId) {
     return {
         code,
@@ -84,37 +144,60 @@ export function createErrorResponse(code, details, requestId) {
         details
     };
 }
+/**
+ * Get HTTP status code for error
+ */
 export function getErrorStatusCode(code) {
     return ERROR_STATUS_CODES[code] || 500;
 }
+// ============================================================================
+// TYPE GUARDS
+// ============================================================================
+/**
+ * Check if data is TS43 strategy data
+ */
 export function isTS43Data(data) {
+    // Check for TS43 data structure - has protocol and data.dcql_query
     return data &&
         typeof data.protocol === 'string' &&
         data.data &&
         data.data.dcql_query;
 }
+/**
+ * Check if data is Link strategy data
+ */
 export function isLinkData(data) {
     return data && data.url && typeof data.url === 'string';
 }
+/**
+ * Check if response is an error
+ */
 export function isErrorResponse(response) {
     return response &&
         typeof response.code === 'string' &&
         typeof response.message === 'string';
 }
+// ============================================================================
+// EXPORTS FOR CONVENIENCE
+// ============================================================================
 export default {
+    // Constants
     USE_CASE,
     AUTHENTICATION_STRATEGY,
     ERROR_CODE,
     ERROR_MESSAGES,
     ERROR_STATUS_CODES,
     E164_REGEX,
+    // Validators
     validatePhoneNumber,
     validatePLMN,
     validateSession,
     validateUseCase,
+    // Type guards
     isTS43Data,
     isLinkData,
     isErrorResponse,
+    // Helpers
     createErrorResponse,
     getErrorStatusCode
 };

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

@@ -12,34 +12,178 @@ export declare class PhoneAuthClient {
     private baseTimeout;
     private lastRequest?;
     constructor(config?: AuthConfig);
+    /**
+     * Get user-friendly error message using error utilities
+     */
     private getUserFriendlyMessage;
+    /**
+     * Log error with proper context and sanitization
+     */
     private logError;
+    /**
+     * Check if the browser supports secure phone authentication
+     */
     isSupported(): boolean;
+    /**
+     * Get detailed browser support information
+     */
     getBrowserSupportInfo(): {
         supported: boolean;
         browser: string;
         message?: string;
         helpUrl?: string;
     };
+    /**
+     * Main verification method with silent retry support
+     */
     verify(options: PhoneAuthOptions): Promise<PhoneAuthResult>;
     private verifyWithRetry;
+    /**
+     * High-level method to get phone number (complete flow)
+     * Handles prepare, credential prompt, and get phone number in one call
+     */
     getPhoneNumberComplete(options?: Omit<PhoneAuthOptions, 'use_case' | 'phone_number'>): Promise<PhoneAuthResult>;
+    /**
+     * High-level method to verify phone number (complete flow)
+     * Handles prepare, credential prompt, and verification in one call
+     */
     verifyPhoneNumberComplete(phoneNumber: string, options?: Omit<PhoneAuthOptions, 'use_case' | 'phone_number'>): Promise<PhoneAuthResult>;
+    /**
+     * 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: PhoneAuthOptions): Promise<PrepareResponse>;
+    /**
+     * 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: PrepareResponse, options?: InvokeOptions | DesktopAuthOptions): Promise<AuthCredential | SecureCredentialResponse['vp_token'] | AnyExtendedResponse>;
+    /**
+     * 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: SecureCredentialResponse['vp_token'] | string, session: SessionInfo): Promise<GetPhoneNumberResponse>;
+    /**
+     * 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: SecureCredentialResponse['vp_token'] | string, session: SessionInfo): Promise<VerifyPhoneNumberResponse>;
+    /**
+     * Helper to extract credential string from various formats
+     */
     private extractCredentialString;
+    /**
+     * Helper to extract error details from response
+     */
     private extractErrorDetails;
+    /**
+     * Fetch with timeout
+     */
     private fetchWithTimeout;
+    /**
+     * Create an AuthError
+     */
     private createError;
+    /**
+     * Type guard for AuthError
+     */
     private isAuthError;
+    /**
+     * Debug logging
+     */
     private log;
+    /**
+     * Determine if an error should trigger a retry
+     */
     private shouldRetry;
+    /**
+     * Analyze and enhance errors specific to cross-device flows
+     */
     private analyzeCrossDeviceError;
+    /**
+     * Cache successful session for retry scenarios
+     */
     private cacheSession;
+    /**
+     * Retrieve cached session if available and recent
+     */
     private getCachedSession;
+    /**
+     * Generate cache key for session storage
+     */
     private getCacheKey;
+    /**
+     * Set up periodic cache cleanup
+     */
     private setupCacheCleanup;
+    /**
+     * Utility delay function
+     */
     private delay;
 }