@convai/web-sdk 0.1.1-beta.5 → 0.2.0

package/README.md

@@ -1,332 +1,840 @@
 # @convai/web-sdk
 
-JavaScript/TypeScript SDK for Convai AI voice assistants. Build voice-powered AI interactions for web applications with real-time audio/video streaming. Supports both **React** and **Vanilla JS/TS**.
+JavaScript/TypeScript SDK for Convai AI voice assistants. Build voice-powered AI interactions for web applications with real-time audio/video streaming. Supports both React and Vanilla JavaScript/TypeScript.
 
-## 🌟 Features
-
-- **React & Vanilla Support**: Use with React or any JavaScript framework (or none!)
-- **Tree-Shakeable**: Import only what you need for optimal bundle size
-- **Voice & Video**: Real-time audio/video conversations with AI characters
-- **Screen Sharing**: Share your screen with the AI assistant
-- **TypeScript**: Fully typed for excellent developer experience
-- **WebRTC Powered**: Built on LiveKit for robust real-time communication
-- **Customizable UI**: Pre-built widgets or build your own
-- **Framework Agnostic Core**: Use the core client with any framework
-
-##  Installation
+## Installation
 
 ```bash
 npm install @convai/web-sdk
 ```
 
-##  Quick Start
+## Basic Setup
 
 ### React
 
 ```tsx
-import { useConvaiClient, ConvaiWidget } from '@convai/web-sdk';
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk";
 
 function App() {
   const convaiClient = useConvaiClient({
-    apiKey: 'your-api-key',
-    characterId: 'your-character-id',
-    // endUserId: 'user-uuid', // Optional: enables memory & analytics
-    enableVideo: true
+    apiKey: "your-api-key",
+    characterId: "your-character-id",
   });
 
   return <ConvaiWidget convaiClient={convaiClient} />;
 }
 ```
 
-[**→ Full React Guide**](./docs/REACT_USAGE.md)
-
-### Vanilla JavaScript/TypeScript
+### Vanilla TypeScript
 
 ```typescript
-import { ConvaiClient, createConvaiWidget } from '@convai/web-sdk/vanilla';
+import { ConvaiClient, createConvaiWidget } from "@convai/web-sdk/vanilla";
 
-// Create client with config (same pattern as React)
+// Create client with configuration
 const client = new ConvaiClient({
-  apiKey: 'your-api-key',
-  characterId: 'your-character-id',
-  // endUserId: 'user-uuid' // Optional: enables memory & analytics
-  enableVideo: true,
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
 });
 
-// Create widget - auto-connects on first click
+// Create widget - auto-connects on first user click
 const widget = createConvaiWidget(document.body, {
   convaiClient: client,
-  showVideo: true,
-  showScreenShare: true
 });
 
-// Listen for events
-client.on('stateChange', (state) => {
-  console.log('State:', state.agentState);
-});
+// Cleanup when done
+widget.destroy();
+```
 
-// Send messages
-client.sendUserTextMessage('Hello!');
+## Exports
 
