@convai/web-sdk 0.0.1

package/README.md

@@ -0,0 +1,239 @@
+# @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.
+
+## Installation
+
+```bash
+npm install @convai/web-sdk
+```
+
+## Quick Start
+
+```tsx
+import { useConvaiClient, RTCWidget } from "@convai/web-sdk";
+
+function App() {
+  const convaiClient = useConvaiClient();
+
+  return (
+    <RTCWidget
+      convaiClient={convaiClient}
+      apiKey="your-convai-api-key"
+      characterId="your-character-id"
+      enableVideo={true}
+      startWithVideoOn={false}
+      enableAudio={true}
+    />
+  );
+}
+```
+
+## Get 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
+
+## API Reference
+
+### useConvaiClient()
+
+Main hook for managing Convai connections.
+
+```tsx
+const convaiClient = useConvaiClient();
+```
+
+**Returns:**
+
+```tsx
+{
+  state: ConvaiClientState;           // Connection and activity state
+  connect: (config) => Promise<void>; // Connect to Convai
+  disconnect: () => Promise<void>;    // Disconnect from Convai
+  resetSession: () => void;           // Reset the session ID
+  room: Room;                         // Internal 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
+}
+```
+
+**State Object:**
+
+```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";
+}
+```
+
+**Audio Controls:**
+
+```tsx
+audioControls: {
+  isAudioMuted: boolean;
+  toggleAudio: () => Promise<void>;
+  muteAudio: () => Promise<void>;
+  unmuteAudio: () => Promise<void>;
+}
+```
+
+**Video Controls:**
+
+```tsx
+videoControls: {
+  isVideoEnabled: boolean;
+  enableVideo: () => Promise<void>;
+  disableVideo: () => Promise<void>;
+}
+```
+
+**Screen Share Controls:**
+
+```tsx
+screenShareControls: {
+  isScreenShareActive: boolean;
+  toggleScreenShare: () => Promise<void>;
+}
+```
+
+### RTCWidget Component
+
+Complete all-in-one chat widget with automatic connection, voice mode, and video support.
+
+**Features:**
+
+- Collapsed circular button that expands on click
+- Auto-connects on first interaction
+- Text and voice mode support
+- Video controls with floating video window
+- Screen sharing capability
+
+```tsx
+<RTCWidget
+  convaiClient={convaiClient}
+  apiKey="your-api-key"
+  characterId="your-character-id"
+  enableVideo={true}
+  startWithVideoOn={false}
+  enableAudio={true}
+  url="https://your-custom-url.com"
+/>
+```
+
+**Props:**
+
+| Prop               | Type           | Required | Default | Description                                         |
+| ------------------ | -------------- | -------- | ------- | --------------------------------------------------- |
+| `convaiClient`     | `ConvaiClient` | Yes      | -       | ConvaiClient instance from useConvaiClient()        |
+| `apiKey`           | `string`       | Yes      | -       | Your Convai API key                                 |
+| `characterId`      | `string`       | No       | -       | Character ID to connect to                          |
+| `enableVideo`      | `boolean`      | No       | `false` | Enable video capability (shows video toggle button) |
+| `startWithVideoOn` | `boolean`      | No       | `false` | Start with camera on when connecting                |
+| `enableAudio`      | `boolean`      | No       | `true`  | Enable audio                                        |
+| `url`              | `string`       | No       | -       | Custom Convai API URL                               |
+
+## Configuration
+
+**Config Interface:**
+
+```tsx
+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 (default: false)
+  enableAudio?: boolean; // Optional: Enable audio (default: true)
+  actionConfig?: ActionConfig; // Optional: Action configuration
+}
+```
+
+## Advanced Usage
+
+### Sending Messages
+
+```tsx
+// Send text message
+convaiClient.sendUserTextMessage("Hello!");
+
+// Send trigger message
+convaiClient.sendTriggerMessage("greet", "Custom greeting");
+
+// Update template keys
+convaiClient.updateTemplateKeys({
+  user_name: "John",
+  location: "New York",
+});
+
+// Update dynamic info
+convaiClient.updateDynamicInfo({
+  text: "Additional context for the character",
+});
+```
+
+### Control Audio/Video
+
+```tsx
+// Toggle microphone
+await convaiClient.audioControls.toggleAudio();
+
+// Mute/unmute
+await convaiClient.audioControls.muteAudio();
+await convaiClient.audioControls.unmuteAudio();
+
+// Enable/disable video
+await convaiClient.videoControls.enableVideo();
+await convaiClient.videoControls.disableVideo();
+
+// Toggle screen share
+await convaiClient.screenShareControls.toggleScreenShare();
+```
+
+### Session Management
+
+```tsx
+// Reset session (clears history)
+convaiClient.resetSession();
+
+// Disconnect
+await convaiClient.disconnect();
+
+// Reconnect with new session
+await convaiClient.connect(config);
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions. Import types as needed:
+
+```tsx
+import {
+  ConvaiClient,
+  ConvaiConfig,
+  ConvaiClientState,
+  ChatMessage,
+} from "@convai/web-sdk";
+```
+
+## License
+
+MIT

package/dist/components/RTCWidget.d.ts

@@ -0,0 +1,56 @@
+import { ConvaiClient } from "../types";
+interface RTCWidgetProps {
+    convaiClient: ConvaiClient & {
+        activity?: string;
+    };
+    apiKey: string;
+    characterId?: string;
+    enableVideo?: boolean;
+    enableAudio?: boolean;
+    url?: string;
+    startWithVideoOn?: boolean;
+}
+/**
+ * RTCWidget - A consolidated chat widget component for real-time conversations
+ *
+ * This component combines all chat UI functionality into a single, easy-to-use widget
+ * with an expandable/collapsible interface similar to modern chat widgets.
+ *
+ * Features:
+ * - Collapsed circular button with status indicator
+ * - Expandable/collapsible chat interface
+ * - Voice mode support
+ * - Real-time message streaming
+ * - Audio controls (mute/unmute)
+ * - Settings tray with session reset
+ * - Auto-connect on first click
+ *
+ * @param {RTCWidgetProps} props - Component props
+ * @param {ConvaiClient} props.convaiClient - Convai client instance
+ * @param {string} props.apiKey - Convai API key
+ * @param {string} props.characterId - Character ID to connect to
+ * @param {boolean} props.enableVideo - Enable video capability (default: false)
+ * @param {boolean} props.enableAudio - Enable audio (default: true)
+ * @param {boolean} props.startWithVideoOn - Start with video camera on when connecting (default: false)
+ * @param {string} props.url - Custom Convai URL
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const convaiClient = useConvaiClient();
+ *
+ *   return (
+ *     <RTCWidget
+ *       convaiClient={convaiClient}
+ *       apiKey="your-api-key"
+ *       characterId="360f1c86-c98a-11ef-82c5-42010a7be016"
+ *       enableVideo={true}
+ *       startWithVideoOn={false}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare const RTCWidget: React.FC<RTCWidgetProps>;
+export {};
+//# sourceMappingURL=RTCWidget.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RTCWidget.d.ts","sourceRoot":"","sources":["../../src/components/RTCWidget.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AA4CxC,UAAU,cAAc;IACtB,YAAY,EAAE,YAAY,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CAqoB9C,CAAC"}