@glideidentity/web-client-sdk 5.1.3 → 6.0.0-beta.2

package/dist/esm/client/strategies/polling.js

@@ -0,0 +1,174 @@
+/**
+ * Shared polling utility for Link and Desktop strategies.
+ * Handles authentication status polling with cancel support.
+ */
+import { createAuthError, ERROR_CODES } from '../../core/errors';
+// ============================================================================
+// POLLING HANDLER
+// ============================================================================
+/**
+ * Creates a polling handler for authentication status.
+ */
+export function createPollingHandler(config) {
+    const { sessionKey, interval = 2000, maxAttempts = 30, pollingEndpoint, statusUrl, logger, } = config;
+    let pollingIntervalId;
+    let attempts = 0;
+    let isCancelled = false;
+    let isPollingActive = false;
+    let rejectFn;
+    /**
+     * Build the status URL.
+     * Priority: 1. Client config endpoint > 2. Backend status_url > 3. Prod fallback
+     */
+    function buildStatusUrl() {
+        // Priority 1: Developer-provided endpoint from client config (highest priority)
+        // Developer provides base path, we append session key
+        // Examples:
+        //   /api/phone-auth/status → /api/phone-auth/status/{sessionKey}
+        //   https://myserver.com/polling → https://myserver.com/polling/{sessionKey}
+        if (pollingEndpoint) {
+            logger?.debug('Using developer config endpoint for polling', { pollingEndpoint });
+            return `${pollingEndpoint}/${sessionKey}`;
+        }
+        // Priority 2: Backend-provided status_url from prepare response
+        // This URL already includes the session key - use as-is
+        // Example: https://api-dev.glideidentity.app/public/status/ee25b966c9395f0b
+        if (statusUrl) {
+            logger?.debug('Using backend status_url for polling', { statusUrl });
+            return statusUrl;
+        }
+        // Priority 3: Fallback to prod API - build URL with session key
+        logger?.debug('Using prod fallback for status polling');
+        return `https://api.glideidentity.app/public/status/${sessionKey}`;
+    }
+    /**
+     * Start polling.
+     */
+    function start() {
+        return new Promise((resolve, reject) => {
+            rejectFn = reject;
+            isPollingActive = true;
+            attempts = 0;
+            const poll = async () => {
+                if (!isPollingActive || isCancelled) {
+                    return;
+                }
+                // Check max attempts
+                if (attempts >= maxAttempts) {
+                    stop();
+                    logger?.warn('Polling timeout reached', { attempts, maxAttempts });
+                    resolve({
+                        status: 'expired',
+                        message: 'Authentication timeout',
+                    });
+                    return;
+                }
+                try {
+                    const url = buildStatusUrl();
+                    logger?.debug('Polling status', { url, attempt: attempts + 1, maxAttempts });
+                    const response = await fetch(url, {
+                        method: 'GET',
+                        headers: { 'Accept': 'application/json' },
+                    });
+                    if (response.status === 200) {
+                        const result = await response.json();
+                        if (result.status === 'completed') {
+                            stop();
+                            logger?.info('Authentication completed');
+                            resolve({
+                                status: 'completed',
+                                credential: result.credential || sessionKey,
+                                session: result.session || { session_key: sessionKey },
+                            });
+                            return;
+                        }
+                        // Still pending - continue
+                        attempts++;
+                    }
+                    else if (response.status === 410) {
+                        // Session expired
+                        stop();
+                        const data = await response.json().catch(() => ({}));
+                        resolve({
+                            status: 'expired',
+                            message: data.message || 'Session expired',
+                        });
+                    }
+                    else if (response.status === 422) {
+                        // Authentication failed
+                        stop();
+                        const data = await response.json().catch(() => ({}));
+                        resolve({
+                            status: 'error',
+                            message: data.message || 'Authentication failed',
+                        });
+                    }
+                    else if (response.status === 404) {
+                        // Session not found
+                        stop();
+                        resolve({
+                            status: 'error',
+                            message: 'Session not found',
+                        });
+                    }
+                    else {
+                        // Unexpected status - continue polling
+                        attempts++;
+                    }
+                }
+                catch (error) {
+                    // Network error - continue polling
+                    logger?.debug('Polling error, retrying', { error, attempt: attempts + 1 });
+                    attempts++;
+                }
+            };
+            // Start immediately
+            poll();
+            // Set up interval
+            pollingIntervalId = setInterval(poll, interval);
+        });
+    }
+    /**
+     * Stop polling.
+     */
+    function stop() {
+        isPollingActive = false;
+        if (pollingIntervalId) {
+            clearInterval(pollingIntervalId);
+            pollingIntervalId = undefined;
+        }
+    }
+    /**
+     * Cancel polling and reject the promise.
+     */
+    function cancel() {
+        logger?.debug('Polling cancelled');
+        isCancelled = true;
+        stop();
+        if (rejectFn) {
+            rejectFn(createAuthError(ERROR_CODES.CANCELLED, 'Authentication cancelled'));
+            rejectFn = undefined;
+        }
+    }
+    /**
+     * Check if polling is active.
+     */
+    function isPolling() {
+        return pollingIntervalId !== undefined;
+    }
+    /**
+     * Cleanup resources.
+     */
+    function cleanup() {
+        stop();
+        isCancelled = false;
+        rejectFn = undefined;
+    }
+    return {
+        start,
+        stop,
+        cancel,
+        isPolling,
+        cleanup,
+    };
+}