-// Cleanup
-widget.destroy();
+### React Exports (`@convai/web-sdk` or `@convai/web-sdk/react`)
+
+**Components:**
+
+- `ConvaiWidget` - Main chat widget component
+
+**Hooks:**
+
+- `useConvaiClient(config?)` - Main client hook
+- `useCharacterInfo(characterId, apiKey)` - Fetch character metadata
+- `useLocalCameraTrack()` - Get local camera track
+
+**Core Client:**
+
+- `ConvaiClient` - Core client class
+
+**Types:**
+
+- `ConvaiConfig` - Configuration interface
+- `ConvaiClientState` - Client state interface
+- `ChatMessage` - Message interface
+- `IConvaiClient` - Client interface
+- `AudioControls` - Audio control interface
+- `VideoControls` - Video control interface
+- `ScreenShareControls` - Screen share control interface
+
+**Components:**
+
+- `AudioRenderer` - Audio playback component
+- `AudioContext` - Audio context provider
+
+### Vanilla Exports (`@convai/web-sdk/vanilla`)
+
+**Functions:**
+
+- `createConvaiWidget(container, options)` - Create widget instance
+- `destroyConvaiWidget(widget)` - Destroy widget instance
+
+**Classes:**
+
+- `ConvaiClient` - Core client class
+- `AudioRenderer` - Audio playback handler
+
+**Types:**
+
+- `VanillaWidget` - Widget instance interface
+- `VanillaWidgetOptions` - Widget options interface
+- `IConvaiClient` - Client interface
+- `ConvaiConfig` - Configuration interface
+- `ConvaiClientState` - Client state interface
+- `ChatMessage` - Message interface
+
+### Core Exports (`@convai/web-sdk/core`)
+
+**Classes:**
+
+- `ConvaiClient` - Main client class
+- `AudioManager` - Audio management
+- `VideoManager` - Video management
+- `ScreenShareManager` - Screen share management
+- `MessageHandler` - Message handling
+- `EventEmitter` - Event emitter base class
+
+**Types:**
+
+- All types from React/Vanilla exports
+- `ConvaiClientType` - Type alias for ConvaiClient
+
+## Props and Configuration
+
+### ConvaiWidget Props (React)
+
+```tsx
+interface ConvaiWidgetProps {
+  /** Convai client instance (required) */
+  convaiClient: IConvaiClient & {
+    activity?: string;
+    isAudioMuted: boolean;
+    isVideoEnabled: boolean;
+    isScreenShareActive: boolean;
+  };
+  /** Show video toggle button in settings (default: true) */
+  showVideo?: boolean;
+  /** Show screen share toggle button in settings (default: true) */
+  showScreenShare?: boolean;
+}
 ```
 
-[**→ Full Vanilla Guide**](./docs/VANILLA_USAGE.md)
+### createConvaiWidget Options (Vanilla)
 
-### Core Only (Framework Agnostic)
+```typescript
+interface VanillaWidgetOptions {
+  /** Convai client instance (required) */
+  convaiClient: IConvaiClient & {
+    activity?: string;
+    chatMessages: ChatMessage[];
+  };
+  /** Show video toggle button in settings (default: true) */
+  showVideo?: boolean;
+  /** Show screen share toggle button in settings (default: true) */
+  showScreenShare?: boolean;
+}
+```
 
-For custom framework integrations:
+### ConvaiConfig
 
 ```typescript
-import { ConvaiClient } from '@convai/web-sdk/core';
+interface ConvaiConfig {
+  /** Your Convai API key from convai.com dashboard (required) */
+  apiKey: string;
+  /** The Character ID to connect to (required) */
+  characterId: string;
+  /**
+   * End user identifier for speaker management (optional).
+   * When provided: enables long-term memory and analytics
+   * When not provided: anonymous mode, no persistent memory
+   */
+  endUserId?: string;
+  /** Custom Convai API URL (optional, defaults to production endpoint) */
+  url?: string;
+  /**
+   * Enable video capability (default: false).
+   * If true, connection_type will be "video" (supports audio, video, and screenshare).
+   * If false, connection_type will be "audio" (audio only).
+   */
+  enableVideo?: boolean;
+  /**
+   * Start with video camera on when connecting (default: false).
+   * Only works if enableVideo is true.
+   */
+  startWithVideoOn?: boolean;
+  /**
+   * Start with microphone on when connecting (default: false).
+   * If false, microphone stays off until user enables it.
+   */
+  startWithAudioOn?: boolean;
+  /** Enable text-to-speech audio generation (default: true) */
+  ttsEnabled?: boolean;
+}
+```
 
-const client = new ConvaiClient();
+## Features
 
-// Listen for events
-client.on('stateChange', (state) => {
-  console.log('State:', state.agentState);
-});
+### Video Enabled Chat
 
