@rqmii_immersive/agent-react-sdk 5.1.2 → 5.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rqmii_immersive/agent-react-sdk",
-  "version": "5.1.2",
+  "version": "5.2.0",
   "description": "Standalone React SDK for Rqmii Agent realtime sessions",
   "type": "module",
   "main": "./dist/index.cjs",

package/README.frameworks.md

@@ -1,244 +0,0 @@
-# Rqmii React Agent SDK - Framework Recipes
-
-This guide shows integration patterns for Vite, Next.js, and CRA.
-
-## 1. Vite
-
-### Install
-
-```bash
-npm install @rqmii_immersive/agent-react-sdk
-```
-
-### Env
-
-`.env`:
-
-```env
-VITE_AGENT_API_URL=https://api.example.com
-VITE_AGENT_WS_URL=wss://realtime.example.com
-```
-
-### App Example
-
-```jsx
-import {
-  RqmiiAgentRoom,
-  useRqmiiMessages,
-} from "@rqmii_immersive/agent-react-sdk";
-
-function UI() {
-  const { sendTextMessage } = useRqmiiMessages();
-  return <button onClick={() => sendTextMessage("Hi")}>Send</button>;
-}
-
-export default function App() {
-  return (
-    <RqmiiAgentRoom
-      wsUrl={import.meta.env.VITE_AGENT_WS_URL}
-      restUrl={import.meta.env.VITE_AGENT_API_URL}
-      session={{ mode: "initialize", apiKey: "YOUR_API_KEY", language: "en" }}
-      connect
-    >
-      <UI />
-    </RqmiiAgentRoom>
-  );
-}
-```
-
-## 2. Next.js (App Router)
-
-Use client components for SDK usage.
-
-### Install
-
-```bash
-npm install @rqmii_immersive/agent-react-sdk
-```
-
-### Env
-
-`.env.local`:
-
-```env
-NEXT_PUBLIC_AGENT_API_URL=https://api.example.com
-NEXT_PUBLIC_AGENT_WS_URL=wss://realtime.example.com
-```
-
-### Client Component
-
-`app/agent/page.jsx`:
-
-```jsx
-"use client";
-
-import {
-  RqmiiAgentRoom,
-  useRqmiiConnection,
-  useRqmiiMessages,
-} from "@rqmii_immersive/agent-react-sdk";
-
-function UI() {
-  const { connectionState } = useRqmiiConnection();
-  const { messages, sendTextMessage } = useRqmiiMessages();
-
-  return (
-    <div>
-      <div>{connectionState}</div>
-      <button onClick={() => sendTextMessage("Hello")}>Send</button>
-      <pre>{JSON.stringify(messages, null, 2)}</pre>
-    </div>
-  );
-}
-
-export default function AgentPage() {
-  return (
-    <RqmiiAgentRoom
-      wsUrl={process.env.NEXT_PUBLIC_AGENT_WS_URL}
-      restUrl={process.env.NEXT_PUBLIC_AGENT_API_URL}
-      session={{ mode: "initialize", apiKey: "YOUR_API_KEY", language: "en" }}
-      connect
-    >
-      <UI />
-    </RqmiiAgentRoom>
-  );
-}
-```
-
-### Next.js Notes
-
-- Do not use SDK in server components.
-- Keep all SDK consumers under `'use client'`.
-- For cloud avatar player, render it only on client.
-
-## 3. Create React App (CRA)
-
-### Install
-
-```bash
-npm install @rqmii_immersive/agent-react-sdk
-```
-
-### Env
-
-`.env`:
-
-```env
-REACT_APP_AGENT_API_URL=https://api.example.com
-REACT_APP_AGENT_WS_URL=wss://realtime.example.com
-```
-
-### App Example
-
-```jsx
-import {
-  RqmiiAgentRoom,
-  useRqmiiMessages,
-} from "@rqmii_immersive/agent-react-sdk";
-
-function UI() {
-  const { sendTextMessage } = useRqmiiMessages();
-  return <button onClick={() => sendTextMessage("Hello")}>Send</button>;
-}
-
-export default function App() {
-  return (
-    <RqmiiAgentRoom
-      wsUrl={process.env.REACT_APP_AGENT_WS_URL}
-      restUrl={process.env.REACT_APP_AGENT_API_URL}
-      session={{ mode: "initialize", apiKey: "YOUR_API_KEY", language: "en" }}
-      connect
-    >
-      <UI />
-    </RqmiiAgentRoom>
-  );
-}
-```
-
-## 4. Common Recipes
-
-### Cloud Avatar
-
-```jsx
-import {
-  RqmiiCloudAvatarPlayer,
-  useRqmiiAvatar,
-} from "@rqmii_immersive/agent-react-sdk";
-
-function AvatarPanel() {
-  const { cloudStreamState, isAvatarSpeaking } = useRqmiiAvatar();
-  return (
-    <>
-      <div>stream: {cloudStreamState}</div>
-      <div>speaking: {String(isAvatarSpeaking)}</div>
-      <RqmiiCloudAvatarPlayer muted={false} />
-    </>
-  );
-}
-```
-
-### Desktop Avatar Join
-
-```jsx
-<RqmiiAgentRoom
-  wsUrl={WS_URL}
-  restUrl={REST_URL}
-  session={{ mode: "join_desktop", uniqueId: "A1B2C3" }}
-  connect
->
-  <UI />
-</RqmiiAgentRoom>
-```
-
-### Manual Provider Control
-
-```jsx
-import {
-  RqmiiAgentProvider,
-  useRqmiiConnection,
-} from "@rqmii_immersive/agent-react-sdk";
-
-function Controls() {
-  const { initializeSession, disconnect } = useRqmiiConnection();
-  return (
-    <>
-      <button
-        onClick={() => initializeSession({ apiKey: "KEY", language: "en" })}
-      >
-        Init
-      </button>
-      <button onClick={disconnect}>Disconnect</button>
-    </>
-  );
-}
-
-export default function App() {
-  return (
-    <RqmiiAgentProvider wsUrl={WS_URL} restUrl={REST_URL}>
-      <Controls />
-    </RqmiiAgentProvider>
-  );
-}
-```
-
-## 5. Troubleshooting by Framework
-
-### Vite
-
-- Ensure env keys start with `VITE_`.
-- Restart dev server after env changes.
-
-### Next.js
-
-- Ensure page/component is client-side (`'use client'`).
-- Use `NEXT_PUBLIC_` env keys.
-
-### CRA
-
-- Ensure env keys start with `REACT_APP_`.
-- Restart `npm start` after env changes.
-
-## 6. Where to Read More
-
-- Full technical docs: `README.md`
-- Quick docs: `README.simple.md`

