@convai/web-sdk 0.1.0 → 0.1.1-beta.0

package/README.md

@@ -1,278 +1,370 @@
 # @convai/web-sdk
 
-The convai/web-sdk helps power characters in websites (brain) and the communication UI with Convai characters. This SDK facilitates the capture of user audio streams and provides appropriate responses in the form of audio, actions, and facial expressions.
+Multi-platform SDK for Convai AI voice assistants. Build voice-powered AI interactions for web applications with real-time audio/video streaming.
 
-## Installation
+## 🌟 Features
+
+- **Multi-Platform Support**: Works with React, Vanilla JS/TS, and any JavaScript framework
+- **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
+
+##  Installation
 
 ```bash
 npm install @convai/web-sdk
 ```
 
-## Quick Start
+##  Quick Start
+
+### React
 
 ```tsx
-import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk";
+import { useConvaiClient, ConvaiWidget } from '@convai/web-sdk';
 
 function App() {
   const convaiClient = useConvaiClient({
-    apiKey: "your-convai-api-key",
-    characterId: "your-character-id",
-    enableVideo: true,
-    startWithVideoOn: false,
+    apiKey: 'your-api-key',
+    characterId: 'your-character-id',
+    // endUserId: 'user-uuid', // Optional: enables memory & analytics
+    enableVideo: true
   });
 
-  return (
-    <ConvaiWidget
-      convaiClient={convaiClient}
-      showVideo={true}
-      showScreenShare={true}
-    />
-  );
+  return <ConvaiWidget convaiClient={convaiClient} />;
 }
 ```
 
-## Get Convai Credentials
+[**→ Full React Guide**](./docs/REACT_USAGE.md)
 
-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
+### Vanilla JavaScript/TypeScript
 
