@glideidentity/web-client-sdk 4.4.8-beta.1

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

@@ -0,0 +1,203 @@
+/**
+ * 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",
+    [ERROR_CODE.INVALID_USE_CASE]: "Use case must be 'GetPhoneNumber' or 'VerifyPhoneNumber'",
+    [ERROR_CODE.INVALID_SESSION]: "Session not found or expired",
+    [ERROR_CODE.SESSION_EXPIRED]: "Session has expired",
+    [ERROR_CODE.CARRIER_NOT_ELIGIBLE]: "Your carrier does not support this verification method",
+    [ERROR_CODE.UNSUPPORTED_PLATFORM]: "Your platform is not supported",
+    [ERROR_CODE.PHONE_NUMBER_MISMATCH]: "Phone number does not match the device",
+    [ERROR_CODE.INVALID_CREDENTIAL]: "Invalid or expired credential",
+    [ERROR_CODE.VERIFICATION_FAILED]: "Phone number verification failed",
+    [ERROR_CODE.USE_CASE_MISMATCH]: "Session was prepared for a different use case",
+    [ERROR_CODE.RATE_LIMIT_EXCEEDED]: "Too many requests. Please try again later",
+    [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,
+    [ERROR_CODE.INVALID_USE_CASE]: 400,
+    [ERROR_CODE.INVALID_SESSION]: 404,
+    [ERROR_CODE.SESSION_EXPIRED]: 404,
+    [ERROR_CODE.CARRIER_NOT_ELIGIBLE]: 422,
+    [ERROR_CODE.UNSUPPORTED_PLATFORM]: 422,
+    [ERROR_CODE.PHONE_NUMBER_MISMATCH]: 422,
+    [ERROR_CODE.INVALID_CREDENTIAL]: 422,
+    [ERROR_CODE.VERIFICATION_FAILED]: 422,
+    [ERROR_CODE.USE_CASE_MISMATCH]: 422,
+    [ERROR_CODE.RATE_LIMIT_EXCEEDED]: 429,
+    [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,
+        message: ERROR_MESSAGES[code],
+        request_id: requestId,
+        timestamp: new Date().toISOString(),
+        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

@@ -0,0 +1,187 @@
+import type { PrepareResponse, GetPhoneNumberResponse, VerifyPhoneNumberResponse, SecureCredentialResponse, SessionInfo, InvokeOptions, HeadlessResult } from './api-types';
+import type { AuthConfig, PhoneAuthOptions, PhoneAuthResult } from './types';
+import type { DesktopAuthOptions } from './strategies/desktop';
+export declare class PhoneAuthClient {
+    private config;
+    private debug;
+    private logger;
+    private crossDeviceActive;
+    private retryCount;
+    private sessionCache;
+    private callbacks;
+    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 Headless Mode (returns data)
+     * ```typescript
+     * // Get raw data without showing UI
+     * const result = await phoneAuth.invokeSecurePrompt(prepareResult, {
+     *   headless: true
+     * });
+     *
+     * if (result.strategy === 'link') {
+     *   // Open URL yourself
+     *   window.open(result.url);
+     *   await result.pollingPromise; // Wait for completion
+     * }
+     * ```
+     *
+     * @param prepareResponse - Response from prepare() with strategy and data
+     * @param options - Control UI behavior or enable headless mode
+     * @returns Credential or HeadlessResult based on mode
+     */
+    invokeSecurePrompt(prepareResponse: PrepareResponse, options?: InvokeOptions | DesktopAuthOptions): Promise<SecureCredentialResponse['vp_token'] | HeadlessResult>;
+    /**
+     * 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;
+}