-client.on('message', (message) => {
-  console.log('New message:', message.content);
-});
+To enable video capabilities, set `enableVideo: true` in your configuration. This enables audio, video, and screen sharing.
 
-// Connect
-await client.connect({
-  apiKey: 'your-api-key',
-  characterId: 'your-character-id',
-  // endUserId: 'user-uuid' // Optional: enables memory & analytics
-});
+**React:**
 
-// Send message
-client.sendUserTextMessage('Hello!');
+```tsx
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk";
+
+function App() {
+  const convaiClient = useConvaiClient({
+    apiKey: "your-api-key",
+    characterId: "your-character-id",
+    enableVideo: true,
+    startWithVideoOn: false, // Camera off by default
+  });
+
+  return (
+    <ConvaiWidget
+      convaiClient={convaiClient}
+      showVideo={true}
+      showScreenShare={true}
+    />
+  );
+}
 ```
 
-## 📖 Documentation
+**Vanilla:**
 
-- [**React Usage Guide**](./docs/REACT_USAGE.md) - Hooks, components, and React integration
-- [**Vanilla Usage Guide**](./docs/VANILLA_USAGE.md) - Vanilla JS/TS integration without React
-- [**API Reference**](./API_REFERENCE.md) - Complete API documentation
+```typescript
+import { ConvaiClient, createConvaiWidget } from "@convai/web-sdk/vanilla";
 
-##  Import Options
+const client = new ConvaiClient({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
+  enableVideo: true,
+  startWithVideoOn: false,
+});
 
-The SDK supports multiple import paths for tree-shaking:
+const widget = createConvaiWidget(document.body, {
+  convaiClient: client,
+  showVideo: true,
+  showScreenShare: true,
+});
+```
+
+**Manual Video Controls:**
 
 ```typescript
-// Default: React version (backward compatible)
-import { useConvaiClient, ConvaiWidget } from '@convai/web-sdk';
+// Enable video camera
+await convaiClient.videoControls.enableVideo();
 
-// Explicit React import
-import { useConvaiClient, ConvaiWidget } from '@convai/web-sdk/react';
+// Disable video camera
+await convaiClient.videoControls.disableVideo();
 
-// Vanilla JS/TS (with UI widget)
-import { ConvaiClient, createConvaiWidget } from '@convai/web-sdk/vanilla';
+// Toggle video
+await convaiClient.videoControls.toggleVideo();
 
-// Core only (no UI, framework agnostic)
-import { ConvaiClient } from '@convai/web-sdk/core';
+// Check video state
+const isVideoEnabled = convaiClient.videoControls.isVideoEnabled;
+
+// Set video quality
+await convaiClient.videoControls.setVideoQuality("high"); // 'low' | 'medium' | 'high'
+
+// Get available video devices
+const devices = await convaiClient.videoControls.getVideoDevices();
+
+// Set specific video device
+await convaiClient.videoControls.setVideoDevice(deviceId);
 ```
 
-## 🔑 Get Convai Credentials
+**Screen Sharing:**
 
