@facepe/widget-mobile-app 1.1.0 → 1.3.0

package/README.md

@@ -1,289 +1,344 @@
-# @facepe/widget-mobile-app
-
-The official **FacePe AI Digital Human Live Streaming SDK** for **React Native** (supporting both **iOS** and **Android**).
-
-Embed interactive, photorealistic, lip-synced 3D digital avatars directly inside your native mobile apps with pure WebRTC media streaming, native microphone capture, bidirectional voice dialog, and live data events — **without webviews**.
-
----
-
-## 📱 Features
-
-- **⚡ Native WebRTC Streaming**: Pure native media streaming powered by `@livekit/react-native` (no WebViews or embedded iframes).
-- **🗣️ Natural Two-Way Voice Dialog**: Real-time microphone capture with hardware echo cancellation, noise suppression, and server VAD.
-- **🍎 Full iOS Support**: Hardware-accelerated video decoding on iOS 13.0+ (iPhone & iPad).
-- **🤖 Full Android Support**: Hardware-accelerated video decoding on Android 7.0+ (API 24+).
-- **💬 Real-Time Transcriptions**: Bidirectional captions for avatar speech and user speech.
-- **🛒 Conversational Commerce**: Automatic detection of cart items, orders, and payment intents.
-- **🎛️ Imperative Controls**: Ref methods to start/stop stream, mute/unmute mic, speak text, or interrupt speech.
-
----
-
-## 📦 Installation
-
-In your React Native project:
-
-```bash
-npm install @facepe/widget-mobile-app @livekit/react-native @livekit/react-native-webrtc
-```
-
-*(or using yarn / pnpm)*:
-
-```bash
-yarn add @facepe/widget-mobile-app @livekit/react-native @livekit/react-native-webrtc
-```
-
----
-
-## 🛠️ Platform Permissions Setup
-
-### iOS Setup (`ios/Podfile` & `Info.plist`)
-
-1. Open `ios/YourAppName/Info.plist` and add permission strings for microphone and audio:
-
-```xml
-<key>NSMicrophoneUsageDescription</key>
-<string>We need access to your microphone to converse with the FacePe AI avatar.</string>
-<key>NSCameraUsageDescription</key>
-<string>Camera access for interactive features.</string>
-```
-
-2. Run CocoaPods:
-```bash
-cd ios && pod install && cd ..
-```
-
----
-
-### Android Setup (`android/app/src/main/AndroidManifest.xml`)
-
-Open `android/app/src/main/AndroidManifest.xml` and include permissions:
-
-```xml
-<uses-permission android:name="android.permission.INTERNET" />
-<uses-permission android:name="android.permission.RECORD_AUDIO" />
-<uses-permission android:name="android.permission.CAMERA" />
-<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
-<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
-```
-
----
-
-## 🚀 Quick Start Example
-
-### 1. Server-side Token Endpoint
-
-Exchange your `accessKey` and `secretKey` on your secure backend (Node.js / Express / Next.js / Python / Go) so credentials are never exposed inside mobile apps:
-
-```javascript
-// Express server route: GET /api/facepe-token
-app.get('/api/facepe-token', async (req, res) => {
-  const response = await fetch('https://api.facepe.ai/api/v1/sdk/token', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      accessKey: process.env.FACEPE_SDK_ACCESS_KEY,
-      secretKey: process.env.FACEPE_SDK_SECRET_KEY,
-      channel: 'sdk',
-    }),
-  });
-  const data = await response.json();
-  res.send(data.data.token);
-});
-```
-
----
-
-### 2. React Native Component
-
-```tsx
-import React, { useRef } from 'react';
-import { StyleSheet, View, SafeAreaView, Text, TouchableOpacity } from 'react-native';
-import {
-  FacePeMobileProvider,
-  FacePeMobileAvatar,
-  FacePeMobileAvatarRef,
-  useFacePeAvatar,
-} from '@facepe/widget-mobile-app';
-
-export default function App() {
-  const avatarRef = useRef<FacePeMobileAvatarRef>(null);
-
-  return (
-    <SafeAreaView style={styles.container}>
-      <Text style={styles.title}>FacePe AI Native Digital Human</Text>
-
-      <FacePeMobileProvider
-        apiBaseUrl="https://api.facepe.ai/api/v1/sdk"
-        getToken={async () => {
-          const res = await fetch('https://your-backend.com/api/facepe-token');
-          return await res.text();
-        }}
-      >
-        <AvatarScreen avatarRef={avatarRef} />
-      </FacePeMobileProvider>
-    </SafeAreaView>
-  );
-}
-
-function AvatarScreen({ avatarRef }: { avatarRef: React.RefObject<FacePeMobileAvatarRef> }) {
-  const { transcripts, isAvatarSpeaking, avatarProps } = useFacePeAvatar();
-
-  return (
-    <View style={styles.content}>
-      <View style={styles.avatarContainer}>
-        <FacePeMobileAvatar
-          ref={avatarRef}
-          language="en"
-          objectFit="cover"
-          autoStart={true}
-          enableMic={true}
-          {...avatarProps}
-        />
-      </View>
-
-      {/* Control bar */}
-      <View style={styles.controls}>
-        <TouchableOpacity
-          style={styles.button}
-          onPress={() => avatarRef.current?.toggleMic()}
-        >
-          <Text style={styles.buttonText}>Toggle Mic</Text>
-        </TouchableOpacity>
-
-        <TouchableOpacity
-          style={styles.button}
-          onPress={() => avatarRef.current?.interrupt()}
-        >
-          <Text style={styles.buttonText}>Interrupt</Text>
-        </TouchableOpacity>
-      </View>
-
-      {/* Real-time speech transcript log */}
-      <View style={styles.transcriptBox}>
-        {transcripts.slice(-3).map((item, idx) => (
-          <Text key={idx} style={styles.transcriptLine}>
-            <Text style={item.role === 'assistant' ? styles.avatarTag : styles.userTag}>
-              {item.role === 'assistant' ? 'Avatar: ' : 'You: '}
-            </Text>
-            {item.text}
-          </Text>
-        ))}
-      </View>
-    </View>
-  );
-}
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    backgroundColor: '#0F172A',
-  },
-  content: {
-    flex: 1,
-    padding: 16,
-  },
-  title: {
-    color: '#FFFFFF',
-    fontSize: 20,
-    fontWeight: 'bold',
-    textAlign: 'center',
-    marginVertical: 12,
-  },
-  avatarContainer: {
-    flex: 1,
-    borderRadius: 24,
-    overflow: 'hidden',
-    backgroundColor: '#1E293B',
-  },
-  controls: {
-    flexDirection: 'row',
-    justifyContent: 'center',
-    gap: 12,
-    marginVertical: 14,
-  },
-  button: {
-    backgroundColor: '#7C3AED',
-    paddingHorizontal: 20,
-    paddingVertical: 10,
-    borderRadius: 12,
-  },
-  buttonText: {
-    color: '#FFFFFF',
-    fontWeight: '600',
-    fontSize: 14,
-  },
-  transcriptBox: {
-    backgroundColor: '#1E293B',
-    padding: 12,
-    borderRadius: 12,
-    minHeight: 80,
-  },
-  transcriptLine: {
-    color: '#E2E8F0',
-    fontSize: 13,
-    marginBottom: 4,
-  },
-  avatarTag: {
-    color: '#A78BFA',
-    fontWeight: '700',
-  },
-  userTag: {
-    color: '#60A5FA',
-    fontWeight: '700',
-  },
-});
-```
-
----
-
-## ⚙️ Props & Configuration
-
-### `<FacePeMobileAvatar />`
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `avatarKey` | `string` | *(optional)* | Specific avatar key or ID assigned to your company. |
-| `language` | `string` | `'en'` | Spoken language code (`'en'`, `'hi'`, `'es'`, `'ta'`, `'te'`, etc.). |
-| `style` | `ViewStyle` | `undefined` | Style applied to avatar container. |
-| `videoStyle` | `ViewStyle` | `undefined` | Style applied to native video view. |
-| `objectFit` | `'cover' \| 'contain'` | `'cover'` | Video aspect scaling mode. |
-| `mirror` | `boolean` | `false` | Mirror video orientation. |
-| `autoStart` | `boolean` | `true` | Automatically connect and start stream on mount. |
-| `enableMic` | `boolean` | `true` | Automatically enable microphone on connect. |
-| `onTranscript` | `function` | `undefined` | Fires when speech transcription arrives. |
-| `onSpeakStart` | `function` | `undefined` | Fires when avatar starts speaking. |
-| `onSpeakEnd` | `function` | `undefined` | Fires when avatar finishes speaking. |
-| `onUserSpeakStart` | `function` | `undefined` | Fires when user voice activity begins. |
-| `onUserSpeakEnd` | `function` | `undefined` | Fires when user voice activity ends. |
-| `onOrderUpdate` | `function` | `undefined` | Fires when cart items or intents are recognized. |
-| `onCheckout` | `function` | `undefined` | Fires when customer requests checkout / payment. |
-| `onStatusChange` | `function` | `undefined` | Stream lifecycle status: `'idle' \| 'connecting' \| 'connected' \| 'reconnecting' \| 'disconnected' \| 'error'`. |
-| `onError` | `function` | `undefined` | Stream error callback `{ code, message }`. |
-
----
-
-### Imperative Ref (`FacePeMobileAvatarRef`)
-
-```tsx
-const avatarRef = useRef<FacePeMobileAvatarRef>(null);
-
-// Start streaming session
-await avatarRef.current?.start();
-
-// Stop streaming session & finalize billing usage
-await avatarRef.current?.stop();
-
-// Toggle mic on/off (returns new state boolean)
-const isNowMuted = await avatarRef.current?.toggleMic();
-
-// Make avatar speak programmatically
-await avatarRef.current?.speak("Hello! How can I assist you today?");
-
-// Interrupt avatar speech immediately
-await avatarRef.current?.interrupt();
-```
-
----
-
-## 📄 License
-MIT © FacePe AI
+# @facepe/widget-mobile-app
+
+The official **FacePe AI Digital Human Live Streaming SDK** for **React Native** (supporting both **iOS** and **Android**).
+
+Embed interactive, photorealistic, lip-synced 3D digital avatars directly inside your native mobile apps with pure WebRTC media streaming, native microphone capture, bidirectional voice dialog, and live data events — **without webviews**.
+
+---
+
+## 📱 Features
+
+- **⚡ Native WebRTC Streaming**: Pure native media streaming powered by `@livekit/react-native` (no WebViews or embedded iframes).
+- **🗣️ Natural Two-Way Voice Dialog**: Real-time microphone capture with hardware echo cancellation, noise suppression, and server VAD.
+- **🍎 Full iOS Support**: Hardware-accelerated video decoding on iOS 13.0+ (iPhone & iPad).
+- **🤖 Full Android Support**: Hardware-accelerated video decoding on Android 7.0+ (API 24+).
+- **💬 Real-Time Transcriptions**: Bidirectional captions for avatar speech and user speech.
+- **🛒 Conversational Commerce**: Automatic detection of cart items, orders, and payment intents.
+- **🎛️ Imperative Controls**: Ref methods to start/stop stream, mute/unmute mic, speak text, or interrupt speech.
+
+---
+
+## 📦 Installation
+
+In your React Native project:
+
+```bash
+npm install @facepe/widget-mobile-app @livekit/react-native @livekit/react-native-webrtc livekit-client @anam-ai/js-sdk
+```
+
+*(or using yarn / pnpm)*:
+
+```bash
+yarn add @facepe/widget-mobile-app @livekit/react-native @livekit/react-native-webrtc livekit-client @anam-ai/js-sdk
+```
+
+All avatars play natively (no WebView). The streaming libraries are loaded
+only when a conversation starts. The app needs a development build (Expo Go
+cannot load the native WebRTC module).
+
+---
+
+## 🛠️ Platform Permissions Setup
+
+### iOS Setup (`ios/Podfile` & `Info.plist`)
+
+1. Open `ios/YourAppName/Info.plist` and add permission strings for microphone and audio:
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>We need access to your microphone to converse with the FacePe AI avatar.</string>
+<key>NSCameraUsageDescription</key>
+<string>Camera access for interactive features.</string>
+```
+
+2. Run CocoaPods:
+```bash
+cd ios && pod install && cd ..
+```
+
+---
+
+### Android Setup (`android/app/src/main/AndroidManifest.xml`)
+
+Open `android/app/src/main/AndroidManifest.xml` and include permissions:
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+```
+
+---
+
+## 🚀 Quick Start Example
+
+### 1. Server-side Token Endpoint
+
+Exchange your `accessKey` and `secretKey` on your secure backend (Node.js / Express / Next.js / Python / Go) so credentials are never exposed inside mobile apps:
+
+```javascript
+// Express server route: GET /api/facepe-token
+app.get('/api/facepe-token', async (req, res) => {
+  const response = await fetch('https://api.facepe.ai/api/v1/sdk/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      accessKey: process.env.FACEPE_SDK_ACCESS_KEY,
+      secretKey: process.env.FACEPE_SDK_SECRET_KEY,
+      channel: 'sdk',
+    }),
+  });
+  const data = await response.json();
+  res.send(data.data.token);
+});
+```
+
+---
+
+### 2. React Native Component
+
+```tsx
+import React, { useRef } from 'react';
+import { StyleSheet, View, SafeAreaView, Text, TouchableOpacity } from 'react-native';
+import {
+  FacePeMobileProvider,
+  FacePeMobileAvatar,
+  FacePeMobileAvatarRef,
+  useFacePeAvatar,
+} from '@facepe/widget-mobile-app';
+
+export default function App() {
+  const avatarRef = useRef<FacePeMobileAvatarRef>(null);
+
+  return (
+    <SafeAreaView style={styles.container}>
+      <Text style={styles.title}>FacePe AI Native Digital Human</Text>
+
+      <FacePeMobileProvider
+        apiBaseUrl="https://api.facepe.ai/api/v1/sdk"
+        getToken={async () => {
+          const res = await fetch('https://your-backend.com/api/facepe-token');
+          return await res.text();
+        }}
+      >
+        <AvatarScreen avatarRef={avatarRef} />
+      </FacePeMobileProvider>
+    </SafeAreaView>
+  );
+}
+
+function AvatarScreen({ avatarRef }: { avatarRef: React.RefObject<FacePeMobileAvatarRef> }) {
+  const { transcripts, isAvatarSpeaking, avatarProps } = useFacePeAvatar();
+
+  return (
+    <View style={styles.content}>
+      <View style={styles.avatarContainer}>
+        <FacePeMobileAvatar
+          ref={avatarRef}
+          language="en"
+          objectFit="cover"
+          autoStart={true}
+          enableMic={true}
+          {...avatarProps}
+        />
+      </View>
+
+      {/* Control bar */}
+      <View style={styles.controls}>
+        <TouchableOpacity
+          style={styles.button}
+          onPress={() => avatarRef.current?.toggleMic()}
+        >
+          <Text style={styles.buttonText}>Toggle Mic</Text>
+        </TouchableOpacity>
+
+        <TouchableOpacity
+          style={styles.button}
+          onPress={() => avatarRef.current?.interrupt()}
+        >
+          <Text style={styles.buttonText}>Interrupt</Text>
+        </TouchableOpacity>
+      </View>
+
+      {/* Real-time speech transcript log */}
+      <View style={styles.transcriptBox}>
+        {transcripts.slice(-3).map((item, idx) => (
+          <Text key={idx} style={styles.transcriptLine}>
+            <Text style={item.role === 'assistant' ? styles.avatarTag : styles.userTag}>
+              {item.role === 'assistant' ? 'Avatar: ' : 'You: '}
+            </Text>
+            {item.text}
+          </Text>
+        ))}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#0F172A',
+  },
+  content: {
+    flex: 1,
+    padding: 16,
+  },
+  title: {
+    color: '#FFFFFF',
+    fontSize: 20,
+    fontWeight: 'bold',
+    textAlign: 'center',
+    marginVertical: 12,
+  },
+  avatarContainer: {
+    flex: 1,
+    borderRadius: 24,
+    overflow: 'hidden',
+    backgroundColor: '#1E293B',
+  },
+  controls: {
+    flexDirection: 'row',
+    justifyContent: 'center',
+    gap: 12,
+    marginVertical: 14,
+  },
+  button: {
+    backgroundColor: '#7C3AED',
+    paddingHorizontal: 20,
+    paddingVertical: 10,
+    borderRadius: 12,
+  },
+  buttonText: {
+    color: '#FFFFFF',
+    fontWeight: '600',
+    fontSize: 14,
+  },
+  transcriptBox: {
+    backgroundColor: '#1E293B',
+    padding: 12,
+    borderRadius: 12,
+    minHeight: 80,
+  },
+  transcriptLine: {
+    color: '#E2E8F0',
+    fontSize: 13,
+    marginBottom: 4,
+  },
+  avatarTag: {
+    color: '#A78BFA',
+    fontWeight: '700',
+  },
+  userTag: {
+    color: '#60A5FA',
+    fontWeight: '700',
+  },
+});
+```
+
+---
+
+## ⚙️ Props & Configuration
+
+### `<FacePeMobileAvatar />`
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `avatarKey` | `string` | *(optional)* | Specific avatar key or ID assigned to your company. |
+| `language` | `string` | `'en'` | Spoken language code (`'en'`, `'hi'`, `'es'`, `'ta'`, `'te'`, etc.). |
+| `style` | `ViewStyle` | `undefined` | Style applied to avatar container. |
+| `videoStyle` | `ViewStyle` | `undefined` | Style applied to native video view. |
+| `objectFit` | `'cover' \| 'contain'` | `'cover'` | Video aspect scaling mode. |
+| `mirror` | `boolean` | `false` | Mirror video orientation. |
+| `autoStart` | `boolean` | `true` | Automatically connect and start stream on mount. |
+| `enableMic` | `boolean` | `true` | Automatically enable microphone on connect. |
+| `onTranscript` | `function` | `undefined` | Fires when speech transcription arrives. |
+| `onSpeakStart` | `function` | `undefined` | Fires when avatar starts speaking. |
+| `onSpeakEnd` | `function` | `undefined` | Fires when avatar finishes speaking. |
+| `onUserSpeakStart` | `function` | `undefined` | Fires when user voice activity begins. |
+| `onUserSpeakEnd` | `function` | `undefined` | Fires when user voice activity ends. |
+| `onOrderUpdate` | `function` | `undefined` | Fires when cart items or intents are recognized. |
+| `onCheckout` | `function` | `undefined` | Fires when customer requests checkout / payment. |
+| `onStatusChange` | `function` | `undefined` | Stream lifecycle status: `'idle' \| 'connecting' \| 'connected' \| 'reconnecting' \| 'disconnected' \| 'error'`. |
+| `onError` | `function` | `undefined` | Stream error callback `{ code, message }`. |
+
+---
+
+### Imperative Ref (`FacePeMobileAvatarRef`)
+
+```tsx
+const avatarRef = useRef<FacePeMobileAvatarRef>(null);
+
+// Start streaming session
+await avatarRef.current?.start();
+
+// Stop streaming session & finalize billing usage
+await avatarRef.current?.stop();
+
+// Toggle mic on/off (returns new state boolean)
+const isNowMuted = await avatarRef.current?.toggleMic();
+
+// Make avatar speak programmatically
+await avatarRef.current?.speak("Hello! How can I assist you today?");
+
+// Interrupt avatar speech immediately
+await avatarRef.current?.interrupt();
+```
+
+---
+
+## 🗂️ Conversation data (`onConversationEnd`)
+
+When a conversation ends, the SDK hands your app the **whole conversation** in
+one record. It stays in your app — the SDK sends it nowhere; you decide whether
+to show it, save it on your server, or ignore it.
+
+```tsx
+<FacePeMobileAvatar
+  onConversationEnd={(conversation) => {
+    console.log(conversation.durationSec, conversation.transcript.length);
+    // e.g. save it on your own server:
+    // fetch('https://your-server.example.com/conversations', { method: 'POST', body: JSON.stringify(conversation) });
+  }}
+/>
+```
+
+It is called once per conversation: after `stop()`, when the stream drops, or
+when the component unmounts.
+
+```json
+{
+  "conversationId": "cm_usage_123",
+  "avatar": { "id": "cm_avatar_456", "name": "Dharun" },
+  "language": "en",
+  "platform": "android",
+  "sdkVersion": "1.3.0",
+  "startedAt": "2026-10-12T11:40:02.000Z",
+  "endedAt":   "2026-10-12T11:43:17.000Z",
+  "durationSec": 195,
+  "endReason": "ended",
+  "transcript": [
+    { "role": "assistant", "text": "Welcome! How can I help you today?", "at": "2026-10-12T11:40:05.000Z" },
+    { "role": "user",      "text": "Two cheeseburgers please.",          "at": "2026-10-12T11:40:11.000Z" }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `conversationId` | The conversation's FacePe id (its usage record) |
+| `avatar` | `{ id, name }` of the avatar |
+| `language` | The language requested for the conversation |
+| `platform` | `web`, `android` or `ios` |
+| `sdkVersion` | The SDK version that recorded it |
+| `startedAt`, `endedAt` | ISO 8601 times |
+| `durationSec` | Length in seconds |
+| `endReason` | `ended` (the user or your code ended it), `disconnected` (the stream dropped), `unmounted` (the component went away) |
+| `transcript` | Every line in order: `{ role: "user" \| "assistant", text, at }` |
+
+---
+
+## 📄 License
+MIT © FacePe AI

package/dist/FacePeMobileAvatar.js

@@ -1,11 +1,44 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useRef, useState, useImperativeHandle, forwardRef, useCallback, } from 'react';
-import { View, StyleSheet, ActivityIndicator, Text, TouchableOpacity } from 'react-native';
+import { View, StyleSheet, ActivityIndicator, Text, TouchableOpacity, Platform } from 'react-native';
+import { SDK_VERSION } from './version';
 import { useFacePeMobileContext } from './FacePeMobileProvider';
-// Resolve @livekit/react-native dynamically at runtime so bare/Expo projects can run smoothly
+// Resolve LiveKit dynamically at runtime so bare/Expo projects can run smoothly.
+// @livekit/react-native brings the native parts (registerGlobals, AudioSession,
+// VideoView); Room, RoomEvent and Track come from livekit-client, which it
+// does not re-export.
 function getLiveKitRN() {
     try {
-        return require('@livekit/react-native');
+        const native = require('@livekit/react-native');
+        const client = require('livekit-client');
+        return { ...native, Room: client.Room, RoomEvent: client.RoomEvent, Track: client.Track };
+    }
+    catch {
+        return null;
+    }
+}
+// "stream" connections (hosted avatars) are played natively with the stream
+// SDK's `stream()`, which returns plain MediaStreams — shown in the native
+// RTCView, no WebView. It needs crypto.randomUUID, which React Native lacks.
+function getStreamSdk() {
+    try {
+        const g = globalThis;
+        g.crypto = g.crypto || {};
+        if (typeof g.crypto.randomUUID !== 'function') {
+            g.crypto.randomUUID = () => 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+                const r = (Math.random() * 16) | 0;
+                return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+            });
+        }
+        return require('@anam-ai/js-sdk');
+    }
+    catch {
+        return null;
+    }
+}
+function getRTCView() {
+    try {
+        return require('@livekit/react-native-webrtc').RTCView;
     }
     catch {
         return null;
@@ -25,7 +58,7 @@ function ensureLiveKitGlobals(LiveKitRN) {
         console.warn('[FacePeMobileAvatar] registerGlobals warning:', err);
     }
 }
-export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', style, videoStyle, objectFit = 'cover', mirror = false, autoStart = true, enableMic = true, onTranscript, onSpeakStart, onSpeakEnd, onUserSpeakStart, onUserSpeakEnd, onOrderUpdate, onCheckout, onStatusChange, onError, }, ref) => {
+export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', style, videoStyle, objectFit = 'cover', mirror = false, autoStart = true, enableMic = true, onTranscript, onSpeakStart, onSpeakEnd, onUserSpeakStart, onUserSpeakEnd, onOrderUpdate, onCheckout, onStatusChange, onError, onConversationEnd, }, ref) => {
     const { token, loading: tokenLoading, error: tokenError, apiBaseUrl, refreshToken } = useFacePeMobileContext();
     const [status, setStatus] = useState('idle');
     const [videoTrack, setVideoTrack] = useState(null);
@@ -36,7 +69,54 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
     const LiveKitRN = getLiveKitRN();
     const hasLiveKit = !!LiveKitRN;
     const roomRef = useRef(null);
+    // A "stream" connection: the stream SDK client, and its video for RTCView.
+    const streamClientRef = useRef(null);
+    const [streamURL, setStreamURL] = useState(null);
     const usageIdRef = useRef(null);
+    // The conversation as it happens, for the onConversationEnd record. Lines
+    // that carry an id (a line that grows while spoken) replace their earlier version.
+    const conversationRef = useRef(null);
+    const onConversationEndRef = useRef(onConversationEnd);
+    onConversationEndRef.current = onConversationEnd;
+    const onTranscriptRef = useRef(onTranscript);
+    onTranscriptRef.current = onTranscript;
+    // A transcript line: recorded for the conversation record, and passed on.
+    const emitLine = (role, text, id) => {
+        const conv = conversationRef.current;
+        if (conv && text) {
+            const same = id ? conv.lines.find((l) => l.id === id) : undefined;
+            if (same)
+                same.text = text;
+            else
+                conv.lines.push({ id, role, text, at: new Date().toISOString() });
+        }
+        onTranscriptRef.current?.({ payload: { role, text, isFinal: true } });
+    };
+    // Hands the whole conversation to the app, once.
+    const finishConversation = (endReason) => {
+        const conv = conversationRef.current;
+        conversationRef.current = null;
+        if (!conv)
+            return;
+        const endedAt = new Date();
+        try {
+            onConversationEndRef.current?.({
+                conversationId: conv.conversationId,
+                avatar: conv.avatar,
+                language: conv.language,
+                platform: Platform.OS === 'ios' ? 'ios' : Platform.OS === 'android' ? 'android' : 'web',
+                sdkVersion: SDK_VERSION,
+                startedAt: conv.startedAt.toISOString(),
+                endedAt: endedAt.toISOString(),
+                durationSec: Math.max(0, Math.round((endedAt.getTime() - conv.startedAt.getTime()) / 1000)),
+                endReason,
+                transcript: conv.lines.map(({ role, text, at }) => ({ role, text, at })),
+            });
+        }
+        catch (err) {
+            console.warn('[FacePeMobileAvatar] onConversationEnd error:', err);
+        }
+    };
     const mountedRef = useRef(true);
     const isConnectingRef = useRef(false);
     const tokenRef = useRef(token);
@@ -95,7 +175,7 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
     };
     // Start streaming session
     const startStream = useCallback(async () => {
-        if (isConnectingRef.current || roomRef.current)
+        if (isConnectingRef.current || roomRef.current || streamClientRef.current)
             return;
         if (!hasLiveKit) {
             const msg = 'Please install `@livekit/react-native` and `@livekit/react-native-webrtc` to enable native AI avatar streaming.';
@@ -121,18 +201,18 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             // Resolve target avatar ID
             let targetAvatarId = avatarKey;
             if (!targetAvatarId) {
-                // If no avatar key passed, retrieve assigned avatars from /sdk/session
-                const sessionRes = await fetch(`${cleanBase}/session`, {
+                // No avatar given: use the first one assigned to this token's user.
+                const listRes = await fetch(`${cleanBase}/avatars`, {
                     method: 'GET',
                     headers: {
                         Authorization: `Bearer ${currentToken}`,
                     },
                 });
-                if (sessionRes.ok) {
-                    const sessionData = await sessionRes.json();
-                    const avatars = sessionData?.data?.avatars || sessionData?.avatars || [];
+                if (listRes.ok) {
+                    const listData = await listRes.json();
+                    const avatars = listData?.data?.avatars || [];
                     if (avatars.length > 0) {
-                        targetAvatarId = avatars[0].id || avatars[0].key;
+                        targetAvatarId = avatars[0].id;
                     }
                 }
             }
@@ -156,14 +236,75 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             const sessionPayload = await sessionResp.json();
             const sessionInfo = sessionPayload?.data || sessionPayload;
             usageIdRef.current = sessionInfo?.usageId || null;
+            conversationRef.current = {
+                conversationId: usageIdRef.current,
+                avatar: { id: String(sessionInfo?.avatar?.id ?? targetAvatarId), name: String(sessionInfo?.avatar?.name ?? '') },
+                language: language ?? null,
+                startedAt: new Date(),
+                lines: [],
+            };
             const connection = sessionInfo?.connection;
+            if (connection?.type === 'stream') {
+                // Hosted avatar: the stream SDK gives plain MediaStreams (video +
+                // the avatar's voice) and captures the microphone itself.
+                const StreamSdk = getStreamSdk();
+                if (!StreamSdk || !getRTCView() || !connection.token) {
+                    throw new Error('This avatar needs `@anam-ai/js-sdk` in the app (npm install @anam-ai/js-sdk).');
+                }
+                const client = StreamSdk.createClient(connection.token);
+                streamClientRef.current = client;
+                const ev = StreamSdk.AnamEvent;
+                const seen = new Set();
+                client.addListener(ev.MESSAGE_HISTORY_UPDATED, (messages) => {
+                    if (!mountedRef.current)
+                        return;
+                    for (const m of messages ?? []) {
+                        const text = String(m?.content ?? '').trim();
+                        const key = `${m?.id}:${text}`;
+                        if (!text || seen.has(key))
+                            continue;
+                        seen.add(key);
+                        emitLine(String(m.role).includes('user') ? 'user' : 'assistant', text, m?.id ? String(m.id) : undefined);
+                    }
+                });
+                client.addListener(ev.USER_SPEECH_STARTED, () => { setIsUserSpeaking(true); onUserSpeakStart?.(); });
+                client.addListener(ev.USER_SPEECH_ENDED, () => { setIsUserSpeaking(false); onUserSpeakEnd?.(); });
+                client.addListener(ev.CONNECTION_CLOSED, () => {
+                    if (!mountedRef.current || streamClientRef.current !== client)
+                        return;
+                    streamClientRef.current = null;
+                    setStreamURL(null);
+                    setIsUserSpeaking(false);
+                    updateStatus('disconnected');
+                    finishConversation('disconnected');
+                    void endUsage();
+                });
+                const streams = await client.stream();
+                const video = streams.find((s) => s?.getVideoTracks?.().length > 0) ?? streams[0];
+                if (!video)
+                    throw new Error('The avatar did not send a video stream.');
+                if (!mountedRef.current) {
+                    await client.stopStreaming().catch(() => undefined);
+                    return;
+                }
+                setStreamURL(video.toURL());
+                setIsMicEnabled(true);
+                updateStatus('connected');
+                if (!enableMic) {
+                    client.muteInputAudio();
+                    setIsMicEnabled(false);
+                }
+                if (connection.greeting)
+                    client.talk(String(connection.greeting)).catch(() => undefined);
+                return;
+            }
             if (!connection || connection.type !== 'room' || !connection.url || !connection.token) {
-                throw new Error('Avatar server did not return a valid LiveKit room connection.');
+                throw new Error('Avatar server did not return a valid room connection.');
             }
             // Initialize LiveKit Room natively
             const room = new LiveKitRN.Room({
-                adaptiveStream: true,
-                dynacast: true,
+                adaptiveStream: false, // Ensure full video frames arrive without adaptive downscaling
+                dynacast: false,
             });
             roomRef.current = room;
             // Start Audio Session on iOS/Android
@@ -247,13 +388,13 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
                     if (type === 'avatar.transcription' || type === 'response.audio_transcript.done') {
                         const str = msg.text || msg.transcript || msg.payload?.text;
                         if (str)
-                            onTranscript?.({ payload: { role: 'assistant', text: String(str).trim() } });
+                            emitLine('assistant', String(str).trim());
                     }
                     else if (type === 'user.transcription' ||
                         type === 'conversation.item.input_audio_transcription.completed') {
                         const str = msg.text || msg.transcript || msg.payload?.text;
                         if (str)
-                            onTranscript?.({ payload: { role: 'user', text: String(str).trim() } });
+                            emitLine('user', String(str).trim());
                     }
                     // Order & checkout intents
                     if (type === 'order.update') {
@@ -270,12 +411,17 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             });
             // 4. Connection state transitions
             room.on(LiveKitRN.RoomEvent.Disconnected, () => {
-                if (!mountedRef.current)
-                    return;
+                if (!mountedRef.current || roomRef.current !== room)
+                    return; // stop() handles its own end
+                roomRef.current = null;
                 setVideoTrack(null);
                 setIsAvatarSpeaking(false);
                 setIsUserSpeaking(false);
                 updateStatus('disconnected');
+                // The stream dropped: close the conversation now, so it is not
+                // left open (and billed) until the server's 30-minute limit.
+                finishConversation('disconnected');
+                void endUsage();
             });
             room.on(LiveKitRN.RoomEvent.Reconnecting, () => {
                 updateStatus('reconnecting');
@@ -285,6 +431,25 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             });
             // Connect room over WebRTC
             await room.connect(connection.url, connection.token, { autoSubscribe: true });
+            // Check already subscribed remote tracks in case track arrived before/during connection
+            try {
+                room.remoteParticipants?.forEach?.((participant) => {
+                    participant.trackPublications?.forEach?.((pub) => {
+                        if (pub?.track) {
+                            const isVid = pub.track.kind === 'video' ||
+                                pub.kind === 'video' ||
+                                (LiveKitRN.Track?.Kind?.Video && pub.track.kind === LiveKitRN.Track.Kind.Video);
+                            if (isVid && mountedRef.current) {
+                                setVideoTrack(pub.track);
+                                updateStatus('connected');
+                            }
+                        }
+                    });
+                });
+            }
+            catch {
+                // ignore inspection error
+            }
             // Enable microphone capture if requested
             if (enableMic) {
                 try {
@@ -310,6 +475,14 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             }
         }
         catch (err) {
+            // A failed hosted-avatar start: close its connection too.
+            const failedClient = streamClientRef.current;
+            streamClientRef.current = null;
+            setStreamURL(null);
+            if (failedClient)
+                await failedClient.stopStreaming().catch(() => undefined);
+            // Opened on the server but never got going: still hand over the record.
+            finishConversation('disconnected');
             if (!mountedRef.current)
                 return;
             const msg = err?.message || 'Connection failed';
@@ -339,9 +512,15 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
         onError,
     ]);
     // Stop streaming session
-    const stopStream = useCallback(async () => {
+    const stopStream = useCallback(async (reason = 'ended') => {
+        finishConversation(reason);
         const room = roomRef.current;
         roomRef.current = null;
+        const streamClient = streamClientRef.current;
+        streamClientRef.current = null;
+        setStreamURL(null);
+        if (streamClient)
+            await streamClient.stopStreaming().catch(() => undefined);
         if (room) {
             try {
                 if (room.localParticipant) {
@@ -368,6 +547,16 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             await stopStream();
         },
         toggleMic: async () => {
+            const streamClient = streamClientRef.current;
+            if (streamClient) {
+                const next = !isMicEnabled;
+                if (next)
+                    streamClient.unmuteInputAudio();
+                else
+                    streamClient.muteInputAudio();
+                setIsMicEnabled(next);
+                return next;
+            }
             const room = roomRef.current;
             if (!room || !room.localParticipant)
                 return isMicEnabled;
@@ -383,6 +572,15 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             }
         },
         setMicEnabled: async (enabled) => {
+            const streamClient = streamClientRef.current;
+            if (streamClient) {
+                if (enabled)
+                    streamClient.unmuteInputAudio();
+                else
+                    streamClient.muteInputAudio();
+                setIsMicEnabled(enabled);
+                return;
+            }
             const room = roomRef.current;
             if (!room || !room.localParticipant)
                 return;
@@ -395,10 +593,17 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             }
         },
         speak: async (text) => {
+            if (streamClientRef.current) {
+                await streamClientRef.current.talk(text).catch(() => undefined);
+                return;
+            }
             sendData({ event_type: 'avatar.speak_text', text });
         },
         interrupt: async () => {
-            sendData({ event_type: 'avatar.interrupt' });
+            if (streamClientRef.current)
+                streamClientRef.current.interruptPersona();
+            else
+                sendData({ event_type: 'avatar.interrupt' });
             setIsAvatarSpeaking(false);
             onSpeakEnd?.();
         },
@@ -417,7 +622,7 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
         }
         return () => {
             mountedRef.current = false;
-            void stopStream();
+            void stopStream('unmounted');
         };
     }, [autoStart, token, tokenLoading, tokenError]);
     // Handle token loading
@@ -434,7 +639,13 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
     }
     // Native LiveKit VideoView component
     const VideoViewComponent = LiveKitRN.VideoView;
-    return (_jsxs(View, { style: [styles.container, style], children: [videoTrack && VideoViewComponent ? (_jsx(VideoViewComponent, { videoTrack: videoTrack, style: [styles.video, videoStyle], objectFit: objectFit, mirror: mirror })) : (_jsx(View, { style: [styles.container, styles.center], children: status === 'connecting' || status === 'reconnecting' ? (_jsxs(_Fragment, { children: [_jsx(ActivityIndicator, { size: "large", color: "#8B5CF6" }), _jsx(Text, { style: styles.loadingText, children: status === 'connecting'
+    // Native WebRTC view, for a hosted avatar's MediaStream
+    const RTCViewComponent = streamURL ? getRTCView() : null;
+    return (_jsxs(View, { style: [styles.container, style], children: [streamURL && RTCViewComponent ? (_jsx(RTCViewComponent, { streamURL: streamURL, style: StyleSheet.flatten([styles.video, videoStyle]), objectFit: objectFit, mirror: mirror, zOrder: 0 })) : videoTrack && VideoViewComponent ? (_jsx(VideoViewComponent, { track: videoTrack, videoTrack: videoTrack, 
+                // A plain object, not an array: VideoView spreads `style` into its
+                // container ({ ...style }), and spreading an array loses every
+                // size — the video got no height and stayed invisible.
+                style: StyleSheet.flatten([styles.video, videoStyle]), objectFit: objectFit, mirror: mirror })) : (_jsx(View, { style: [styles.container, styles.center], children: status === 'connecting' || status === 'reconnecting' ? (_jsxs(_Fragment, { children: [_jsx(ActivityIndicator, { size: "large", color: "#8B5CF6" }), _jsx(Text, { style: styles.loadingText, children: status === 'connecting'
                                 ? 'Connecting to FacePe AI Avatar…'
                                 : 'Reconnecting stream…' })] })) : status === 'error' ? (_jsxs(_Fragment, { children: [_jsx(Text, { style: styles.errorTitle, children: "Connection Failed" }), _jsx(Text, { style: styles.errorText, children: errorMessage || 'Unable to connect to stream' }), _jsx(TouchableOpacity, { style: styles.retryButton, onPress: () => void startStream(), children: _jsx(Text, { style: styles.retryText, children: "Reconnect" }) })] })) : (_jsx(TouchableOpacity, { style: styles.startButton, onPress: () => void startStream(), children: _jsx(Text, { style: styles.startText, children: "Start Avatar Session" }) })) })), status === 'connected' && (isAvatarSpeaking || isUserSpeaking) && (_jsxs(View, { style: styles.speakerPill, children: [_jsx(View, { style: [
                             styles.speakerDot,
@@ -452,6 +663,7 @@ const styles = StyleSheet.create({
         position: 'relative',
     },
     video: {
+        flex: 1,
         width: '100%',
         height: '100%',
     },

package/dist/FacePeMobileProvider.d.ts

@@ -1,4 +1,4 @@
-import React, { type ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import type { FacePeMobileConfig, TokenProvider } from './types';
 interface FacePeContextValue {
     config: FacePeMobileConfig;
@@ -14,6 +14,6 @@ export interface FacePeMobileProviderProps {
     apiBaseUrl?: string;
     config?: FacePeMobileConfig;
 }
-export declare function FacePeMobileProvider({ children, getToken, apiBaseUrl, config, }: FacePeMobileProviderProps): React.JSX.Element;
+export declare function FacePeMobileProvider({ children, getToken, apiBaseUrl, config, }: FacePeMobileProviderProps): import("react/jsx-runtime").JSX.Element;
 export declare function useFacePeMobileContext(): FacePeContextValue;
 export {};

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from './types';
 export * from './FacePeMobileProvider';
 export * from './FacePeMobileAvatar';
 export * from './useFacePeAvatar';
+export { SDK_VERSION } from './version';

package/dist/index.js

@@ -2,3 +2,4 @@ export * from './types';
 export * from './FacePeMobileProvider';
 export * from './FacePeMobileAvatar';
 export * from './useFacePeAvatar';
+export { SDK_VERSION } from './version';

package/dist/types.d.ts

@@ -11,6 +11,37 @@ export interface TranscriptPayload {
     text: string;
     isFinal?: boolean;
 }
+/** One line of a finished conversation, with the time it was said (ISO 8601). */
+export interface FacePeConversationLine {
+    role: 'user' | 'assistant';
+    text: string;
+    at: string;
+}
+/**
+ * Everything about one conversation, given once when it ends
+ * (`onConversationEnd`). It stays in your app: the SDK sends it nowhere — you
+ * decide whether to show, keep or send it.
+ */
+export interface FacePeConversation {
+    /** The conversation's id (its FacePe usage record), or null if none was opened. */
+    conversationId: string | null;
+    avatar: {
+        id: string;
+        name: string;
+    };
+    /** The language requested for the conversation (ISO 639-1). */
+    language: string | null;
+    platform: 'android' | 'ios' | 'web';
+    sdkVersion: string;
+    /** When it started and ended (ISO 8601). */
+    startedAt: string;
+    endedAt: string;
+    durationSec: number;
+    /** `ended`: by `stop()`; `disconnected`: the stream dropped; `unmounted`: the component went away. */
+    endReason: 'ended' | 'disconnected' | 'unmounted';
+    /** Every line, in order (a line that grew while being spoken appears once, complete). */
+    transcript: FacePeConversationLine[];
+}
 export interface OrderItem {
     name: string;
     qty: number;
@@ -69,6 +100,8 @@ export interface FacePeMobileAvatarProps {
     onCheckout?: () => void;
     /** Called when stream connection status changes */
     onStatusChange?: (status: FacePeConnectionStatus) => void;
+    /** Called once when a conversation ends, with the whole conversation (stays in your app) */
+    onConversationEnd?: (conversation: FacePeConversation) => void;
     /** Called when an error occurs */
     onError?: (event: {
         code: string;

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** This package's version, reported in conversation records. Keep in step with package.json. */
+export declare const SDK_VERSION = "1.3.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** This package's version, reported in conversation records. Keep in step with package.json. */
+export const SDK_VERSION = '1.3.0';

package/package.json

@@ -1,53 +1,61 @@
-{
-  "name": "@facepe/widget-mobile-app",
-  "version": "1.1.0",
-  "description": "FacePe AI 3D Video Avatar Native Live Streaming SDK for React Native (iOS & Android)",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "facepe",
-    "avatar",
-    "ai-avatar",
-    "livekit",
-    "react-native",
-    "ios",
-    "android",
-    "webrtc",
-    "streaming",
-    "digital-human"
-  ],
-  "author": "FacePe AI",
-  "license": "MIT",
-  "scripts": {
-    "lint": "tsc --noEmit",
-    "build": "tsc"
-  },
-  "peerDependencies": {
-    "@livekit/react-native": ">=2.0.0",
-    "@livekit/react-native-webrtc": ">=124.0.0",
-    "react": ">=18.0.0",
-    "react-native": ">=0.70.0"
-  },
-  "peerDependenciesMeta": {
-    "@livekit/react-native": {
-      "optional": true
-    },
-    "@livekit/react-native-webrtc": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/react": "^18.3.3",
-    "react": "18.3.1",
-    "react-native": "0.74.0",
-    "typescript": "^5.4.5"
-  }
-}
+{
+  "name": "@facepe/widget-mobile-app",
+  "version": "1.3.0",
+  "description": "FacePe AI 3D Video Avatar Native Live Streaming SDK for React Native (iOS & Android)",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "facepe",
+    "avatar",
+    "ai-avatar",
+    "livekit",
+    "react-native",
+    "ios",
+    "android",
+    "webrtc",
+    "streaming",
+    "digital-human"
+  ],
+  "author": "FacePe AI",
+  "license": "MIT",
+  "scripts": {
+    "lint": "tsc --noEmit",
+    "build": "tsc"
+  },
+  "peerDependencies": {
+    "@livekit/react-native": ">=2.0.0",
+    "@livekit/react-native-webrtc": ">=124.0.0",
+    "livekit-client": ">=2.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.70.0",
+    "@anam-ai/js-sdk": ">=4.27.0"
+  },
+  "peerDependenciesMeta": {
+    "@livekit/react-native": {
+      "optional": true
+    },
+    "@livekit/react-native-webrtc": {
+      "optional": true
+    },
+    "livekit-client": {
+      "optional": true
+    },
+    "@anam-ai/js-sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "react": "18.3.1",
+    "react-native": "0.74.0",
+    "typescript": "^5.4.5"
+  }
+}