@glideidentity/web-client-sdk 4.4.8-beta.2 → 4.4.8

package/README.md

@@ -7,703 +7,321 @@ The official web SDK for integrating Glide's carrier-grade phone verification in
 - 🚀 **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
+- 📱 **Multi-Strategy Support**: Desktop QR code, mobile App Clips, and Android deep links
+- 🎯 **Extended Mode**: Granular control over authentication flow
+- 🔄 **Unified API**: Consistent interface for all authentication strategies
 - 🌐 **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
+### 🎉 Enhanced Control & Better DX
+- **Extended Mode**: More control with `executionMode: 'extended'` for granular authentication flow
+- **Prevent Default UI**: Use `preventDefaultUI: true` to disable all SDK modals
 - **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)
+- **Faster Timeout**: Polling timeout reduced to 1 minute for better UX
+- **Dual-Platform QR**: Support for iOS and Android specific QR codes
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [Smart Defaults & Type Guards](#smart-defaults--type-guards)
-- [Cross-Device Support](#cross-device-support)
+- [Extended Mode - Advanced Control](#extended-mode---advanced-control)
+- [Authentication Strategies](#authentication-strategies)
 - [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
+npm install @glideidentity/web-client-sdk
 ```
 
 ## Quick Start
 
-### React
+### React Example
 
 ```jsx
-import { usePhoneAuth } from 'glide-web-client-sdk/react'
+import React, { useState } from 'react';
+import { PhoneAuthClient } from '@glideidentity/web-client-sdk';
 
 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 [phoneAuth] = useState(() => new PhoneAuthClient({
+    pollingInterval: 2000,
+    maxPollingAttempts: 30,
+    debug: false
+  }));
+
+  const handleGetPhoneNumber = async () => {
+    try {
+      // Prepare the request
+      const prepareResult = await phoneAuth.preparePhoneRequest({
+        use_case: 'GetPhoneNumber'
+      });
+      
+      // Invoke authentication (SDK handles UI by default)
+      const credential = await phoneAuth.invokeSecurePrompt(prepareResult);
+      
+      // Process the credential
+      const result = await phoneAuth.getPhoneNumberCredential(
+        credential, 
+        prepareResult.session
+      );
+      
+      console.log('Phone number:', result.phone_number);
+    } catch (error) {
+      console.error('Verification failed:', error);
     }
-  })
+  };
 
-  const handleVerify = async () => {
+  const handleVerifyPhoneNumber = async () => {
     try {
-      // Verify a specific phone number
-      await verifyPhoneNumber('+1234567890')
+      // Prepare with phone number
+      const prepareResult = await phoneAuth.preparePhoneRequest({
+        use_case: 'VerifyPhoneNumber',
+        phone_number: '+14155551234'
+      });
+      
+      // Invoke authentication
+      const credential = await phoneAuth.invokeSecurePrompt(prepareResult);
+      
+      // Verify the number
+      const result = await phoneAuth.verifyPhoneNumberCredential(
+        credential,
+        prepareResult.session
+      );
+      
+      console.log('Verified:', result.verified);
     } catch (error) {
-      // Error only thrown after all retries exhausted
-      console.error('Verification failed:', error)
+      console.error('Verification failed:', error);
     }
-  }
+  };
 
   return (
     <div>
-      <button onClick={handleVerify} disabled={isLoading}>
-        Verify My Phone
+      <button onClick={handleGetPhoneNumber}>
+        Get Phone Number
+      </button>
+      <button onClick={handleVerifyPhoneNumber}>
+        Verify Phone Number
       </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.
+## Extended Mode - Advanced Control
 
-### **Headless Mode** - Complete Control
-Returns raw data without any UI, allowing you to build completely custom experiences.
+The SDK supports an **Extended Mode** that provides granular control over the authentication flow. This mode returns an `ExtendedResponse` object with additional methods and data for custom implementations.
 
-### When to Use Each Mode
+### When to Use Extended 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 |
+| Use Case | Standard Mode | Extended Mode |
+|----------|--------------|---------------|
+| Simple verification | ✓ Best choice | Use if needed |
+| Custom retry logic | Limited | ✓ Full control |
+| Progressive UI updates | No | ✓ Real-time status |
+| Custom polling control | No | ✓ Start/stop control |
+| Multiple auth attempts | Manual | ✓ Built-in retry |
 
-### UI Mode Example (Default)
+### Extended Mode Example
 
 ```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
+// Enable extended mode for granular control
 const result = await phoneAuth.invokeSecurePrompt(prepareResult, {
-  headless: true
+  executionMode: 'extended',
+  preventDefaultUI: true  // Optional: disable all SDK UI
 });
 
-// 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');
+// Extended response provides more control
+if (result.strategy === 'desktop') {
+  // Custom QR display
+  displayQR(result.qr_code_data.ios_qr_image);
   
-  // 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');
+  // Start polling when ready (only if preventDefaultUI was true)
+  if (result.start_polling) {
+    const credential = await result.start_polling();
+  }
   
-  // Trigger when user clicks your custom button
-  const credential = await result.trigger();
+  // Or wait for credential
+  const credential = await result.credential;
   
-  // 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
+  // Cancel if needed
+  result.cancel();
 }
-```
-
-### 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 (result.strategy === 'link') {
+  // Re-trigger app opening
+  result.trigger();
   
-  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();
+  // Check polling status
+  if (result.is_polling) {
+    console.log('Currently polling...');
   }
-  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);
+  
+  // Wait for completion
+  const credential = await result.credential;
 }
-```
-
-#### 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);
+if (result.strategy === 'ts43') {
+  // Trigger when user is ready
+  await result.trigger();
   
-  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>
-  );
+  // Get credential
+  const credential = await result.credential;
 }
 ```
 
-### 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'
-  }
-});
+### Extended Response Types
 