package/dist/esm/core/errors.js

@@ -0,0 +1,193 @@
+/**
+ * Error utilities for phone authentication.
+ *
+ * This file only handles CLIENT-SIDE errors (validation, browser issues, etc.).
+ * Server errors from Magic Auth are passed through as-is since they already
+ * have proper error codes and messages.
+ */
+// ============================================================================
+// CLIENT-SIDE ERROR CODES
+// ============================================================================
+/**
+ * Error codes for client-side errors only.
+ * Server errors use their own codes from Magic Auth backend.
+ */
+export const ERROR_CODES = {
+    // --- Validation Errors (before sending to server) ---
+    INVALID_PHONE_NUMBER: 'INVALID_PHONE_NUMBER',
+    INVALID_PLMN: 'INVALID_PLMN',
+    MISSING_PARAMETERS: 'MISSING_PARAMETERS',
+    // --- Browser/Platform Errors ---
+    BROWSER_NOT_SUPPORTED: 'BROWSER_NOT_SUPPORTED',
+    UNSUPPORTED_STRATEGY: 'UNSUPPORTED_STRATEGY',
+    // --- User Actions ---
+    USER_CANCELLED: 'USER_CANCELLED',
+    CANCELLED: 'CANCELLED',
+    // --- Verification Errors (client-side) ---
+    VERIFICATION_FAILED: 'VERIFICATION_FAILED',
+    // --- Network/Client Errors ---
+    NETWORK_ERROR: 'NETWORK_ERROR',
+    TIMEOUT: 'TIMEOUT',
+    INVALID_RESPONSE: 'INVALID_RESPONSE',
+};
+// ============================================================================
+// CLIENT-SIDE ERROR MESSAGES
+// ============================================================================
+/**
+ * User-facing messages for client-side errors only.
+ */
+const CLIENT_ERROR_MESSAGES = {
+    [ERROR_CODES.INVALID_PHONE_NUMBER]: 'Please enter a valid phone number in E.164 format (e.g., +14155551234).',
+    [ERROR_CODES.INVALID_PLMN]: 'Invalid carrier information provided.',
+    [ERROR_CODES.MISSING_PARAMETERS]: 'Required information is missing.',
+    [ERROR_CODES.BROWSER_NOT_SUPPORTED]: 'Your browser does not support this authentication method. Please use Chrome or Edge with the Digital Credentials flag enabled.',
+    [ERROR_CODES.UNSUPPORTED_STRATEGY]: 'This authentication strategy is not supported.',
+    [ERROR_CODES.USER_CANCELLED]: 'Authentication was cancelled.',
+    [ERROR_CODES.CANCELLED]: 'Authentication was cancelled.',
+    [ERROR_CODES.VERIFICATION_FAILED]: 'Verification failed. Please try again.',
+    [ERROR_CODES.NETWORK_ERROR]: 'Network connection failed. Please check your connection and try again.',
+    [ERROR_CODES.TIMEOUT]: 'Request timed out. Please try again.',
+    [ERROR_CODES.INVALID_RESPONSE]: 'Invalid response received.',
+};
+// ============================================================================
+// ERROR HELPER FUNCTIONS
+// ============================================================================
+/**
+ * Type guard to check if an error is an AuthError.
+ */
+export function isAuthError(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        'code' in error &&
+        'message' in error &&
+        typeof error.code === 'string' &&
+        typeof error.message === 'string');
+}
+/**
+ * Check if error is a client-side error (not from server).
+ */
+export function isClientError(error) {
+    return Object.values(ERROR_CODES).includes(error.code);
+}
+/**
+ * Check if error is retryable.
+ */
+export function isRetryableError(error) {
+    return error.code === ERROR_CODES.NETWORK_ERROR || error.code === ERROR_CODES.TIMEOUT;
+}
+/**
+ * Get user-friendly message for client-side errors.
+ * For server errors, returns the server's message as-is.
+ */
+export function getUserMessage(error) {
+    // For client-side errors, use our messages
+    if (isClientError(error)) {
+        return CLIENT_ERROR_MESSAGES[error.code] || error.message;
+    }
+    // For server errors, use the server's message directly
+    return error.message;
+}
+/**
+ * Create a client-side AuthError.
+ *
+ * @example
+ * ```typescript
+ * throw createAuthError('INVALID_PHONE_NUMBER', 'Phone number must start with +');
+ * ```
+ */
+export function createAuthError(code, message, details) {
+    const error = new Error(message || CLIENT_ERROR_MESSAGES[code] || code);
+    error.code = code;
+    error.details = details;
+    error.timestamp = new Date().toISOString();
+    return error;
+}
+/**
+ * Create a client-side AuthError with context.
+ */
+export function createAuthErrorWithContext(code, context) {
+    const error = createAuthError(code, context.message, context.details);
+    error.context = {
+        step: context.step,
+        useCase: context.useCase,
+        timestamp: new Date().toISOString(),
+        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : undefined,
+        url: typeof window !== 'undefined' ? window.location.href : undefined,
+    };
+    return error;
+}
+/**
+ * Parse error response from backend API.
+ * Simply converts the server response to AuthError format without modifying the message.
+ */
+export function parseBackendError(response) {
+    // Server error with code and message - pass through as-is
+    if (response && typeof response === 'object' && ('code' in response || 'error' in response)) {
+        const resp = response;
+        const errorCode = (resp.code || resp.error);
+        const errorMessage = resp.message;
+        // Create error with server's message directly
+        const error = new Error(errorMessage || 'An error occurred');
+        error.code = errorCode;
+        error.status = resp.status;
+        error.requestId = (resp.requestId || resp.request_id);
+        error.timestamp = resp.timestamp;
+        error.details = resp.details;
+        error.traceId = (resp.trace_id || resp.traceId);
+        error.spanId = (resp.span_id || resp.spanId);
+        error.service = resp.service;
+        // Extract retryAfter if present
+        if (resp.details && typeof resp.details === 'object' && 'retryAfter' in resp.details) {
+            error.retryAfter = resp.details.retryAfter;
+        }
+        return error;
+    }
+    // HTTP response without structured error - use status to create generic error
+    if (response && typeof response === 'object' && 'status' in response) {
+        const resp = response;
+        const status = resp.status;
+        const error = new Error(resp.message || `Request failed with status ${status}`);
+        error.code = `HTTP_${status}`;
+        error.status = status;
+        return error;
+    }
+    // Unknown error format
+    const error = new Error('An unexpected error occurred');
+    error.code = 'UNKNOWN_ERROR';
+    return error;
+}
+/**
+ * Serialize error for logging (sanitizes sensitive info).
+ */
+export function serializeError(error) {
+    return {
+        code: error.code,
+        message: error.message,
+        status: error.status,
+        requestId: error.requestId,
+        timestamp: error.timestamp,
+        traceId: error.traceId,
+        spanId: error.spanId,
+        service: error.service,
+        retryAfter: error.retryAfter,
+        browserError: error.browserError,
+        context: error.context,
+        details: sanitizeDetails(error.details),
+    };
+}
+/**
+ * Sanitize error details to remove sensitive information.
+ */
+function sanitizeDetails(details) {
+    if (!details || typeof details !== 'object') {
+        return details;
+    }
+    const sanitized = JSON.parse(JSON.stringify(details));
+    const sensitiveFields = ['carrier', 'phone_number', 'mnc', 'mcc', 'carrier_name'];
+    for (const field of sensitiveFields) {
+        delete sanitized[field];
+    }
+    return sanitized;
+}
+// TODO: Test cancel behavior - when cancel() is called, credential promise should reject
+// with error code 'CANCELLED'. Need to verify this works correctly in all scenarios.

