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

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

@@ -0,0 +1,525 @@
+/**
+ * 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;
+}
+/**
+ * User consent information for privacy compliance
+ */
+export interface ConsentData {
+    /** What the user is consenting to */
+    consent_text: string;
+    /** URL to privacy policy */
+    policy_link: string;
+    /** Brief policy description */
+    policy_text: 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: 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 */
+    /** User consent information */
+    consent_data?: ConsentData;
+    /** 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;
+/**
+ * Options for invokeSecurePrompt to control UI behavior
+ */
+export interface InvokeOptions {
+    /**
+     * If true, returns raw data without showing any UI
+     * If false/undefined, shows appropriate UI (modal/button)
+     * @default false
+     */
+    headless?: boolean;
+    /**
+     * 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 headless=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 headless=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;
+    };
+}
+/**
+ * Result returned in headless mode
+ */
+export interface HeadlessResult {
+    /** The authentication strategy being used */
+    strategy: AuthenticationStrategy;
+    /** For Link strategy: the URL to open */
+    url?: string;
+    /** For Desktop strategy: the QR code data */
+    qrCode?: string;
+    /** For TS43: the credential request data */
+    credentialRequest?: any;
+    /**
+     * Promise that resolves when authentication completes
+     * - For Link/Desktop: polls for completion
+     * - For TS43: not used (trigger returns credential directly)
+     */
+    pollingPromise?: Promise<any>;
+    /**
+     * Function to trigger authentication action
+     * - For Link: opens App Clip URL (can be called multiple times)
+     * - For TS43: invokes Digital Credentials API (returns credential)
+     * - For Desktop: not used (QR code is shown)
+     */
+    trigger?: (() => void) | (() => Promise<any>);
+    /** Session information */
+    session: SessionInfo;
+}
+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;