-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);
+```typescript
+interface ExtendedResponse {
+  strategy: 'desktop' | 'link' | 'ts43';
+  session: SessionInfo;
+  credential: Promise<AuthCredential>;
+  cancel: () => void;
 }
 
-// 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;
-  }
+interface DesktopExtendedResponse extends ExtendedResponse {
+  qr_code_data: {
+    ios_qr_image?: string;
+    android_qr_image?: string;
+    qr_code?: string;
+  };
+  start_polling?: () => Promise<AuthCredential>;
+  is_polling?: boolean;
 }
-</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 LinkExtendedResponse extends ExtendedResponse {
+  data: {
+    app_url: string;
   };
+  trigger: () => void;
+  start_polling?: () => Promise<AuthCredential>;
+  is_polling?: boolean;
 }
 
-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;
+interface TS43ExtendedResponse extends ExtendedResponse {
+  trigger: () => Promise<void>;
 }
 ```
 
-## Smart Defaults & Type Guards
-
-### Smart Mode Selection
+### Prevent Default UI
 
-The SDK automatically chooses the optimal mode based on the authentication strategy:
+Use `preventDefaultUI: true` to completely disable SDK modals and handle all UI yourself:
 
 ```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
+// Desktop: No QR modal shown
+const result = await phoneAuth.invokeSecurePrompt(prepareResult, {
+  executionMode: 'extended',
+  preventDefaultUI: true
 });
-```
-
-### 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);
+// You must display QR yourself
+if (result.strategy === 'desktop') {
+  showYourCustomQR(result.qr_code_data);
   
-  // 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);
+  // Start polling manually (required when preventDefaultUI is true)
+  const credential = await result.start_polling();
 }
 ```
 
-### Unified Trigger Pattern
+### Parent Session Support
 
-All headless strategies use the same `trigger()` pattern:
+For continuing authentication from another device:
 
 ```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
+// Desktop starts authentication
+const desktopResult = await phoneAuth.preparePhoneRequest({
+  use_case: 'GetPhoneNumber'
 });
-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');
-  }
+// Mobile continues with parent session
+const mobileResult = await phoneAuth.preparePhoneRequest({
+  parent_session_id: desktopResult.session.session_id
+  // use_case inherited from parent
 });
-```
-
-## 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
 
+// Complete authentication on mobile
+const credential = await phoneAuth.invokeSecurePrompt(mobileResult);
 ```
-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!
-```
+## Authentication Strategies
 
-### Monitoring Retries
+The SDK automatically selects the appropriate authentication strategy based on the device and browser:
 
-```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
+### Desktop Strategy (QR Code)
+- **When**: Desktop browsers
+- **How**: Displays QR code for mobile scanning
+- **Default**: Shows built-in QR modal
+- **Custom**: Use `preventDefaultUI: true` to handle QR display yourself
 
