@rqmii_immersive/agent-react-sdk 5.6.8 → 5.6.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rqmii Immersive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# @rqmii_immersive/agent-react-sdk
+
+[![npm version](https://img.shields.io/npm/v/@rqmii_immersive/agent-react-sdk.svg)](https://www.npmjs.com/package/@rqmii_immersive/agent-react-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Standalone React SDK for **Rqmii Agent** realtime multimodal AI sessions. Power your web applications with interactive conversational AI agents featuring text chat, streaming low-latency voice, and 3D cloud-streamed avatars.
+
+---
+
+## Features
+
+- 💬 **Ready-to-use Chat Widget**: `<RqmiiAgentChat />` with custom theming, accent colors, multi-language support (40+ languages), feedback ratings, and markdown rendering.
+- 🚀 **Next.js & SEO Optimized**: `<RqmiiAgentChatLazy />` from `@rqmii_immersive/agent-react-sdk/lazy` provides on-demand dynamic importing with zero impact on Core Web Vitals (LCP/INP) and crawler HTML.
+- 🎙️ **Realtime Voice & Audio**: Low-latency PCM stream playback, microphone capture, Push-To-Talk (`useRqmiiPressToTalk`), and Voice Activity Detection (`useRqmiiVAD`).
+- 🤖 **Interactive Cloud Avatars**: Cloud-rendered 3D avatar streaming powered by Unreal Engine Pixel Streaming (`RqmiiCloudAvatarPlayer`) and interactive 3D WebGL Orb.
+- 🧩 **Headless Hooks & Provider**: Build custom AI interfaces with granular hooks (`useRqmiiAgent`, `useRqmiiConnection`, `useRqmiiMessages`, `useRqmiiVoice`, `useRqmiiAvatar`, `useRqmiiEvents`).
+- 🔄 **Built-in Resilience**: Automatic reconnection with exponential backoff, state recovery, and typed event emitter system.
+- 📦 **Full TypeScript Support**: Built entirely in TypeScript with complete type definitions included.
+
+---
+
+## Installation
+
+```bash
+npm install @rqmii_immersive/agent-react-sdk
+```
+
+### Peer Dependencies
+
+Install the required peer dependencies in your React project:
+
+```bash
+npm install react react-dom lucide-react
+```
+
+> **Note:** If you use the 3D Orb component, install the optional 3D dependencies:
+> ```bash
+> npm install three @react-three/fiber @react-three/drei
+> ```
+
+---
+
+## Quick Start
+
+### 1. Ready-to-Use Chat Widget
+
+Import the widget and its stylesheet to add a fully-featured AI chat to your app:
+
+```tsx
+import '@rqmii_immersive/agent-react-sdk/style.css';
+import { RqmiiAgentChat } from '@rqmii_immersive/agent-react-sdk/ui';
+
+export default function App() {
+  return (
+    <RqmiiAgentChat
+      publicChatId="YOUR_PUBLIC_CHAT_ID"
+      // Optional: custom backend endpoints (defaults to production Rqmii endpoints)
+      // wsUrl="wss://your-ws-server"
+      // restUrl="https://your-api-server"
+    />
+  );
+}
+```
+
+### 2. Next.js / Performance-Friendly Lazy Widget
+
+For marketing and landing pages where SEO and Core Web Vitals matter, load the chat widget lazily:
+
+```tsx
+'use client';
+
+import '@rqmii_immersive/agent-react-sdk/style.css';
+import { RqmiiAgentChatLazy } from '@rqmii_immersive/agent-react-sdk/lazy';
+
+export default function AgentWidget() {
+  return (
+    <RqmiiAgentChatLazy
+      publicChatId="YOUR_PUBLIC_CHAT_ID"
+      loadOn="idle" // Options: 'idle' | 'load' | 'interaction' | 'immediate'
+    />
+  );
+}
+```
+
+| `loadOn` Strategy | Behavior |
+| ----------------- | -------- |
+| `idle` (default)  | Downloads when the browser is idle after page load. |
+| `load`            | Downloads immediately after the window `load` event. |
+| `interaction`     | Downloads on the first user interaction (pointer, scroll, touch, key). |
+| `immediate`       | Downloads on component mount. |
+
+### 3. Auto-Connecting Room (`RqmiiAgentRoom`)
+
+If you are building your own UI but want automated session connection and state management:
+
+```tsx
+import { RqmiiAgentRoom, useRqmiiMessages, useRqmiiConnection } from '@rqmii_immersive/agent-react-sdk';
+
+function ChatUI() {
+  const { connectionState, isConnected } = useRqmiiConnection();
+  const { messages, sendTextMessage } = useRqmiiMessages();
+
+  return (
+    <div>
+      <p>Status: {connectionState}</p>
+      <div className="messages">
+        {messages.map((m) => (
+          <div key={m.id} className={m.role}>
+            <strong>{m.role}: </strong>{m.text}
+          </div>
+        ))}
+      </div>
+      <button onClick={() => sendTextMessage('Hello!')}>Send</button>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <RqmiiAgentRoom
+      wsUrl="wss://your-ws-server"
+      restUrl="https://your-api-server"
+      session={{ mode: 'initialize', apiKey: 'YOUR_API_KEY', language: 'en' }}
+      connect
+    >
+      <ChatUI />
+    </RqmiiAgentRoom>
+  );
+}
+```
+
+### 4. Cloud Avatar Streaming
+
+Stream high-fidelity Unreal Engine cloud avatars with low latency:
+
+```tsx
+import {
+  RqmiiAgentRoom,
+  RqmiiCloudAvatarPlayer,
+  useRqmiiAvatar,
+} from '@rqmii_immersive/agent-react-sdk';
+
+function AvatarView() {
+  const { cloudStreamState, isAvatarSpeaking } = useRqmiiAvatar();
+
+  return (
+    <div>
+      <div>Stream State: {cloudStreamState}</div>
+      <div>Avatar Speaking: {isAvatarSpeaking ? 'Yes' : 'No'}</div>
+      <RqmiiCloudAvatarPlayer muted={false} />
+    </div>
+  );
+}
+```
+
+---
+
+## Package Entry Points
+
+| Entry Point | Content |
+| ----------- | ------- |
+| `@rqmii_immersive/agent-react-sdk` | Core provider (`RqmiiAgentProvider`), `RqmiiAgentRoom`, headless hooks, constants, types, and audio capture. |
+| `@rqmii_immersive/agent-react-sdk/ui` | Pre-built UI components: `<RqmiiAgentChat>`, preview widgets, markdown renderer, language tools, avatar players. |
+| `@rqmii_immersive/agent-react-sdk/lazy` | Code-split lazy chat launcher `<RqmiiAgentChatLazy>` for Next.js & SSR frameworks. |
+| `@rqmii_immersive/agent-react-sdk/style.css` | Default styles for the chat interface and UI components. |
+
+---
+
+## Hooks Reference
+
+| Hook | Purpose |
+| ---- | ------- |
+| `useRqmiiAgent()` | Full SDK context value and state. |
+| `useRqmiiConnection()` | Connection status, session state, `initializeSession`, `joinDesktopSession`, and `disconnect`. |
+| `useRqmiiSession()` | Boolean flags for session lifecycle (`isInitializing`, `isSessionReady`, `isTerminating`, `isExpired`). |
+| `useRqmiiMessages()` | Message history (`messages`), `sendTextMessage`, and `clearMessages`. |
+| `useRqmiiVoice()` | Voice controls: `sendAudioChunk`, `endAudioStream`, `interrupt`, and live transcript state. |
+| `useRqmiiAvatar()` | Cloud avatar streaming state and speaking indicators. |
+| `useRqmiiPressToTalk(options)` | Push-To-Talk microphone recorder handlers and recording state. |
+| `useRqmiiVAD(options)` | Voice Activity Detection (VAD) with automatic utterance boundaries. |
+| `useRqmiiEvents(event, handler, deps)` | Typed subscription to SDK lifecycle and realtime events. |
+| `useRqmiiAudioElement(ref)` | Connects output audio playback to an HTMLAudioElement. |
+
+---
+
+## Event System
+
+Subscribe to realtime SDK events using `useRqmiiEvents` or the `events` emitter from `useRqmiiAgent`:
+
+```tsx
+import { useRqmiiEvents } from '@rqmii_immersive/agent-react-sdk';
+
+function EventLogger() {
+  useRqmiiEvents('message:received', (message) => {
+    console.log('New message received:', message);
+  });
+
+  useRqmiiEvents('session:ready', (data) => {
+    console.log('Session is ready:', data);
+  });
+
+  useRqmiiEvents('credits:exhausted', () => {
+    console.warn('Credits exhausted');
+  });
+
+  return null;
+}
+```
+
+Supported events: `session:ready`, `session:joined`, `session:terminated`, `session:expired`, `message:received`, `message:sent`, `audio:playing`, `audio:stopped`, `avatar:speaking`, `avatar:speaking_done`, `connection:connected`, `connection:disconnected`, `connection:reconnecting`, `connection:failed`, `transcript`, `partial_transcript`, `interrupted`, `credits:exhausted`, `error`.
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rqmii_immersive/agent-react-sdk",
-  "version": "5.6.8",
+  "version": "5.6.9",
   "description": "Standalone React SDK for Rqmii Agent realtime sessions",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -27,7 +27,9 @@
     "./style.css": "./dist/agent-react-sdk.css"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
   "sideEffects": [
     "*.css",
@@ -94,5 +96,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "UNLICENSED"
+  "license": "MIT"
 }