-## API Reference
+```typescript
+import { ConvaiClient, ConvaiWidget } from '@convai/web-sdk/vanilla';
 
-### useConvaiClient()
+const client = new ConvaiClient();
+const widget = new ConvaiWidget(client, {
+  characterName: 'AI Assistant'
+});
 
-Main hook for managing Convai connections. Pass configuration to store it for later use when connecting.
+widget.mount(document.body);
 
-```tsx
-const convaiClient = useConvaiClient({
+await client.connect({
   apiKey: 'your-api-key',
   characterId: 'your-character-id',
-  enableVideo: true,
-  startWithVideoOn: false,
+  // endUserId: 'user-uuid', // Optional: enables memory & analytics
+  enableVideo: true
 });
 ```
 
-**Note:** The hook stores the configuration but does not auto-connect. Connection happens when `convaiClient.connect()` is called (automatically by ConvaiWidget on first click, or manually in custom implementations).
+[**→ Full Vanilla Guide**](./docs/VANILLA_USAGE.md)
 
-**Returns:**
+### Core Only (Framework Agnostic)
 
-```tsx
-{
-  state: ConvaiClientState;           // Connection and activity state
-  connectionType: 'audio' | 'video' | null; // Current connection type
-  apiKey: string | null;              // Stored API key
-  characterId: string | null;         // Stored character ID
-  connect: (config?) => Promise<void>; // Connect using stored or override config
-  disconnect: () => Promise<void>;    // Disconnect from Convai
-  reconnect: () => Promise<void>;     // Disconnect and reconnect
-  resetSession: () => void;           // Reset the session ID for fresh start
-  room: Room;                         // Internal LiveKit room instance
-  sendUserTextMessage: (text) => void;       // Send text message
-  sendTriggerMessage: (name?, msg?) => void; // Send trigger message
-  updateTemplateKeys: (keys) => void;        // Update template keys
-  updateDynamicInfo: (info) => void;         // Update dynamic info
-  chatMessages: ChatMessage[];        // Message history
-  audioControls: AudioControls;       // Audio control methods
-  videoControls: VideoControls;       // Video control methods
-  screenShareControls: ScreenShareControls; // Screen share controls
-  toggleTts: (enabled) => void;       // Toggle text-to-speech
-}
-```
+For custom framework integrations:
 
-**State Object:**
+```typescript
+import { ConvaiClient } from '@convai/web-sdk/core';
 
-```tsx
-interface ConvaiClientState {
-  isConnected: boolean; // Connected to Convai
-  isConnecting: boolean; // Connection in progress
-  isListening: boolean; // Listening to user
-  isThinking: boolean; // Processing response
-  isSpeaking: boolean; // Speaking to user
-  agentState:
-    | "disconnected"
-    | "connected"
-    | "listening"
-    | "thinking"
-    | "speaking";
-}
+const client = new ConvaiClient();
+
+// Listen for events
+client.on('stateChange', (state) => {
+  console.log('State:', state.agentState);
+});
+
+client.on('message', (message) => {
+  console.log('New message:', message.content);
+});
+
+// Connect
+await client.connect({
+  apiKey: 'your-api-key',
+  characterId: 'your-character-id',
+  // endUserId: 'user-uuid' // Optional: enables memory & analytics
+});
+
+// Send message
+client.sendUserTextMessage('Hello!');
 ```
 
-**Audio Controls:**
+## 📖 Platform-Specific Guides
 
-```tsx
-audioControls: {
-  isAudioMuted: boolean;
-  toggleAudio: () => Promise<void>;
-  muteAudio: () => Promise<void>;
-  unmuteAudio: () => Promise<void>;
-}
+Choose your platform:
+
+- [**React Usage Guide**](./docs/REACT_USAGE.md) - Hooks, components, and React integration
+- [**Vanilla JS/TS Guide**](./docs/VANILLA_USAGE.md) - Class-based API for vanilla JavaScript
+- [**API Reference**](./API_REFERENCE.md) - Complete API documentation
+
+##  Import Options
+
+The SDK supports multiple import paths for tree-shaking:
+
+```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 JavaScript/TypeScript
+import { ConvaiClient, ConvaiWidget } from '@convai/web-sdk/vanilla';
+
+// Core only (no UI, framework agnostic)
+import { ConvaiClient } from '@convai/web-sdk/core';
 ```
 
-**Video Controls:**
+## 🔑 Get Convai Credentials
 
-```tsx
-videoControls: {
-  isVideoEnabled: boolean;
-  enableVideo: () => Promise<void>;
-  disableVideo: () => Promise<void>;
-}
+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
+
+## Core Features
+
+### Connection Management
+
+```typescript
+// Connect
+await client.connect(config);
+
+// Disconnect
+await client.disconnect();
+
+// Reset session (clear history)
+client.resetSession();
+
+// Reconnect
+await client.reconnect();
 ```
 
-**Screen Share Controls:**
+### Messaging
 
-```tsx
-screenShareControls: {
-  isScreenShareActive: boolean;
-  toggleScreenShare: () => Promise<void>;
-}
+```typescript
+// Send text message
+client.sendUserTextMessage('Hello!');
+
+// Send trigger for specific actions
+client.sendTriggerMessage('greet', 'User entered room');
+
+// Update context
+client.updateTemplateKeys({ user_name: 'John' });
+client.updateDynamicInfo({ text: 'User is happy' });
 ```
 
-### ConvaiWidget Component
+### Media Controls
+
+```typescript
+// Audio (always available)
+await client.audioControls.toggleAudio();
+await client.audioControls.muteAudio();
+await client.audioControls.unmuteAudio();
 
-Complete all-in-one chat widget with automatic connection, voice mode, and video support.
+// Video (if enableVideo: true)
+await client.videoControls.toggleVideo();
+await client.videoControls.enableVideo();
+await client.videoControls.disableVideo();
 
-**Features:**
+// Screen Share (if enableVideo: true)
+await client.screenShareControls.toggleScreenShare();
+```
 
-- Collapsed circular button that expands on click
-- Connects on first user click (using config from useConvaiClient)
-- Text and voice mode support
-- Video controls with floating video window (when connection type is video)
-- Screen sharing capability (when connection type is video)
+### State Monitoring
 
-```tsx
-<ConvaiWidget
-  convaiClient={convaiClient}
-  showVideo={true}
-  showScreenShare={true}
-/>
+```typescript
+// React
+const { state, chatMessages, userTranscription } = convaiClient;
+
+// Vanilla
+client.on('stateChange', (state) => {
+  console.log(state.agentState); // 'listening' | 'thinking' | 'speaking'
+});
+
+client.on('message', (message) => {
+  console.log('New message:', message);
+});
 ```
 
-**Props:**
+## 🎨 UI Components
 
-| Prop               | Type           | Required | Default | Description                                                      |
-| ------------------ | -------------- | -------- | ------- | ---------------------------------------------------------------- |
-| `convaiClient`     | `ConvaiClient` | Yes      | -       | ConvaiClient instance from useConvaiClient() with stored config  |
-| `showVideo`        | `boolean`      | No       | `true`  | Show video toggle button (only works if connection type is video)|
-| `showScreenShare`  | `boolean`      | No       | `true`  | Show screen share button (only works if connection type is video)|
+### Pre-built Widget
 
-## Configuration
+Both React and Vanilla versions include a complete chat widget:
 
-**Config Interface:**
+- 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
+### Custom UI
+
+Build your own UI using the client API. The client handles all the AI logic while you control the presentation.
+
+##  Message Types
+
+The SDK handles various message types:
+
+- `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
+
+## 🔧 Configuration
+
+```typescript
 interface ConvaiConfig {
-  apiKey: string; // Required: Your Convai API key
-  characterId: string; // Required: Character ID
-  url?: string; // Optional: Custom API URL
-  enableVideo?: boolean; // Optional: Enable video capability (default: false)
-                         // If true, connection_type is "video" (audio + video + screenshare)
-                         // If false, connection_type is "audio" (audio only)
-  startWithVideoOn?: boolean; // Optional: Start with camera on (default: false)
-                              // Only works if enableVideo is true
-  ttsEnabled?: boolean; // Optional: Enable text-to-speech (default: true)
-  actionConfig?: ActionConfig; // Optional: Action configuration
+  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 }>;
+  };
 }
 ```
 
-**Note:** Audio is always enabled - the microphone is always active when connected. Use `enableVideo` to control whether video capabilities are available.
+### About endUserId
 
-## Advanced Usage
+The `endUserId` parameter is **optional** and serves two important purposes:
 
-### Sending Messages
+1. **Long-term Memory**: When provided, the character remembers context from previous conversations with this user, enabling personalized and continuous interactions across sessions.
 
-```tsx
-// Send text message
-convaiClient.sendUserTextMessage("Hello!");
+2. **Analytics & Tracking**: Track user engagement, behavior patterns, and conversation metrics for your application.
 
