@centive/aria-sdk 0.5.8 → 0.6.0

package/README.md

@@ -1,906 +1,375 @@
 # Aria React SDK
 
-A production-ready React SDK for [Anam AI](https://docs.anam.ai/) with dual-mode operation, WebSocket integration, and comprehensive message accumulation for seamless AI assistant experiences.
+A production-ready React SDK for [Anam AI](https://docs.anam.ai/) with simple initialization, automatic session management, and a beautiful AI assistant interface.
 
 [![npm version](https://img.shields.io/npm/v/@centive/aria-sdk.svg)](https://www.npmjs.com/package/@centive/aria-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## ✨ Key Features
-
-### 🎯 Dual-Mode Operation
-- **Floating Button Mode** - Always-visible button for user-initiated conversations
-- **Center Modal Mode** - Auto-opens when WebSocket events arrive (e.g., incoming calls)
-- **Both modes work simultaneously** - Maximum flexibility for any use case
-
-### 🚀 Global Session Management
-- **Lazy Session Initialization** - Greeting plays exactly when user opens widget (not preloaded)
-- **Session Persistence** - Session survives page navigation in SPAs
-- **Widget Toggle Persistence** - Keep session alive when widget is closed/reopened (optional)
-- **Minimized Widget State** - Click outside to minimize, keeping session active
-- **Proactive Refresh** - Automatically refreshes session before expiration
-- **Tab Visibility Awareness** - Only refreshes when tab is active
-- **Error Recovery** - Exponential backoff retry on failures
-
-### 🔌 WebSocket Integration
-- Real-time bidirectional communication
-- Automatic session management
-- Message accumulation and persistence
-- Auto-save and circuit breaker patterns
-
-### 💬 Full-Featured Communication
-- Real-time video streaming with AI personas
-- Toggle-able chat panel with conversation history
-- Mute/unmute audio controls
-- Live transcription display
-- Message history tracking
-- **Tool Call Indicators** - Visual feedback when AI is executing tools/functions
-
-### 🎨 Modern UI
-- Video-call-style interface
-- Light and dark theme support
-- Landscape video (16:9) optimization
-- Built with Shad/CN UI components
-- Fully responsive design
-
-### 🔧 Developer-Friendly
-- TypeScript support with full type safety
-- Simple React components and hooks
-- Comprehensive documentation
-- Example servers included
-
-## 📦 Installation
+## Quick Start
 
-```bash
-npm install @centive/aria-sdk
-```
-
-### Peer Dependencies
-
-The SDK requires React 18+ as a peer dependency:
-
-```bash
-npm install react@^18.0.0 react-dom@^18.0.0
-```
-
-## 🚀 Quick Start
-
-### 1. Simple Integration (Recommended)
-
-The SDK provides an all-in-one container that handles WebSocket connection, state management, and the UI. Just import and drop it in! By default, this includes both the floating trigger button and the assistant widget.
-
-> **Important:** Place `Aria` (or `AriaProvider`) at your app's root level, **above your router**. This ensures the session persists across page navigation and provides instant response when users click the trigger button.
-
-```tsx
+```typescript
 import { Aria } from '@centive/aria-sdk';
-import '@centive/aria-sdk/styles.css';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
 
-function App() {
-  const config = {
-    websocketUrl: 'ws://localhost:8000/ws',
-    userId: 'user_123',
-    theme: 'light', // or 'dark'
-    // Session preloading is enabled by default
-    preloadSession: true,
-    // Refresh session 5 minutes before expiry (default)
-    sessionRefreshBuffer: 5,
-  };
+// Initialize with just 3 lines
+Aria.init({
+  websocketUrl: 'wss://your-server.com/ws',
+  userId: 'user_123',
+});
 
-  return (
-    // Place Aria at the root, ABOVE the router for session persistence
-    <Aria config={config}>
-      <BrowserRouter>
-        <Routes>
-          <Route path="/" element={<Home />} />
-          <Route path="/dashboard" element={<Dashboard />} />
-        </Routes>
-      </BrowserRouter>
-    </Aria>
-  );
-}
+// That's it! The floating button appears automatically.
 ```
 
-### 2. Advanced Integration (Manual Placement)
+## Installation
 
-If you need full control over where components are rendered, you can disable the automatic rendering and place the component yourself:
-
-```tsx
-import { AriaProvider, AriaAssistant } from '@centive/aria-sdk';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
+```bash
+npm install @centive/aria-sdk
+```
 
-function App() {
-  const config = {
-    websocketUrl: 'ws://localhost:8000/ws',
-    userId: 'user_123',
-    showAssistant: false, // Disable automatic rendering
-  };
+### Peer Dependencies
 
-  return (
-    // Always place AriaProvider at the root, above the router
-    <AriaProvider config={config}>
-      <BrowserRouter>
-        <Routes>
-          <Route path="/" element={<Home />} />
-          <Route path="/dashboard" element={<Dashboard />} />
-        </Routes>
-      </BrowserRouter>
-      
-      {/* AriaAssistant includes both the trigger button and the widget */}
-      <AriaAssistant 
-        showTrigger={true}      // Show floating trigger button
-        showAvatar={true}       // Show avatar in trigger
-        triggerLabel="Chat"     // Custom button label
-      />
-    </AriaProvider>
-  );
-}
+```bash
+npm install react@^18.0.0 react-dom@^18.0.0
 ```
 
-### 3. Trigger Button Only (No Auto-Popup)
+## Features
 
-If you only want the trigger button without the automatic assistant:
+| Feature | Description |
+|---------|-------------|
+| **Simple Init** | Single function call to set up everything |
+| **Auto Session Management** | WebSocket connection, token refresh, reconnection - all automatic |
+| **Dual-Mode UI** | Floating button + center modal for WebSocket-triggered events |
+| **Session Persistence** | Sessions survive page navigation and widget close/reopen |
+| **Error Recovery** | Automatic reconnection with exponential backoff |
+| **Tool Call Indicators** | Visual feedback when AI executes functions |
+| **Theme Support** | Light and dark themes |
 
-```tsx
-import { AriaProvider, AriaTriggerButton } from '@centive/aria-sdk';
+## Configuration Options
 
-function App() {
-  return (
-    <AriaProvider config={config}>
-      <YourApp />
-      <AriaTriggerButton showAvatar={true} label="Help" />
-    </AriaProvider>
-  );
+```typescript
+interface AriaInitConfig {
+  // Required
+  websocketUrl: string;  // Your backend WebSocket URL
+  userId: string;        // Unique user identifier
+
+  // Optional
+  theme?: 'light' | 'dark';  // UI theme (default: 'light')
+  triggerLabel?: string;     // Button label (e.g., 'Help', 'Chat')
+  onError?: (error: Error) => void;  // Error callback
 }
 ```
 
-### 2. Import Styles
+### Example with All Options
 
-Make sure to import the CSS file in your app:
+```typescript
+import { Aria } from '@centive/aria-sdk';
 
-```tsx
-import '@centive/aria-sdk/styles.css';
+Aria.init({
+  websocketUrl: 'wss://api.example.com/ws',
+  userId: 'user_123',
+  theme: 'dark',
+  triggerLabel: 'Talk to Aria',
+  onError: (error) => {
+    console.error('Aria SDK error:', error);
+    // Send to your error tracking service
+  },
+});
 ```
 
-### 3. Set Up Backend WebSocket Server
+## Programmatic Control
 
-The SDK requires a backend WebSocket server that:
-- **Configures AI persona** based on user context (role, permissions, etc.)
-- Handles session token generation via Anam AI API
-- Manages WebSocket connections
-- Accumulates and persists messages
-- Handles trigger events
+```typescript
+import { Aria } from '@centive/aria-sdk';
 
-**Important:** Persona configuration (avatar, voice, LLM, system prompt) is now controlled by the backend, not the frontend. This allows for:
-- Security: Frontend cannot manipulate AI behavior
-- Flexibility: Change personas based on user roles, context, or A/B testing
-- Centralization: Manage all persona configurations in one place
+// Open the assistant
+Aria.open();
 
-See the included example servers:
-- `example-ws-server.js` - WebSocket server with backend persona configuration
-- `example-server.js` - HTTP server for session tokens
+// Open in center mode (like incoming call)
+Aria.open('websocket');
 
-## 📖 Core Concepts
+// Close the assistant
+Aria.close();
 
-### Dual-Mode Operation
+// Minimize to compact floating state
+Aria.minimize();
 
-#### User-Initiated Mode (Floating Button)
-```tsx
-// User clicks the floating button
-<AriaTriggerButton showAvatar={true} label="Chat with Aria" />
-```
+// Maximize from minimized state
+Aria.maximize();
 
-Opens in bottom-right corner with landscape video display.
+// Check status
+Aria.isInitialized();  // true/false
+Aria.isOpen();         // true/false
+Aria.isConnected();    // true/false
+Aria.getSessionId();   // string | null
 
-#### WebSocket-Triggered Mode (Center Modal)
-```tsx
-// Server sends trigger event
-{
-  "type": "trigger_event",
-  "data": {
-    "message": "Incoming call",
-    "caller": "John Doe"
-  }
-}
+// Cleanup (when removing from app)
+Aria.destroy();
 ```
 
-Automatically opens in center with large display.
-
-### Message Accumulation
+---
 
-The SDK automatically:
-- Sends message history to your backend via WebSocket
-- Tracks real-time message streams
-- Handles session end events
-- Supports auto-save for long sessions
-- Includes circuit breaker for API failures
+## Backend Requirements
 
-## 🎨 Components
+The SDK connects to your backend via WebSocket. Your backend is responsible for:
 
-### AriaProvider
+### 1. WebSocket Server
 
-Main provider component that wraps your application.
+Provide a WebSocket endpoint that the SDK connects to.
 
-```tsx
-<AriaProvider config={config}>
-  {children}
-</AriaProvider>
 ```
-
-### AriaAssistant
-
-Complete assistant component that includes both the floating trigger button and the assistant widget.
-
-```tsx
-<AriaAssistant 
-  showTrigger={true}      // Show floating trigger button (default: true)
-  showAvatar={true}       // Show avatar in trigger button (default: true)
-  triggerLabel="Chat"     // Optional custom label for trigger button
-/>
+wss://your-server.com/ws
 ```
 
-### AriaTriggerButton
-
-Floating trigger button for user-initiated mode.
+### 2. Session Token Generation
 
-```tsx
-<AriaTriggerButton 
-  showAvatar={true}
-  label="Talk to Aria"
-  variant="default"
-  size="default"
-/>
-```
+When a user connects, your backend should:
+1. Authenticate the user
+2. Call the Anam AI API to create a session
+3. Return the session token to the SDK
 
-### useAria Hook
+**Expected Response Format:**
 
-Access SDK state and methods from any component.
-
-```tsx
-import { useAria } from '@centive/aria-sdk';
-
-function MyComponent() {
-  const {
-    // UI State
-    isOpen,
-    isMinimized,           // True when widget is minimized (compact floating state)
-    isConnected,
-    isLoading,
-    displayMode,
-    triggerMode,
-    theme,
-    chatMessages,
-    liveTranscript,
-    isChatVisible,
-    isMuted,
-    error,
-    
-    // Tool Call State
-    toolCallState,         // { isActive: boolean, toolName: string | null, toolData: object | null }
-    
-    // Session State
-    sessionState,
-    sessionManagerStatus,  // 'idle' | 'connecting' | 'connected' | 'preloading' | 'ready' | 'refreshing' | 'error'
-    isSessionPreloaded,    // True when session token is ready
-    isSessionPaused,       // True when session is paused (widget closed with persistSession: true)
-    
-    // Actions
-    openAssistant,
-    closeAssistant,
-    minimizeAssistant,     // Minimize widget to compact floating state
-    maximizeAssistant,     // Restore widget from minimized state
-    toggleChat,
-    sendMessage,
-    toggleMute,
-    startSession,
-    stopSession,           // Ends session (ignores persistSession setting)
-    triggerSession,
-    refreshSession,        // Manually refresh the session
-    setVideoElement,
-    
-    // Utilities
-    getSessionId,
-    config,
-  } = useAria();
-  
-  // Use the methods and state
+```json
+{
+  "status": "success",
+  "message": "Session created successfully",
+  "session_data": {
+    "session_id": "sess_abc123",
+    "token": "eyJhbGciOiJIUzI1NiIs...",
+    "expires_at": "2026-01-23T12:00:00Z"
+  },
+  "time_taken": 1234
 }
 ```
 
-### 🔑 Token Utilities
-
-The SDK provides utilities to extract session IDs from tokens, supporting both JWT and opaque tokens.
-
-#### In React Components (via useAria hook)
-
-```tsx
-import { useAria } from '@centive/aria-sdk';
-
-function MyComponent() {
-  const { getSessionIdFromToken, sessionState } = useAria();
-  
-  // Get session ID from current state
-  const currentSessionId = getSessionIdFromToken();
-  
-  // Extract session ID from a stored token (e.g., JWT)
-  const storedToken = localStorage.getItem('token');
-  const sessionId = getSessionIdFromToken(storedToken);
-  
-  return <div>Session: {currentSessionId}</div>;
-}
-```
+### 3. Persona Configuration
 
-#### In External Code (non-React)
+**Important:** Persona configuration (avatar, voice, LLM, system prompt) is controlled by your backend, not the frontend. This provides:
 
-```tsx
-import { 
-  extractSessionIdFromToken,
-  isJWT,
-  decodeJWT,
-  getTokenInfo,
-  isTokenExpired
-} from '@centive/aria-sdk';
-
-// Check if token is a JWT
-if (isJWT(token)) {
-  // Extract session ID
-  const sessionId = extractSessionIdFromToken(token);
-  
-  // Get full token information
-  const tokenInfo = getTokenInfo(token);
-  console.log('Session ID:', tokenInfo.sessionId);
-  console.log('Expires:', tokenInfo.exp ? new Date(tokenInfo.exp * 1000) : 'N/A');
-  
-  // Check if expired
-  if (isTokenExpired(token)) {
-    console.log('Token expired, need to refresh');
-  }
-  
-  // Decode full payload
-  const payload = decodeJWT(token);
-  console.log('Payload:', payload);
-}
-```
+- **Security**: Frontend cannot manipulate AI behavior
+- **Flexibility**: Change personas based on user roles, context, or A/B testing
+- **Centralization**: Manage all configurations in one place
 
-**Supported JWT Claims** (checked in order):
-- `session_id`
-- `sessionId`
-- `sid`
-- `jti` (JWT ID)
-- `sub` (Subject)
+**Backend Example (Node.js):**
 
-**Note:** JWT decoding is done client-side without signature verification. Only use for extracting public information.
+```javascript
+const WebSocket = require('ws');
+const axios = require('axios');
 
-## ⚙️ Configuration
+const wss = new WebSocket.Server({ port: 8000 });
 
-### AriaSDKConfig
+wss.on('connection', (ws) => {
+  ws.on('message', async (message) => {
+    const data = JSON.parse(message);
+    
+    if (data.user_trigger !== undefined) {
+      // Create Anam session with persona config
+      const session = await createAnamSession(data.userId);
+      
+      ws.send(JSON.stringify({
+        status: 'success',
+        message: 'Session created',
+        session_data: {
+          session_id: session.id,
+          token: session.token,
+          expires_at: session.expiresAt,
+        },
+        time_taken: Date.now() - startTime,
+      }));
+    }
+  });
+});
 
-```typescript
-interface AriaSDKConfig {
-  websocketUrl: string;              // WebSocket server URL
-  userId?: string;                   // User ID for backend persona selection & message accumulation
-  theme?: 'light' | 'dark';          // Initial theme (default: 'light')
-  triggerLabel?: string;             // Button label text
-  
-  // Event callbacks
-  onError?: (error: Error) => void;
-  onSessionReady?: () => void;
-  onConnectionStateChange?: (connected: boolean) => void;
-  onWebSocketEvent?: (event: any) => void;
+async function createAnamSession(userId) {
+  // Get persona config based on user context
+  const personaConfig = getPersonaForUser(userId);
   
-  // Message accumulation callbacks
-  onMessageHistoryAck?: (messageCount: number) => void;
-  onMessageStreamAck?: () => void;
-  onSessionEndAck?: (savedCount: number) => void;
-  onSessionEndError?: (error: string, errorType: string) => void;
+  const response = await axios.post('https://api.anam.ai/v1/sessions', {
+    persona: personaConfig,
+  }, {
+    headers: { 'Authorization': `Bearer ${process.env.ANAM_API_KEY}` }
+  });
   
-  // Session preloading options (Global Session Management)
-  preloadSession?: boolean;          // Enable session preloading on mount (default: true)
-  sessionRefreshBuffer?: number;     // Minutes before expiry to refresh (default: 5)
-  onSessionPreloaded?: () => void;   // Callback when session is preloaded and ready
-  onSessionRefresh?: () => void;     // Callback when session is refreshed
-  onSessionRefreshError?: (error: Error) => void; // Callback when refresh fails
-  
-  // Session persistence options (Widget Toggle Persistence)
-  persistSession?: boolean;          // Keep session alive when widget closes (default: false)
-  keepWebSocketAlive?: boolean;      // Keep WebSocket connected when paused (default: true)
-  onSessionPaused?: () => void;      // Callback when session is paused (widget closed)
-  onSessionResumed?: () => void;     // Callback when session is resumed (widget reopened)
-  
-  // Rendering options
-  showFloatingButton?: boolean;      // Show the default floating button (default: true)
-  showAssistant?: boolean;           // Show the assistant widget (default: true)
+  return response.data;
 }
-```
-
-### Backend Persona Configuration
 
-**Persona configuration is now handled entirely by your backend server.** This provides:
-
-- **Security**: Frontend cannot manipulate AI behavior or system prompts
-- **Flexibility**: Dynamically select personas based on user roles, context, subscription tier, or A/B testing
-- **Centralization**: Manage all persona configurations in one secure location
-
-Your backend should configure personas when creating Anam sessions:
-
-```javascript
-// Backend example: Configure persona based on user context
-const getPersonaConfig = (userId, userRole) => {
+function getPersonaForUser(userId) {
   // Your business logic here
   return {
-    name: 'Aria - AI Assistant',
+    name: 'Aria',
     avatarId: 'your-avatar-id',
     voiceId: 'your-voice-id',
     llmId: 'your-llm-id',
     systemPrompt: 'You are Aria, a helpful AI assistant.',
   };
-};
-
-// Use this config when calling Anam AI API
-const personaConfig = getPersonaConfig(userId, userRole);
+}
 ```
 
-See `example-ws-server.js` for a complete implementation.
-
-## 🌐 WebSocket Events
-
-### Automatic Session Trigger (Backend → Frontend)
+### 4. WebSocket Message Types
 
-```json
-{
-  "status": "success",
-  "message": "Session created successfully",
-  "session_data": {
-    "session_id": "sess_abc123",
-    "token": "tok_xyz789",
-    "expires_at": "2025-12-30T12:00:00Z"
-  }
-}
-```
+**Frontend → Backend:**
 
-### Manual Session Trigger (Frontend → Backend)
+| Message | Description |
+|---------|-------------|
+| `{ user_trigger: true }` | User clicked trigger button |
+| `{ user_trigger: false }` | Auto-preload session |
+| `{ type: 'message_history', ... }` | Conversation history |
+| `{ type: 'session_end', ... }` | User ended session |
 
-```json
-{
-  "user_trigger": true
-}
-```
+**Backend → Frontend:**
 
-### Message History Event (Frontend → Backend)
+| Message | Description |
+|---------|-------------|
+| Session response | Token and session data |
+| `{ type: 'trigger_event', data: {...} }` | Open assistant in center mode |
+| Acknowledgments | Confirm message receipt |
 
-```json
-{
-  "type": "message_history",
-  "session_id": "sess_abc123",
-  "user_id": "user_123",
-  "messages": [
-    {
-      "role": "user",
-      "content": "Hello",
-      "timestamp": "2026-01-06T10:00:00Z"
-    },
-    {
-      "role": "persona",
-      "content": "Hi! How can I help?",
-      "timestamp": "2026-01-06T10:00:02Z"
-    }
-  ]
-}
-```
+### 5. Trigger Events (Optional)
 
-### Session End Event (Frontend → Backend)
+Send events from your backend to open the assistant automatically:
 
 ```json
 {
-  "type": "session_end",
-  "session_id": "sess_abc123",
-  "user_id": "user_123"
+  "type": "trigger_event",
+  "data": {
+    "message": "Incoming support request",
+    "caller": "John Doe",
+    "eventType": "support_call"
+  }
 }
 ```
 
-## 🔄 Session Management
-
-### Global Session Architecture
-
-The SDK uses a singleton pattern to maintain session state globally, ensuring:
-
-1. **Lazy Session Initialization** - When `AriaProvider` mounts, it automatically:
-   - Connects to WebSocket
-   - Requests a session token (token is ready)
-   - **Does NOT initialize Anam client yet** (lazy mode)
-
-2. **Greeting Plays on Open** - When users click the trigger button:
-   - Anam client initializes at this moment
-   - **Greeting plays exactly when user sees the widget**
-   - No missed greetings from preloading
-
-3. **Session Persistence** - During page navigation:
-   - Session survives component unmounts/remounts
-   - No reconnection needed when navigating between pages
-
-4. **Minimized Widget State** - When users click outside the widget:
-   - Widget minimizes to a compact floating state
-   - Session stays active (no interruption)
-   - Click to restore full widget
-
-### Provider Placement (Critical)
-
-**Correct:** Place at app root, above router:
-```tsx
-function App() {
-  return (
-    <AriaProvider config={config}>
-      <BrowserRouter>
-        <Routes>...</Routes>
-      </BrowserRouter>
-    </AriaProvider>
-  );
-}
-```
+---
 
-**Incorrect:** Inside route (session lost on navigation):
-```tsx
-function App() {
-  return (
-    <BrowserRouter>
-      <Routes>
-        <Route path="/" element={
-          <AriaProvider config={config}>  {/* Don't do this! */}
-            <Home />
-          </AriaProvider>
-        } />
-      </Routes>
-    </BrowserRouter>
-  );
-}
-```
+## What the SDK Handles Automatically
 
-> **Note:** Even if placed incorrectly, the SDK's singleton pattern provides a safety net to maintain session continuity.
+You don't need to manage any of these - the SDK handles them internally:
 
-### Minimized Widget State
+| Feature | How It Works |
+|---------|--------------|
+| **WebSocket Connection** | Connects on `init()`, maintains connection |
+| **Auto-Reconnect** | Exponential backoff (1s → 30s max), up to 10 attempts |
+| **Session Refresh** | Refreshes 5 minutes before expiry |
+| **Tab Visibility** | Only refreshes when tab is active |
+| **Session Persistence** | Survives page navigation, widget close/reopen |
+| **Error Recovery** | Automatic retries with backoff |
+| **UI Rendering** | Mounts trigger button and widget to DOM |
 
-When users click outside the widget (on the backdrop), the widget minimizes to a compact floating state instead of closing completely. This allows users to:
+---
 
-- Navigate the platform while keeping the session active
-- See a preview of the live transcript
-- Quickly resume the conversation with one click
+## Security Best Practices
 
-```tsx
-function WidgetController() {
-  const { 
-    isMinimized,
-    minimizeAssistant,
-    maximizeAssistant,
-    closeAssistant,
-  } = useAria();
-  
-  return (
-    <div>
-      <p>Minimized: {isMinimized ? 'Yes' : 'No'}</p>
-      
-      {/* Programmatic control */}
-      <button onClick={minimizeAssistant}>Minimize</button>
-      <button onClick={maximizeAssistant}>Maximize</button>
-      <button onClick={closeAssistant}>Close (End Session)</button>
-    </div>
-  );
-}
-```
+### Do
 
-**Behavior:**
-| Action | Result |
-|--------|--------|
-| Click outside widget (backdrop) | Widget minimizes, session stays active |
-| Click minimized widget | Widget maximizes |
-| Click "End Call" button | Session ends completely |
-| Click X on minimized widget | Session ends completely |
+- Use secure WebSocket connections (`wss://`) in production
+- Validate user IDs on your backend
+- Store Anam API keys only on the backend
+- Implement proper CORS configuration
+- Use environment variables for sensitive data
 
-### Tool Call Indicators
+### Don't
 
-When Aria executes tool calls (function calling), the widget displays a visual indicator showing:
-- The tool name being executed
-- An animated "processing" state
-- Auto-clears when the tool completes
+- Expose Anam API keys in frontend code
+- Trust user-provided data without validation
+- Allow arbitrary persona configuration from frontend
 
-```tsx
-function ToolCallMonitor() {
-  const { toolCallState } = useAria();
-  
-  return (
-    <div>
-      {toolCallState.isActive && (
-        <p>
-          Running tool: {toolCallState.toolName}
-          Data: {JSON.stringify(toolCallState.toolData)}
-        </p>
-      )}
-    </div>
-  );
-}
-```
+---
 
-### Session Persistence (Widget Toggle)
+## Legacy React Provider API
 
-By default, the SDK ends the session when the widget is closed. With `persistSession: true`, the session stays alive across widget open/close cycles:
+For existing applications using the Provider pattern, it's still supported but deprecated:
 
 ```tsx
-const config = {
-  websocketUrl: 'ws://localhost:8000/ws',
-  userId: 'user_123',
-  
-  // Enable session persistence
-  persistSession: true,              // Keep session alive when widget closes
-  keepWebSocketAlive: true,          // Keep WebSocket connected (default: true)
-  
-  // Callbacks
-  onSessionPaused: () => {
-    console.log('Session paused - widget closed');
-  },
-  onSessionResumed: () => {
-    console.log('Session resumed - widget reopened');
-  },
-};
-```
+// Deprecated - will be removed in v2.0
+import { AriaProvider } from '@centive/aria-sdk';
 
-**Behavior with `persistSession: true`:**
-
-| Action | Result |
-|--------|--------|
-| User opens widget | Uses existing session (or creates new if none) |
-| User closes widget | Session paused, stays alive |
-| User reopens widget | Session resumed instantly |
-| User calls `stopSession()` | Session ends (explicit action) |
-| Tab/window closes | Session ends (beforeunload) |
-| Session token expires | New session created on next open |
-
-**Use Cases:**
-- Customer support chat - User minimizes to browse, reopens to continue
-- Sales assistant - Persistent context across multiple page views
-- Onboarding flow - AI maintains context as user navigates steps
-- Dashboard help - Toggle help widget without losing conversation
-
-```tsx
-function SessionController() {
-  const { 
-    isSessionPaused,
-    stopSession,
-  } = useAria();
-  
+function App() {
   return (
-    <div>
-      <p>Session paused: {isSessionPaused ? 'Yes' : 'No'}</p>
-      
-      {/* Explicitly end session (ignores persistSession) */}
-      <button onClick={stopSession}>
-        End Session
-      </button>
-    </div>
+    <AriaProvider config={{
+      websocketUrl: 'ws://localhost:8000/ws',
+      userId: 'user_123',
+    }}>
+      <YourApp />
+    </AriaProvider>
   );
 }
 ```
 
-### Session Refresh
-
-The SDK automatically refreshes sessions before they expire:
+**Migration:** Replace `AriaProvider` with `Aria.init()` for simpler integration.
 
-```tsx
-const config = {
-  websocketUrl: 'ws://localhost:8000/ws',
-  userId: 'user_123',
-  
-  // Session refresh configuration
-  sessionRefreshBuffer: 5, // Refresh 5 minutes before expiry (default)
-  
-  // Callbacks
-  onSessionPreloaded: () => {
-    console.log('Session is preloaded and ready!');
-  },
-  onSessionRefresh: () => {
-    console.log('Session refreshed successfully');
-  },
-  onSessionRefreshError: (error) => {
-    console.error('Session refresh failed:', error);
-  },
-};
-```
+---
 
-### Manual Session Control
+## Browser Support
 
-```tsx
-function SessionController() {
-  const { 
-    sessionState,
-    sessionManagerStatus,
-    isSessionPreloaded,
-    refreshSession,
-  } = useAria();
-  
-  return (
-    <div>
-      <p>Status: {sessionManagerStatus}</p>
-      <p>Preloaded: {isSessionPreloaded ? 'Yes' : 'No'}</p>
-      <p>Session ID: {sessionState.session_id}</p>
-      <p>Expires: {sessionState.expires_at}</p>
-      
-      {/* Manual refresh if needed */}
-      <button onClick={refreshSession}>
-        Refresh Session
-      </button>
-    </div>
-  );
-}
-```
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Opera (latest)
 
-## 💡 Advanced Usage
+Requires WebRTC support for video streaming.
 
-### Programmatic Control
+---
 
-```tsx
-function CustomController() {
-  const { 
-    openAssistant, 
-    closeAssistant, 
-    minimizeAssistant,
-    maximizeAssistant,
-    triggerSession,
-    isMinimized,
-  } = useAria();
-  
-  return (
-    <div>
-      {/* Open in user mode */}
-      <button onClick={() => openAssistant('user')}>
-        Start Chat
-      </button>
-      
-      {/* Open in center mode */}
-      <button onClick={() => openAssistant('websocket')}>
-        Start Video Call
-      </button>
-      
-      {/* Minimize/Maximize widget */}
-      <button onClick={isMinimized ? maximizeAssistant : minimizeAssistant}>
-        {isMinimized ? 'Maximize' : 'Minimize'}
-      </button>
-      
-      {/* Close widget (ends session) */}
-      <button onClick={closeAssistant}>
-        End Session
-      </button>
-      
-      {/* Manually trigger session */}
-      <button onClick={triggerSession}>
-        Create New Session
-      </button>
-    </div>
-  );
-}
-```
+## Troubleshooting
 
-### Custom Event Handling
+### "WebSocket connection failed"
 
-```tsx
-// Note: Persona configuration is handled by the backend
-const config = {
-  websocketUrl: 'ws://localhost:8000/ws',
-  userId: 'user_123', // Backend uses this for persona selection
-  
-  onWebSocketEvent: (event) => {
-    if (event.data.eventType === 'incoming_call') {
-      showNotification(`Call from ${event.data.caller}`);
-      playRingtone();
-    }
-  },
-  
-  onSessionReady: () => {
-    console.log('AI assistant is ready!');
-  },
-  
-  onError: (error) => {
-    captureError(error);
-  },
-  
-  // Message accumulation callbacks
-  onMessageHistoryAck: (messageCount) => {
-    console.log(`Conversation saved: ${messageCount} messages`);
-    updateUI({ messagesSaved: true });
-  },
-  
-  onSessionEndAck: (savedCount) => {
-    console.log(`Session completed: ${savedCount} messages persisted`);
-    showSuccessNotification('Conversation saved successfully');
-  },
-  
-  onSessionEndError: (error, errorType) => {
-    console.error(`Failed to save: ${errorType}`, error);
-    if (errorType === 'CIRCUIT_BREAKER_OPEN') {
-      showWarning('Saving temporarily unavailable, will retry automatically');
-    } else {
-      showError('Failed to save conversation');
-    }
-  },
-};
-```
+- Check that your backend WebSocket server is running
+- Verify the `websocketUrl` is correct
+- Check browser console for CORS errors
 
-### Access Session State
+### "Session token expired"
 
-```tsx
-function SessionMonitor() {
-  const { sessionState } = useAria();
-  
-  return (
-    <div>
-      <p>Session ID: {sessionState.session_id}</p>
-      <p>Expires: {sessionState.expires_at}</p>
-      <p>Ready: {sessionState.isSessionReady ? 'Yes' : 'No'}</p>
-      {sessionState.lastError && <p>Error: {sessionState.lastError}</p>}
-    </div>
-  );
-}
-```
+- The SDK auto-refreshes tokens, but if you see this:
+  - Check your backend is returning valid `expires_at` timestamps
+  - Ensure your Anam API key is valid
 
-## 🎯 Use Cases
+### "Not initialized" errors
 
-- **Customer Support** - Floating help button + proactive agent-initiated conversations
-- **Healthcare** - Patient consultations + appointment reminders
-- **Financial Services** - Account questions + market alert notifications  
-- **E-commerce** - Product inquiries + order status updates
-- **Education** - Student support + class notifications
-- **Sales** - Lead qualification + follow-up calls
+- Call `Aria.init()` before using other methods
+- Check that `init()` completed without errors
 
-## 📋 Requirements
+### UI not appearing
 
-- React 18.0.0 or higher
-- React DOM 18.0.0 or higher
-- Node.js 18+ (for backend server)
-- Modern browser with WebRTC support
-- Anam AI API key ([Get one here](https://docs.anam.ai/get-your-api-key))
+- Ensure you're not blocking the SDK's DOM elements with CSS
+- Check browser console for React rendering errors
 
-## 🌍 Browser Support
+---
 
-- Chrome/Edge (latest)
-- Firefox (latest)
-- Safari (latest)
-- Opera (latest)
+## API Reference
 
-## 🔒 Security Best Practices
+### Aria (Static Class)
 
-- Never expose your Anam API key in frontend code
-- Use secure WebSocket connections (WSS) in production
-- Implement proper CORS configuration
-- Validate user IDs on the backend
-- Use environment variables for sensitive data
+| Method | Description |
+|--------|-------------|
+| `init(config)` | Initialize the SDK |
+| `destroy()` | Cleanup and remove SDK |
+| `open(mode?)` | Open assistant widget |
+| `close()` | Close assistant widget |
+| `minimize()` | Minimize to compact state |
+| `maximize()` | Restore from minimized |
+| `isInitialized()` | Check if SDK is initialized |
+| `isOpen()` | Check if widget is open |
+| `isConnected()` | Check WebSocket connection |
+| `getSessionId()` | Get current session ID |
+| `refreshSession()` | Manually refresh session |
 
-## 📚 Documentation
+---
 
-For more detailed documentation, see:
-- [Type Reference](./TYPE_REFERENCE.md) - Complete TypeScript type reference
-- [WebSocket Events Guide](./WEBSOCKET_EVENTS.md) - Complete WebSocket message specification
-- [WebSocket Guide](./WEBSOCKET_GUIDE.md) - WebSocket integration details
-- [Publishing Guide](./PUBLISHING_GUIDE.md) - npm publishing instructions  
-- [Setup Summary](./SETUP_SUMMARY.md) - Complete setup overview
+## Documentation
 
-## 🤝 Contributing
+- [Type Reference](./TYPE_REFERENCE.md) - Complete TypeScript types
+- [WebSocket Events](./WEBSOCKET_EVENTS.md) - Message specifications
+- [Anam AI Docs](https://docs.anam.ai/) - Anam AI platform documentation
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+---
 
-## 📄 License
+## License
 
 MIT © Centive
 
-## 🆘 Support
-
-- 📚 [Anam AI Documentation](https://docs.anam.ai/)
-- 🐛 [GitHub Issues](https://github.com/centive/aria-sdk/issues)
-
-## 🙏 Acknowledgments
-
-Built with:
-- [Anam AI](https://anam.ai/) - AI persona platform
-- [Shad/CN UI](https://ui.shadcn.com/) - UI components
-- [Tailwind CSS](https://tailwindcss.com/) - Styling
-- [Lucide Icons](https://lucide.dev/) - Icons
-- [React](https://react.dev/) - UI framework
-
 ---
 
-**Made with ❤️ by Centive**
+## Support
+
+- [GitHub Issues](https://github.com/centive/aria-sdk/issues)
+- [Anam AI Documentation](https://docs.anam.ai/)