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

package/dist/core/phone-auth/error-utils.js

@@ -11,31 +11,38 @@ exports.parseBackendError = parseBackendError;
 exports.serializeError = serializeError;
 exports.createErrorBreadcrumb = createErrorBreadcrumb;
 const version_1 = require("../version");
+// Error constants matching the backend for consistency
 exports.PhoneAuthErrorCode = {
+    // 400 Bad Request errors
     BAD_REQUEST: 'BAD_REQUEST',
     VALIDATION_ERROR: 'VALIDATION_ERROR',
     INVALID_PARAMETERS: 'INVALID_PARAMETERS',
     MISSING_PARAMETERS: 'MISSING_PARAMETERS',
     INVALID_PHONE_NUMBER: 'INVALID_PHONE_NUMBER',
     INVALID_MCC_MNC: 'INVALID_MCC_MNC',
+    // 401 Unauthorized errors
     UNAUTHORIZED: 'UNAUTHORIZED',
     INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
     EXPIRED_TOKEN: 'EXPIRED_TOKEN',
     TOKEN_ACQUISITION_FAILED: 'TOKEN_ACQUISITION_FAILED',
     INVALID_API_KEY: 'INVALID_API_KEY',
     MISSING_AUTH_HEADER: 'MISSING_AUTH_HEADER',
+    // 403 Forbidden errors
     FORBIDDEN: 'FORBIDDEN',
     INSUFFICIENT_PERMISSIONS: 'INSUFFICIENT_PERMISSIONS',
     ACCESS_DENIED: 'ACCESS_DENIED',
+    // 404 Not Found errors
     NOT_FOUND: 'NOT_FOUND',
     RESOURCE_NOT_FOUND: 'RESOURCE_NOT_FOUND',
     SESSION_NOT_FOUND: 'SESSION_NOT_FOUND',
     CARRIER_NOT_FOUND: 'CARRIER_NOT_FOUND',
     ENDPOINT_NOT_FOUND: 'ENDPOINT_NOT_FOUND',
+    // 409 Conflict errors
     CONFLICT: 'CONFLICT',
     RESOURCE_ALREADY_EXISTS: 'RESOURCE_ALREADY_EXISTS',
     DUPLICATE_SESSION: 'DUPLICATE_SESSION',
     CONCURRENT_MODIFICATION: 'CONCURRENT_MODIFICATION',
+    // 422 Unprocessable Entity errors
     UNPROCESSABLE_ENTITY: 'UNPROCESSABLE_ENTITY',
     UNSUPPORTED_VERIFICATION: 'UNSUPPORTED_VERIFICATION',
     INVALID_VERIFICATION: 'INVALID_VERIFICATION',
@@ -51,117 +58,160 @@ exports.PhoneAuthErrorCode = {
     INVALID_SESSION_STATE: 'INVALID_SESSION_STATE',
     PHONE_NUMBER_MISMATCH: 'PHONE_NUMBER_MISMATCH',
     INVALID_CREDENTIAL_FORMAT: 'INVALID_CREDENTIAL_FORMAT',
+    // 429 Too Many Requests errors
     RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
     TOO_MANY_REQUESTS: 'TOO_MANY_REQUESTS',
     QUOTA_EXCEEDED: 'QUOTA_EXCEEDED',
+    // 500 Internal Server errors
     INTERNAL_SERVER_ERROR: 'INTERNAL_SERVER_ERROR',
     CIRCUIT_BREAKER_CONFIGURATION_ERROR: 'CIRCUIT_BREAKER_CONFIGURATION_ERROR',
     DATABASE_ERROR: 'DATABASE_ERROR',
     CACHE_ERROR: 'CACHE_ERROR',
     SERIALIZATION_ERROR: 'SERIALIZATION_ERROR',
     CRYPTO_ERROR: 'CRYPTO_ERROR',
+    // 502 Bad Gateway errors
     BAD_GATEWAY: 'BAD_GATEWAY',
     UPSTREAM_ERROR: 'UPSTREAM_ERROR',
     INVALID_RESPONSE: 'INVALID_RESPONSE',
+    // 503 Service Unavailable errors
     SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
     DOWNSTREAM_SERVICE_ERROR: 'DOWNSTREAM_SERVICE_ERROR',
     PROVIDER_ERROR: 'PROVIDER_ERROR',
     CIRCUIT_BREAKER_OPEN: 'CIRCUIT_BREAKER_OPEN',
     MAINTENANCE_MODE: 'MAINTENANCE_MODE',
+    // 504 Gateway Timeout errors
     GATEWAY_TIMEOUT: 'GATEWAY_TIMEOUT',
     REQUEST_TIMEOUT: 'REQUEST_TIMEOUT',
     UPSTREAM_TIMEOUT: 'UPSTREAM_TIMEOUT',
     DEADLINE_EXCEEDED: 'DEADLINE_EXCEEDED',
+    // Browser-specific errors (never thrown by backend)
     BROWSER_NOT_SUPPORTED: 'BROWSER_NOT_SUPPORTED',
     USER_DENIED: 'USER_DENIED',
     NETWORK_ERROR: 'NETWORK_ERROR',
 };
+// User-facing error messages - NEVER expose carrier names or phone numbers
 const USER_ERROR_MESSAGES = {
+    // Privacy-conscious messages - no carrier/phone info exposed
     CARRIER_NOT_ELIGIBLE: 'Your carrier is not eligible for this verification method.',
     CARRIER_IDENTIFICATION_FAILED: 'Unable to identify carrier for the provided phone number.',
     CARRIER_NOT_FOUND: 'Carrier information not available.',
     UNSUPPORTED_CARRIER: 'This carrier is not supported.',
+    // Rate limiting
     RATE_LIMIT_EXCEEDED: 'Too many attempts. Please wait a moment and try again.',
     TOO_MANY_REQUESTS: 'Too many requests. Please slow down and try again.',
     QUOTA_EXCEEDED: 'Usage limit reached. Please try again later.',
+    // Session errors
     SESSION_NOT_FOUND: 'Your session has expired. Please start over.',
     INVALID_SESSION_STATE: 'Invalid session state. Please start over.',
     DUPLICATE_SESSION: 'A session already exists. Please complete or cancel it first.',
+    // Browser/platform errors
     BROWSER_NOT_SUPPORTED: 'Digital Credentials API is not available. Please enable the #web-identity-digital-credentials flag in chrome://flags',
     UNSUPPORTED_PLATFORM: 'This platform is not supported for authentication.',
     UNSUPPORTED_STRATEGY: 'This authentication method is not available.',
     USER_DENIED: 'Authentication was cancelled. Please try again when you\'re ready.',
+    // Service availability
     SERVICE_UNAVAILABLE: 'The service is temporarily unavailable. Please try again later.',
     CIRCUIT_BREAKER_OPEN: 'Service is experiencing issues. Please try again later.',
     MAINTENANCE_MODE: 'Service is under maintenance. Please try again later.',
     DOWNSTREAM_SERVICE_ERROR: 'A required service is unavailable. Please try again later.',
+    // Authentication errors
     TOKEN_ACQUISITION_FAILED: 'Failed to acquire authentication token. Please try again.',
     EXPIRED_TOKEN: 'Your authentication has expired. Please start over.',
     INVALID_CREDENTIALS: 'Invalid credentials provided.',
+    // Validation errors
     INVALID_PHONE_NUMBER: 'Please enter a valid phone number.',
     PHONE_NUMBER_MISMATCH: 'Phone number mismatch. Please verify your number.',
     INVALID_PARAMETERS: 'Invalid parameters provided.',
     MISSING_PARAMETERS: 'Required information is missing.',
     VALIDATION_ERROR: 'Validation failed. Please check your input.',
+    // Network errors
     NETWORK_ERROR: 'Network connection failed. Please check your connection and try again.',
     GATEWAY_TIMEOUT: 'Request timed out. Please try again.',
     REQUEST_TIMEOUT: 'Request timed out. Please try again.',
     DEADLINE_EXCEEDED: 'Operation took too long. Please try again.',
+    // Verification errors
     VERIFICATION_FAILED: 'Verification failed. Please try again.',
     INVALID_VERIFICATION: 'Invalid verification response.',
     INVALID_CREDENTIAL_FORMAT: 'Invalid credential format.',
+    // Generic fallbacks
     BAD_REQUEST: 'Invalid request. Please try again.',
     UNAUTHORIZED: 'Authentication required.',
     FORBIDDEN: 'Access denied.',
     NOT_FOUND: 'Resource not found.',
     INTERNAL_SERVER_ERROR: 'An error occurred. Please try again later.',
 };
+// Errors that should be shown to users vs logged internally
 const USER_FACING_ERRORS = new Set([
+    // Carrier errors (privacy-safe messages)
     'CARRIER_NOT_ELIGIBLE',
     'CARRIER_IDENTIFICATION_FAILED',
     'CARRIER_NOT_FOUND',
     'UNSUPPORTED_CARRIER',
+    // Rate limiting
     'RATE_LIMIT_EXCEEDED',
     'TOO_MANY_REQUESTS',
     'QUOTA_EXCEEDED',
+    // Browser/platform
     'BROWSER_NOT_SUPPORTED',
     'UNSUPPORTED_PLATFORM',
     'UNSUPPORTED_STRATEGY',
     'USER_DENIED',
+    // Session
     'SESSION_NOT_FOUND',
     'INVALID_SESSION_STATE',
     'EXPIRED_TOKEN',
+    // Service availability
     'SERVICE_UNAVAILABLE',
     'CIRCUIT_BREAKER_OPEN',
     'MAINTENANCE_MODE',
+    // Network
     'NETWORK_ERROR',
     'GATEWAY_TIMEOUT',
     'REQUEST_TIMEOUT',
+    // Validation
     'INVALID_PHONE_NUMBER',
     'PHONE_NUMBER_MISMATCH',
     'MISSING_PARAMETERS',
     'VALIDATION_ERROR',
 ]);
+/**
+ * Type guard to check if an error is a PhoneAuthError
+ */
 function isPhoneAuthError(error) {
     return error &&
         typeof error.code === 'string' &&
         typeof error.message === 'string';
 }
+/**
+ * Check if error should be shown to user
+ */
 function isUserError(error) {
     return USER_FACING_ERRORS.has(error.code);
 }
+/**
+ * Get user-friendly error message
+ */
 function getUserMessage(error) {
     return USER_ERROR_MESSAGES[error.code] || 'An unexpected error occurred. Please try again.';
 }
+/**
+ * Check if error matches a specific code
+ */
 function isErrorCode(error, code) {
     return error.code === code;
 }
+/**
+ * Get retry delay for rate-limited requests
+ */
 function getRetryDelay(error) {
     if (error.code === exports.PhoneAuthErrorCode.RATE_LIMIT_EXCEEDED && error.retryAfter) {
-        return error.retryAfter * 1000;
+        return error.retryAfter * 1000; // Convert to milliseconds
     }
     return null;
 }
+/**
+ * Check if error is retryable
+ */
 function isRetryableError(error) {
     const retryableCodes = [
         exports.PhoneAuthErrorCode.NETWORK_ERROR,
@@ -171,8 +221,12 @@ function isRetryableError(error) {
     ];
     return retryableCodes.includes(error.code);
 }
+/**
+ * Parse error response from backend API
+ */
 function parseBackendError(response) {
     var _a, _b;
+    // Direct error structure from backend
     if (response && typeof response === 'object' && (response.code || response.error)) {
         const errorCode = response.code || response.error;
         const error = {
@@ -182,15 +236,18 @@ function parseBackendError(response) {
             requestId: response.requestId || response.request_id,
             timestamp: response.timestamp,
             details: response.details,
+            // Include trace info for observability
             traceId: response.trace_id || response.traceId,
             spanId: response.span_id || response.spanId,
             service: response.service
         };
+        // Extract retryAfter from details if present
         if ((_a = response.details) === null || _a === void 0 ? void 0 : _a.retryAfter) {
             error.retryAfter = response.details.retryAfter;
         }
         return error;
     }
+    // Handle HTTP response with error
     if (response && response.status) {
         const code = mapStatusToErrorCode(response.status);
         return {
@@ -200,12 +257,16 @@ function parseBackendError(response) {
             requestId: (_b = response.headers) === null || _b === void 0 ? void 0 : _b['x-request-id']
         };
     }
+    // Default to unexpected error
     return {
         code: exports.PhoneAuthErrorCode.INTERNAL_SERVER_ERROR,
         message: 'An unexpected error occurred',
         status: 500
     };
 }
+/**
+ * Map HTTP status to error code
+ */
 function mapStatusToErrorCode(status) {
     switch (status) {
         case 400: return exports.PhoneAuthErrorCode.BAD_REQUEST;
@@ -222,35 +283,56 @@ function mapStatusToErrorCode(status) {
         default: return exports.PhoneAuthErrorCode.INTERNAL_SERVER_ERROR;
     }
 }
+/**
+ * Serialize error for logging/observability tools like Sentry
+ * This ensures all error details are captured in a format that can be sent over the network
+ */
 function serializeError(error) {
     return {
+        // Core error info
         code: error.code,
         message: error.message,
+        // Backend error details
         status: error.status,
         requestId: error.requestId,
         timestamp: error.timestamp,
+        // Trace context for distributed tracing
         traceId: error.traceId,
         spanId: error.spanId,
         service: error.service,
+        // Specific error fields
         retryAfter: error.retryAfter,
+        // Browser error details
         browserError: error.browserError,
+        // Context
         context: error.context,
+        // Additional details (sanitized - no sensitive info)
         details: sanitizeDetails(error.details),
+        // SDK metadata
         sdkVersion: version_1.SDK_VERSION,
         errorCapturedAt: new Date().toISOString()
     };
 }
+/**
+ * Sanitize error details to remove sensitive information
+ */
 function sanitizeDetails(details) {
     if (!details || typeof details !== 'object') {
         return details;
     }
+    // Clone the object
     const sanitized = JSON.parse(JSON.stringify(details));
+    // Remove sensitive fields
     const sensitiveFields = ['carrier', 'phone_number', 'mnc', 'mcc', 'carrier_name'];
     for (const field of sensitiveFields) {
         delete sanitized[field];
     }
     return sanitized;
 }
+/**
+ * Create a breadcrumb trail for error tracking
+ * Useful for understanding the sequence of events leading to an error
+ */
 function createErrorBreadcrumb(error) {
     var _a, _b, _c;
     return {

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

@@ -2,6 +2,6 @@ export { PhoneAuthClient } from './client';
 export * from './types';
 export { PhoneAuthErrorCode, isPhoneAuthError, isUserError, getUserMessage, isErrorCode, getRetryDelay, isRetryableError, serializeError, createErrorBreadcrumb } from './error-utils';
 export type { PhoneAuthErrorCode as PhoneAuthErrorCodeType } from './error-utils';
-export { validatePhoneNumber, validatePlmn, validateUseCaseRequirements, validateNonce } from './validation-utils';
+export { validatePhoneNumber, validatePlmn, validateUseCaseRequirements } from './validation-utils';
 export { MobileDebugConsole } from './ui/mobile-debug-console';
 export { isExtendedResponse, isCredential, isAuthCredential, isLinkStrategy, isTS43Strategy, isDesktopStrategy, getStrategy, hasPollingControls, hasTrigger, isHeadlessResult, requiresPolling, requiresUserAction } from './type-guards';

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

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.requiresUserAction = exports.requiresPolling = exports.isHeadlessResult = exports.hasTrigger = exports.hasPollingControls = exports.getStrategy = exports.isDesktopStrategy = exports.isTS43Strategy = exports.isLinkStrategy = exports.isAuthCredential = exports.isCredential = exports.isExtendedResponse = exports.MobileDebugConsole = exports.validateNonce = exports.validateUseCaseRequirements = exports.validatePlmn = exports.validatePhoneNumber = exports.createErrorBreadcrumb = exports.serializeError = exports.isRetryableError = exports.getRetryDelay = exports.isErrorCode = exports.getUserMessage = exports.isUserError = exports.isPhoneAuthError = exports.PhoneAuthErrorCode = exports.PhoneAuthClient = void 0;
+exports.requiresUserAction = exports.requiresPolling = exports.isHeadlessResult = exports.hasTrigger = exports.hasPollingControls = exports.getStrategy = exports.isDesktopStrategy = exports.isTS43Strategy = exports.isLinkStrategy = exports.isAuthCredential = exports.isCredential = exports.isExtendedResponse = exports.MobileDebugConsole = exports.validateUseCaseRequirements = exports.validatePlmn = exports.validatePhoneNumber = exports.createErrorBreadcrumb = exports.serializeError = exports.isRetryableError = exports.getRetryDelay = exports.isErrorCode = exports.getUserMessage = exports.isUserError = exports.isPhoneAuthError = exports.PhoneAuthErrorCode = exports.PhoneAuthClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "PhoneAuthClient", { enumerable: true, get: function () { return client_1.PhoneAuthClient; } });
 __exportStar(require("./types"), exports);
@@ -32,7 +32,6 @@ var validation_utils_1 = require("./validation-utils");
 Object.defineProperty(exports, "validatePhoneNumber", { enumerable: true, get: function () { return validation_utils_1.validatePhoneNumber; } });
 Object.defineProperty(exports, "validatePlmn", { enumerable: true, get: function () { return validation_utils_1.validatePlmn; } });
 Object.defineProperty(exports, "validateUseCaseRequirements", { enumerable: true, get: function () { return validation_utils_1.validateUseCaseRequirements; } });
-Object.defineProperty(exports, "validateNonce", { enumerable: true, get: function () { return validation_utils_1.validateNonce; } });
 var mobile_debug_console_1 = require("./ui/mobile-debug-console");
 Object.defineProperty(exports, "MobileDebugConsole", { enumerable: true, get: function () { return mobile_debug_console_1.MobileDebugConsole; } });
 var type_guards_1 = require("./type-guards");
@@ -45,6 +44,7 @@ Object.defineProperty(exports, "isDesktopStrategy", { enumerable: true, get: fun
 Object.defineProperty(exports, "getStrategy", { enumerable: true, get: function () { return type_guards_1.getStrategy; } });
 Object.defineProperty(exports, "hasPollingControls", { enumerable: true, get: function () { return type_guards_1.hasPollingControls; } });
 Object.defineProperty(exports, "hasTrigger", { enumerable: true, get: function () { return type_guards_1.hasTrigger; } });
+// Deprecated aliases
 Object.defineProperty(exports, "isHeadlessResult", { enumerable: true, get: function () { return type_guards_1.isHeadlessResult; } });
 Object.defineProperty(exports, "requiresPolling", { enumerable: true, get: function () { return type_guards_1.requiresPolling; } });
 Object.defineProperty(exports, "requiresUserAction", { enumerable: true, get: function () { return type_guards_1.requiresUserAction; } });

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

@@ -1,12 +1,69 @@
+/**
+ * Status Types for Public Status Endpoint
+ *
+ * These types define the response format for the public status endpoint
+ * Used for polling authentication status without exposing sensitive data
+ */
+/**
+ * Status values returned by the public endpoint (HTTP 200 only)
+ */
 export type AuthenticationStatus = 'pending' | 'completed';
+/**
+ * Authentication protocol/strategy used
+ */
 export type AuthenticationProtocol = 'ts43' | 'link' | 'desktop';
+/**
+ * Public Status Response (HTTP 200 OK)
+ *
+ * This response is only returned with HTTP 200 status code
+ * Failed/expired sessions return HTTP 4xx with ErrorResponse
+ *
+ * @example
+ * ```typescript
+ * // Public endpoint (no auth required)
+ * const response = await fetch('/public/public/status/{sessionKey}');
+ *
+ * if (response.status === 200) {
+ *   const status: StatusResponse = await response.json();
+ *   if (status.status === 'completed') {
+ *     // Authentication successful - now call process endpoint
+ *     const result = await processAuthentication(sessionKey);
+ *   }
+ * } else if (response.status === 410) {
+ *   // Session expired
+ * } else if (response.status === 422) {
+ *   // Authentication failed (user cancelled, etc.)
+ * }
+ * ```
+ */
 export interface StatusResponse {
+    /**
+     * The session key/identifier
+     */
     session_key: string;
+    /**
+     * Current status of the authentication (only successful states)
+     */
     status: AuthenticationStatus;
+    /**
+     * Protocol/strategy used for authentication
+     * Optional - may not be present during pending state
+     */
     protocol?: AuthenticationProtocol;
+    /**
+     * ISO 8601 timestamp when session was created
+     */
     created_at: string;
+    /**
+     * ISO 8601 timestamp of last status update
+     */
     last_updated: string;
 }
+/**
+ * Error Response (HTTP 4xx)
+ *
+ * Returned when session is expired, failed, or not found
+ */
 export interface StatusErrorResponse {
     code: 'SESSION_EXPIRED' | 'USER_CANCELLED' | 'AUTHENTICATION_FAILED' | 'SESSION_NOT_FOUND' | 'INVALID_SESSION_KEY';
     message: string;
@@ -19,11 +76,32 @@ export interface StatusErrorResponse {
         duration_seconds?: number;
     };
 }
+/**
+ * Type guard to check if authentication was successful
+ */
 export declare function isSuccessStatus(status: AuthenticationStatus): boolean;
+/**
+ * Helper to determine if polling should continue based on HTTP status
+ */
 export declare function shouldContinuePolling(httpStatus: number, response?: StatusResponse): boolean;
+/**
+ * Helper to determine if session is terminated based on HTTP status
+ */
 export declare function isTerminalHttpStatus(httpStatus: number): boolean;
+/**
+ * Session binding types for parent-child relationships
+ */
 export interface SessionBinding {
+    /**
+     * Parent session ID (desktop QR code session)
+     */
     parent_session_id?: string;
+    /**
+     * Child session ID (mobile authentication session)
+     */
     child_session_id?: string;
+    /**
+     * Whether this is a parent or child session
+     */
     session_type?: 'parent' | 'child';
 }

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

@@ -1,14 +1,31 @@
 "use strict";
+/**
+ * Status Types for Public Status Endpoint
+ *
+ * These types define the response format for the public status endpoint
+ * Used for polling authentication status without exposing sensitive data
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSuccessStatus = isSuccessStatus;
 exports.shouldContinuePolling = shouldContinuePolling;
 exports.isTerminalHttpStatus = isTerminalHttpStatus;
+/**
+ * Type guard to check if authentication was successful
+ */
 function isSuccessStatus(status) {
     return status === 'completed';
 }
+/**
+ * Helper to determine if polling should continue based on HTTP status
+ */
 function shouldContinuePolling(httpStatus, response) {
+    // Only continue if HTTP 200 and status is pending
     return httpStatus === 200 && (response === null || response === void 0 ? void 0 : response.status) === 'pending';
 }
+/**
+ * Helper to determine if session is terminated based on HTTP status
+ */
 function isTerminalHttpStatus(httpStatus) {
+    // 410 Gone (expired), 422 Unprocessable (failed), 404 Not Found
     return httpStatus === 410 || httpStatus === 422 || httpStatus === 404;
 }

package/dist/core/phone-auth/strategies/desktop.d.ts

@@ -21,6 +21,8 @@ export interface DesktopAuthOptions {
     maxPollingAttempts?: number;
     /** Custom polling endpoint (overrides backend-provided or uses configured endpoint) */
     pollingEndpoint?: string;
+    /** Developer environment (adds 'developer' header to requests) */
+    devEnv?: string;
     /** Callback when QR code is ready to display */
     onQRCodeReady?: (qrCodeData: string | QRCodeData) => void;
     /** Callback for polling status updates */