package/dist/esm/core/index.js

@@ -0,0 +1,60 @@
+/**
+ * Glide Phone Authentication - Core Package
+ *
+ * This package contains:
+ * - All TypeScript types (API and SDK types)
+ * - Pure validation functions
+ * - Type guards for type-safe development
+ * - Error codes and utilities
+ *
+ * ZERO RUNTIME DEPENDENCIES - safe to import anywhere.
+ *
+ * @example
+ * ```typescript
+ * // Import from core for types-only usage
+ * import {
+ *   type PrepareRequest,
+ *   type PrepareResponse,
+ *   validatePhoneNumber,
+ *   isDesktopStrategy,
+ *   ERROR_CODES
+ * } from '@glideidentity/web-client-sdk/core';
+ * ```
+ */
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+export { USE_CASE, AUTHENTICATION_STRATEGY, } from './types';
+export { ERROR_CODES, } from './errors';
+// ============================================================================
+// VALIDATORS
+// ============================================================================
+export { validatePhoneNumber, validatePlmn, validateUseCaseRequirements, validateNonce, validateSessionKey, E164_REGEX, } from './validators';
+// ============================================================================
+// TYPE GUARDS
+// ============================================================================
+export { 
+// Invoke result guards
+isInvokeResult, isAuthCredential, 
+// Strategy guards
+isTS43Strategy, isLinkStrategy, isDesktopStrategy, isCancellable, 
+// Prepare response guards
+isTS43Data, isLinkData, isDesktopData, getStrategyData, 
+// Process response guards
+isGetPhoneNumberResponse, isVerifyPhoneNumberResponse, 
+// Error response guard
+isErrorResponse, } from './type-guards';
+// ============================================================================
+// ERROR UTILITIES
+// ============================================================================
+export { 
+// Type guards
+isAuthError, isClientError, isRetryableError, 
+// Message helpers
+getUserMessage, 
+// Error creation (for client-side errors only)
+createAuthError, createAuthErrorWithContext, 
+// Server error parsing (passes through as-is)
+parseBackendError, 
+// Logging
+serializeError, } from './errors';

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