-Both callbacks are optional and have no performance impact when not used:
+### Link Strategy (App Clips/Deep Links)
+- **When**: Mobile browsers on iOS/Android
+- **How**: Opens native app or App Clip
+- **Default**: Opens app link immediately
+- **Custom**: Control when to open with `trigger()` in extended mode
 
-| Callback | Purpose | Use Case |
-|----------|---------|----------|
-| `onCrossDeviceDetected` | Fires when QR code flow detected | Analytics, custom UI |
-| `onRetryAttempt` | Fires on each retry attempt | Monitoring, debugging |
+### TS43 Strategy (Digital Credentials)
+- **When**: Chrome/Edge on Android with Digital Credentials API
+- **How**: Uses browser's native credential prompt
+- **Default**: Shows credential prompt immediately
+- **Custom**: Control timing with `trigger()` in extended mode
 
-### TypeScript Support
+## Type Guards for Safe Handling
 
-Full TypeScript support with exported types:
+Use built-in type guards for type-safe result handling:
 
 ```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
+  isExtendedResponse,
+  isDesktopStrategy,
+  isLinkStrategy,
+  isTS43Strategy
+} from '@glideidentity/web-client-sdk';
 
-The SDK provides specific error information for cross-device issues:
+const result = await phoneAuth.invokeSecurePrompt(prepareResponse, {
+  executionMode: 'extended'
+});
 
-```javascript
-if (error.details?.errorType === 'CROSS_DEVICE_TIMEOUT') {
-  // QR code expired
-}
-if (error.details?.errorType === 'CROSS_DEVICE_CONNECTION_LOST') {
-  // Connection lost during phone verification
+// Check if extended response
+if (isExtendedResponse(result)) {
+  console.log('Strategy:', result.strategy);
+  
+  // Check specific strategies
+  if (isDesktopStrategy(result)) {
+    // TypeScript knows this is DesktopExtendedResponse
+    console.log('QR data:', result.qr_code_data);
+  } else if (isLinkStrategy(result)) {
+    // TypeScript knows this is LinkExtendedResponse
+    console.log('App URL:', result.data.app_url);
+  } else if (isTS43Strategy(result)) {
+    // TypeScript knows this is TS43ExtendedResponse
+    await result.trigger();
+  }
+} else {
+  // Standard mode - got credential directly
+  const verified = await phoneAuth.verifyPhoneNumberCredential(result, session);
 }
 ```
 
-## Browser Support
-
-### Requirements
+## Framework Examples
 
-- 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 3 Example
 
 ```vue
 <template>
   <div>
-    <button @click="verify" :disabled="isLoading">
+    <button @click="verifyPhone" :disabled="isLoading">
       Verify Phone
     </button>
     
-    <!-- Retry button -->
-    <button v-if="error" @click="retryLastRequest">
-      Retry
-    </button>
-    
     <div v-if="result">
       Phone: {{ result.phone_number }}
     </div>
@@ -711,201 +329,274 @@ if (!isSupported) {
 </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');
-  }
-})
+import { ref } from 'vue';
+import { PhoneAuthClient } from '@glideidentity/web-client-sdk';
 
