@wix/legends-platform-sdk 1.16.0 → 1.17.0

package/README.md

@@ -16,24 +16,23 @@ The SDK exposes two entry points:
 
 | Entry point | What's inside |
 |---|---|
-| `@wix/legends-platform-sdk` | Types, hooks for text chat and conversation state (`useTextChat`, `useConversationEvents`, `useMicrophone`, `useSpeaker`, `useCamera`, etc.) |
+| `@wix/legends-platform-sdk` | Types and server-safe hooks (`useTextChat`, `useConversationEvents`, `useMicrophone`, `useSpeaker`, `useCamera`, etc.) — no LiveKit dependency |
 | `@wix/legends-platform-sdk/livekit/sdk` | Everything above **+** `LegendsPlatform`, `useConversation`, `useScreenShare`, `useParticipantTrack`, `useSpeechActivityDetector`, `useAudioLevel` |
 
-Use the main entry when you only need types or non-livekit hooks (e.g. in server-side code or Jest tests). Use `livekit/sdk` for React components and hooks that require an active LiveKit room.
+Use the main entry when you only need types or hooks without a LiveKit room (e.g. server-side code or Jest tests). Use `livekit/sdk` for React components and live conversation hooks.
 
 ---
 
 ## Quick Start
 
-Store the raw namespace API key returned by MCP onboarding in `.env.local`:
+Get a namespace API key from the Legends Platform team, then store it in `.env.local`:
 
 ```bash
-VITE_LEGENDS_NAMESPACE=your-namespace
-VITE_LEGENDS_API_KEY=lp_your_raw_api_key
-VITE_LEGENDS_CHAT_ID=your-chat-id
+LEGENDS_API_KEY=lp_your_raw_api_key
+LEGENDS_CHAT_ID=your-chat-id
 ```
 
-Wrap your app with `LegendsPlatform` and pass those values:
+Wrap your app with `LegendsPlatform`. External apps use `HEADLESS` as the namespace value:
 
 ```tsx
 import { LegendsPlatform, useConversation, useMicrophone } from '@wix/legends-platform-sdk/livekit/sdk';
@@ -61,9 +60,9 @@ function VoiceButton() {
 export default function App() {
   return (
     <LegendsPlatform
-      chatId={import.meta.env.VITE_LEGENDS_CHAT_ID}
-      namespace={import.meta.env.VITE_LEGENDS_NAMESPACE}
-      apiKey={import.meta.env.VITE_LEGENDS_API_KEY}
+      chatId="your-chat-id"
+      namespace="HEADLESS"
+      apiKey="lp_your_api_key"
     >
       <VoiceButton />
     </LegendsPlatform>
@@ -81,15 +80,14 @@ The root context provider. Must wrap all SDK hooks and components.
 |------|------|-------------|
 | `chatId` | `string` | Required. The chat instance ID |
 | `namespace` | `string` | Required. Your namespace |
-| `apiKey` | `string` | API key for authentication (external apps) |
-| `personaChatService` | `IPersonaChatService` | Custom service implementation (advanced) |
+| `apiKey` | `string` | Raw namespace API key — pass `lp_...` as-is, the SDK sends it as `Authorization: Api-Key <token>` |
+| `personaChatService` | `IPersonaChatService` | Custom service for advanced use cases (see below) |
+| `tools` | `ToolsRegistry` | Optional client-side tool handlers |
 | `queryClient` | `QueryClient` | Optional TanStack Query client |
 | `children` | `ReactNode` | Required |
 
 Either `apiKey` or `personaChatService` must be provided.
 
-Pass the raw namespace key as `apiKey`, for example `lp_...`. The SDK sends it as `Authorization: Api-Key <token>`.
-
 ---
 
 ### Hooks
@@ -139,6 +137,21 @@ const { messages, status, send, fetchNext } = useTextChat();
 await send({ message: 'Hello' });
 ```
 
