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

package/README.md

@@ -1,43 +1,16 @@
 # 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.
+The official web SDK for integrating Glide's carrier-grade phone verification into your web applications.
 
 ## 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
-- 📱 **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
-
-### 🎉 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
-- **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)
-- [Development](#development)
-- [Quick Start](#quick-start)
-- [Extended Mode - Advanced Control](#extended-mode---advanced-control)
-- [Authentication Strategies](#authentication-strategies)
-- [Framework Examples](#framework-examples)
-- [Error Handling](#error-handling)
-- [Browser Support](#browser-support)
-- [API Reference](#api-reference)
-- [Documentation](#documentation)
+- 🚀 **Instant Verification** - Direct carrier verification without SMS delays
+- 🔐 **Fraud Resistant** - Can't be intercepted or spoofed like SMS codes
+- 📱 **Multi-Platform** - Desktop QR codes, iOS App Clips, Android deep links
+- 🎨 **Customizable UI** - Built-in modal with themes and view modes
+- 🔧 **Flexible Architecture** - Use the full SDK or just the core types
+- 🌐 **Framework Support** - React, Vue, Angular, and vanilla JavaScript
+- 📦 **Tree-Shakeable** - Import only what you need
 
 ## Installation
 
@@ -45,617 +18,455 @@ The official web SDK for integrating Glide's carrier-grade phone verification in
 npm install @glideidentity/web-client-sdk
 ```
 
-## Development
-
-### Using Docker (Recommended)
+## Quick Start
 
-```bash
-# Build the SDK
-docker compose run --rm build
+### High-Level API (Recommended)
 
-# Run tests
-docker compose run --rm test
+The simplest way to integrate phone verification:
 
-# Interactive development shell
-docker compose run --rm dev
-```
-
-### Without Docker
+```javascript
+import { PhoneAuthClient, USE_CASE } from '@glideidentity/web-client-sdk';
 
-```bash
-# Install dependencies
-npm install
+const client = new PhoneAuthClient({
+  endpoints: {
+    prepare: '/api/phone-auth/prepare',
+    process: '/api/phone-auth/process',
+  }
+});
 
-# Build the SDK
-npm run build
+// Get a phone number
+const result = await client.authenticate({
+  use_case: USE_CASE.GET_PHONE_NUMBER
+});
+console.log('Phone:', result.phone_number);
 
-# Run tests
-npm test
+// Or verify a specific number
+const verified = await client.authenticate({
+  use_case: USE_CASE.VERIFY_PHONE_NUMBER,
+  phone_number: '+14155551234'
+});
+console.log('Verified:', verified.verified);
 ```
 
-## Quick Start
+### Granular API
 
-### React Example
+For more control over the authentication flow:
 
-```jsx
-import React, { useState } from 'react';
-import { PhoneAuthClient } from '@glideidentity/web-client-sdk';
+```javascript
+import { PhoneAuthClient, USE_CASE } from '@glideidentity/web-client-sdk';
 
-function PhoneVerification() {
-  const [phoneAuth] = useState(() => new PhoneAuthClient({
-    pollingInterval: 2000,
-    maxPollingAttempts: 30,
-    debug: false
-  }));
+const client = new PhoneAuthClient({
+  endpoints: {
+    prepare: '/api/phone-auth/prepare',
+    process: '/api/phone-auth/process',
+  }
+});
 
-  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.getPhoneNumber(
-        credential, 
-        prepareResult.session
-      );
-      
-      console.log('Phone number:', result.phone_number);
-    } catch (error) {
-      console.error('Verification failed:', error);
-    }
-  };
+// Step 1: Prepare the request
+const prepared = await client.prepare({
+  use_case: USE_CASE.VERIFY_PHONE_NUMBER,
+  phone_number: '+14155551234'
+});
 
-  const handleVerifyPhoneNumber = async () => {
-    try {
-      // 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.verifyPhoneNumber(
-        credential,
-        prepareResult.session
-      );
-      
-      console.log('Verified:', result.verified);
-    } catch (error) {
-      console.error('Verification failed:', error);
-    }
-  };
+// Step 2: Invoke authentication (shows UI based on strategy)
+const invokeResult = await client.invokeSecurePrompt(prepared);
+const credential = await invokeResult.credential;
 
-  return (
-    <div>
-      <button onClick={handleGetPhoneNumber}>
-        Get Phone Number
-      </button>
-      <button onClick={handleVerifyPhoneNumber}>
-        Verify Phone Number
-      </button>
-    </div>
-  );
-}
-```
+// Step 3: Process the credential
+const result = await client.verifyPhoneNumber(credential, invokeResult.session);
 
-## Extended Mode - Advanced Control
+console.log('Verified:', result.verified);
+```
 
-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.
+## Configuration
 
-### When to Use Extended Mode
+### Client Options
 
-| 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 |
+```typescript
+const client = new PhoneAuthClient({
+  // Required: Your backend endpoints
+  endpoints: {
+    prepare: '/api/phone-auth/prepare',   // Prepare request endpoint
+    process: '/api/phone-auth/process',   // Process credential endpoint
+    polling: '/api/phone-auth/status',    // Optional: Status polling endpoint
+  },
+  
+  // Polling configuration
+  pollingInterval: 2000,      // Polling interval in ms (default: 2000)
+  maxPollingAttempts: 30,     // Max attempts before timeout (default: 30)
+  timeout: 30000,             // API request timeout in ms (default: 30000)
+  
+  // Debug options
+  debug: false,               // Enable console logging (default: false)
+  devtools: {
+    showMobileConsole: false  // Show on-screen console on mobile (default: false)
+  }
+});
+```
 
-### Extended Mode Example
+### Invoke Options
 
-```javascript
-// Enable extended mode for granular control
-const result = await phoneAuth.invokeSecurePrompt(prepareResult, {
-  executionMode: 'extended',
-  preventDefaultUI: true  // Optional: disable all SDK UI
-});
+Customize the authentication UI and behavior:
 
-// Extended response provides more control
-if (result.strategy === 'desktop') {
-  // Custom QR display
-  displayQR(result.qr_code_data.ios_qr_image);
-  
-  // Start polling when ready (only if preventDefaultUI was true)
-  if (result.start_polling) {
-    const credential = await result.start_polling();
-  }
-  
-  // Or wait for credential
-  const credential = await result.credential;
+```typescript
+const result = await client.invokeSecurePrompt(prepared, {
+  // Prevent SDK from showing any UI (use your own)
+  preventDefaultUI: false,
   
-  // Cancel if needed
-  result.cancel();
-}
-
-if (result.strategy === 'link') {
-  // Re-trigger app opening
-  result.trigger();
+  // Polling configuration (overrides client config)
+  pollingInterval: 2000,
+  maxPollingAttempts: 30,
   
-  // Check polling status
-  if (result.is_polling) {
-    console.log('Currently polling...');
+  // Modal customization (for desktop QR strategy)
+  modalOptions: {
+    theme: 'auto',              // 'dark' | 'light' | 'auto'
+    viewMode: 'toggle',         // 'toggle' | 'dual' | 'pre-step'
+    title: 'Scan to Verify',    // Custom title text
+    description: '',            // Optional subtitle
+    showCloseButton: true,      // Show X button
+    closeOnBackdropClick: true, // Close on outside click
+    closeOnEscape: true,        // Close on Escape key
   }
-  
-  // Wait for completion
-  const credential = await result.credential;
-}
-
-if (result.strategy === 'ts43') {
-  // Trigger when user is ready
-  await result.trigger();
-  
-  // Get credential
-  const credential = await result.credential;
-}
+});
 ```
 
-### Extended Response Types
+## Modal Customization
 
-```typescript
-interface ExtendedResponse {
-  strategy: 'desktop' | 'link' | 'ts43';
-  session: SessionInfo;
-  credential: Promise<AuthCredential>;
-  cancel: () => void;
-}
+The SDK provides a built-in modal for desktop QR code display.
 
-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;
-}
+### View Modes
 
-interface LinkExtendedResponse extends ExtendedResponse {
-  data: {
-    app_url: string;
-  };
-  trigger: () => void;
-  start_polling?: () => Promise<AuthCredential>;
-  is_polling?: boolean;
-}
+| Mode | Description | Best For |
+|------|-------------|----------|
+| `toggle` | Single QR with iOS/Android switch | Clean, minimal UI (default) |
+| `dual` | Side-by-side QR codes | Users who may not know their OS |
+| `pre-step` | OS selection screen first | Guided experience |
 
-interface TS43ExtendedResponse extends ExtendedResponse {
-  trigger: () => Promise<void>;
-}
-```
+### Themes
+
+| Theme | Description |
+|-------|-------------|
+| `auto` | Follows system preference (default) |
+| `dark` | Dark background with light text |
+| `light` | Light background with dark text |
 
-### Prevent Default UI
+### Custom UI
 
-Use `preventDefaultUI: true` to completely disable SDK modals and handle all UI yourself:
+To use your own UI instead of the built-in modal:
 
 ```javascript
-// Desktop: No QR modal shown
-const result = await phoneAuth.invokeSecurePrompt(prepareResult, {
-  executionMode: 'extended',
+const result = await client.invokeSecurePrompt(prepared, {
   preventDefaultUI: true
 });
 
-// You must display QR yourself
+// For desktop strategy, display your own QR code
 if (result.strategy === 'desktop') {
-  showYourCustomQR(result.qr_code_data);
+  // Access QR data from the prepare response
+  const qrData = prepared.data;
+  displayYourQRCode(qrData.ios_qr_image, qrData.android_qr_image);
   
-  // Start polling manually (required when preventDefaultUI is true)
-  const credential = await result.start_polling();
+  // Wait for credential
+  const credential = await result.credential;
+  
+  // Or cancel if needed
+  result.cancel?.();
 }
 ```
 
-### Parent Session Support
-
-For continuing authentication from another device:
-
-```javascript
-// Desktop starts authentication
-const desktopResult = await phoneAuth.preparePhoneRequest({
-  use_case: 'GetPhoneNumber'
-});
+## Authentication Strategies
 
-// Mobile continues with parent session
-const mobileResult = await phoneAuth.preparePhoneRequest({
-  parent_session_id: desktopResult.session.session_id
-  // use_case inherited from parent
-});
+The SDK automatically selects the best strategy based on the device:
 
-// Complete authentication on mobile
-const credential = await phoneAuth.invokeSecurePrompt(mobileResult);
-```
+| Strategy | Platform | Description |
+|----------|----------|-------------|
+| `ts43` | Android Chrome 128+ | Native Digital Credentials API |
+| `link` | iOS / Android | App Clip (iOS) or carrier app (Android) |
+| `desktop` | Desktop browsers | QR code scanned by mobile |
 
-## Authentication Strategies
+### Strategy-Specific Handling
 
-The SDK automatically selects the appropriate authentication strategy based on the device and browser:
-
-### 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
+```javascript
+const result = await client.invokeSecurePrompt(prepared);
 
-### 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
+switch (result.strategy) {
+  case 'ts43':
+    // Android: Credential returned directly
+    const credential = await result.credential;
+    break;
+    
+  case 'link':
+    // iOS: Opens App Clip, polls for completion
+    // Android: Opens carrier's privileged app, polls for completion
+    const credential = await result.credential;
+    // Optionally cancel polling
+    result.cancel?.();
+    break;
+    
+  case 'desktop':
+    // Desktop: Shows QR modal, polls for completion
+    const credential = await result.credential;
+    result.cancel?.();
+    break;
+}
+```
 
-### 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
+## Framework Integration
 
-## Type Guards for Safe Handling
+### React
 
-Use built-in type guards for type-safe result handling:
+```jsx
+import { usePhoneAuth, USE_CASE } from '@glideidentity/web-client-sdk/react';
 
-```typescript
-import { 
-  isExtendedResponse,
-  isDesktopStrategy,
-  isLinkStrategy,
-  isTS43Strategy
-} from '@glideidentity/web-client-sdk';
+function PhoneVerification() {
+  const { authenticate, isLoading, error, result } = usePhoneAuth({
+    endpoints: {
+      prepare: '/api/phone-auth/prepare',
+      process: '/api/phone-auth/process',
+    }
+  });
 
-const result = await phoneAuth.invokeSecurePrompt(prepareResponse, {
-  executionMode: 'extended'
-});
+  const handleVerify = async () => {
+    try {
+      const result = await authenticate({
+        use_case: USE_CASE.VERIFY_PHONE_NUMBER,
+        phone_number: '+14155551234'
+      });
+      console.log('Verified:', result.verified);
+    } catch (err) {
+      console.error('Failed:', err);
+    }
+  };
 
-// 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.verifyPhoneNumber(result, session);
+  return (
+    <button onClick={handleVerify} disabled={isLoading}>
+      {isLoading ? 'Verifying...' : 'Verify Phone'}
+    </button>
+  );
 }
 ```
 
-## Framework Examples
-
-### Vue 3 Example
+### Vue
 
 ```vue
-<template>
-  <div>
-    <button @click="verifyPhone" :disabled="isLoading">
-      Verify Phone
-    </button>
-    
-    <div v-if="result">
-      Phone: {{ result.phone_number }}
-    </div>
-  </div>
-</template>
-
 <script setup>
-import { ref } from 'vue';
-import { PhoneAuthClient } from '@glideidentity/web-client-sdk';
+import { usePhoneAuth, USE_CASE } from '@glideidentity/web-client-sdk/vue';
 
-const phoneAuth = new PhoneAuthClient({
-  maxPollingAttempts: 30
+const { authenticate, isLoading, error, result } = usePhoneAuth({
+  endpoints: {
+    prepare: '/api/phone-auth/prepare',
+    process: '/api/phone-auth/process',
+  }
 });
 
-const isLoading = ref(false);
-const result = ref(null);
+const handleVerify = async () => {
+  await authenticate({
+    use_case: USE_CASE.VERIFY_PHONE_NUMBER,
+    phone_number: '+14155551234'
+  });
+};
+</script>
 
-async function verifyPhone() {
-  isLoading.value = true;
-  try {
-    const prepared = await phoneAuth.preparePhoneRequest({
-      use_case: 'VerifyPhoneNumber',
+<template>
+  <button @click="handleVerify" :disabled="isLoading">
+    {{ isLoading ? 'Verifying...' : 'Verify Phone' }}
+  </button>
+</template>
+```
+
+### Vanilla JavaScript (Browser)
+
+```html
+<script src="https://unpkg.com/@glideidentity/web-client-sdk/dist/browser/web-client-sdk.min.js"></script>
+<script>
+  const { PhoneAuthClient, USE_CASE } = GlideWebClientSDK;
+  
+  const client = new PhoneAuthClient({
+    endpoints: {
+      prepare: '/api/phone-auth/prepare',
+      process: '/api/phone-auth/process',
+    }
+  });
+  
+  document.getElementById('verify-btn').onclick = async () => {
+    const result = await client.authenticate({
+      use_case: USE_CASE.VERIFY_PHONE_NUMBER,
       phone_number: '+14155551234'
     });
-    
-    const credential = await phoneAuth.invokeSecurePrompt(prepared);
-    result.value = await phoneAuth.verifyPhoneNumber(
-      credential,
-      prepared.session
-    );
-  } catch (error) {
-    console.error('Failed:', error);
-  } finally {
-    isLoading.value = false;
-  }
-}
+    console.log('Verified:', result.verified);
+  };
 </script>
 ```
 
-### Angular Example
+## Advanced Features
 
-```typescript
-import { Component } from '@angular/core';
-import { PhoneAuthClient } from '@glideidentity/web-client-sdk';
-
-@Component({
-  selector: 'app-phone-verify',
-  template: `
-    <button (click)="verify()" [disabled]="isLoading">
-      Verify
-    </button>
-    
-    <div *ngIf="result">
-      Phone: {{ result.phone_number }}
-    </div>
-  `
-})
-export class PhoneVerifyComponent {
-  phoneAuth = new PhoneAuthClient({
-    // Optional configuration
-    debug: false
-  });
-  
-  isLoading = false;
-  result: any = null;
-  
-  async verify() {
-    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.verifyPhoneNumber(
-        credential,
-        prepared.session
-      );
-    } catch (error) {
-      console.error('Failed:', error);
-    } finally {
-      this.isLoading = false;
+### Custom HTTP Headers
+
+Add custom headers to all SDK requests:
+
+```javascript
+const client = new PhoneAuthClient({
+  endpoints: { ... },
+  headers: {
+    common: {
+      'X-Custom-Header': 'your-value'
     }
   }
-}
+});
 ```
 
-### Vanilla JavaScript
+### Custom Logger
 
-```javascript
-import { PhoneAuthClient } from '@glideidentity/web-client-sdk';
+Provide your own logger implementation:
 
+```javascript
 const client = new PhoneAuthClient({
-  pollingInterval: 2000,
-  maxPollingAttempts: 30,
-  debug: false
+  endpoints: { ... },
+  logger: {
+    debug: (msg, data) => console.debug('[SDK]', msg, data),
+    info: (msg, data) => console.info('[SDK]', msg, data),
+    warn: (msg, data) => console.warn('[SDK]', msg, data),
+    error: (msg, data) => console.error('[SDK]', msg, data),
+  }
 });
+```
 
-// 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.getPhoneNumber(
-      credential,
-      prepareResult.session
-    );
-    
-    console.log('Phone:', result.phone_number);
-  } catch (error) {
-    console.error('Failed:', error);
-  }
-}
+### Custom HTTP Client
 
-// 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!');
+Bring your own HTTP client for full control:
+
+```javascript
+const client = new PhoneAuthClient({
+  endpoints: { ... },
+  httpClient: {
+    post: async (url, body, options) => {
+      const response = await yourHttpLib.post(url, body, options);
+      return response.data;
+    },
+    get: async (url, options) => {
+      const response = await yourHttpLib.get(url, options);
+      return response.data;
     }
-  } catch (error) {
-    console.error('Failed:', error);
   }
-}
+});
 ```
 
-## Error Handling
+## Core Package
 
-The SDK provides detailed error information:
+For advanced use cases, you can import just the types and validators without the full client:
 
-```javascript
-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
+```typescript
+import { 
+  // Types
+  type PrepareRequest,
+  type PrepareResponse,
+  type InvokeResult,
+  type SessionInfo,
   
-  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
-  }
-}
-```
-
-## Browser Support
+  // Constants
+  USE_CASE,
+  AUTHENTICATION_STRATEGY,
+  ERROR_CODES,
+  
+  // Validators
+  validatePhoneNumber,
+  validatePlmn,
+  
+  // Type Guards
+  isTS43Strategy,
+  isLinkStrategy,
+  isDesktopStrategy,
+  isAuthError,
+} from '@glideidentity/web-client-sdk/core';
 
-### Requirements
+// Use validators
+const { valid, error } = validatePhoneNumber('+14155551234');
 
-- Chrome 118+ or Edge 118+ (for TS43 strategy)
-- Digital Credentials API flag enabled (for TS43)
-- Any modern browser for Desktop/Link strategies
+// Use type guards
+if (isDesktopStrategy(result)) {
+  // TypeScript knows result has desktop-specific properties
+}
+```
 
-### Checking Support
+## Error Handling
 
 ```javascript
-// Check if current browser/device is supported
-const isSupported = phoneAuth.isSupported();
+import { ERROR_CODES, isAuthError } from '@glideidentity/web-client-sdk';
 
-if (!isSupported) {
-  console.log('Phone authentication not supported on this device');
+try {
+  await client.authenticate({ ... });
+} catch (error) {
+  if (isAuthError(error)) {
+    switch (error.code) {
+      case ERROR_CODES.USER_CANCELLED:
+        // User closed the modal or cancelled
+        break;
+      case ERROR_CODES.TIMEOUT:
+        // Authentication timed out
+        break;
+      case ERROR_CODES.NETWORK_ERROR:
+        // Network request failed
+        break;
+      default:
+        // Handle other errors
+        console.error(error.message);
+    }
+  }
 }
 ```
 
-## API Reference
+## Type Reference
 
-### Configuration Options
+### Use Cases
 
 ```typescript
-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)
-  };
-}
+type UseCase = 'GetPhoneNumber' | 'VerifyPhoneNumber';
+
+// Or use the constant
+USE_CASE.GET_PHONE_NUMBER    // 'GetPhoneNumber'
+USE_CASE.VERIFY_PHONE_NUMBER // 'VerifyPhoneNumber'
 ```
 
-### Invoke Options
+### Prepare Request
 
 ```typescript
-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;
-  };
+interface PrepareRequest {
+  use_case: UseCase;
+  phone_number?: string;      // Required for VerifyPhoneNumber
+  parent_session_id?: string; // For cross-device flows
 }
 ```
 
-### Methods
+### Invoke Result
 
 ```typescript
-// Core methods (granular control)
-preparePhoneRequest(options: PrepareRequest): Promise<PrepareResponse>
-invokeSecurePrompt(response: PrepareResponse, options?: InvokeOptions): Promise<any>
-getPhoneNumber(credential: any, session: SessionInfo): Promise<GetPhoneNumberResponse>
-verifyPhoneNumber(credential: any, session: SessionInfo): Promise<VerifyPhoneNumberResponse>
-
-// High-level convenience methods (full flow)
-getPhoneNumberComplete(): Promise<GetPhoneNumberResponse>
-verifyPhoneNumberComplete(phoneNumber: string): Promise<VerifyPhoneNumberResponse>
-
-// Utility methods
-isSupported(): boolean
+interface InvokeResult {
+  strategy: 'ts43' | 'link' | 'desktop';
+  session: SessionInfo;
+  credential: Promise<AuthCredential>;
+  cancel?: () => void;  // Available for link and desktop
+}
 ```
 
-### Response Types
+### Responses
 
 ```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;
 }
 
 interface VerifyPhoneNumberResponse {
   phone_number: string;
   verified: boolean;
-  aud?: string;
 }
 ```
 
-## Documentation
-
-For detailed documentation, see the [docs](./docs) folder:
-
-| Document | Description |
-|----------|-------------|
-| [Architecture](./docs/architecture.md) | SDK architecture and design principles |
-| [Phone Authentication](./docs/phone-auth.md) | Complete phone auth usage guide |
-| [Desktop Authentication](./docs/desktop-auth.md) | QR code authentication flow |
-| [Dual Platform QR](./docs/dual-platform-qr.md) | iOS/Android specific QR codes |
-| [Error Handling](./docs/error-handling.md) | Error codes and handling strategies |
-| [Trigger Pattern](./docs/trigger-pattern.md) | Consistent trigger API across strategies |
-| [Implementation Notes](./docs/implementation-notes.md) | Technical implementation details |
-| [Local Development](./docs/local-development.md) | Testing the SDK locally |
-| [TS43 Data Flow](./docs/TS43_DATA_FLOW.md) | Digital Credentials API details |
-| [Type Hierarchy](./docs/TYPE_HIERARCHY.md) | TypeScript type system |
-| [Naming Conventions](./docs/NAMING_CONVENTIONS.md) | API naming standards |
-| [Security Checklist](./docs/security-checklist.md) | NPM publishing security |
+## Browser Support
+
+| Browser | Strategy | Requirements |
+|---------|----------|--------------|
+| Chrome Android 128+ | TS43 | Digital Credentials API |
+| Safari iOS | Link | App Clips support |
+| Chrome/Edge/Firefox Desktop | Desktop | Any modern version |
 
 ## Support
 
@@ -664,4 +475,4 @@ For detailed documentation, see the [docs](./docs) folder:
 
 ## License
 
-MIT
+MIT