-const verify = async () => {
-  await verifyPhoneNumber('+1234567890')
+const phoneAuth = new PhoneAuthClient({
+  maxPollingAttempts: 30
+});
+
+const isLoading = ref(false);
+const result = ref(null);
+
+async function verifyPhone() {
+  isLoading.value = true;
+  try {
+    const prepared = await phoneAuth.preparePhoneRequest({
+      use_case: 'VerifyPhoneNumber',
+      phone_number: '+14155551234'
+    });
+    
+    const credential = await phoneAuth.invokeSecurePrompt(prepared);
+    result.value = await phoneAuth.verifyPhoneNumberCredential(
+      credential,
+      prepared.session
+    );
+  } catch (error) {
+    console.error('Failed:', error);
+  } finally {
+    isLoading.value = false;
+  }
 }
 </script>
 ```
 
-## Angular Example
+### Angular Example
 
 ```typescript
 import { Component } from '@angular/core';
-import { PhoneAuthService } from 'glide-web-client-sdk/angular';
+import { PhoneAuthClient } from '@glideidentity/web-client-sdk';
 
 @Component({
   selector: 'app-phone-verify',
   template: `
-    <button (click)="verify()" [disabled]="isLoading$ | async">
+    <button (click)="verify()" [disabled]="isLoading">
       Verify
     </button>
     
-    <button *ngIf="error$ | async" (click)="retry()">
-      Retry
-    </button>
-    
-    <div *ngIf="result$ | async as result">
+    <div *ngIf="result">
       Phone: {{ result.phone_number }}
     </div>
   `
 })
 export class PhoneVerifyComponent {
-  isLoading$ = this.phoneAuth.isLoading$;
-  error$ = this.phoneAuth.error$;
-  result$ = this.phoneAuth.result$;
+  phoneAuth = new PhoneAuthClient({
+    // Optional configuration
+    debug: false
+  });
   
-  constructor(private phoneAuth: PhoneAuthService) {
-    this.phoneAuth.configure({
-      endpoints: {
-        prepare: '/api/phone-auth/prepare',
-        process: '/api/phone-auth/process'
-      },
-      onCrossDeviceDetected: () => {
-        console.log('QR code detected');
-      }
-    });
-  }
+  isLoading = false;
+  result: any = null;
   
   async verify() {
-    await this.phoneAuth.verifyPhoneNumber('+1234567890');
-  }
-  
-  async retry() {
-    await this.phoneAuth.retryLastRequest();
+    this.isLoading = true;
+    try {
+      const prepared = await this.phoneAuth.preparePhoneRequest({
+        use_case: 'VerifyPhoneNumber',
+        phone_number: '+14155551234'
+      });
+      
+      const credential = await this.phoneAuth.invokeSecurePrompt(prepared);
+      this.result = await this.phoneAuth.verifyPhoneNumberCredential(
+        credential,
+        prepared.session
+      );
+    } catch (error) {
+      console.error('Failed:', error);
+    } finally {
+      this.isLoading = false;
+    }
   }
 }
 ```
 
-## Vanilla JavaScript
+### Vanilla JavaScript
 
 ```javascript
-import { PhoneAuthClient } from 'glide-web-client-sdk';
+import { PhoneAuthClient } from '@glideidentity/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}`);
-  }
+  pollingInterval: 2000,
+  maxPollingAttempts: 30,
+  debug: false
 });
 
-// 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);
+// Get phone number
+async function getPhoneNumber() {
+  try {
+    const prepareResult = await client.preparePhoneRequest({
+      use_case: 'GetPhoneNumber'
+    });
+    
+    const credential = await client.invokeSecurePrompt(prepareResult);
+    
+    const result = await client.getPhoneNumberCredential(
+      credential,
+      prepareResult.session
+    );
+    
+    console.log('Phone:', result.phone_number);
+  } catch (error) {
+    console.error('Failed:', error);
+  }
+}
+
+// Verify with extended mode
+async function verifyWithExtendedMode() {
+  try {
+    const prepareResult = await client.preparePhoneRequest({
+      use_case: 'VerifyPhoneNumber',
+      phone_number: '+14155551234'
+    });
+    
+    const extendedResult = await client.invokeSecurePrompt(prepareResult, {
+      executionMode: 'extended',
+      preventDefaultUI: true
+    });
+    
+    // Handle based on strategy
+    if (extendedResult.strategy === 'desktop') {
+      // Show custom QR
+      document.getElementById('qr').src = extendedResult.qr_code_data.qr_code;
+      
+      // Start polling
+      const credential = await extendedResult.start_polling();
+      console.log('Verified!');
+    }
+  } catch (error) {
+    console.error('Failed:', error);
+  }
 }
 ```
 
-## Migration from v3
+## Error Handling
 
-No breaking changes! The SDK is fully backward compatible. New features are additive:
+The SDK provides detailed error information:
 
 ```javascript
