@facepe/widget-mobile-app 1.5.0 → 1.5.2

package/README.md

@@ -80,7 +80,14 @@ Exchange your `accessKey` and `secretKey` on your secure backend (Node.js / Expr
 
 ```javascript
 // Express server route: GET /api/facepe-token
+// A token lasts 2 hours (expiresIn, in seconds): keep one and fetch a new one a
+// minute before it expires, or when the app asks with ?refresh=1 (after a 401).
+let cached = null; // { token, until }
+
 app.get('/api/facepe-token', async (req, res) => {
+  if (cached && cached.until > Date.now() && req.query.refresh !== '1') {
+    return res.send(cached.token);
+  }
   const response = await fetch('https://api.facepe.ai/api/v1/sdk/token', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
@@ -91,10 +98,16 @@ app.get('/api/facepe-token', async (req, res) => {
     }),
   });
   const data = await response.json();
-  res.send(data.data.token);
+  if (!response.ok) return res.status(response.status).json(data.error);
+  cached = { token: data.data.token, until: Date.now() + (data.data.expiresIn - 60) * 1000 };
+  res.send(cached.token);
 });
 ```
 
+**Tokens last 2 hours.** The SDK renews them by itself: it calls `getToken({ forceRefresh: true })`
+about 5 minutes before the token expires, and again (then retries once) if FacePe answers
+`401 SESSION_EXPIRED`. Renewal is silent: a conversation in progress is not interrupted.
+
 ---
 
 ### 2. React Native Component
@@ -118,8 +131,9 @@ export default function App() {
 
       <FacePeMobileProvider
         apiBaseUrl="https://api.facepe.ai/api/v1/sdk"
-        getToken={async () => {
-          const res = await fetch('https://your-backend.com/api/facepe-token');
+        getToken={async ({ forceRefresh }) => {
+          // Tokens last 2 hours: forceRefresh asks your server for a new one.
+          const res = await fetch('https://your-backend.com/api/facepe-token' + (forceRefresh ? '?refresh=1' : ''));
           return await res.text();
         }}
       >
@@ -253,6 +267,7 @@ const styles = StyleSheet.create({
 | `videoStyle` | `ViewStyle` | `undefined` | Style applied to native video view. |
 | `objectFit` | `'cover' \| 'contain'` | `'cover'` | Video aspect scaling mode. |
 | `mirror` | `boolean` | `false` | Mirror video orientation. |
+| `showSpeakingIndicator` | `boolean` | `true` | The "Avatar speaking" / "Listening to you…" label on the video. Set `false` to show it yourself with `onSpeakStart`/`onSpeakEnd` and `onUserSpeakStart`/`onUserSpeakEnd`. |
 | `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. |

package/dist/FacePeMobileAvatar.js

@@ -67,14 +67,26 @@ const joinNumberParts = (text) => text.replace(/\d+(?:[ \t]*[-\u2010\u2011\u2013
     return digits.length >= 7 ? digits : m;
 });
 /**
- * Calls the gateway's agent route; a FacePe server from before agents has
- * only the avatar route (404), so that one is tried next.
+ * A gateway call with the app's token. Answered 401 (the token expired or was
+ * revoked), it asks the app for a fresh token once and tries again. A server
+ * from before agents has only /avatars…, tried when /agents… is missing.
  */
-async function gatewayFetch(base, agentPath, avatarPath, init) {
-    const res = await fetch(`${base}${agentPath}`, init);
-    return res.status === 404 ? fetch(`${base}${avatarPath}`, init) : res;
+async function gatewayFetch(base, agentPath, avatarPath, init, tokenFor) {
+    const send = async (path, force) => {
+        const headers = { ...(init.headers ?? {}) };
+        const token = await tokenFor(force);
+        if (token)
+            headers.Authorization = `Bearer ${token}`;
+        return fetch(`${base}${path}`, { ...init, headers });
+    };
+    const attempt = async (force) => {
+        const res = await send(agentPath, force);
+        return res.status === 404 ? send(avatarPath, force) : res;
+    };
+    const res = await attempt(false);
+    return res.status === 401 ? attempt(true) : res;
 }
-export const FacePeMobileAvatar = forwardRef(({ agentId, 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) => {
+export const FacePeMobileAvatar = forwardRef(({ agentId, avatarKey, language = 'en', style, videoStyle, objectFit = 'cover', mirror = false, showSpeakingIndicator = true, 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 agent to talk to (`avatarKey` is its name from before agents).
     const chosenAgent = agentId ?? avatarKey;
@@ -87,9 +99,7 @@ export const FacePeMobileAvatar = forwardRef(({ agentId, avatarKey, language = '
         let cancelled = false;
         void (async () => {
             try {
-                const res = await gatewayFetch(apiBaseUrl.replace(/\/+$/, ''), '/agents', '/avatars', {
-                    headers: { Authorization: `Bearer ${token}` },
-                });
+                const res = await gatewayFetch(apiBaseUrl.replace(/\/+$/, ''), '/agents', '/avatars', {}, tokenFor);
                 if (!res.ok)
                     return;
                 const data = (await res.json())?.data;
@@ -151,15 +161,14 @@ export const FacePeMobileAvatar = forwardRef(({ agentId, avatarKey, language = '
         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) {
+            if (conv.conversationId && transcript.length > 0) {
                 try {
                     const id = encodeURIComponent(conv.conversationId);
                     const res = await gatewayFetch(apiBaseUrl.replace(/\/+$/, ''), `/agent-sessions/${id}/form`, `/avatar-sessions/${id}/form`, {
                         method: 'POST',
-                        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+                        headers: { 'Content-Type': 'application/json' },
                         body: JSON.stringify({ transcript: transcript.map(({ role, text }) => ({ role, text })) }),
-                    });
+                    }, tokenFor);
                     if (res.ok)
                         form = (await res.json())?.data?.form ?? null;
                 }
@@ -192,6 +201,10 @@ export const FacePeMobileAvatar = forwardRef(({ agentId, avatarKey, language = '
     const isConnectingRef = useRef(false);
     const tokenRef = useRef(token);
     tokenRef.current = token;
+    // The app's token for gateway calls, or (force) a fresh one after a 401.
+    const refreshRef = useRef(refreshToken);
+    refreshRef.current = refreshToken;
+    const tokenFor = useCallback(async (force) => (force ? refreshRef.current(true) : tokenRef.current ?? refreshRef.current()), []);
     // Helper: Safely emit status changes
     const updateStatus = useCallback((newStatus) => {
         if (!mountedRef.current)
@@ -227,18 +240,14 @@ export const FacePeMobileAvatar = forwardRef(({ agentId, avatarKey, language = '
     const endUsage = async () => {
         const uId = usageIdRef.current;
         usageIdRef.current = null;
-        const currentToken = tokenRef.current;
-        if (!uId || !currentToken)
+        if (!uId)
             return;
         try {
             const cleanBase = apiBaseUrl.replace(/\/+$/, '');
             await gatewayFetch(cleanBase, `/agent-sessions/${uId}/end`, `/avatar-sessions/${uId}/end`, {
                 method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    Authorization: `Bearer ${currentToken}`,
-                },
-            });
+                headers: { 'Content-Type': 'application/json' },
+            }, tokenFor);
         }
         catch {
             // ignore background teardown error
@@ -273,12 +282,7 @@ export const FacePeMobileAvatar = forwardRef(({ agentId, avatarKey, language = '
             let targetAgentId = chosenAgent;
             if (!targetAgentId) {
                 // No agent given: use the first one assigned to this token's user.
-                const listRes = await gatewayFetch(cleanBase, '/agents', '/avatars', {
-                    method: 'GET',
-                    headers: {
-                        Authorization: `Bearer ${currentToken}`,
-                    },
-                });
+                const listRes = await gatewayFetch(cleanBase, '/agents', '/avatars', { method: 'GET' }, tokenFor);
                 if (listRes.ok) {
                     const listData = (await listRes.json())?.data;
                     const agents = listData?.agents || listData?.avatars || [];
@@ -294,12 +298,9 @@ export const FacePeMobileAvatar = forwardRef(({ agentId, avatarKey, language = '
             const agentPath = encodeURIComponent(targetAgentId);
             const sessionResp = await gatewayFetch(cleanBase, `/agents/${agentPath}/sessions`, `/avatars/${agentPath}/sessions`, {
                 method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    Authorization: `Bearer ${currentToken}`,
-                },
+                headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ language }),
-            });
+            }, tokenFor);
             if (!sessionResp.ok) {
                 const errBody = await sessionResp.json().catch(() => ({}));
                 const errMsg = errBody?.error?.message || errBody?.message || 'Failed to start the conversation';
@@ -722,7 +723,7 @@ export const FacePeMobileAvatar = forwardRef(({ agentId, avatarKey, language = '
                 // size — the video got no height and stayed invisible.
                 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: [
+                    _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" }) }))] })), showSpeakingIndicator && 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…' })] }))] }));

package/dist/FacePeMobileProvider.js

@@ -1,25 +1,50 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, useState, useEffect, useRef, useMemo } from 'react';
 const FacePeContext = createContext(null);
+/** When a token runs out (its JWT `exp`, in seconds), or null if it doesn't say. */
+function expiryOf(token) {
+    try {
+        const part = token.split('.')[1] ?? '';
+        const b64 = part.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(part.length / 4) * 4, '=');
+        const exp = JSON.parse(globalThis.atob(b64))?.exp;
+        return typeof exp === 'number' ? exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Fetch a new token this long before the current one runs out. */
+const REFRESH_EARLY_MS = 5 * 60 * 1000;
 export function FacePeMobileProvider({ children, getToken, apiBaseUrl = 'https://api.facepe.ai/api/v1/sdk', config = {}, }) {
     const [token, setToken] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
     const tokenPromiseRef = useRef(null);
+    const tokenRef = useRef(null);
+    // A refresh with a token already in hand is silent: no "loading" (which would
+    // replace a live call with the sign-in screen), and on failure the current
+    // token stays — the next call's 401 asks again.
     const refreshToken = async (force = false) => {
         if (tokenPromiseRef.current && !force) {
             return tokenPromiseRef.current;
         }
-        setLoading(true);
-        setError(null);
+        const silent = tokenRef.current !== null;
+        if (!silent) {
+            setLoading(true);
+            setError(null);
+        }
         const promise = (async () => {
             try {
                 const fetched = await getToken({ forceRefresh: force });
+                tokenRef.current = fetched;
                 setToken(fetched);
+                setError(null);
                 setLoading(false);
                 return fetched;
             }
             catch (err) {
+                if (silent)
+                    return null;
                 const normalized = err instanceof Error ? err : new Error(String(err));
                 setError(normalized);
                 setLoading(false);
@@ -35,6 +60,19 @@ export function FacePeMobileProvider({ children, getToken, apiBaseUrl = 'https:/
     useEffect(() => {
         void refreshToken();
     }, []);
+    // Tokens expire (2 hours by default): fetch a new one a little before this one
+    // runs out, so a conversation never starts on a token about to expire. A 401
+    // on any call also fetches a new one.
+    useEffect(() => {
+        if (!token)
+            return;
+        const exp = expiryOf(token);
+        if (!exp)
+            return;
+        const wait = Math.min(Math.max(10000, exp * 1000 - Date.now() - REFRESH_EARLY_MS), 2 ** 31 - 1);
+        const timer = setTimeout(() => void refreshToken(true), wait);
+        return () => clearTimeout(timer);
+    }, [token]);
     const value = useMemo(() => ({
         config,
         token,

package/dist/types.d.ts

@@ -111,6 +111,12 @@ export interface FacePeMobileAvatarProps {
     objectFit?: 'cover' | 'contain';
     /** Whether to mirror the video stream (default: false) */
     mirror?: boolean;
+    /**
+     * Show the "Avatar speaking" / "Listening to you…" label on the video
+     * (default: true). Turn it off to show who is talking yourself, with
+     * onSpeakStart/onSpeakEnd and onUserSpeakStart/onUserSpeakEnd.
+     */
+    showSpeakingIndicator?: boolean;
     /** Auto start streaming when component mounts (default: true) */
     autoStart?: boolean;
     /** Whether microphone should be automatically enabled on stream start (default: true) */

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.5.0";
+export declare const SDK_VERSION = "1.5.2";

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.5.0';
+export const SDK_VERSION = '1.5.2';

package/package.json

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