@facepe/widget-mobile-app 1.3.0 → 1.4.0

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. |
@@ -337,6 +338,25 @@ when the component unmounts.
 | `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 }` |
+| `form` | For a form avatar: `{ title, complete, fields: [{ label, question, required, value }] }`; `null` otherwise |
+
+For an avatar that **fills a form**, the record also carries the form as the
+conversation filled it: each question with the customer's answer (`value` is
+`null` for a question that was not answered). FacePe reads the answers from the
+conversation when it ends, so the record arrives a few seconds after the call.
+For other avatars `form` is `null`.
+
+```json
+"form": {
+  "title": "Customer Intake Form",
+  "complete": true,
+  "fields": [
+    { "label": "Name",  "question": "Could you please tell me your full name?", "required": true, "value": "Tony" },
+    { "label": "Phone", "question": "What is the best phone number to reach you?", "required": true, "value": "9659390715" },
+    { "label": "Email", "question": "May I have your email address?", "required": false, "value": "tony@gmail.com" }
+  ]
+}
+```
 
 ---
 

package/dist/FacePeMobileAvatar.js

@@ -1,6 +1,6 @@
 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, Platform } 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.
@@ -58,8 +58,44 @@ 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, onConversationEnd, }, ref) => {
+/**
+ * Speech recognition writes a spoken phone number in parts ("9659-3907-1526").
+ * Long numbers are shown as plain digits; short ones ("2-3") are left as said.
+ */
+const joinNumberParts = (text) => text.replace(/\d+(?:[ \t]*[-\u2010\u2011\u2013][ \t]*\d+)+/g, (m) => {
+    const digits = m.replace(/\D/g, '');
+    return digits.length >= 7 ? digits : m;
+});
+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);
@@ -81,7 +117,8 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
     const onTranscriptRef = useRef(onTranscript);
     onTranscriptRef.current = onTranscript;
     // A transcript line: recorded for the conversation record, and passed on.
-    const emitLine = (role, text, id) => {
+    const emitLine = (role, said, id) => {
+        const text = joinNumberParts(said);
         const conv = conversationRef.current;
         if (conv && text) {
             const same = id ? conv.lines.find((l) => l.id === id) : undefined;
@@ -92,30 +129,51 @@ export const FacePeMobileAvatar = forwardRef(({ avatarKey, language = 'en', styl
         }
         onTranscriptRef.current?.({ payload: { role, text, isFinal: true } });
     };
-    // Hands the whole conversation to the app, once.
+    // Hands the whole conversation to the app, once. For a form avatar it first
+    // asks FacePe for the form as the conversation filled it (a few seconds).
     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 transcript = conv.lines.map(({ role, text, at }) => ({ role, text, at }));
+        void (async () => {
+            let form = null;
+            const token = tokenRef.current;
+            if (conv.conversationId && transcript.length > 0 && token) {
+                try {
+                    const res = await fetch(`${apiBaseUrl.replace(/\/+$/, '')}/avatar-sessions/${encodeURIComponent(conv.conversationId)}/form`, {
+                        method: 'POST',
+                        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+                        body: JSON.stringify({ transcript: transcript.map(({ role, text }) => ({ role, text })) }),
+                    });
+                    if (res.ok)
+                        form = (await res.json())?.data?.form ?? null;
+                }
+                catch {
+                    /* offline: the record goes without the form */
+                }
+            }
+            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,
+                    form,
+                });
+            }
+            catch (err) {
+                console.warn('[FacePeMobileAvatar] onConversationEnd error:', err);
+            }
+        })();
     };
     const mountedRef = useRef(true);
     const isConnectingRef = useRef(false);
@@ -645,9 +703,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…' })] }))] }));
@@ -667,6 +725,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/types.d.ts

@@ -22,6 +22,20 @@ export interface FacePeConversationLine {
  * (`onConversationEnd`). It stays in your app: the SDK sends it nowhere — you
  * decide whether to show, keep or send it.
  */
+/** One question of a form avatar, with the customer's answer (null: not answered). */
+export interface FacePeFormAnswer {
+    label: string;
+    question: string;
+    required: boolean;
+    value: string | null;
+}
+/** A form avatar's form, filled from the conversation. */
+export interface FacePeFilledForm {
+    title: string;
+    /** Every required question has an answer. */
+    complete: boolean;
+    fields: FacePeFormAnswer[];
+}
 export interface FacePeConversation {
     /** The conversation's id (its FacePe usage record), or null if none was opened. */
     conversationId: string | null;
@@ -41,6 +55,12 @@ export interface FacePeConversation {
     endReason: 'ended' | 'disconnected' | 'unmounted';
     /** Every line, in order (a line that grew while being spoken appears once, complete). */
     transcript: FacePeConversationLine[];
+    /**
+     * For an avatar that fills a form: its questions with the customer's answers,
+     * read from the conversation. Null for other avatars, or when the answers
+     * could not be read.
+     */
+    form: FacePeFilledForm | null;
 }
 export interface OrderItem {
     name: string;
@@ -100,6 +120,11 @@ 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 */

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@facepe/widget-mobile-app",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "FacePe AI 3D Video Avatar Native Live Streaming SDK for React Native (iOS & Android)",
   "main": "./dist/index.js",
   "module": "./dist/index.js",