-// v3 code continues to work
-const { getPhoneNumber } = usePhoneAuth(config);
-
-// v4 adds new optional features
-const { getPhoneNumber, retryLastRequest } = usePhoneAuth({
-  ...config,
-  onCrossDeviceDetected: () => {}, // Optional
-  onRetryAttempt: () => {}          // Optional
-});
+try {
+  const result = await phoneAuth.invokeSecurePrompt(prepareResponse);
+} catch (error) {
+  console.log(error.code);    // e.g., 'CARRIER_NOT_ELIGIBLE'
+  console.log(error.message); // User-friendly error message
+  
+  switch (error.code) {
+    case 'CARRIER_NOT_ELIGIBLE':
+      // Handle unsupported carrier
+      break;
+    case 'USER_DENIED':
+      // User cancelled authentication
+      break;
+    case 'TIMEOUT':
+      // Authentication timed out
+      break;
+    default:
+      // Handle other errors
+  }
+}
 ```
 
-## Debug Tools
+## Browser Support
 
-For development and testing, debug components are available in the `/examples/debug-components/` folder:
+### Requirements
+
+- Chrome 118+ or Edge 118+ (for TS43 strategy)
+- Digital Credentials API flag enabled (for TS43)
+- Any modern browser for Desktop/Link strategies
 
-- `PhoneAuthDebugger.jsx` - Comprehensive debugging interface
-- `AppEnhanced.jsx` - Production app with debug mode
+### Checking Support
 
-These are not included in the main bundle. Copy them to your project if needed.
+```javascript
+// Check if current browser/device is supported
+const isSupported = phoneAuth.isSupported();
+
+if (!isSupported) {
+  console.log('Phone authentication not supported on this device');
+}
+```
 
 ## 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
+interface PhoneAuthConfig {
+  endpoints?: {
+    prepare?: string;                      // Custom prepare endpoint
+    process?: string;                      // Custom process endpoint  
+    polling?: string;                      // Custom polling endpoint
+  };
+  pollingInterval?: number;                // Polling interval in ms (default: 2000)
+  maxPollingAttempts?: number;             // Max polling attempts (default: 30 = 1 minute)
+  timeout?: number;                        // API timeout in ms (default: 30000)
+  debug?: boolean;                         // Enable debug logging (default: false)
+  devtools?: {
+    showMobileConsole?: boolean;           // Show debug console on mobile (default: false)
   };
-  
-  // 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)
+### Invoke Options
 
 ```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)
+interface InvokeOptions {
+  // Execution mode
+  executionMode?: 'standard' | 'extended';  // Default: 'standard'
+  preventDefaultUI?: boolean;                // Default: false
+  
+  // UI customization (when preventDefaultUI is false)
+  modalOptions?: {
+    className?: string;
+    title?: string;
+    description?: string;
+    buttonText?: string;
+    showCloseButton?: boolean;
+  };
+  
+  // Callbacks
+  callbacks?: {
+    onOpen?: () => void;
+    onClose?: () => void;
+    onAuthStart?: () => void;
+    onAuthComplete?: (result: any) => void;
+    onError?: (error: Error) => void;
+  };
 }
-
-// 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)
+// Core methods
 preparePhoneRequest(options: PrepareRequest): Promise<PrepareResponse>
-invokeSecurePrompt(response: PrepareResponse, options?: InvokeOptions): Promise<HeadlessResult | Credential>
+invokeSecurePrompt(response: PrepareResponse, options?: InvokeOptions): Promise<any>
 getPhoneNumberCredential(credential: any, session: SessionInfo): Promise<GetPhoneNumberResponse>
 verifyPhoneNumberCredential(credential: any, session: SessionInfo): Promise<VerifyPhoneNumberResponse>
 
+// High-level convenience methods
+getPhoneNumberComplete(): Promise<GetPhoneNumberResponse>
+verifyPhoneNumberComplete(phoneNumber: string): Promise<VerifyPhoneNumberResponse>
+
 // Utility methods
-retryLastRequest(): Promise<any>
+isSupported(): boolean
 cancelCurrentRequest(): void
 ```
 
 ### Response Types
 
 ```typescript
+interface PrepareRequest {
+  use_case: 'GetPhoneNumber' | 'VerifyPhoneNumber';
+  phone_number?: string;
+  parent_session_id?: string;
+}
+
+interface PrepareResponse {
+  authentication_strategy: 'desktop' | 'link' | 'ts43';
+  session: SessionInfo;
+  data: any;
+}
+
 interface GetPhoneNumberResponse {
   phone_number: string;
   aud?: string;
@@ -916,23 +607,13 @@ interface VerifyPhoneNumberResponse {
   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)
+- [API Reference](https://docs.glideidentity.com/api-reference)
 
 ## License
 
-MIT
+MIT