package/README.md

@@ -1,168 +0,0 @@
-# @rqmii_immersive/agent-react-sdk
-
-Standalone React SDK for Rqmii Agent realtime sessions. Version 4.0.0 — complete TypeScript rewrite with reducer-based state management and event emitter system.
-
-## Installation
-
-```bash
-npm install @rqmii_immersive/agent-react-sdk
-```
-
-### Peer Dependencies
-
-```bash
-npm install react react-dom lucide-react
-# Optional (for 3D orb):
-npm install three @react-three/fiber @react-three/drei
-```
-
-## Quick Start
-
-### Core Setup
-
-```tsx
-import { RqmiiAgentProvider, useRqmiiConnection, useRqmiiMessages } from '@rqmii_immersive/agent-react-sdk';
-
-function App() {
-  return (
-    <RqmiiAgentProvider wsUrl="wss://your-server" restUrl="https://your-api">
-      <Chat />
-    </RqmiiAgentProvider>
-  );
-}
-
-function Chat() {
-  const { initializeSession, isConnected } = useRqmiiConnection();
-  const { messages, sendTextMessage } = useRqmiiMessages();
-
-  return (
-    <div>
-      {messages.map(m => <div key={m.id}>{m.text}</div>)}
-      <button onClick={() => sendTextMessage("Hello")}>Send</button>
-    </div>
-  );
-}
-```
-
-### Using RqmiiAgentRoom (auto-connect)
-
-```tsx
-import { RqmiiAgentRoom, useRqmiiMessages } from '@rqmii_immersive/agent-react-sdk';
-
-function App() {
-  return (
-    <RqmiiAgentRoom
-      wsUrl="wss://your-server"
-      restUrl="https://your-api"
-      session={{ apiKey: 'your-key', language: 'en' }}
-    >
-      <Chat />
-    </RqmiiAgentRoom>
-  );
-}
-```
-
-### Full Chat Widget
-
-```tsx
-import { RqmiiAgentChat } from '@rqmii_immersive/agent-react-sdk/ui';
-
-function App() {
-  return (
-    <RqmiiAgentChat
-      wsUrl="wss://your-server"
-      restUrl="https://your-api"
-      publicChatId="your-chat-id"
-    />
-  );
-}
-```
-
-## Architecture
-
-### Entry Points
-
-- `@rqmii_immersive/agent-react-sdk` — Core: provider, hooks, types, constants
-- `@rqmii_immersive/agent-react-sdk/ui` — UI components: chat widget, avatar player, orb
-- `@rqmii_immersive/agent-react-sdk/style.css` — Chat widget styles
-
-### State Management
-
-State is managed via `useReducer` with a single `RqmiiState` shape. All mutations go through typed actions.
-
-### Event System
-
-The provider exposes an `events` EventEmitter for subscribing to lifecycle events:
-
-```tsx
-import { useRqmiiAgent } from '@rqmii_immersive/agent-react-sdk';
-
-function Component() {
-  const { events } = useRqmiiAgent();
-
-  useEffect(() => {
-    const unsub = events.on('session:ready', (payload) => {
-      console.log('Session ready', payload);
-    });
-    return unsub;
-  }, []);
-}
-```
-
-Available events: `session:ready`, `session:joined`, `session:terminated`, `session:expired`, `message:received`, `message:sent`, `audio:playing`, `audio:stopped`, `avatar:speaking`, `avatar:speaking_done`, `state:changed`, `connection:connected`, `connection:disconnected`, `connection:reconnecting`, `connection:failed`, `error`, `credits:exhausted`, `transcript`, `partial_transcript`, `interrupted`.
-
-## API Reference
-
-### RqmiiAgentProvider Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `wsUrl` | `string` | required | WebSocket server URL |
-| `restUrl` | `string` | required | REST API base URL |
-| `reconnectOptions` | `RqmiiReconnectOptions` | `{ enabled: true, maxAttempts: 8, initialDelayMs: 500, maxDelayMs: 5000, timeoutMs: 8000 }` | Reconnection config |
-| `enableAudio` | `boolean` | `true` | Enable PCM audio playback |
-| `pcmOptions` | `RqmiiPCMOptions` | `{ encoding: '16bitInt', channels: 1, sampleRate: 16000 }` | PCM player config |
-| `debug` | `boolean` | `false` | Enable debug logging |
-| `withCredentials` | `boolean` | `false` | Include cookies in CORS requests |
-| `heartbeatIntervalSeconds` | `number` | `15` | Heartbeat interval |
-| `onSessionExpired` | `(payload?) => void` | — | Callback |
-| `onSessionTerminated` | `() => void` | — | Callback |
-| `onError` | `(payload?) => void` | — | Callback |
-| `onDisconnect` | `(reason?) => void` | — | Callback |
-| `onReconnectSuccess` | `(payload?) => void` | — | Callback |
-| `onReconnectFailed` | `(payload?) => void` | — | Callback |
-
-### Hooks
-
-| Hook | Returns |
-|------|---------|
-| `useRqmiiAgent()` | Full context value |
-| `useRqmiiConnection()` | Connection state + session actions |
-| `useRqmiiSession()` | Session state booleans |
-| `useRqmiiMessages()` | Messages array + send/clear |
-| `useRqmiiVoice()` | Audio controls + transcript |
-| `useRqmiiAvatar()` | Avatar state + cloud stream |
-| `useRqmiiAudioElement(ref)` | Attaches audio element |
-| `useRqmiiPressToTalk(options)` | PTT recording |
-| `useRqmiiVAD(options)` | Voice Activity Detection |
-| `useRqmiiEvents(event, handler, deps)` | Event subscription |
-
-## Breaking Changes from v3
-
-1. **`useRqmiiSessionState` renamed to `useRqmiiSession`** — The hook is now `useRqmiiSession()`.
-
-2. **Context value spread** — The context value now includes all state fields directly (no nested `state` object). Access `ctx.messages` instead of `ctx.state.messages`.
-
-3. **Event emitter replaces some callbacks** — While legacy callbacks (`onSessionExpired`, etc.) still work, the preferred approach is using `events.on()`.
-
-4. **TypeScript only** — All source is now `.ts`/`.tsx`. JavaScript consumers get full type inference via bundled `.d.ts` files.
-
-5. **`terminateSession` return type simplified** — Now returns `Promise<{ success: boolean }>` instead of the previous shape with `skipped` and `error` fields.
-
-6. **`useRqmiiVAD` return** — Added `isErrored` field to match the VAD library's state.
-
-7. **Internal module structure changed** — If you were importing from internal paths (e.g., `@rqmii_immersive/agent-react-sdk/react/core/...`), those paths no longer exist. Use the public exports only.
-
-## License
-
-UNLICENSED

