@cuekit-ai/react 1.1.2 → 1.2.0

package/README.md

@@ -1,22 +1,19 @@
 # @cuekit-ai/react
 
-A powerful React SDK for integrating AI-powered voice interactions into your web applications. Built with TypeScript and designed for seamless voice navigation, commands, and interactions.
+A powerful React SDK for integrating AI-powered voice interactions into your web applications. Built with TypeScript and designed for seamless voice navigation, commands, and interactions with WebRTC support for real-time voice communication.
 
 [![npm version](https://badge.fury.io/js/%40cuekit-ai%2Freact.svg)](https://badge.fury.io/js/%40cuekit-ai%2Freact)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## 🚀 Features
 
-- **🎤 Voice Recognition**: Real-time speech-to-text with high accuracy
-- **🤖 AI-Powered Navigation**: Intelligent voice commands for app navigation
-- **🎯 Intent Recognition**: Understands user intent and performs actions
-- **🔊 Text-to-Speech**: Natural voice responses using ElevenLabs
-- **🎨 Beautiful UI**: Modern, animated voice assistant interface
-- **📱 Responsive Design**: Works seamlessly across all devices
-- **⚡ Real-time Processing**: Instant voice command processing
-- **🔄 State Management**: Robust state handling for voice interactions
-- **🎭 Portal Rendering**: Modal components render at document body level
-- **✨ Visual Feedback**: Border glow effects and animations
+- **🎤 Real-time Voice Recognition**: High-accuracy, real-time speech-to-text powered by WebRTC.
+- **🤖 AI-Powered Navigation**: Intelligent voice commands for seamless app navigation.
+- **🎯 Intent Recognition**: Understands user intent to perform actions on your site.
+- **🎨 Modern UI**: A beautiful, animated, and customizable voice assistant interface.
+- **🌙 Theme Support**: Automatic light/dark theme detection, with the ability to override.
+- **✍️ Text Input**: A built-in chat interface for text-based commands.
+- **🔧 Customizable**: Easily customize the look and feel to match your brand.
 
 ## 📦 Installation
 
@@ -24,183 +21,185 @@ A powerful React SDK for integrating AI-powered voice interactions into your web
 npm install @cuekit-ai/react
 ```
 
-```bash
-yarn add @cuekit-ai/react
-```
+After installation, you need to import the CSS file for styling:
 
-```bash
-pnpm add @cuekit-ai/react
+```tsx
+// In your main CSS file or a root component
+import '@cuekit-ai/react/styles.css'
 ```
 
 ## 🎯 Quick Start
 
-### 1. Wrap your app with CuekitProvider
+Get up and running with CueKit in just two steps.
+
+### 1. Wrap Your App with `CuekitProvider`
+
+The `CuekitProvider` initializes the SDK and provides the necessary context to all child components. You should wrap your application's root component with it.
 
 ```tsx
+// Example for a React Router v6 application
 import { CuekitProvider } from '@cuekit-ai/react'
+import { useNavigate } from 'react-router-dom'
 
 function App() {
+  const navigate = useNavigate()
+
+  const handleNavigation = (path, params) => {
+    navigate(path, { state: params })
+  }
+
   return (
-  <CuekitProvider
-  apiKey="your-api-key"
-  appId="your-app-id"
-  deviceId="optional-device-id"
-  navigationHandler={(path, params) => {
-    const qs = params ? `?${new URLSearchParams(params).toString()}` : ''
-    // Example with Next.js App Router
-    router.push(`${path}${qs}`)
-    // Or with React Router v6
-    // navigate(`${path}${qs}`)
-  }}
+    <CuekitProvider apiKey="YOUR_API_KEY" appId="YOUR_APP_ID" navigationHandler={handleNavigation}>
+      {/* Your application components */}
+    </CuekitProvider>
   )
 }
 ```
 
-### 2. Add the MicButton component
+### 2. Add the `MicButton`
+
+The `MicButton` is the main UI component for the voice assistant. It can be placed anywhere in your application, but it's best to place it in a layout component that's always visible.
 
 ```tsx
 import { MicButton } from '@cuekit-ai/react'
 
-function YourApp() {
+function Layout({ children }) {
   return (
     <div>
-      <h1>My Voice-Enabled App</h1>
-      <MicButton
-        screenPosition="bottom-right"
-        buttonStyle={{
-          backgroundColor: 'blue',
-          borderRadius: '50%',
-        }}
-      />
+      {children}
+      <MicButton screenPosition="bottom-right" />
     </div>
   )
 }
 ```
 
-## 🎨 Components
+## API Reference
 
-### MicButton
+### `CuekitProvider`
 
-The main voice interaction component with a beautiful animated interface.
+The main provider component that enables all CueKit functionality.
 
-```tsx
-import { MicButton } from '@cuekit-ai/react'
-;<MicButton
-  screenPosition="bottom-right" // 'bottom-left' | 'bottom-center' | 'bottom-right'
-  buttonStyle={
-    {
-      /* custom styles */
-    }
-  }
-  buttonSize={60}
-  hasText={false}
-  text="Voice Assistant"
-  textStyle={
-    {
-      /* text styles */
-    }
-  }
-  imageSource="path/to/image.png"
-  imageStyle={
-    {
-      /* image styles */
-    }
-  }
-/>
-```
+| Prop                      | Type                                                   | Required | Description                                                                                                |
+| ------------------------- | ------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------- |
+| `apiKey`                  | `string`                                               | ✅       | Your CueKit API key.                                                                                       |
+| `appId`                   | `string`                                               | ✅       | Your application ID.                                                                                       |
+| `navigationHandler`       | `(path: string, params?: Record<string, any>) => void` | ❌       | A function to handle navigation events. See [Routing Integration](#-routing-integration) for more details. |
+| `onConnectionStateChange` | `(state: ConnectionState) => void`                     | ❌       | A callback for WebRTC connection state changes.                                                            |
+| `onParticipantUpdate`     | `(participants: string[]) => void`                     | ❌       | A callback for when the list of participants in the room changes.                                          |
+| `children`                | `ReactNode`                                            | ✅       | Your app components.                                                                                       |
 
-#### Props
+### `MicButton`
 
-| Prop             | Type                                                 | Default          | Description                          |
-| ---------------- | ---------------------------------------------------- | ---------------- | ------------------------------------ |
-| `screenPosition` | `'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-right'` | Position of the mic button           |
-| `buttonStyle`    | `React.CSSProperties`                                | `{}`             | Custom styles for the button         |
-| `buttonSize`     | `number`                                             | `60`             | Size of the button in pixels         |
-| `hasText`        | `boolean`                                            | `false`          | Whether to show text with the button |
-| `text`           | `string`                                             | `'CueKit VC'`    | Text to display with the button      |
-| `textStyle`      | `React.CSSProperties`                                | `{}`             | Styles for the text                  |
-| `imageSource`    | `string`                                             | `undefined`      | Image source for the button          |
-| `imageStyle`     | `React.CSSProperties`                                | `{}`             | Styles for the image                 |
+The main UI component for the voice assistant.
 
-### CuekitProvider
+| Prop             | Type                                                 | Default          | Description                                                                                |
+| ---------------- | ---------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------ |
+| `screenPosition` | `'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-right'` | The position of the mic button on the screen.                                              |
+| `bottomSpace`    | `number`                                             | `20`             | The distance of the button from the bottom of the screen, in pixels.                       |
+| `buttonSize`     | `number`                                             | `52`             | The size of the button, in pixels.                                                         |
+| `defaultTheme`   | `'light' \| 'dark' \| 'system'`                      | `'system'`       | The default theme for the chat popup. `'system'` will auto-detect the user's system theme. |
+| `buttonStyle`    | `React.CSSProperties`                                | `{}`             | Custom styles for the button.                                                              |
+| `imageSource`    | `string`                                             | `undefined`      | An image to display in the button instead of the default icon.                             |
+| `imageStyle`     | `React.CSSProperties`                                | `{}`             | Custom styles for the image.                                                               |
+| `showBorderGlow` | `boolean`                                            | `false`          | Whether to show an animated border glow around the button during active states.            |
 
-The context provider that initializes the voice assistant.
+### `useCuekit` Hook
 
-```tsx
-import { CuekitProvider } from '@cuekit-ai/react'
+The `useCuekit` hook is the primary way to interact with the CueKit SDK. It provides all the necessary state and functions to build a custom voice experience.
 
-;<CuekitProvider
-  apiKey="your-api-key"
-  appId="your-app-id"
-  deviceId="optional-device-id"
-  navigationHandler={(path, params) => {
-    const qs = params ? `?${new URLSearchParams(params).toString()}` : ''
-    // Example with Next.js App Router
-    router.push(`${path}${qs}`)
-    // Or with React Router v6
-    // navigate(`${path}${qs}`)
-  }}
->
-  {children}
-</CuekitProvider>
+```tsx
+import { useCuekit } from '@cuekit-ai/react'
+
+function CustomVoiceComponent() {
+  const {
+    isConnected,
+    isConnecting,
+    error,
+    connect,
+    disconnect,
+    sendUserCommand,
+    messages,
+    micState,
+    status,
+  } = useCuekit()
+
+  // Your custom UI and logic here
+}
 ```
 
-#### Props
+**Return Values**:
 
-| Prop                | Type                                                   | Required | Description                                                                |
-| ------------------- | ------------------------------------------------------ | -------- | -------------------------------------------------------------------------- |
-| `apiKey`            | `string`                                               | ✅       | Your CueKit API key                                                        |
-| `appId`             | `string`                                               | ✅       | Your application ID                                                        |
-| `deviceId`          | `string`                                               | ❌       | Unique device identifier (auto-generated if not provided)                  |
-| `navigationHandler` | `(path: string, params?: Record<string, any>) => void` | ❌       | Custom router handler. If not provided, falls back to internal navigation. |
-| `children`          | `ReactNode`                                            | ✅       | Your app components                                                        |
+| Property          | Type                                                                   | Description                                                   |
+| ----------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `isConnected`     | `boolean`                                                              | Whether the SDK is currently connected to the CueKit backend. |
+| `isConnecting`    | `boolean`                                                              | Whether the SDK is currently attempting to connect.           |
+| `error`           | `string \| null`                                                       | Any error that occurred during connection or operation.       |
+| `connect`         | `(identity: string, apiKey?: string, appId?: string) => Promise<void>` | A function to connect to the CueKit backend.                  |
+| `disconnect`      | `() => Promise<void>`                                                  | A function to disconnect from the CueKit backend.             |
+| `sendUserCommand` | `(command: string) => Promise<void>`                                   | A function to send a text command to the CueKit backend.      |
+| `messages`        | `ChatMessage[]`                                                        | An array of chat messages.                                    |
+| `micState`        | `'idle' \| 'listening' \| 'thinking' \| 'replying'`                    | The current state of the microphone.                          |
+| `status`          | `string`                                                               | A user-friendly status message.                               |
 
-### Routing integration
-
-You can integrate your app's router by passing a `navigationHandler` to `CuekitProvider`.
-
-Next.js App Router example:
-
-```tsx
-'use client'
-import { useEffect } from 'react'
-import { useRouter } from 'next/navigation'
-import { CuekitProvider } from '@cuekit-ai/react'
+## 🎨 Styling
 
-export default function Providers({ children }: { children: React.ReactNode }) {
-  const router = useRouter()
+The SDK is styled with CSS variables, which makes it easy to customize the look and feel of the components.
+
+### CSS Variables
+
+You can override the default values of these variables in your own CSS to match your brand.
+
+```css
+/* Light theme (default) */
+:root {
+  --voice-bg: 0 0% 100%;
+  --voice-surface: 0 0% 100%;
+  --voice-border: 214.3 31.8% 91.4%;
+  --voice-text: 222.2 84% 4.9%;
+  --voice-text-muted: 215.4 16.3% 46.9%;
+  --voice-accent: 200 98% 39%;
+  --voice-accent-light: 200 98% 95%;
+  --voice-user-bubble: 200 98% 39%;
+  --voice-user-text: 0 0% 100%;
+  --voice-ai-bubble: 0 0% 95%;
+  --voice-ai-text: 222.2 84% 4.9%;
+}
 
-  return (
-    <CuekitProvider
-      apiKey={process.env.NEXT_PUBLIC_CUEKIT_API_KEY!}
-      appId={process.env.NEXT_PUBLIC_CUEKIT_APP_ID!}
-      navigationHandler={(path, params) => {
-        const qs = params ? `?${new URLSearchParams(params).toString()}` : ''
-        router.push(`${path}${qs}`)
-      }}
-    >
-      {children}
-    </CuekitProvider>
-  )
+/* Dark theme */
+.cuekit-dark {
+  --voice-bg: 211 32% 11%;
+  --voice-surface: 217.2 32.6% 17.5%;
+  --voice-border: 217.2 32.6% 17.5%;
+  --voice-text: 210 40% 98%;
+  --voice-text-muted: 215 20.2% 65.1%;
+  --voice-accent: 200 98% 60%;
+  --voice-accent-light: 200 98% 20%;
+  --voice-user-bubble: 200.12 80.39% 60%;
+  --voice-user-text: 0 0% 100%;
+  --voice-ai-bubble: 200.57 32.71% 20.98%;
+  --voice-ai-text: 0 0% 100%;
 }
 ```
 
-React Router v6 example:
+### Routing Integration
+
+The SDK can integrate with your application's router via the `navigationHandler` prop on the `CuekitProvider`.
+
+**React Router v6 Example**:
 
 ```tsx
 import { useNavigate } from 'react-router-dom'
 import { CuekitProvider } from '@cuekit-ai/react'
 
-function AppProviders({ children }: { children: React.ReactNode }) {
+function AppProviders({ children }) {
   const navigate = useNavigate()
 
   return (
     <CuekitProvider
-      apiKey={import.meta.env.VITE_CUEKIT_API_KEY}
-      appId={import.meta.env.VITE_CUEKIT_APP_ID}
+      apiKey="YOUR_API_KEY"
+      appId="YOUR_APP_ID"
       navigationHandler={(path, params) => {
-        const qs = params ? `?${new URLSearchParams(params).toString()}` : ''
-        navigate(`${path}${qs}`)
+        navigate(path, { state: params })
       }}
     >
       {children}
@@ -209,205 +208,14 @@ function AppProviders({ children }: { children: React.ReactNode }) {
 }
 ```
 
-## 🔧 Hooks
-
-### useVoice
-
-Hook for voice recognition and processing.
-
-```tsx
-import { useVoice } from '@cuekit-ai/react'
-
-function MyComponent() {
-  const { isListening, start, stop, transcript } = useVoice()
-
-  const handleVoiceStart = () => {
-    start('Hello, how can I help you?')
-  }
-
-  const handleVoiceStop = () => {
-    stop()
-  }
-
-  return (
-    <div>
-      <p>Listening: {isListening ? 'Yes' : 'No'}</p>
-      <p>Transcript: {transcript}</p>
-      <button onClick={handleVoiceStart}>Start Listening</button>
-      <button onClick={handleVoiceStop}>Stop Listening</button>
-    </div>
-  )
-}
-```
-
-### useAudioController
-
-Hook for audio playback control.
-
-```tsx
-import { useAudioController } from '@cuekit-ai/react'
-
-function AudioComponent() {
-  const { play, pause, stop, isPlaying } = useAudioController()
-
-  return (
-    <div>
-      <button onClick={play}>Play</button>
-      <button onClick={pause}>Pause</button>
-      <button onClick={stop}>Stop</button>
-      <p>Playing: {isPlaying ? 'Yes' : 'No'}</p>
-    </div>
-  )
-}
-```
-
-### useVoiceRecognition
-
-Hook for advanced voice recognition features.
-
-```tsx
-import { useVoiceRecognition } from '@cuekit-ai/react'
-
-function VoiceRecognitionComponent() {
-  const { isListening, transcript, startListening, stopListening, resetTranscript } =
-    useVoiceRecognition()
-
-  return (
-    <div>
-      <button onClick={startListening}>Start</button>
-      <button onClick={stopListening}>Stop</button>
-      <button onClick={resetTranscript}>Reset</button>
-      <p>Transcript: {transcript}</p>
-    </div>
-  )
-}
-```
-
-## 🛠️ Utilities
-
-### processVoice
-
-Process voice commands and execute actions.
-
-```tsx
-import { processVoice } from '@cuekit-ai/react'
-
-const handleVoiceCommand = async (transcript: string) => {
-  const result = await processVoice(transcript, apiKey, appId, deviceId)
-
-  if (result) {
-    console.log('Voice command processed:', result)
-  }
-}
-```
-
-### onStateChange
-
-Handle navigation state changes.
-
-```tsx
-import { onStateChange } from '@cuekit-ai/react'
-
-// Automatically called by CuekitProvider
-// Handles route changes and voice command re-triggering
-```
-
-## 🎯 Voice Commands
-
-The SDK supports various voice commands for navigation and interaction:
-
-### Navigation Commands
-
-- "Go to home"
-- "Navigate to settings"
-- "Open profile page"
-- "Go back"
-
-### Action Commands
-
-- "Click the submit button"
-- "Press the login button"
-- "Select the first option"
-- "Scroll down"
-
-### Information Commands
-
-- "What's on this page?"
-- "Tell me about this screen"
-- "What can I do here?"
-
-## 🎨 Styling
-
-### Custom Button Styling
-
-```tsx
-<MicButton
-  buttonStyle={{
-    backgroundColor: 'linear-gradient(45deg, #667eea 0%, #764ba2 100%)',
-    boxShadow: '0 4px 15px rgba(0, 0, 0, 0.2)',
-    transform: 'scale(1.1)',
-  }}
-/>
-```
-
-### Custom Modal Styling
-
-The modal automatically adapts to your app's theme and provides:
-
-- Beautiful gradient backgrounds
-- Smooth animations
-- Responsive design
-- Accessibility features
-
-```env
-CUEKIT_API_KEY=your-api-key
-CUEKIT_APP_ID=your-app-id
-CUEKIT_DEVICE_ID=optional-device-id
-```
-
-### API Configuration
-
-The SDK communicates with the CueKit API for:
-
-- Voice command processing
-- Intent recognition
-- Navigation handling
-- Text-to-speech synthesis
-
-## 🔒 Security
-
-- All API calls are made over HTTPS
-- API keys are stored securely
-- No sensitive data is logged
-- Device IDs are anonymized
-
-## 🚀 Performance
-
-- Lightweight bundle (~40KB gzipped)
-- Optimized for React 18+
-- Efficient re-rendering
-- Minimal memory footprint
-
 ## 🐛 Troubleshooting
 
-### Common Issues
-
-1. **Mic not working**
-
-   - Check browser permissions
-   - Ensure HTTPS connection
-   - Verify API key is valid
-
-2. **Voice commands not recognized**
-
-   - Check internet connection
-   - Verify app ID is correct
-   - Ensure proper CuekitProvider setup
+If you're having trouble, here are a few things to check:
 
-3. **Modal not appearing**
-   - Check z-index conflicts
-   - Verify portal rendering
-   - Ensure proper state management
+- **Microphone Not Working**: Ensure that you've granted microphone permissions to your site. Also, the SDK requires a secure (HTTPS) connection to function.
+- **Voice Commands Not Recognized**: Check your internet connection and ensure that you've provided a valid API key and app ID to the `CuekitProvider`.
+- **Styling Issues**: Make sure you've imported the CSS file as described in the [Installation](#-installation) section.
+- **WebRTC Connection Issues**: Check your browser's console for any error messages related to WebRTC. Ensure your network doesn't block the necessary ports.
 
 ---