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

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

@@ -1,18 +1,52 @@
+/**
+ * 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
+ */
+/** E.164 format phone number: "+1234567890" */
 export type PhoneNumber = string;
+/** ISO 8601 timestamp: "2024-01-15T09:30:00Z" */
 export type Timestamp = string;
+/** RFC 4122 UUID: "550e8400-e29b-41d4-a716-446655440000" */
 export type UUID = string;
+/**
+ * Session information used across all operations
+ * Maintains state between prepare and process steps
+ */
 export interface SessionInfo {
+    /** Unique session identifier */
     session_key: string;
+    /** Security nonce */
     nonce?: string;
+    /** Encryption key for secure operations */
     enc_key?: string;
+    /** Additional metadata from server */
     metadata?: Record<string, string>;
 }
+/**
+ * Public Land Mobile Network identifiers
+ * Identifies the carrier network
+ */
 export interface PLMN {
+    /** Mobile Country Code (exactly 3 digits) */
     mcc: string;
+    /** Mobile Network Code (2-3 digits) */
     mnc: string;
 }
+/**
+ * Browser/client information for strategy selection
+ */
 export interface ClientInfo {
+    /** navigator.userAgent */
     user_agent: string;
+    /** navigator.platform */
     platform: string;
 }
 export declare const USE_CASE: {
@@ -26,25 +60,60 @@ export declare const AUTHENTICATION_STRATEGY: {
     readonly DESKTOP: "desktop";
 };
 export type AuthenticationStrategy = typeof AUTHENTICATION_STRATEGY[keyof typeof AUTHENTICATION_STRATEGY];
+/**
+ * Advanced options for prepare requests
+ * Contains optional configuration for special features and future extensibility
+ */
 export interface PrepareOptions {
+    /**
+     * Parent session ID for desktop-mobile binding.
+     * When a mobile device scans a desktop QR code, the mobile session (child)
+     * links back to the desktop session (parent)
+     */
     parent_session_id?: string;
+    /**
+     * UI theme preference for consistency across all authentication touchpoints.
+     * Affects SDK modals, mobile app, and OAuth callback pages.
+     * @default 'dark'
+     */
     theme?: 'dark' | 'light';
+    /** Additional options can be added here for future extensibility */
     [key: string]: any;
 }
+/**
+ * Request to prepare authentication session
+ * Note: id is auto-generated by SDK if not provided
+ */
 export interface PrepareRequest {
+    /** Use case for this authentication (optional when parent_session_id is provided - inherited from parent) */
     use_case?: UseCase;
+    /** One of these is required (or parent_session_id in options) */
+    /** E.164 format phone number */
     phone_number?: PhoneNumber;
+    /** Alternative to phone_number */
     plmn?: PLMN;
-    nonce?: string;
+    /** Request identifier (SDK generates unique ID if not provided) */
     id?: string;
+    /** Optional fields */
+    /** Client information for strategy selection */
     client_info?: ClientInfo;
+    /** Advanced options for special features */
     options?: PrepareOptions;
 }
+/**
+ * Response from prepare authentication
+ */
 export interface PrepareResponse {
+    /** Selected authentication strategy */
     authentication_strategy: AuthenticationStrategy;
+    /** Session information for subsequent requests - named 'session' consistently */
     session: SessionInfo;
+    /** Strategy-specific data */
     data: TS43Data | LinkData | DesktopData;
 }
+/**
+ * TS43 strategy data
+ */
 export interface TS43Data {
     protocol: string;
     data: {
@@ -64,65 +133,142 @@ export interface TS43Data {
         };
     };
 }
+/**
+ * Link strategy data
+ */
 export interface LinkData {
+    /** URL to redirect user to */
     url: string;
+    /** URL to return to after authentication */
     return_url?: string;
+    /** Status URL for polling authentication status */
     status_url?: string;
+    /** Additional parameters */
     params?: Record<string, string>;
 }
+/**
+ * Desktop strategy data
+ * Used for QR code-based authentication from desktop browsers
+ */
 export interface DesktopData {
+    /** Protocol version for QR authentication */
     protocol?: string;
+    /** Inner data container with QR code details */
     data?: {
+        /** QR code image as base64 data URI (data:image/png;base64,...) */
         qr_code_image?: string;
+        /** Alternative field name for QR code (for compatibility) */
         qr_code?: string;
+        /** iOS-specific QR code image */
         ios_qr_image?: string;
+        /** Android-specific QR code image */
         android_qr_image?: string;
+        /** iOS authentication URL */
         ios_url?: string;
+        /** Android authentication URL */
         android_url?: string;
+        /** Unique session identifier for the QR code */
         session_id?: string;
+        /** Status polling URL */
         status_url?: string;
+        /** Mobile authentication URL */
         url?: string;
+        /** Polling interval in milliseconds (default: 2000) */
         polling_interval?: number;
+        /** QR code expiration time in seconds */
         expires_in?: number;
     };
+    /** Legacy flat structure support */
+    /** QR code image as base64 data URI (data:image/png;base64,...) */
     qr_code_image?: string;
+    /** Alternative field name for QR code (for compatibility) */
     qr_code?: string;
+    /** iOS-specific QR code image */
     ios_qr_image?: string;
+    /** Android-specific QR code image */
     android_qr_image?: string;
+    /** iOS authentication URL */
     ios_url?: string;
+    /** Android authentication URL */
     android_url?: string;
+    /** Unique session identifier for the QR code */
     session_id?: string;
+    /** Polling endpoint to check authentication status */
     polling_endpoint?: string;
+    /** Status polling URL */
     status_url?: string;
+    /** Polling interval in milliseconds (default: 2000) */
     polling_interval?: number;
+    /** QR code expiration time in seconds */
     expires_in?: number;
+    /** Optional deep link URL for mobile app */
     deep_link?: string;
+    /** Mobile authentication URL */
     url?: string;
 }
+/**
+ * Response from browser's Digital Credentials API
+ * This type is only used in frontend SDKs
+ */
 export interface SecureCredentialResponse {
     vp_token: {
         [aggregator_id: string]: string | string[];
     };
 }
+/**
+ * Base type for processing credential requests
+ * Both GetPhoneNumber and VerifyPhoneNumber use the same request structure
+ * but are kept as separate types for:
+ * - Future extensibility (each may add unique fields)
+ * - Clear API semantics (distinct operations)
+ * - Type safety (prevents accidental misuse)
+ */
+/**
+ * Request to get phone number
+ */
 export interface GetPhoneNumberRequest {
+    /** Session from PrepareResponse - consistent naming */
     session: SessionInfo;
+    /** Credential string extracted from SecureCredentialResponse.vp_token[id] */
     credential: string;
+    /** Use case must be 'GetPhoneNumber' - required for server routing */
     use_case: typeof USE_CASE.GET_PHONE_NUMBER;
 }
+/**
+ * Response with phone number
+ */
 export interface GetPhoneNumberResponse {
+    /** E.164 format phone number */
     phone_number: PhoneNumber;
+    /** Audience from TS43 (optional) */
     aud?: string;
 }
+/**
+ * Request to verify phone number
+ * Note: Similar to GetPhoneNumberRequest but with different use_case value
+ */
 export interface VerifyPhoneNumberRequest {
+    /** Session from PrepareResponse - consistent naming */
     session: SessionInfo;
+    /** Credential string extracted from SecureCredentialResponse.vp_token[id] */
     credential: string;
+    /** Use case must be 'VerifyPhoneNumber' - required for server routing */
     use_case: typeof USE_CASE.VERIFY_PHONE_NUMBER;
 }
+/**
+ * Response from phone number verification
+ */
 export interface VerifyPhoneNumberResponse {
+    /** The phone number that was verified */
     phone_number: PhoneNumber;
+    /** Whether verification was successful */
     verified: boolean;
+    /** Audience from TS43 (optional) */
     aud?: string;
 }
+/**
+ * Error codes - MUST match server implementation
+ */
 export declare const ERROR_CODE: {
     readonly INVALID_PHONE_NUMBER: "INVALID_PHONE_NUMBER";
     readonly MISSING_REQUIRED_FIELD: "MISSING_REQUIRED_FIELD";
@@ -140,106 +286,272 @@ export declare const ERROR_CODE: {
     readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
 };
 export type ErrorCode = typeof ERROR_CODE[keyof typeof ERROR_CODE];
+/**
+ * Error messages - User-friendly messages for each error code
+ */
 export declare const ERROR_MESSAGES: Record<ErrorCode, string>;
+/**
+ * HTTP status codes for each error
+ */
 export declare const ERROR_STATUS_CODES: Record<ErrorCode, number>;
+/**
+ * Additional error details
+ */
 export interface ErrorDetails {
+    /** Field that caused the error */
     field?: string;
+    /** Detailed reason for the error */
     reason?: string;
+    /** Carrier name for carrier-specific errors */
     carrier_name?: string;
+    /** Seconds until retry allowed (for rate limits) */
     retry_after?: number;
+    /** Additional context */
     [key: string]: any;
 }
+/**
+ * Standard error response format
+ */
 export interface ErrorResponse {
+    /** Machine-readable error code */
     code: ErrorCode;
+    /** User-friendly error message */
     message: string;
+    /** Request tracking ID */
     request_id?: UUID;
+    /** ISO 8601 timestamp */
     timestamp?: Timestamp;
+    /** Distributed tracing ID */
     trace_id?: string;
+    /** Span ID for tracing */
     span_id?: string;
+    /** Service that generated the error */
     service?: string;
+    /** Additional error context */
     details?: ErrorDetails;
 }
+/**
+ * E.164 phone number validation regex
+ */
 export declare const E164_REGEX: RegExp;
+/**
+ * Validate phone number format
+ */
 export declare function validatePhoneNumber(phone: string): boolean;
+/**
+ * Validate PLMN format
+ */
 export declare function validatePLMN(plmn: PLMN): boolean;
+/**
+ * Validate session info
+ */
 export declare function validateSession(session: SessionInfo): boolean;
+/**
+ * Validate use case
+ */
 export declare function validateUseCase(useCase: string): useCase is UseCase;
+/**
+ * Create error response helper
+ */
 export declare function createErrorResponse(code: ErrorCode, details?: ErrorDetails, requestId?: string): ErrorResponse;
+/**
+ * Get HTTP status code for error
+ */
 export declare function getErrorStatusCode(code: ErrorCode): number;
+/**
+ * Check if data is TS43 strategy data
+ */
 export declare function isTS43Data(data: any): data is TS43Data;
+/**
+ * Check if data is Link strategy data
+ */
 export declare function isLinkData(data: any): data is LinkData;
+/**
+ * Check if response is an error
+ */
 export declare function isErrorResponse(response: any): response is ErrorResponse;
+/**
+ * Execution mode for authentication flow
+ */
 export type ExecutionMode = 'standard' | 'extended';
+/**
+ * Options for invokeSecurePrompt to control UI behavior
+ */
 export interface InvokeOptions {
+    /**
+     * Prevents SDK from showing its own UI components.
+     * Only affects Desktop strategy (shows modal by default).
+     * Link/TS43 never show SDK UI, so this has no effect on them.
+     *
+     * @default false
+     */
     preventDefaultUI?: boolean;
+    /**
+     * Controls the response type:
+     * - 'standard': Returns credential when complete (Promise<AuthCredential>)
+     * - 'extended': Returns control methods + credential promise
+     *
+     * @default 'standard'
+     */
     executionMode?: ExecutionMode;
+    /**
+     * UI theme to use for modals and components
+     * @default 'dark'
+     */
     theme?: 'dark' | 'light';
+    /**
+     * Whether to automatically trigger the authentication
+     * - For Link: automatically opens App Clip URL on invocation
+     * - For TS43: attempts to trigger credential API (may fail due to browser restrictions)
+     * - For Desktop: N/A (QR code is shown)
+     * @default true
+     */
     autoTrigger?: boolean;
+    /**
+     * Called when trigger is attempted (for Link/TS43)
+     * @param data Information about the trigger attempt
+     */
     onTriggerAttempt?: (data: {
         strategy: string;
         url?: string;
         success?: boolean;
         error?: any;
     }) => void;
+    /**
+     * Options for customizing the modal UI (only used when preventDefaultUI=false)
+     * Simplified to only include commonly used options
+     */
     modalOptions?: {
+        /** CSS class to add to the modal container */
         className?: string;
+        /** Title text for the modal */
         title?: string;
+        /** Description text for the modal */
         description?: string;
+        /** Button text */
         buttonText?: string;
+        /** Whether to show close button @default true */
         showCloseButton?: boolean;
+        /** Allow closing modal by clicking backdrop/overlay @default true */
         closeOnBackdrop?: boolean;
+        /** Allow closing modal by pressing Escape key @default true */
         closeOnEscape?: boolean;
     };
+    /**
+     * Callback functions for UI events (only used when preventDefaultUI=false)
+     */
     callbacks?: {
+        /** Called when modal is opened */
         onOpen?: () => void;
+        /** Called when modal is closed */
         onClose?: () => void;
+        /** Called when authentication starts */
         onAuthStart?: () => void;
+        /** Called when authentication completes */
         onAuthComplete?: (result: any) => void;
+        /** Called on error */
         onError?: (error: Error) => void;
     };
+    /**
+     * Custom polling endpoint for Desktop/Link strategies
+     * Overrides the SDK configured endpoint and backend-provided status URL
+     * Useful for testing or using a proxy endpoint
+     * @example '/api/phone-auth/status' or 'https://custom-polling.example.com/status'
+     */
     pollingEndpoint?: string;
+    /**
+     * Custom polling interval in milliseconds
+     * @default 2000 (2 seconds)
+     */
     pollingInterval?: number;
+    /**
+     * Maximum number of polling attempts before timeout
+     * @default 30 (1 minute with 2s interval)
+     */
     maxPollingAttempts?: number;
 }
+/**
+ * Authentication credential result
+ */
 export interface AuthCredential {
+    /** Authentication credential token */
     credential: string;
+    /** Phone number if available */
     phone_number?: PhoneNumber;
+    /** Session information */
     session: SessionInfo;
+    /** Whether authentication was successful */
     authenticated: boolean;
 }
+/**
+ * Base interface for extended mode responses
+ */
 export interface ExtendedResponse {
+    /** Authentication strategy */
     strategy: AuthenticationStrategy;
+    /** Session information */
     session: SessionInfo;
+    /** Promise that resolves to the credential */
     credential: Promise<AuthCredential>;
+    /** Cancel the authentication flow */
     cancel: () => void;
 }
+/**
+ * Extended response for Desktop strategy.
+ * Note: Polling starts immediately even with preventDefaultUI: true (consistent with Link strategy)
+ */
 export interface DesktopExtendedResponse extends ExtendedResponse {
     strategy: 'desktop';
+    /** QR code data for custom UI */
     qr_code_data: {
+        /** iOS QR code image */
         ios_qr_image?: string;
+        /** Android QR code image */
         android_qr_image?: string;
+        /** Generic QR code image */
         qr_code?: string;
+        /** Challenge pattern */
         challenge?: any;
     };
+    /** Returns the existing polling promise (polling starts immediately) */
     start_polling: () => Promise<AuthCredential>;
+    /** Stop polling */
     stop_polling: () => void;
+    /** Whether currently polling */
     is_polling: boolean;
+    /** Modal reference if UI was shown */
     modal_ref?: any;
 }
+/**
+ * Extended response for Link strategy
+ */
 export interface LinkExtendedResponse extends ExtendedResponse {
     strategy: 'link';
+    /** Additional data for Link strategy */
     data: {
+        /** App URL that was opened */
         app_url: string;
     };
+    /** Re-open the app link */
     trigger: () => void;
+    /** Start or restart polling */
     start_polling?: () => Promise<AuthCredential>;
+    /** Stop polling */
     stop_polling?: () => void;
+    /** Whether currently polling */
     is_polling?: boolean;
 }
+/**
+ * Extended response for TS43 strategy
+ */
 export interface TS43ExtendedResponse extends ExtendedResponse {
     strategy: 'ts43';
+    /** Re-trigger credential request */
     trigger: () => Promise<void>;
 }
+/**
+ * Combined type for all extended responses
+ */
 export type AnyExtendedResponse = DesktopExtendedResponse | LinkExtendedResponse | TS43ExtendedResponse;
 declare const _default: {
     USE_CASE: {