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

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

@@ -0,0 +1,150 @@
+/**
+ * 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 a HeadlessResult (headless mode)
+ * or a Credential (UI mode).
+ *
+ * @example
+ * ```typescript
+ * const result = await invokeSecurePrompt(sdkRequest);
+ *
+ * if (isHeadlessResult(result)) {
+ *   // TypeScript knows this is HeadlessResult
+ *   console.log(result.strategy);
+ *   await result.trigger();
+ * } else {
+ *   // TypeScript knows this is a Credential
+ *   const processedResult = await verifyPhoneNumberCredential(result, session);
+ * }
+ * ```
+ */
+export function isHeadlessResult(result) {
+    return result &&
+        typeof result === 'object' &&
+        'strategy' in result &&
+        'trigger' in result &&
+        typeof result.trigger === 'function';
+}
+/**
+ * Type guard to check if the result is a Credential (UI mode response).
+ * A credential is either a string token or an object without HeadlessResult 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 HeadlessResult properties
+    if (typeof result === 'object') {
+        return !('strategy' in result) && !('trigger' in result);
+    }
+    return false;
+}
+/**
+ * Type guard to check if a HeadlessResult is using the Link strategy.
+ * Link strategy involves opening an app link (App Clip on iOS, app on Android).
+ *
+ * @example
+ * ```typescript
+ * if (isHeadlessResult(result) && isLinkStrategy(result)) {
+ *   // Show custom button for opening app
+ *   myButton.onclick = () => result.trigger();
+ *   await result.pollingPromise;
+ * }
+ * ```
+ */
+export function isLinkStrategy(result) {
+    return result.strategy === 'link';
+}
+/**
+ * Type guard to check if a HeadlessResult is using the TS43 strategy.
+ * TS43 strategy uses the browser's Digital Credentials API.
+ *
+ * @example
+ * ```typescript
+ * if (isHeadlessResult(result) && isTS43Strategy(result)) {
+ *   // Invoke credential API immediately or on button click
+ *   const credential = await result.trigger();
+ * }
+ * ```
+ */
+export function isTS43Strategy(result) {
+    return result.strategy === 'ts43';
+}
+/**
+ * Type guard to check if a HeadlessResult is using the Desktop strategy.
+ * Desktop strategy involves QR codes for cross-device authentication.
+ *
+ * @example
+ * ```typescript
+ * if (isHeadlessResult(result) && isDesktopStrategy(result)) {
+ *   // Show custom QR code UI
+ *   displayQRCode(result.qrCodeUrl);
+ *   await result.pollingPromise;
+ * }
+ * ```
+ */
+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 a HeadlessResult.
+ *
+ * @example
+ * ```typescript
+ * const strategy = getStrategy(result);
+ * if (strategy === 'link') {
+ *   // Handle link strategy
+ * }
+ * ```
+ */
+export function getStrategy(result) {
+    if (isHeadlessResult(result)) {
+        return result.strategy;
+    }
+    return undefined;
+}
+/**
+ * Helper function to determine if a result requires polling.
+ * Link and Desktop strategies require polling, TS43 does not.
+ *
+ * @example
+ * ```typescript
+ * if (requiresPolling(result)) {
+ *   await result.pollingPromise;
+ * }
+ * ```
+ */
+export function requiresPolling(result) {
+    if (!isHeadlessResult(result))
+        return false;
+    return result.strategy === 'link' || result.strategy === 'desktop';
+}
+/**
+ * Helper function to determine if a result requires user interaction.
+ * All headless strategies require some form of user interaction.
+ *
+ * @example
+ * ```typescript
+ * if (requiresUserAction(result)) {
+ *   showActionButton();
+ * }
+ * ```
+ */
+export function requiresUserAction(result) {
+    return isHeadlessResult(result);
+}

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

@@ -0,0 +1,232 @@
+/**
+ * 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 150 (5 minutes with 2s interval)
+     */
+    maxPollingAttempts?: number;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * 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;
+    details?: any;
+    status?: number;
+    requestId?: string;
+    timestamp?: string;
+    traceId?: string;
+    spanId?: string;
+    service?: string;
+    retryAfter?: number;
+    browserError?: {
+        name: string;
+        message: string;
+        stack?: string;
+        code?: number;
+    };
+    context?: {
+        step?: 'prepare' | 'prompt' | 'process' | 'complete';
+        useCase?: string;
+        timestamp: string;
+        userAgent?: string;
+        url?: string;
+        [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";
+    readonly NOT_SUPPORTED: "NotSupportedError";
+    readonly SECURITY: "SecurityError";
+    readonly ABORT: "AbortError";
+    readonly TIMEOUT: "TimeoutError";
+    readonly INVALID_STATE: "InvalidStateError";
+    readonly DATA_CLONE: "DataCloneError";
+    readonly ENCODING: "EncodingError";
+    readonly NOT_READABLE: "NotReadableError";
+    readonly UNKNOWN: "UnknownError";
+    readonly TYPE: "TypeError";
+    readonly RANGE: "RangeError";
+    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;
+    readonly POSITION_UNAVAILABLE: 2;
+    readonly TIMEOUT: 3;
+    readonly NOT_FOUND: 8;
+    readonly ABORT: 20;
+    readonly NETWORK: 19;
+    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";
+    readonly SAFARI: "Safari";
+    readonly FIREFOX: "Firefox";
+    readonly OPERA: "Opera";
+    readonly BRAVE: "Brave";
+    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: {
+            [aggregatorId: string]: string | string[];
+        };
+    };
+}
+/**
+ * Browser credential request structure
+ */
+export interface SecureCredentialRequest {
+    digital: {
+        requests: Array<{
+            protocol: string;
+            data: any;
+        }>;
+    };
+}
+/**
+ * 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

@@ -0,0 +1,76 @@
+/**
+ * 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',
+    NOT_SUPPORTED: 'NotSupportedError',
+    SECURITY: 'SecurityError',
+    ABORT: 'AbortError',
+    TIMEOUT: 'TimeoutError',
+    INVALID_STATE: 'InvalidStateError',
+    DATA_CLONE: 'DataCloneError',
+    ENCODING: 'EncodingError',
+    NOT_READABLE: 'NotReadableError',
+    UNKNOWN: 'UnknownError',
+    TYPE: 'TypeError',
+    RANGE: 'RangeError',
+    SYNTAX: 'SyntaxError'
+};
+/**
+ * Browser error codes
+ */
+export const BrowserErrorCode = {
+    USER_CANCELLED_DC_API: 19,
+    PERMISSION_DENIED: 1,
+    POSITION_UNAVAILABLE: 2,
+    TIMEOUT: 3,
+    NOT_FOUND: 8,
+    ABORT: 20,
+    NETWORK: 19,
+    SECURITY: 18
+};
+/**
+ * Browser names for detection
+ */
+export const BrowserName = {
+    CHROME: 'Chrome',
+    EDGE: 'Edge',
+    SAFARI: 'Safari',
+    FIREFOX: 'Firefox',
+    OPERA: 'Opera',
+    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

@@ -0,0 +1,25 @@
+/**
+ * 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;
+    private container;
+    private logsContainer;
+    private floatingToggle;
+    private isAtBottom;
+    private isVisible;
+    private originalConsole;
+    constructor();
+    static init(): MobileDebugConsole;
+    static destroy(): void;
+    private interceptConsole;
+    private addLog;
+    private updateDisplay;
+    private createUI;
+    private escapeHtml;
+    private toggle;
+    private clear;
+    private cleanup;
+}