-1. Visit [convai.com](https://convai.com) and create an account
-2. Navigate to your dashboard
-3. Create a new character or use an existing one
-4. Copy your **API Key** from the dashboard
-5. Copy your **Character ID** from the character details
+```typescript
+// Enable screen share
+await convaiClient.screenShareControls.enableScreenShare();
 
-## Core Features
+// Enable screen share with audio
+await convaiClient.screenShareControls.enableScreenShareWithAudio();
 
-### Connection Management
+// Disable screen share
+await convaiClient.screenShareControls.disableScreenShare();
+
+// Toggle screen share
+await convaiClient.screenShareControls.toggleScreenShare();
+
+// Check screen share state
+const isActive = convaiClient.screenShareControls.isScreenShareActive;
+```
+
+**Video State Monitoring:**
 
 ```typescript
-// Connect
-await client.connect(config);
+// React
+const { isVideoEnabled } = convaiClient;
+
+// Core API (event-based)
+convaiClient.videoControls.on("videoStateChange", (state) => {
+  console.log("Video enabled:", state.isVideoEnabled);
+  console.log("Video hidden:", state.isVideoHidden);
+});
+```
 
-// Disconnect
-await client.disconnect();
+### Interruption
 
-// Reset session (clear history)
-client.resetSession();
+Interrupt the character's current response to allow the user to speak immediately.
 
-// Reconnect
-await client.reconnect();
+**React:**
+
+```tsx
+function ChatInterface() {
+  const convaiClient = useConvaiClient({
+    /* config */
+  });
+
+  const handleInterrupt = () => {
+    // Interrupt the bot's current response
+    convaiClient.sendInterruptMessage();
+  };
+
+  return <button onClick={handleInterrupt}>Interrupt</button>;
+}
 ```
 
-### Messaging
+**Vanilla:**
 
 ```typescript
-// Send text message
-client.sendUserTextMessage('Hello!');
+const interruptButton = document.getElementById("interrupt-btn");
+
+interruptButton.addEventListener("click", () => {
+  client.sendInterruptMessage();
+});
+```
+
+**Voice Mode Interruption Pattern:**
+
+When implementing voice mode, interrupt the bot when the user starts speaking:
+
+```typescript
+// When user enters voice mode
+const enterVoiceMode = async () => {
+  // Interrupt any ongoing bot response
+  convaiClient.sendInterruptMessage();
+
+  // Unmute microphone
+  await convaiClient.audioControls.unmuteAudio();
+};
+
+// When user exits voice mode
+const exitVoiceMode = async () => {
+  // Interrupt any ongoing bot response
+  convaiClient.sendInterruptMessage();
+
+  // Mute microphone
+  await convaiClient.audioControls.muteAudio();
+};
+```
 
-// Send trigger for specific actions
-client.sendTriggerMessage('greet', 'User entered room');
+### User Microphone Mute/Unmute
 
-// Update context
-client.updateTemplateKeys({ user_name: 'John' });
-client.updateDynamicInfo({ text: 'User is happy' });
+Control the user's microphone input.
+
+**React:**
+
+```tsx
+function AudioControls() {
+  const convaiClient = useConvaiClient({
+    /* config */
+  });
+
+  const handleMute = async () => {
+    await convaiClient.audioControls.muteAudio();
+  };
+
+  const handleUnmute = async () => {
+    await convaiClient.audioControls.unmuteAudio();
+  };
+
+  const handleToggle = async () => {
+    await convaiClient.audioControls.toggleAudio();
+  };
+
+  return (
+    <div>
+      <button onClick={handleMute}>Mute</button>
+      <button onClick={handleUnmute}>Unmute</button>
+      <button onClick={handleToggle}>Toggle</button>
+      <p>Muted: {convaiClient.audioControls.isAudioMuted ? "Yes" : "No"}</p>
+    </div>
+  );
+}
 ```
 
-### Media Controls
+**Vanilla:**
 
 ```typescript
-// Audio (always available)
-await client.audioControls.toggleAudio();
+// Mute microphone
 await client.audioControls.muteAudio();
+
+// Unmute microphone
 await client.audioControls.unmuteAudio();
 
-// Video (if enableVideo: true)
-await client.videoControls.toggleVideo();
-await client.videoControls.enableVideo();
-await client.videoControls.disableVideo();
+// Toggle mute state
+await client.audioControls.toggleAudio();
+
+// Check mute state
+const isMuted = client.audioControls.isAudioMuted;
+
+// Enable audio (request permissions if needed)
+await client.audioControls.enableAudio();
 
-// Screen Share (if enableVideo: true)
-await client.screenShareControls.toggleScreenShare();
+// Disable audio
+await client.audioControls.disableAudio();
 ```
 
-### State Monitoring
+**Audio Device Management:**
+
+```typescript
+// Get available audio devices
+const devices = await convaiClient.audioControls.getAudioDevices();
+
+// Set specific audio device
+await convaiClient.audioControls.setAudioDevice(deviceId);
+
+// Monitor audio level
+convaiClient.audioControls.startAudioLevelMonitoring();
+
+convaiClient.audioControls.on("audioLevelChange", (level) => {
+  console.log("Audio level:", level);
+  // level is a number between 0 and 1
+});
+
+convaiClient.audioControls.stopAudioLevelMonitoring();
+```
+
+**Audio State Monitoring:**
 
 ```typescript
 // React
-const { state, chatMessages, userTranscription } = convaiClient;
+const { isAudioMuted } = convaiClient;
 
 // Core API (event-based)
-client.on('stateChange', (state) => {
-  console.log(state.agentState); // 'listening' | 'thinking' | 'speaking'
+convaiClient.audioControls.on("audioStateChange", (state) => {
+  console.log("Audio enabled:", state.isAudioEnabled);
+  console.log("Audio muted:", state.isAudioMuted);
+  console.log("Audio level:", state.audioLevel);
 });
+```
+
+### Character TTS Mute/Unmute
+
+Control whether the character's responses are spoken aloud (text-to-speech).
 
-client.on('message', (message) => {
-  console.log('New message:', message);
+**React:**
+
+```tsx
+function TTSControls() {
+  const convaiClient = useConvaiClient({
+    /* config */
+  });
+
+  const handleToggleTTS = (enabled: boolean) => {
+    convaiClient.toggleTts(enabled);
+  };
+
+  return (
+    <div>
+      <button onClick={() => handleToggleTTS(true)}>Enable TTS</button>
+      <button onClick={() => handleToggleTTS(false)}>Disable TTS</button>
+    </div>
+  );
+}
+```
+
+**Vanilla:**
+
+```typescript
+// Enable text-to-speech (character will speak responses)
+client.toggleTts(true);
+
+// Disable text-to-speech (character will only send text, no audio)
+client.toggleTts(false);
+```
+
+**Initial TTS Configuration:**
+
+```typescript
+// Set TTS state during connection
+const client = new ConvaiClient({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
+  ttsEnabled: true, // Enable TTS by default
+});
+
+// Or disable initially
+const client = new ConvaiClient({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
+  ttsEnabled: false, // Disable TTS
 });
 ```
 
-## 🎨 UI Components
+### Voice Mode Implementation
 
-### Pre-built Widget
+Voice mode allows users to speak instead of typing. The widget automatically handles voice mode, but you can implement it manually.
 
-React version includes a complete chat widget:
+**React - Manual Voice Mode:**
 
-- Expandable circular button
-- Chat interface with message history
-- Voice/text input modes
-- Video controls (when enabled)
-- Screen sharing (when enabled)
-- Auto-connects on first interaction
+```tsx
+import { useConvaiClient } from "@convai/web-sdk";
+import { useState, useEffect } from "react";
 
-### Custom UI
+function CustomChatInterface() {
+  const convaiClient = useConvaiClient({
+    /* config */
+  });
+  const [isVoiceMode, setIsVoiceMode] = useState(false);
 
-Build your own UI using the client API. The client handles all the AI logic while you control the presentation.
+  const enterVoiceMode = async () => {
+    // Interrupt any ongoing bot response
+    convaiClient.sendInterruptMessage();
 
-##  Message Types
+    // Unmute microphone
+    await convaiClient.audioControls.unmuteAudio();
 
-The SDK handles various message types:
+    setIsVoiceMode(true);
+  };
 
-- `user-transcription` - Real-time speech-to-text
-- `bot-llm-text` - AI character responses
-- `bot-emotion` - Character emotional states
-- `action` - Action executions
-- `behavior-tree` - Behavior responses
+  const exitVoiceMode = async () => {
+    // Interrupt any ongoing bot response
+    convaiClient.sendInterruptMessage();
 
-## 🔧 Configuration
+    // Mute microphone
+    await convaiClient.audioControls.muteAudio();
 
-```typescript
-interface ConvaiConfig {
-  apiKey: string;              // Required
-  characterId: string;         // Required
-  endUserId?: string;          // Optional: unique ID for memory & analytics
-  url?: string;                // Optional: API URL
-  enableVideo?: boolean;       // Optional: Enable video (default: false)
-  startWithVideoOn?: boolean;  // Optional: Start with camera on
-  ttsEnabled?: boolean;        // Optional: Enable TTS (default: true)
-  actionConfig?: {             // Optional: Actions & context
-    actions: string[];
-    characters: Array<{ name: string; bio: string }>;
-    objects: Array<{ name: string; description: string }>;
+    setIsVoiceMode(false);
   };
+
+  // Monitor user transcription for voice input
+  useEffect(() => {
+    const transcription = convaiClient.userTranscription;
+    if (transcription && isVoiceMode) {
+      // Display real-time transcription
+      console.log("User is saying:", transcription);
+    }
+  }, [convaiClient.userTranscription, isVoiceMode]);
+
+  return (
+    <div>
+      {isVoiceMode ? (
+        <div>
+          <p>Listening: {convaiClient.userTranscription}</p>
+          <button onClick={exitVoiceMode}>Stop Voice Mode</button>
+        </div>
+      ) : (
+        <button onClick={enterVoiceMode}>Start Voice Mode</button>
+      )}
+    </div>
+  );
 }
 ```
 
-### About endUserId
+**Vanilla - Manual Voice Mode:**
+
+```typescript
+let isVoiceMode = false;
+
+const enterVoiceMode = async () => {
+  // Interrupt any ongoing bot response
+  client.sendInterruptMessage();
 
-The `endUserId` parameter is **optional** and serves two important purposes:
+  // Unmute microphone
+  await client.audioControls.unmuteAudio();
 
-1. **Long-term Memory**: When provided, the character remembers context from previous conversations with this user, enabling personalized and continuous interactions across sessions.
+  isVoiceMode = true;
+  updateUI();
+};
 
-2. **Analytics & Tracking**: Track user engagement, behavior patterns, and conversation metrics for your application.
+const exitVoiceMode = async () => {
+  // Interrupt any ongoing bot response
+  client.sendInterruptMessage();
 
-**Usage:**
-- **With endUserId**: Pass a unique identifier (UUID, device ID, or user ID) to enable persistent memory and analytics
-- **Without endUserId**: Anonymous mode - each session is independent with no conversation history or tracking
+  // Mute microphone
+  await client.audioControls.muteAudio();
+
+  isVoiceMode = false;
+  updateUI();
+};
+
+// Monitor user transcription
+client.on("userTranscriptionChange", (transcription) => {
+  if (isVoiceMode && transcription) {
+    // Display real-time transcription
+    document.getElementById("transcription").textContent = transcription;
+  }
+});
+
+function updateUI() {
+  const voiceButton = document.getElementById("voice-btn");
+  const transcriptionDiv = document.getElementById("transcription");
+
+  if (isVoiceMode) {
+    voiceButton.textContent = "Stop Voice Mode";
+    transcriptionDiv.style.display = "block";
+  } else {
+    voiceButton.textContent = "Start Voice Mode";
+    transcriptionDiv.style.display = "none";
+  }
+}
+```
+
+**Voice Mode with State Monitoring:**
 
 ```typescript
-// With persistent memory and analytics
-await client.connect({
-  apiKey: 'your-api-key',
-  characterId: 'your-character-id',
-  endUserId: 'user-12345' // User will be remembered
+// Monitor agent state to handle voice mode transitions
+convaiClient.on("stateChange", (state) => {
+  if (isVoiceMode) {
+    switch (state.agentState) {
+      case "listening":
+        // User can speak
+        console.log("Bot is listening");
+        break;
+      case "thinking":
+        // Bot is processing
+        console.log("Bot is thinking");
+        break;
+      case "speaking":
+        // Bot is responding
+        console.log("Bot is speaking");
+        // Optionally interrupt if user wants to speak
+        break;
+    }
+  }
+});
+```
+
+### Connection Management
+
+**Connect:**
+
+```typescript
+// React - config passed to hook
+const convaiClient = useConvaiClient({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
+});
+
+// Or connect manually
+await convaiClient.connect({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
 });
 
-// Anonymous mode (no memory, no tracking)
+// Vanilla
+const client = new ConvaiClient();
 await client.connect({
-  apiKey: 'your-api-key',
-  characterId: 'your-character-id'
-  // No endUserId = anonymous
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
 });
 ```
 
-##  Browser Support
+**Disconnect:**
 
-- Chrome/Edge:  Full support
-- Firefox:  Full support
-- Safari:  Full support
-- Mobile browsers:  Supported
+```typescript
+await convaiClient.disconnect();
+```
 
-##  Package Structure
+**Reconnect:**
 
+```typescript
+await convaiClient.reconnect();
 ```
-@convai/web-sdk
-├── /core       # Framework-agnostic core (ConvaiClient)
-├── /react      # React hooks and components
-└── (default)   # React (backward compatible)
+
+**Reset Session:**
+
+```typescript
+// Clear conversation history and start new session
+convaiClient.resetSession();
 ```
 
-## 🔄 Migration from Previous Versions
+**Connection State:**
 
-### Backward Compatible
+```typescript
+// React
+const { state } = convaiClient;
+console.log("Connected:", state.isConnected);
+console.log("Connecting:", state.isConnecting);
+console.log("Agent state:", state.agentState); // 'disconnected' | 'connected' | 'listening' | 'thinking' | 'speaking'
 
-No breaking changes! Existing code continues to work:
+// Core API (event-based)
+convaiClient.on("stateChange", (state) => {
+  console.log("State changed:", state);
+});
 
-```tsx
-//  Still works
-import { useConvaiClient, ConvaiWidget } from '@convai/web-sdk';
+convaiClient.on("connect", () => {
+  console.log("Connected");
+});
+
+convaiClient.on("disconnect", () => {
+  console.log("Disconnected");
+});
 ```
 
-### New Features Available
+### Messaging
 
-```tsx
-//  New: Explicit React import
-import { useConvaiClient } from '@convai/web-sdk/react';
+**Send Text Message:**
 
-//  New: Core-only for custom frameworks
-import { ConvaiClient } from '@convai/web-sdk/core';
+```typescript
+convaiClient.sendUserTextMessage("Hello, how are you?");
 ```
 
-## 🎓 Examples
+**Send Trigger Message:**
 
-- [React Example](./examples/react/) - Complete React application
+```typescript
+// Trigger specific character action
+convaiClient.sendTriggerMessage("greet", "User entered the room");
+
+// Trigger without message
+convaiClient.sendTriggerMessage("wave");
+```
 
-##  Best Practices
+**Update Context:**
 
-1. **Single Client Instance**: Create one client per application
-2. **State Management**: Check `state.isConnected` before sending messages
-3. **Session Management**: Use `resetSession()` when changing contexts
-4. **Error Handling**: Always wrap connect/disconnect in try-catch
-5. **Resource Cleanup**: Disconnect when done to free resources
-6. **Tree Shaking**: Import from specific paths to reduce bundle size
+```typescript
+// Update template keys (e.g., user name, location)
+convaiClient.updateTemplateKeys({
+  user_name: "John",
+  location: "New York",
+});
 
-##  TypeScript Support
+// Update dynamic information
+convaiClient.updateDynamicInfo({
+  text: "User is currently browsing the products page",
+});
+```
 
-Fully typed with TypeScript:
+**Message History:**
+
+```typescript
+// React
+const { chatMessages } = convaiClient;
+
+// Core API (event-based)
+convaiClient.on("message", (message: ChatMessage) => {
+  console.log("New message:", message.content);
+  console.log("Message type:", message.type);
+});
+
+convaiClient.on("messagesChange", (messages: ChatMessage[]) => {
+  console.log("All messages:", messages);
+});
+```
+
+**Message Types:**
+
+```typescript
+type ChatMessageType =
+  | "user" // User's sent message
+  | "convai" // Character's response
+  | "user-transcription" // Real-time speech-to-text from user
+  | "bot-llm-text" // Character's LLM-generated text
+  | "emotion" // Character's emotional state
+  | "behavior-tree" // Behavior tree response
+  | "action" // Action execution
+  | "bot-emotion" // Bot emotional response
+  | "user-llm-text" // User text processed by LLM
+  | "interrupt-bot"; // Interrupt message
+```
+
+### State Monitoring
+
+**Agent State:**
+
+```typescript
+// React
+const { state } = convaiClient;
+
+// Check specific states
+if (state.isListening) {
+  console.log("Bot is listening");
+}
+
+if (state.isThinking) {
+  console.log("Bot is thinking");
+}
+
+if (state.isSpeaking) {
+  console.log("Bot is speaking");
+}
+
+// Combined state
+console.log(state.agentState); // 'disconnected' | 'connected' | 'listening' | 'thinking' | 'speaking'
+```
+
+**User Transcription:**
+
+```typescript
+// React
+const { userTranscription } = convaiClient;
+
+// Core API (event-based)
+convaiClient.on("userTranscriptionChange", (transcription: string) => {
+  console.log("User is saying:", transcription);
+});
+```
+
+**Bot Ready State:**
+
+```typescript
+// React
+const { isBotReady } = convaiClient;
+
+// Core API (event-based)
+convaiClient.on("botReady", () => {
+  console.log("Bot is ready to receive messages");
+});
+```
+
+## Getting Convai Credentials
+
+1. Visit [convai.com](https://convai.com) and create an account
+2. Navigate to your dashboard
+3. Create a new character or use an existing one
+4. Copy your **API Key** from the dashboard
+5. Copy your **Character ID** from the character details
+
+## Import Paths
+
+```typescript
+// Default: React version (backward compatible)
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk";
+
+// Explicit React import
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
+
+// Vanilla JS/TS
+import { ConvaiClient, createConvaiWidget } from "@convai/web-sdk/vanilla";
+
+// Core only (no UI, framework agnostic)
+import { ConvaiClient } from "@convai/web-sdk/core";
+```
+
+## TypeScript Support
+
+All exports are fully typed:
 
 ```typescript
 import type {
@@ -337,37 +845,36 @@ import type {
   AudioControls,
   VideoControls,
   ScreenShareControls,
-} from '@convai/web-sdk';
+  IConvaiClient,
+} from "@convai/web-sdk";
 ```
 
-## 🔗 Dependencies
+## Browser Support
 
-### Core
-- `livekit-client` - WebRTC functionality
+- Chrome/Edge: Full support
+- Firefox: Full support
+- Safari: Full support
+- Mobile browsers: Supported
+
+## Dependencies
+
+### Peer Dependencies (React)
 
-### React (Peer)
 - `react ^18.0.0`
 - `react-dom ^18.0.0`
-- `@livekit/components-react`
-- `styled-components`
-- `framer-motion`
-- `react-icons`
 
-## 📄 License
+### Included Dependencies
+
+- `styled-components` - Styling
+- `framer-motion` - Animations
+- `react-icons` - Icon components
+
+## License
 
 MIT
 
-## 🆘 Support
+## Support
 
 - [GitHub Issues](https://github.com/convai/web-sdk/issues)
-- [Documentation](./docs/)
 - [API Reference](./API_REFERENCE.md)
 - [Convai Website](https://convai.com)
-
-## 🤝 Contributing
-
-Contributions are welcome! Please read our contributing guidelines before submitting PRs.
-
----
-
-Built by [Convai](https://convai.com)