@convai/web-sdk 0.2.3 → 0.2.4

package/README.md

@@ -79,6 +79,163 @@ function App() {
 
 **That's it!** The widget auto-connects on first user interaction and handles all UI/audio for you.
 
+---
+
+## 🤖 For AI Code Generators (v0, Lovable, Bolt, etc.)
+
+**If you're using an AI coding assistant to add Convai to your project, use this exact template to avoid errors:**
+
+### Copy-Paste Template (Works Every Time)
+
+```tsx
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
+
+export default function App() {
+  // Step 1: Create the client with your credentials
+  const convaiClient = useConvaiClient({
+    apiKey: "your-api-key-here",
+    characterId: "your-character-id-here"
+  });
+
+  // Step 2: Pass ONLY the client to the widget
+  return <ConvaiWidget convaiClient={convaiClient} />;
+}
+```
+
+### Common Mistakes AI Tools Make
+
+❌ **DON'T DO THIS:**
+```tsx
+// Wrong: Passing props directly to ConvaiWidget
+<ConvaiWidget apiKey="..." characterId="..." />
+
+// Wrong: Stringifying the client
+<ConvaiWidget convaiClient={JSON.stringify(convaiClient)} />
+
+// Wrong: Spreading client properties
+<ConvaiWidget {...convaiClient} />
+
+// Wrong: Using client in string context
+const info = `Client: ${convaiClient}`; // "Cannot convert object to primitive value"
+
+// Wrong: Passing client through env vars
+const client = process.env.CONVAI_CLIENT; // This won't work
+```
+
+✅ **DO THIS:**
+```tsx
+// Correct: Client created in component, passed as object
+const convaiClient = useConvaiClient({
+  apiKey: "your-api-key",
+  characterId: "your-character-id"
+});
+
+return <ConvaiWidget convaiClient={convaiClient} />;
+```
+
+### If You Get "Cannot convert object to primitive value"
+
+This error means you're using the client object in a primitive context. Check for:
+
+1. **String concatenation:**
+   ```tsx
+   // ❌ Wrong
+   console.log("Client: " + convaiClient);
+   
+   // ✅ Correct
+   console.log("Connected:", convaiClient.state.isConnected);
+   ```
+
+2. **Template literals:**
+   ```tsx
+   // ❌ Wrong
+   const text = `Client: ${convaiClient}`;
+   
+   // ✅ Correct
+   const text = `Status: ${convaiClient.state.agentState}`;
+   ```
+
+3. **Using as a key:**
+   ```tsx
+   // ❌ Wrong
+   <div key={convaiClient}>...</div>
+   
+   // ✅ Correct
+   <div key="convai-widget">...</div>
+   ```
+
+### Complete Working Example for AI Tools
+
+```tsx
+import React from 'react';
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
+
+function App() {
+  // Initialize the client
+  const convaiClient = useConvaiClient({
+    apiKey: "your-api-key-here",
+    characterId: "your-character-id-here",
+    enableVideo: false, // Set to true if you need video
+  });
+
+  // Optional: Add debug logging
+  console.log("Convai client initialized:", !!convaiClient);
+  console.log("Connection status:", convaiClient?.state?.isConnected);
+
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <ConvaiWidget convaiClient={convaiClient} />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Prompt for AI Code Generators
+
+**Use this prompt to get correct code:**
+
+```
+Add Convai voice chat to this app using @convai/web-sdk.
+
+CRITICAL RULES:
+1. Import: import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
+2. Create client INSIDE component: const convaiClient = useConvaiClient({ apiKey: "...", characterId: "..." });
+3. Pass ONLY client to widget: <ConvaiWidget convaiClient={convaiClient} />
+4. DO NOT pass apiKey or characterId directly to ConvaiWidget
+5. DO NOT stringify, spread, or destructure the client object
+6. DO NOT use the client object in string contexts
+
+Example:
+const convaiClient = useConvaiClient({ apiKey: "KEY", characterId: "ID" });
+return <ConvaiWidget convaiClient={convaiClient} />;
+```
+
+### Video & Screen Share with AI Tools
+
+If you need video/screen share, add these TWO changes:
+
+```tsx
+// Step 1: Add enableVideo to client config
+const convaiClient = useConvaiClient({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
+  enableVideo: true  // ← Required for video features
+});
+
+// Step 2: Show controls in widget
+<ConvaiWidget 
+  convaiClient={convaiClient}
+  showVideo={true}           // ← Shows video button
+  showScreenShare={true}     // ← Shows screen share button
+/>
+```
+
+**Without `enableVideo: true`, video and screen share will NOT work even if you show the buttons.**
+
+
+
 ### Vanilla JS/TS - ConvaiWidget
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convai/web-sdk",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Convai Web SDK for AI voice assistants. Supports both React and vanilla JavaScript/TypeScript. Build voice-powered AI interactions with real-time audio/video streaming.",
   "private": false,
   "type": "module",