+#### `useTextChatStream(options)`
+
+Streaming counterpart to `useTextChat`. Sends messages over SSE and drips the assistant reply into `streamingText` at a steady rate via `requestAnimationFrame`.
+
+```tsx
+const { messages, status, send } = useTextChatStream({
+  onError: (err) => console.error(err),
+  revealMsPerChar: 16, // ms per character, default 16 (~62 chars/s)
+});
+
+// messages[n].streamStatus === 'streaming' while the reply is in-flight
+const result = await send({ message: 'Hello' });
+// result: { ok: boolean, producedContent: boolean, aborted: boolean }
+```
+
 #### `useConversationStatus()`
 
 ```tsx
@@ -155,10 +168,10 @@ const { elapsed, remaining } = useConversationTimer();
 
 #### `useTools()`
 
-Read the list of tool calls executed by the SDK. To register tool handlers, pass a `tools` registry to `LegendsPlatform`.
+Observe client-side tool calls executed by the SDK. Register tool handlers by passing a `tools` registry to `LegendsPlatform`.
 
 ```tsx
-import { LegendsPlatform, useTools, type ToolsRegistry } from '@wix/legends-platform-sdk';
+import { LegendsPlatform, useTools, type ToolsRegistry } from '@wix/legends-platform-sdk/livekit/sdk';
 
 const tools: ToolsRegistry = {
   get_weather: async ({ city }) => {
@@ -172,25 +185,14 @@ function ToolLog() {
   return <pre>{JSON.stringify(calls, null, 2)}</pre>;
 }
 
-return (
-  <LegendsPlatform ... tools={tools}>
-    <ToolLog />
-  </LegendsPlatform>
-);
-```
-
-#### `useTextChatStream(options)`
-
-Streaming counterpart to `useTextChat`. Sends messages over SSE and drips the assistant reply into `streamingText` at a steady rate via `requestAnimationFrame`.
-
-```tsx
-const { messages, send } = useTextChatStream({
-  streamUrl: '/api/chat/stream',
-  onError: (err) => console.error(err),
-});
-
-// messages[n].streamStatus === 'streaming' while the reply is in-flight
-await send({ message: 'Hello' });
+<LegendsPlatform
+  chatId="your-chat-id"
+  namespace="HEADLESS"
+  apiKey="lp_your_api_key"
+  tools={tools}
+>
+  <ToolLog />
+</LegendsPlatform>
 ```
 
 #### `useSpeechActivityDetector(options)`
@@ -211,21 +213,25 @@ useSpeechActivityDetector({
 
 ## Advanced: Custom Service
 
-For advanced use cases, inject a custom `IPersonaChatService` instead of using `apiKey`:
+For advanced integration, inject a custom `IPersonaChatService` instead of `apiKey`. Your implementation owns authentication and must forward valid credentials on every request.
 
 ```tsx
 import { LegendsPlatform } from '@wix/legends-platform-sdk/livekit/sdk';
 import type { IPersonaChatService } from '@wix/legends-platform-sdk';
 
 const myService: IPersonaChatService = {
-  async createVoiceConversation(params) { ... },
-  async createInteractiveConversation(params) { ... },
-  async endInteractiveConversation(params) { ... },
-  async sendChatMessage(params) { ... },
-  async queryChatMessages(params) { ... },
+  async createVoiceConversation(params) { /* ... */ },
+  async createInteractiveConversation(params) { /* ... */ },
+  async endInteractiveConversation(params) { /* ... */ },
+  async sendChatMessage(params) { /* ... */ },
+  async queryChatMessages(params) { /* ... */ },
 };
 
-<LegendsPlatform personaChatService={myService} ...>
+<LegendsPlatform
+  chatId="your-chat-id"
+  namespace="your-namespace"
+  personaChatService={myService}
+>
   ...
 </LegendsPlatform>
 ```

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.16.0",
+  "version": "1.17.0",
   "name": "@wix/legends-platform-sdk",
   "license": "MIT",
   "author": {
@@ -103,5 +103,5 @@
   "wallaby": {
     "autoDetect": true
   },
-  "falconPackageHash": "f9a5891b405ebfa64741ade86c1a924e1e787822a89b42952a939184"
+  "falconPackageHash": "00f289d892a702bdfe7fe6700d234d05983ad90ae438862ab75a68c9"
 }