package/README.simple.md

@@ -1,114 +0,0 @@
-# Rqmii React Agent SDK (Simple Guide)
-
-Minimal guide to integrate quickly.
-
-## Install
-
-```bash
-npm install @rqmii_immersive/agent-react-sdk
-```
-
-## Required Config
-
-You need:
-
-- `restUrl` -> REST API URL
-- `wsUrl` -> realtime Socket.IO URL
-
-Example env:
-
-```env
-VITE_AGENT_API_URL=https://api.example.com
-VITE_AGENT_WS_URL=wss://realtime.example.com
-```
-
-## Basic Usage
-
-```jsx
-import {
-  RqmiiAgentRoom,
-  useRqmiiConnection,
-  useRqmiiMessages,
-  useRqmiiPressToTalk,
-} from "@rqmii_immersive/agent-react-sdk";
-
-function ChatUI() {
-  const { connectionState, isSessionReady, error } = useRqmiiConnection();
-  const { messages, sendTextMessage } = useRqmiiMessages();
-  const { eventHandlers, isRecording } = useRqmiiPressToTalk();
-
-  return (
-    <div>
-      <div>{connectionState}</div>
-      <div>ready: {String(isSessionReady)}</div>
-      {error && <div style={{ color: "red" }}>{error}</div>}
-
-      <button onClick={() => sendTextMessage("Hello")}>Send</button>
-      <button {...eventHandlers}>
-        {isRecording ? "Recording..." : "Hold to Talk"}
-      </button>
-      <pre>{JSON.stringify(messages, null, 2)}</pre>
-    </div>
-  );
-}
-
-export default function App() {
-  return (
-    <RqmiiAgentRoom
-      wsUrl={import.meta.env.VITE_AGENT_WS_URL}
-      restUrl={import.meta.env.VITE_AGENT_API_URL}
-      session={{ mode: "initialize", apiKey: "YOUR_API_KEY", language: "en" }}
-      connect
-    >
-      <ChatUI />
-    </RqmiiAgentRoom>
-  );
-}
-```
-
-## Cloud Avatar
-
-```jsx
-import {
-  RqmiiCloudAvatarPlayer,
-  useRqmiiAvatar,
-} from "@rqmii_immersive/agent-react-sdk";
-
-function CloudAvatarUI() {
-  const { isAvatarSpeaking, cloudStreamState } = useRqmiiAvatar();
-
-  return (
-    <>
-      <div>speaking: {String(isAvatarSpeaking)}</div>
-      <div>stream: {cloudStreamState}</div>
-      <RqmiiCloudAvatarPlayer muted={false} />
-    </>
-  );
-}
-```
-
-## Desktop Avatar Join
-
-```jsx
-<RqmiiAgentRoom
-  wsUrl={WS_URL}
-  restUrl={REST_URL}
-  session={{ mode: "join_desktop", uniqueId: "A1B2C3" }}
-  connect
->
-  <YourUI />
-</RqmiiAgentRoom>
-```
-
-## Voice Input / Output
-
-- send mic chunks: `sendAudioChunk(chunk)`
-- end utterance: `endAudioStream()`
-- interrupt: `interrupt()`
-- SDK plays output audio internally using `pcm-stream-player`
-
-## Notes
-
-- Reconnection is built-in and follows backend reconnect credential flow.
-- Avatar speaking state comes from backend avatar events.
-- For full docs, see `README.md`.