-// Send trigger message
-convaiClient.sendTriggerMessage("greet", "Custom greeting");
+**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
 
-// Update template keys
-convaiClient.updateTemplateKeys({
-  user_name: "John",
-  location: "New York",
+```typescript
+// With persistent memory and analytics
+await client.connect({
+  apiKey: 'your-api-key',
+  characterId: 'your-character-id',
+  endUserId: 'user-12345' // User will be remembered
 });
 
-// Update dynamic info
-convaiClient.updateDynamicInfo({
-  text: "Additional context for the character",
+// Anonymous mode (no memory, no tracking)
+await client.connect({
+  apiKey: 'your-api-key',
+  characterId: 'your-character-id'
+  // No endUserId = anonymous
 });
 ```
 
-### Control Audio/Video
+##  Browser Support
 
-```tsx
-// Toggle microphone
-await convaiClient.audioControls.toggleAudio();
-
-// Mute/unmute
-await convaiClient.audioControls.muteAudio();
-await convaiClient.audioControls.unmuteAudio();
+- Chrome/Edge:  Full support
+- Firefox:  Full support
+- Safari:  Full support
+- Mobile browsers:  Supported
 
-// Enable/disable video
-await convaiClient.videoControls.enableVideo();
-await convaiClient.videoControls.disableVideo();
+##  Package Structure
 
-// Toggle screen share
-await convaiClient.screenShareControls.toggleScreenShare();
+```
+@convai/web-sdk
+├── /core       # Framework-agnostic core (ConvaiClient)
+├── /react      # React hooks and components
+├── /vanilla    # Vanilla JS/TS widget
+└── (default)   # React (backward compatible)
 ```
 
-### Session Management
+## 🔄 Migration from Previous Versions
 
-```tsx
-// Reset session (clears history)
-convaiClient.resetSession();
+### Backward Compatible
 
-// Disconnect
-await convaiClient.disconnect();
+No breaking changes! Existing code continues to work:
 
-// Reconnect with new session
-await convaiClient.connect(config);
+```tsx
+//  Still works
+import { useConvaiClient, ConvaiWidget } from '@convai/web-sdk';
 ```
 
-## Advanced Usage
+### New Features Available
 
-### Custom Audio/Video Rendering
+```tsx
+//  New: Explicit React import
+import { useConvaiClient } from '@convai/web-sdk/react';
 
-For custom implementations, you can use the exported `AudioRenderer` and `AudioContext` components:
+//  New: Vanilla JS/TS support
+import { ConvaiClient, ConvaiWidget } from '@convai/web-sdk/vanilla';
 
-```tsx
-import { useConvaiClient, AudioRenderer, AudioContext } from "@convai/web-sdk";
-
-function CustomApp() {
-  const convaiClient = useConvaiClient();
-
-  return (
-    <AudioContext.Provider value={convaiClient.room}>
-      {/* AudioRenderer is required for audio playback */}
-      <AudioRenderer />
-      
-      {/* Your custom UI here */}
-      <YourCustomUI />
-    </AudioContext.Provider>
-  );
-}
+//  New: Core-only for custom frameworks
+import { ConvaiClient } from '@convai/web-sdk/core';
 ```
 
-**Note:** `AudioRenderer` and `AudioContext` are re-exported from `@livekit/components-react` for convenience. These are required for proper audio/video functionality when building custom UIs instead of using `ConvaiWidget`.
+## 🎓 Examples
 
-## TypeScript Support
+- [React Example](./examples/react/) - Complete React application
+- More examples coming soon!
 
-The SDK is written in TypeScript and provides full type definitions. Import types as needed:
+##  Best Practices
 
-```tsx
-import {
+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 Support
+
+Fully typed with TypeScript:
+
+```typescript
+import type {
   ConvaiClient,
   ConvaiConfig,
   ConvaiClientState,
   ChatMessage,
-  AudioRenderer,
-  AudioContext,
-} from "@convai/web-sdk";
+  AudioControls,
+  VideoControls,
+  ScreenShareControls,
+} from '@convai/web-sdk';
 ```
 
-## License
+## 🔗 Dependencies
+
+### Core
+- `livekit-client` - WebRTC functionality
+
+### React (Peer)
+- `react ^18.0.0`
+- `react-dom ^18.0.0`
+- `@livekit/components-react`
+- `styled-components`
+- `framer-motion`
+- `react-icons`
+
+### Vanilla
+- None! Pure JavaScript
+
+## 📄 License
 
 MIT
+
+## 🆘 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)

package/dist/components/ConvaiWidget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConvaiWidget.d.ts","sourceRoot":"","sources":["../../src/components/ConvaiWidget.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAyCxC,UAAU,iBAAiB;IACzB,wCAAwC;IACxC,YAAY,EAAE,YAAY,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAuoBpD,CAAC"}
+{"version":3,"file":"ConvaiWidget.d.ts","sourceRoot":"","sources":["../../src/components/ConvaiWidget.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAyCxC,UAAU,iBAAiB;IACzB,wCAAwC;IACxC,YAAY,EAAE,YAAY,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAqpBpD,CAAC"}

package/dist/components/ConvaiWidget.js

@@ -66,6 +66,16 @@ export const ConvaiWidget = ({ convaiClient, showVideo = true, showScreenShare =
         name: characterName,
         image: characterImage,
     };
+    // Get bot status color for character image border
+    const getBotStatusColor = () => {
+        if (!convaiClient.state.isConnected) {
+            return { color: "#ef4444", label: "Disconnected" }; // Red
+        }
+        if (convaiClient.state.isConnecting || !convaiClient.isBotReady) {
+            return { color: "#f59e0b", label: "Connecting" }; // Yellow/Orange
+        }
+        return { color: "#10b981", label: "Connected" }; // Green
+    };
     // Format chat messages for UI
     const formatMessages = () => {
         // Filter to only show relevant message types and exclude empty messages
@@ -268,6 +278,9 @@ export const ConvaiWidget = ({ convaiClient, showVideo = true, showScreenShare =
                                                             borderRadius: "50%",
                                                             objectFit: "cover",
                                                             marginRight: "0.5rem",
+                                                            border: `1.5px solid ${getBotStatusColor().color}`,
+                                                            boxShadow: `0 0 6px ${getBotStatusColor().color}40`,
+                                                            transition: "all 0.3s ease",
                                                         } })), selectedCharacter.name, _jsx(motion.button, { onClick: handleToggleMute, whileHover: { scale: 1.1 }, whileTap: { scale: 0.9 }, transition: iosTransitions.snappy, style: {
                                                             cursor: "pointer",
                                                             pointerEvents: "auto",