@@ -0,0 +1,181 @@
+/**
+ * Type Guards for Phone Authentication.
+ *
+ * These utilities help developers work with SDK responses in a type-safe way
+ * without having to write their own type checking logic.
+ */
+import { AUTHENTICATION_STRATEGY } from './types';
+// ============================================================================
+// INVOKE RESULT TYPE GUARDS
+// ============================================================================
+/**
+ * Type guard to check if result is an InvokeResult.
+ *
+ * @example
+ * ```typescript
+ * const result = await sdk.invokeSecurePrompt(prepared);
+ * if (isInvokeResult(result)) {
+ *   const credential = await result.credential;
+ * }
+ * ```
+ */
+export function isInvokeResult(result) {
+    return (result !== null &&
+        typeof result === 'object' &&
+        'credential' in result &&
+        'strategy' in result &&
+        'session' in result);
+}
+/**
+ * Type guard to check if result is an AuthCredential.
+ *
+ * @example
+ * ```typescript
+ * const credential = await result.credential;
+ * if (isAuthCredential(credential)) {
+ *   console.log(credential.phone_number);
+ * }
+ * ```
+ */
+export function isAuthCredential(result) {
+    return (result !== null &&
+        typeof result === 'object' &&
+        'credential' in result &&
+        'authenticated' in result &&
+        'session' in result);
+}
+// ============================================================================
+// STRATEGY TYPE GUARDS
+// ============================================================================
+/**
+ * Check if result is from TS43 strategy.
+ * TS43 uses Android Digital Credentials API.
+ *
+ * @example
+ * ```typescript
+ * const result = await sdk.invokeSecurePrompt(prepared);
+ * if (isTS43Strategy(result)) {
+ *   // result.cancel is undefined for TS43
+ *   // To retry: call invokeSecurePrompt again
+ * }
+ * ```
+ */
+export function isTS43Strategy(result) {
+    return result.strategy === AUTHENTICATION_STRATEGY.TS43;
+}
+/**
+ * Check if result is from Link strategy.
+ * Link strategy uses iOS App Clips or Android App Links.
+ *
+ * @example
+ * ```typescript
+ * const result = await sdk.invokeSecurePrompt(prepared);
+ * if (isLinkStrategy(result)) {
+ *   // Can cancel polling
+ *   result.cancel?.();
+ * }
+ * ```
+ */
+export function isLinkStrategy(result) {
+    return result.strategy === AUTHENTICATION_STRATEGY.LINK;
+}
+/**
+ * Check if result is from Desktop strategy.
+ * Desktop strategy uses QR codes for cross-device auth.
+ *
+ * @example
+ * ```typescript
+ * const result = await sdk.invokeSecurePrompt(prepared);
+ * if (isDesktopStrategy(result)) {
+ *   // QR code data is in prepared.data
+ *   // Can cancel polling
+ *   result.cancel?.();
+ * }
+ * ```
+ */
+export function isDesktopStrategy(result) {
+    return result.strategy === AUTHENTICATION_STRATEGY.DESKTOP;
+}
+/**
+ * Check if result has cancel capability.
+ * Only Link and Desktop strategies support cancel.
+ */
+export function isCancellable(result) {
+    return result.cancel !== undefined;
+}
+// ============================================================================
+// PREPARE RESPONSE TYPE GUARDS
+// ============================================================================
+/**
+ * Check if prepare response data is TS43Data.
+ */
+export function isTS43Data(data) {
+    return (data !== null &&
+        typeof data === 'object' &&
+        'protocol' in data &&
+        'data' in data &&
+        typeof data.data === 'object' &&
+        'dcql_query' in data.data);
+}
+/**
+ * Check if prepare response data is LinkData.
+ */
+export function isLinkData(data) {
+    return (data !== null &&
+        typeof data === 'object' &&
+        'url' in data &&
+        typeof data.url === 'string');
+}
+/**
+ * Check if prepare response data is DesktopData.
+ */
+export function isDesktopData(data) {
+    return (data !== null &&
+        typeof data === 'object' &&
+        'data' in data &&
+        typeof data.data === 'object');
+}
+/**
+ * Get strategy-specific data from PrepareResponse with proper typing.
+ *
+ * @example
+ * ```typescript
+ * const prepared = await sdk.prepare(request);
+ *
+ * if (prepared.authentication_strategy === 'desktop') {
+ *   const desktopData = getStrategyData(prepared);
+ *   // Show QR code: desktopData.data.ios_qr_image
+ * }
+ * ```
+ */
+export function getStrategyData(prepared) {
+    return prepared.data;
+}
+// ============================================================================
+// PROCESS RESPONSE TYPE GUARDS
+// ============================================================================
+/**
+ * Check if response is GetPhoneNumberResponse.
+ */
+export function isGetPhoneNumberResponse(result) {
+    return !('verified' in result);
+}
+/**
+ * Check if response is VerifyPhoneNumberResponse.
+ */
+export function isVerifyPhoneNumberResponse(result) {
+    return 'verified' in result;
+}
+// ============================================================================
+// ERROR TYPE GUARDS
+// ============================================================================
+// Note: isAuthError is exported from errors.ts to avoid duplication
+/**
+ * Check if response is an error response from server.
+ */
+export function isErrorResponse(response) {
+    return (response !== null &&
+        typeof response === 'object' &&
+        'code' in response &&
+        'message' in response);
+}

package/dist/esm/core/types.js

@@ -1 +1,22 @@
-export {};
+/**
+ * Glide Phone Authentication - Core Types
+ *
+ * This file contains all types for the Phone Auth SDK.
+ * Zero runtime dependencies - pure TypeScript types and constants.
+ *
+ * NAMING CONVENTION:
+ * - All types use snake_case to match API communication
+ * - This eliminates conversion errors and makes debugging easier
+ */
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+export const USE_CASE = {
+    GET_PHONE_NUMBER: 'GetPhoneNumber',
+    VERIFY_PHONE_NUMBER: 'VerifyPhoneNumber'
+};
+export const AUTHENTICATION_STRATEGY = {
+    TS43: 'ts43',
+    LINK: 'link',
+    DESKTOP: 'desktop'
+};