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

package/README.md

@@ -0,0 +1,938 @@
+# Glide Web Client SDK
+
+The official web SDK for integrating Glide's carrier-grade phone verification into your web applications. Supports React, Vue, Angular, and vanilla JavaScript/TypeScript.
+
+## Features
+
+- 🚀 **Instant Verification**: Direct carrier verification without SMS
+- 🔐 **Fraud Resistant**: Can't be intercepted or spoofed like SMS codes  
+- ⚡ **Real-time Progress**: Track verification steps with detailed state management
+- 📱 **Cross-Device Support**: Desktop QR code, mobile App Clips, and Android deep links
+- 🤖 **Smart Defaults**: Automatic headless/UI mode selection based on strategy
+- 🔄 **Unified Trigger Pattern**: Consistent API for Link and TS43 authentication
+- 🌐 **Framework Support**: React, Vue 3, Angular, and vanilla JS/TS
+- 🛡️ **Type Safe**: Full TypeScript support with type guards and IntelliSense
+- 🎯 **Developer Friendly**: Clear error messages and browser compatibility checks
+
+## What's New in v4.4
+
+### 🎉 Smart Defaults & Better DX
+- **Smart Mode Selection**: Link/TS43 default to headless, Desktop defaults to UI mode
+- **Type Guards**: Helper functions for type-safe result handling
+- **Unified Trigger Pattern**: Consistent `trigger()` function for all strategies
+- **Auto-Trigger Support**: Automatic App Clip opening with retry capability
+- **TypeScript Enhancements**: Full IntelliSense and type safety
+- **Cleaner API**: Removed non-functional options (iframe, redundant callbacks)
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Smart Defaults & Type Guards](#smart-defaults--type-guards)
+- [Cross-Device Support](#cross-device-support)
+- [Framework Examples](#framework-examples)
+- [Error Handling](#error-handling)
+- [Advanced Features](#advanced-features)
+- [Browser Support](#browser-support)
+- [API Reference](#api-reference)
+
+## Installation
+
+```bash
+npm install glide-web-client-sdk
+```
+
+## Quick Start
+
+### React
+
+```jsx
+import { usePhoneAuth } from 'glide-web-client-sdk/react'
+
+function PhoneVerification() {
+  const {
+    getPhoneNumber,
+    verifyPhoneNumber,
+    retryLastRequest,  // NEW: Manual retry capability
+    isLoading,
+    error,
+    result,
+    currentStep,
+    isSupported
+  } = usePhoneAuth({
+    endpoints: {
+      prepare: '/api/phone-auth/prepare',
+      process: '/api/phone-auth/process'
+    },
+    // Optional callbacks for monitoring
+    onCrossDeviceDetected: () => {
+      console.log('QR code detected - user completing on phone');
+    },
+    onRetryAttempt: (attempt, maxAttempts) => {
+      console.log(`Silent retry ${attempt}/${maxAttempts}`);
+    }
+  })
+
+  const handleVerify = async () => {
+    try {
+      // Verify a specific phone number
+      await verifyPhoneNumber('+1234567890')
+    } catch (error) {
+      // Error only thrown after all retries exhausted
+      console.error('Verification failed:', error)
+    }
+  }
+
+  return (
+    <div>
+      <button onClick={handleVerify} disabled={isLoading}>
+        Verify My Phone
+      </button>
+      
+      {/* Manual retry button (NEW) */}
+      {error && !isLoading && (
+        <button onClick={retryLastRequest}>
+          Retry
+        </button>
+      )}
+      
+      {result && <p>Phone verified: {result.phone_number}</p>}
+    </div>
+  )
+}
+```
+
+## 🎨 Dual-Mode API: UI Mode vs Headless Mode
+
+The SDK now supports two distinct modes for authentication, giving you complete control over the user experience:
+
+### **UI Mode (Default)** - Ready-to-Use Components
+The SDK provides built-in modals and buttons for authentication. Perfect for quick integration.
+
+### **Headless Mode** - Complete Control
+Returns raw data without any UI, allowing you to build completely custom experiences.
+
+### When to Use Each Mode
+
+| Use Case | Mode | Why |
+|----------|------|-----|
+| Quick integration | UI Mode | Get running in minutes with pre-built components |
+| Custom design requirements | Headless | Match your exact brand guidelines |
+| Mobile apps (React Native, etc) | Headless | Native UI components |
+| Testing/Automation | Headless | Direct control over flow |
+| Standard web apps | UI Mode | Optimized UX out of the box |
+
+### UI Mode Example (Default)
+
+```javascript
+// Shows SDK's built-in UI based on authentication strategy
+const prepareResult = await phoneAuth.preparePhoneRequest({
+  use_case: 'VerifyPhoneNumber',
+  phone_number: '+14155551234'
+});
+
+// Behavior varies by strategy:
+// - Desktop: Shows QR code modal
+// - Link: Shows button modal to open app
+// - TS43: Directly invokes Digital Credentials API (no modal - OS provides UI)
+const credential = await phoneAuth.invokeSecurePrompt(prepareResult);
+
+// Or customize the built-in UI
+const credential = await phoneAuth.invokeSecurePrompt(prepareResult, {
+  modalOptions: {
+    title: 'Verify Your Identity',
+    description: 'Complete verification to continue',
+    buttonText: 'Verify with Verizon',
+    className: 'my-custom-modal'
+  },
+  callbacks: {
+    onOpen: () => console.log('Modal opened'),
+    onAuthComplete: (result) => console.log('Success!', result)
+  }
+});
+```
+
+### Headless Mode Example
+
+```javascript
+// Get raw data without any UI
+const prepareResult = await phoneAuth.preparePhoneRequest({
+  use_case: 'VerifyPhoneNumber',
+  phone_number: '+14155551234'
+});
+
+// Returns data instead of showing UI
+const result = await phoneAuth.invokeSecurePrompt(prepareResult, {
+  headless: true
+});
+
+// Handle each strategy with your custom UI
+if (result.strategy === 'link') {
+  // iOS/Android - App Clip or native app
+  console.log('URL to open:', result.url);
+  
+  // Open in your custom way
+  window.open(result.url, '_blank');
+  
+  // Wait for completion
+  const credential = await result.pollingPromise;
+  
+} else if (result.strategy === 'desktop') {
+  // Desktop - QR code
+  console.log('QR code image:', result.qrCode);
+  
+  // Display QR in your custom UI
+  document.getElementById('qr').src = result.qrCode;
+  
+  // Wait for mobile scan completion
+  const credential = await result.pollingPromise;
+  
+} else if (result.strategy === 'ts43') {
+  // Android/Chrome - Digital Credentials
+  console.log('Ready to invoke Digital Credentials');
+  
+  // Trigger when user clicks your custom button
+  const credential = await result.trigger();
+  
+  // Note: TS43 never shows a modal in UI mode - the OS provides its own UI
+  // The Digital Credentials API shows a native drawer/bottom sheet
+}
+```
+
+### Smart Defaults & Type Guards (NEW in v4.4+)
+
+The SDK now uses **smart defaults** that match the most common use case for each authentication strategy:
+
+| Strategy | Default Mode | Returns | Why |
+|----------|-------------|---------|-----|
+| **Link** | Headless | `HeadlessResult` with `trigger()` | Developers want custom "Open App" buttons |
+| **TS43** | Headless | `HeadlessResult` with `trigger()` | Browser provides native credential UI |
+| **Desktop** | UI Mode | `Credential` directly | QR modal is complex to build from scratch |
+
+#### Using Type Guards
+
+Instead of manual type checking, use the SDK's built-in type guards for cleaner, type-safe code:
+
+```typescript
+import { 
+  invokeSecurePrompt, 
+  isHeadlessResult, 
+  isLinkStrategy,
+  isTS43Strategy,
+  isDesktopStrategy 
+} from 'glide-web-client-sdk';
+
+// No need to specify headless for Link/TS43 - it's the default!
+const result = await invokeSecurePrompt(prepareResult);
+
+// Use type guards for type-safe handling
+if (isHeadlessResult(result)) {
+  // TypeScript knows this is HeadlessResult
+  console.log('Strategy:', result.strategy);
+  
+  if (isLinkStrategy(result)) {
+    // Handle Link: custom button to open app
+    myButton.onclick = () => result.trigger();
+    await result.pollingPromise;
+  } 
+  else if (isTS43Strategy(result)) {
+    // Handle TS43: invoke immediately or on button
+    const credential = await result.trigger();
+  }
+  else if (isDesktopStrategy(result)) {
+    // Desktop in headless mode (explicitly requested)
+    showCustomQR(result.qrCodeUrl);
+    await result.pollingPromise;
+  }
+} else {
+  // Got credential directly (Desktop UI mode by default)
+  const processedResult = await verifyPhoneNumberCredential(result, session);
+}
+```
+
+#### Available Type Guards
+
+```typescript
+// Check if result is headless or UI mode
+isHeadlessResult(result)  // true if headless mode
+isCredential(result)      // true if UI mode (got credential)
+
+// Strategy-specific guards (for HeadlessResult)
+isLinkStrategy(result)    // true if Link strategy
+isTS43Strategy(result)    // true if TS43 strategy  
+isDesktopStrategy(result) // true if Desktop strategy
+
+// Helper functions
+getStrategy(result)       // Returns: 'link' | 'ts43' | 'desktop' | undefined
+requiresPolling(result)   // Returns: true for Link/Desktop, false for TS43
+requiresUserAction(result)// Returns: true if user interaction needed
+```
+
+#### Override Defaults When Needed
+
+You can still override the defaults when you have specific requirements:
+
+```javascript
+// Force UI mode for Link/TS43 (rarely needed)
+const credential = await invokeSecurePrompt(prepareResult, {
+  headless: false  // Show SDK modal instead of using custom UI
+});
+
+// Force headless mode for Desktop (for custom QR display)
+const result = await invokeSecurePrompt(prepareResult, {
+  headless: true   // Get QR data instead of showing modal
+});
+```
+
+### React Example with Custom UI
+
+```jsx
+function CustomPhoneAuth() {
+  const [qrCode, setQrCode] = useState(null);
+  const [appUrl, setAppUrl] = useState(null);
+  
+  const handleVerify = async () => {
+    const prepareResult = await phoneAuth.preparePhoneRequest({
+      use_case: 'VerifyPhoneNumber',
+      phone_number: phoneNumber
+    });
+    
+    // No need for headless: true for Link/TS43 - it's the default!
+    const result = await phoneAuth.invokeSecurePrompt(prepareResult);
+    
+    // Use type guards for clean code
+    if (isHeadlessResult(result)) {
+      if (isDesktopStrategy(result)) {
+        // Desktop in headless (explicitly requested)
+        setQrCode(result.qrCode);
+      } else if (isLinkStrategy(result)) {
+        // Link defaults to headless
+        setAppUrl(result.url);
+    }
+    
+    // Handle completion
+    const credential = await result.pollingPromise;
+    console.log('Verified!');
+  };
+  
+  return (
+    <div className="my-custom-design">
+      {qrCode && (
+        <div className="qr-container">
+          <img src={qrCode} alt="Scan to verify" />
+          <p>Scan with your phone</p>
+        </div>
+      )}
+      
+      {appUrl && (
+        <button onClick={() => window.open(appUrl)}>
+          Open Verification App
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+### Vue Example with Both Modes
+
+```vue
+<template>
+  <div>
+    <!-- Use SDK UI for quick setup -->
+    <button @click="verifyWithUI">
+      Verify (SDK UI)
+    </button>
+    
+    <!-- Or build custom UI -->
+    <button @click="verifyHeadless">
+      Verify (Custom UI)
+    </button>
+    
+    <!-- Custom QR display -->
+    <div v-if="qrCode" class="custom-qr">
+      <img :src="qrCode" />
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { usePhoneAuth } from 'glide-web-client-sdk/vue'
+
+const phoneAuth = usePhoneAuth({
+  endpoints: {
+    prepare: '/api/phone-auth/prepare',
+    process: '/api/phone-auth/process'
+  }
+});
+
+const qrCode = ref(null);
+
+// Using built-in UI
+async function verifyWithUI() {
+  const prepared = await phoneAuth.preparePhoneRequest({
+    use_case: 'VerifyPhoneNumber',
+    phone_number: '+14155551234'
+  });
+  
+  // Shows SDK modal
+  const credential = await phoneAuth.invokeSecurePrompt(prepared);
+}
+
+// Using headless mode
+async function verifyHeadless() {
+  const prepared = await phoneAuth.preparePhoneRequest({
+    use_case: 'VerifyPhoneNumber',
+    phone_number: '+14155551234'
+  });
+  
+  // Get raw data
+  const result = await phoneAuth.invokeSecurePrompt(prepared, {
+    headless: true
+  });
+  
+  if (result.strategy === 'desktop') {
+    qrCode.value = result.qrCode;
+    await result.pollingPromise;
+  }
+}
+</script>
+```
+
+### TypeScript Types
+
+```typescript
+interface InvokeOptions {
+  // Enable headless mode (no UI)
+  headless?: boolean;
+  
+  // Customize built-in UI (only for UI mode)
+  modalOptions?: {
+    className?: string;
+    title?: string;
+    description?: string;
+    buttonText?: string;
+    showCloseButton?: boolean;
+    zIndex?: number;
+  };
+  
+  // UI event callbacks (only for UI mode)
+  callbacks?: {
+    onOpen?: () => void;
+    onClose?: () => void;
+    onAuthStart?: () => void;
+    onAuthComplete?: (result: any) => void;
+    onError?: (error: Error) => void;
+  };
+}
+
+interface HeadlessResult {
+  strategy: 'ts43' | 'link' | 'desktop';
+  url?: string;           // For Link strategy
+  qrCode?: string;         // For Desktop strategy
+  pollingPromise?: Promise<any>;  // Resolves when complete
+  trigger?: () => Promise<any>;   // For TS43 strategy
+  session: SessionInfo;
+}
+```
+
+## Smart Defaults & Type Guards
+
+### Smart Mode Selection
+
+The SDK automatically chooses the optimal mode based on the authentication strategy:
+
+```javascript
+// Link Strategy (App Clips) - Defaults to HEADLESS
+const result = await phoneAuth.invokeSecurePrompt(prepareResponse);
+// No need to specify headless: true - it's automatic!
+
+// TS43 Strategy (Android) - Defaults to HEADLESS  
+const result = await phoneAuth.invokeSecurePrompt(prepareResponse);
+// Automatically headless for custom UI control
+
+// Desktop Strategy (QR Code) - Defaults to UI MODE
+const result = await phoneAuth.invokeSecurePrompt(prepareResponse);
+// Shows built-in QR modal automatically
+
+// Override defaults if needed
+const result = await phoneAuth.invokeSecurePrompt(prepareResponse, {
+  headless: false // Force UI mode for any strategy
+});
+```
+
+### Type Guards for Safe Result Handling
+
+Use built-in type guards for type-safe result handling:
+
+```typescript
+import { 
+  isHeadlessResult,
+  isCredential,
+  isLinkStrategy,
+  isTS43Strategy,
+  isDesktopStrategy,
+  requiresPolling,
+  requiresUserAction
+} from 'glide-web-client-sdk';
+
+const result = await phoneAuth.invokeSecurePrompt(prepareResponse);
+
+// Check result type
+if (isHeadlessResult(result)) {
+  // TypeScript knows this is HeadlessResult
+  console.log('Strategy:', result.strategy);
+  
+  // Check specific strategies
+  if (isLinkStrategy(result)) {
+    // Handle Link (App Clip) flow
+    await result.trigger(); // Opens App Clip
+    const credential = await result.pollingPromise;
+  } else if (isTS43Strategy(result)) {
+    // Handle TS43 (Android) flow
+    const credential = await result.trigger(); // Invokes credential API
+  }
+  
+  // Check capabilities
+  if (requiresPolling(result)) {
+    // Link or Desktop - needs polling
+    const credential = await result.pollingPromise;
+  }
+  
+  if (requiresUserAction(result)) {
+    // Link or TS43 - needs user interaction
+    button.onclick = () => result.trigger();
+  }
+} else if (isCredential(result)) {
+  // Direct credential (UI mode handled everything)
+  const verified = await phoneAuth.processCredential(result);
+}
+```
+
+### Unified Trigger Pattern
+
+All headless strategies use the same `trigger()` pattern:
+
+```javascript
+// Link Strategy - trigger opens App Clip
+const linkResult = await phoneAuth.invokeSecurePrompt(prepareResponse, {
+  autoTrigger: false // Don't auto-open, let user click
+});
+button.onclick = () => linkResult.trigger(); // User controls when to open
+
+// TS43 Strategy - trigger invokes credential API  
+const ts43Result = await phoneAuth.invokeSecurePrompt(prepareResponse, {
+  autoTrigger: false // Preserve user gesture
+});
+button.onclick = async () => {
+  const credential = await ts43Result.trigger(); // Must be in click handler
+};
+
+// Auto-trigger (default for Link)
+const autoResult = await phoneAuth.invokeSecurePrompt(prepareResponse);
+// App Clip opens immediately, retry available
+retryButton.onclick = () => autoResult.trigger(); // Retry if needed
+```
+
+## Cross-Device Support
+
+The SDK automatically handles cross-device authentication flows (QR code scenarios) without any configuration needed.
+
+### How It Works
+
+1. **Detection**: After 3 seconds with credential prompt open, the SDK detects likely QR code flow
+2. **Timeout Extension**: Automatically extends timeout from 30 seconds to 2 minutes
+3. **User Experience**: Users have ample time to scan QR and complete on their phone
+
+### Monitoring Cross-Device Flows
+
+```javascript
+const { getPhoneNumber } = usePhoneAuth({
+  endpoints: { /* ... */ },
+  
+  // Optional: Track when QR codes are shown
+  onCrossDeviceDetected: () => {
+    // Analytics: Track QR code usage
+    analytics.track('phone_auth_qr_code_shown');
+  }
+});
+```
+
+## Silent Retry Pattern
+
+The SDK automatically retries transient failures without showing errors to users.
+
+### Default Behavior
+
+- **2 automatic retries** on network/timeout errors
+- **Exponential backoff** between attempts (1s, 2s)
+- **Error only shown** after all retries are exhausted
+- **Session caching** to recover from interruptions
+
+### Example Flow
+
+```
+User clicks verify → 
+  Try 1 fails (network glitch) → 
+    [Silent retry - no error shown] →
+      Try 2 succeeds → 
+        ✓ Success shown to user
+
+User never sees the transient failure!
+```
+
+### Monitoring Retries
+
+```javascript
+const { verifyPhoneNumber } = usePhoneAuth({
+  endpoints: { /* ... */ },
+  
+  // Optional: Track retry patterns
+  onRetryAttempt: (attempt, maxAttempts) => {
+    // Log to monitoring service
+    logger.info('Phone auth retry', { 
+      attempt, 
+      maxAttempts 
+    });
+  }
+});
+```
+
+## Advanced Features
+
+### Manual Retry
+
+Users can manually retry failed verifications:
+
+```javascript
+const { retryLastRequest, error } = usePhoneAuth(config);
+
+// Show retry button after error
+if (error) {
+  <button onClick={retryLastRequest}>Try Again</button>
+}
+```
+
+### Callbacks
+
+Both callbacks are optional and have no performance impact when not used:
+
+| Callback | Purpose | Use Case |
+|----------|---------|----------|
+| `onCrossDeviceDetected` | Fires when QR code flow detected | Analytics, custom UI |
+| `onRetryAttempt` | Fires on each retry attempt | Monitoring, debugging |
+
+### TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import { 
+  usePhoneAuth, 
+  PhoneAuthResult,
+  AuthError,
+  UsePhoneAuthOptions 
+} from 'glide-web-client-sdk/react';
+
+const config: UsePhoneAuthOptions = {
+  endpoints: {
+    prepare: '/api/prepare',
+    process: '/api/process'
+  },
+  onCrossDeviceDetected: () => void,
+  onRetryAttempt: (attempt: number, max: number) => void
+};
+```
+
+## Error Handling
+
+### Enhanced Error Context
+
+Errors now include additional context for debugging:
+
+```javascript
+catch (error) {
+  console.log(error.code);        // 'REQUEST_TIMEOUT'
+  console.log(error.message);     // User-friendly message
+  console.log(error.context);     // { attemptNumber: 3, maxAttempts: 3 }
+  console.log(error.browserError); // Browser-specific error details
+}
+```
+
+### Cross-Device Error Types
+
+The SDK provides specific error information for cross-device issues:
+
+```javascript
+if (error.details?.errorType === 'CROSS_DEVICE_TIMEOUT') {
+  // QR code expired
+}
+if (error.details?.errorType === 'CROSS_DEVICE_CONNECTION_LOST') {
+  // Connection lost during phone verification
+}
+```
+
+## Browser Support
+
+### Requirements
+
+- Chrome 118+ or Edge 118+ 
+- Digital Credentials API flag enabled
+
+### Checking Support
+
+```javascript
+const { isSupported, browserSupportInfo } = usePhoneAuth();
+
+if (!isSupported) {
+  console.log(browserSupportInfo.message);
+  // "Please enable chrome://flags/#web-identity-digital-credentials"
+}
+```
+
+## Vue 3 Example
+
+```vue
+<template>
+  <div>
+    <button @click="verify" :disabled="isLoading">
+      Verify Phone
+    </button>
+    
+    <!-- Retry button -->
+    <button v-if="error" @click="retryLastRequest">
+      Retry
+    </button>
+    
+    <div v-if="result">
+      Phone: {{ result.phone_number }}
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { usePhoneAuth } from 'glide-web-client-sdk/vue'
+
+const {
+  verifyPhoneNumber,
+  retryLastRequest,
+  isLoading,
+  error,
+  result
+} = usePhoneAuth({
+  endpoints: {
+    prepare: '/api/phone-auth/prepare',
+    process: '/api/phone-auth/process'
+  },
+  onCrossDeviceDetected: () => {
+    console.log('QR code shown');
+  }
+})
+
+const verify = async () => {
+  await verifyPhoneNumber('+1234567890')
+}
+</script>
+```
+
+## Angular Example
+
+```typescript
+import { Component } from '@angular/core';
+import { PhoneAuthService } from 'glide-web-client-sdk/angular';
+
+@Component({
+  selector: 'app-phone-verify',
+  template: `
+    <button (click)="verify()" [disabled]="isLoading$ | async">
+      Verify
+    </button>
+    
+    <button *ngIf="error$ | async" (click)="retry()">
+      Retry
+    </button>
+    
+    <div *ngIf="result$ | async as result">
+      Phone: {{ result.phone_number }}
+    </div>
+  `
+})
+export class PhoneVerifyComponent {
+  isLoading$ = this.phoneAuth.isLoading$;
+  error$ = this.phoneAuth.error$;
+  result$ = this.phoneAuth.result$;
+  
+  constructor(private phoneAuth: PhoneAuthService) {
+    this.phoneAuth.configure({
+      endpoints: {
+        prepare: '/api/phone-auth/prepare',
+        process: '/api/phone-auth/process'
+      },
+      onCrossDeviceDetected: () => {
+        console.log('QR code detected');
+      }
+    });
+  }
+  
+  async verify() {
+    await this.phoneAuth.verifyPhoneNumber('+1234567890');
+  }
+  
+  async retry() {
+    await this.phoneAuth.retryLastRequest();
+  }
+}
+```
+
+## Vanilla JavaScript
+
+```javascript
+import { PhoneAuthClient } from 'glide-web-client-sdk';
+
+const client = new PhoneAuthClient({
+  endpoints: {
+    prepare: '/api/phone-auth/prepare',
+    process: '/api/phone-auth/process'
+  },
+  onCrossDeviceDetected: () => {
+    console.log('QR code detected');
+  },
+  onRetryAttempt: (attempt, max) => {
+    console.log(`Retry ${attempt}/${max}`);
+  }
+});
+
+// Verify phone number with automatic retry
+try {
+  const result = await client.verifyPhoneNumber('+1234567890');
+  console.log('Verified:', result.verified);
+} catch (error) {
+  // Only thrown after all retries exhausted
+  console.error('Failed after retries:', error);
+}
+```
+
+## Migration from v3
+
+No breaking changes! The SDK is fully backward compatible. New features are additive:
+
+```javascript
+// v3 code continues to work
+const { getPhoneNumber } = usePhoneAuth(config);
+
+// v4 adds new optional features
+const { getPhoneNumber, retryLastRequest } = usePhoneAuth({
+  ...config,
+  onCrossDeviceDetected: () => {}, // Optional
+  onRetryAttempt: () => {}          // Optional
+});
+```
+
+## Debug Tools
+
+For development and testing, debug components are available in the `/examples/debug-components/` folder:
+
+- `PhoneAuthDebugger.jsx` - Comprehensive debugging interface
+- `AppEnhanced.jsx` - Production app with debug mode
+
+These are not included in the main bundle. Copy them to your project if needed.
+
+## API Reference
+
+### Configuration Options
+
+```typescript
+interface AuthConfig {
+  // Required endpoints
+  endpoints: {
+    prepare: string;    // Your backend prepare endpoint
+    process: string;    // Your backend process endpoint
+    polling?: string;   // Optional custom polling endpoint
+  };
+  
+  // Optional settings
+  pollingInterval?: number;        // Polling interval in ms (default: 2000)
+  maxPollingAttempts?: number;     // Max polling attempts (default: 150)
+  timeout?: number;                // API timeout in ms (default: 30000)
+  debug?: boolean;                 // Enable debug logging (default: false)
+  
+  // Optional callbacks
+  onCrossDeviceDetected?: () => void;     // QR code shown
+  onRetryAttempt?: (attempt: number, maxAttempts: number) => void;
+  onTimeout?: () => void;
+  onCancel?: () => void;
+}
+```
+
+### Modal Customization (UI Mode)
+
+```typescript
+interface ModalOptions {
+  className?: string;        // Custom CSS class
+  title?: string;           // Modal title
+  description?: string;     // Modal description
+  buttonText?: string;      // Button label
+  showCloseButton?: boolean; // Show close button (default: true)
+}
+
+// Usage
+const result = await phoneAuth.invokeSecurePrompt(prepareResponse, {
+  headless: false,
+  modalOptions: {
+    title: 'Verify Your Identity',
+    buttonText: 'Continue'
+  }
+});
+```
+
+### Methods
+
+```typescript
+// High-level methods (handle everything)
+getPhoneNumber(): Promise<GetPhoneNumberResponse>
+verifyPhoneNumber(phoneNumber?: string): Promise<VerifyPhoneNumberResponse>
+
+// Low-level methods (granular control)
+preparePhoneRequest(options: PrepareRequest): Promise<PrepareResponse>
+invokeSecurePrompt(response: PrepareResponse, options?: InvokeOptions): Promise<HeadlessResult | Credential>
+getPhoneNumberCredential(credential: any, session: SessionInfo): Promise<GetPhoneNumberResponse>
+verifyPhoneNumberCredential(credential: any, session: SessionInfo): Promise<VerifyPhoneNumberResponse>
+
+// Utility methods
+retryLastRequest(): Promise<any>
+cancelCurrentRequest(): void
+```
+
+### Response Types
+
+```typescript
+interface GetPhoneNumberResponse {
+  phone_number: string;
+  aud?: string;
+}
+
+interface VerifyPhoneNumberResponse {
+  phone_number: string;
+  verified: boolean;
+  aud?: string;
+}
+
+interface HeadlessResult {
+  strategy: 'link' | 'ts43' | 'desktop';
+  trigger?: () => void | Promise<any>;
+  pollingPromise?: Promise<any>;
+  session: SessionInfo;
+  url?: string;        // For Link strategy
+  qrCode?: string;     // For Desktop strategy
+}
+```
+
+## Support
+
+- [Documentation](https://docs.glideidentity.com)
+- [API Reference](https://api.glideidentity.com/docs)
+- [Support](https://support.glideidentity.com)
+
+## License
+
+MIT