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

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

@@ -1,52 +1,18 @@
-/**
- * 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: {
@@ -60,63 +26,25 @@ 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: nonce and id are auto-generated by SDKs 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;
-    /** Optional: Auto-generated by SDKs if not provided */
-    /** Unique nonce (SDK generates secure random if not provided) */
     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: {
@@ -136,142 +64,65 @@ 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";
@@ -289,272 +140,106 @@ 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: {