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

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

@@ -1,593 +0,0 @@
-/**
- * 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;
-    /** 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: {
-    readonly GET_PHONE_NUMBER: "GetPhoneNumber";
-    readonly VERIFY_PHONE_NUMBER: "VerifyPhoneNumber";
-};
-export type UseCase = typeof USE_CASE[keyof typeof USE_CASE];
-export declare const AUTHENTICATION_STRATEGY: {
-    readonly TS43: "ts43";
-    readonly LINK: "link";
-    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;
-    /** 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: {
-        nonce: string;
-        response_mode: string;
-        response_type: string;
-        dcql_query: {
-            credentials: Array<{
-                id: string;
-                format: string;
-                meta: {
-                    vct_values: string[];
-                    credential_authorization_jwt: string;
-                };
-                claims?: string[];
-            }>;
-        };
-    };
-}
-/**
- * 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";
-    readonly INVALID_USE_CASE: "INVALID_USE_CASE";
-    readonly INVALID_SESSION: "INVALID_SESSION";
-    readonly SESSION_EXPIRED: "SESSION_EXPIRED";
-    readonly CARRIER_NOT_ELIGIBLE: "CARRIER_NOT_ELIGIBLE";
-    readonly UNSUPPORTED_PLATFORM: "UNSUPPORTED_PLATFORM";
-    readonly PHONE_NUMBER_MISMATCH: "PHONE_NUMBER_MISMATCH";
-    readonly INVALID_CREDENTIAL: "INVALID_CREDENTIAL";
-    readonly VERIFICATION_FAILED: "VERIFICATION_FAILED";
-    readonly USE_CASE_MISMATCH: "USE_CASE_MISMATCH";
-    readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
-    readonly INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR";
-    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: {
-        readonly GET_PHONE_NUMBER: "GetPhoneNumber";
-        readonly VERIFY_PHONE_NUMBER: "VerifyPhoneNumber";
-    };
-    AUTHENTICATION_STRATEGY: {
-        readonly TS43: "ts43";
-        readonly LINK: "link";
-        readonly DESKTOP: "desktop";
-    };
-    ERROR_CODE: {
-        readonly INVALID_PHONE_NUMBER: "INVALID_PHONE_NUMBER";
-        readonly MISSING_REQUIRED_FIELD: "MISSING_REQUIRED_FIELD";
-        readonly INVALID_USE_CASE: "INVALID_USE_CASE";
-        readonly INVALID_SESSION: "INVALID_SESSION";
-        readonly SESSION_EXPIRED: "SESSION_EXPIRED";
-        readonly CARRIER_NOT_ELIGIBLE: "CARRIER_NOT_ELIGIBLE";
-        readonly UNSUPPORTED_PLATFORM: "UNSUPPORTED_PLATFORM";
-        readonly PHONE_NUMBER_MISMATCH: "PHONE_NUMBER_MISMATCH";
-        readonly INVALID_CREDENTIAL: "INVALID_CREDENTIAL";
-        readonly VERIFICATION_FAILED: "VERIFICATION_FAILED";
-        readonly USE_CASE_MISMATCH: "USE_CASE_MISMATCH";
-        readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
-        readonly INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR";
-        readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
-    };
-    ERROR_MESSAGES: Record<ErrorCode, string>;
-    ERROR_STATUS_CODES: Record<ErrorCode, number>;
-    E164_REGEX: RegExp;
-    validatePhoneNumber: typeof validatePhoneNumber;
-    validatePLMN: typeof validatePLMN;
-    validateSession: typeof validateSession;
-    validateUseCase: typeof validateUseCase;
-    isTS43Data: typeof isTS43Data;
-    isLinkData: typeof isLinkData;
-    isErrorResponse: typeof isErrorResponse;
-    createErrorResponse: typeof createErrorResponse;
-    getErrorStatusCode: typeof getErrorStatusCode;
-};
-export default _default;