@facepe/widget-mobile-app 1.2.0 → 1.3.1

package/README.md

@@ -253,6 +253,7 @@ const styles = StyleSheet.create({
 | `objectFit` | `'cover' \| 'contain'` | `'cover'` | Video aspect scaling mode. |
 | `mirror` | `boolean` | `false` | Mirror video orientation. |
 | `autoStart` | `boolean` | `true` | Automatically connect and start stream on mount. |
+| `posterUrl` | `string \| null` | avatar's portrait | Picture shown until the video starts. Defaults to the avatar's portrait from FacePe; pass `null` for none. |
 | `enableMic` | `boolean` | `true` | Automatically enable microphone on connect. |
 | `onTranscript` | `function` | `undefined` | Fires when speech transcription arrives. |
 | `onSpeakStart` | `function` | `undefined` | Fires when avatar starts speaking. |
@@ -289,5 +290,56 @@ 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,6 +1,7 @@
 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, Image } from 'react-native';
+import { SDK_VERSION } from './version';
 import { useFacePeMobileContext } from './FacePeMobileProvider';
 // Resolve LiveKit dynamically at runtime so bare/Expo projects can run smoothly.
 // @livekit/react-native brings the native parts (registerGlobals, AudioSession,
@@ -57,8 +58,36 @@ 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, posterUrl, }, ref) => {
     const { token, loading: tokenLoading, error: tokenError, apiBaseUrl, refreshToken } = useFacePeMobileContext();
+    // The avatar's portrait, shown until its video arrives. Looked up from the
+    // avatars this token may use, unless the app gave one (or null for none).
+    const [autoPoster, setAutoPoster] = useState(null);
+    useEffect(() => {
+        if (posterUrl !== undefined || !token)
+            return;
+        let cancelled = false;
+        void (async () => {
+            try {
+                const res = await fetch(`${apiBaseUrl.replace(/\/+$/, '')}/avatars`, {
+                    headers: { Authorization: `Bearer ${token}` },
+                });
+                if (!res.ok)
+                    return;
+                const avatars = (await res.json())?.data?.avatars ?? [];
+                const avatar = avatarKey ? avatars.find((a) => a.id === avatarKey) : avatars[0];
+                if (!cancelled)
+                    setAutoPoster(avatar?.previewUrl ?? null);
+            }
+            catch {
+                /* no picture: the plain background stays */
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [token, apiBaseUrl, avatarKey, posterUrl]);
+    const poster = posterUrl !== undefined ? posterUrl : autoPoster;
     const [status, setStatus] = useState('idle');
     const [videoTrack, setVideoTrack] = useState(null);
     const [isMicEnabled, setIsMicEnabled] = useState(enableMic);
@@ -72,6 +101,50 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
     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);
@@ -191,6 +264,13 @@ 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 +
@@ -212,7 +292,7 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
                         if (!text || seen.has(key))
                             continue;
                         seen.add(key);
-                        onTranscript?.({ payload: { role: String(m.role).includes('user') ? 'user' : 'assistant', text, isFinal: true } });
+                        emitLine(String(m.role).includes('user') ? 'user' : 'assistant', text, m?.id ? String(m.id) : undefined);
                     }
                 });
                 client.addListener(ev.USER_SPEECH_STARTED, () => { setIsUserSpeaking(true); onUserSpeakStart?.(); });
@@ -224,6 +304,7 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
                     setStreamURL(null);
                     setIsUserSpeaking(false);
                     updateStatus('disconnected');
+                    finishConversation('disconnected');
                     void endUsage();
                 });
                 const streams = await client.stream();
@@ -335,13 +416,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') {
@@ -358,12 +439,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');
@@ -423,6 +509,8 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
             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';
@@ -452,7 +540,8 @@ 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;
@@ -561,7 +650,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
@@ -584,9 +673,9 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
                 // 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: [
+                style: StyleSheet.flatten([styles.video, videoStyle]), objectFit: objectFit, mirror: mirror })) : (_jsxs(View, { style: [styles.container, styles.center, !!poster && (status === 'idle' || status === 'disconnected') && styles.overPoster], children: [poster && _jsx(Image, { source: { uri: poster }, style: StyleSheet.absoluteFill, resizeMode: "cover" }), poster && status !== 'idle' && status !== 'disconnected' && _jsx(View, { style: [StyleSheet.absoluteFill, styles.dim] }), status === 'connecting' || status === 'reconnecting' || status === 'connected' ? (
+                    // connected: the stream is up and the first video frame is on its way.
+                    _jsxs(_Fragment, { children: [_jsx(ActivityIndicator, { size: "large", color: "#8B5CF6" }), _jsx(Text, { style: styles.loadingText, children: status === 'reconnecting' ? 'Reconnecting stream…' : 'Connecting to FacePe AI Avatar…' })] })) : 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,
                             isAvatarSpeaking ? styles.dotAvatar : styles.dotUser,
                         ] }), _jsx(Text, { style: styles.speakerText, children: isAvatarSpeaking ? 'Avatar speaking' : 'Listening to you…' })] }))] }));
@@ -606,6 +695,14 @@ const styles = StyleSheet.create({
         width: '100%',
         height: '100%',
     },
+    // Over a portrait, keep the face clear: the button sits at the bottom.
+    overPoster: {
+        justifyContent: 'flex-end',
+        paddingBottom: 28,
+    },
+    dim: {
+        backgroundColor: 'rgba(15, 23, 42, 0.45)',
+    },
     center: {
         justifyContent: 'center',
         alignItems: 'center',

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,13 @@ export interface FacePeMobileAvatarProps {
     onCheckout?: () => void;
     /** Called when stream connection status changes */
     onStatusChange?: (status: FacePeConnectionStatus) => void;
+    /**
+     * Picture shown until the video starts (idle, connecting, errors). By default
+     * the avatar's own portrait from FacePe; pass your own URL, or null for none.
+     */
+    posterUrl?: string | null;
+    /** 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.1";

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.1';

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "@facepe/widget-mobile-app",
-  "version": "1.2.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"
-  }
-}
+{
+  "name": "@facepe/widget-mobile-app",
+  "version": "1.3.1",
+  "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"
+  }
+}