andy-widget-react 2.0.5 → 2.1.0

package/dist/index.esm.js

@@ -869,7 +869,7 @@ const _mapApiDataToChatbotConfig = (apiData, defaultConfig) => {
 		throw new Error('Invalid chatbot configuration response.')
 	}
 
-	const { chatbot, faqs: rawFaqs } = apiData;
+	const { chatbot, faqs: rawFaqs, bootstrap } = apiData;
 	const appearance = chatbot.appearance || {};
 	const behavior = chatbot.behavior || {};
 
@@ -939,6 +939,7 @@ const _mapApiDataToChatbotConfig = (apiData, defaultConfig) => {
 			)
 			.map(faq => ({ question: faq.question.trim(), answer: faq.answer.trim() }));
 	}
+	config.bootstrap = bootstrap;
 
 	return config
 };
@@ -988,7 +989,7 @@ const fetchChatbotConfig = async embedId => {
  * @param {string} message - The user's message
  * @returns {Promise<string>} The bot's response text
  */
-const sendMessage = async (embedId, sessionId, message) => {
+const sendMessageForWidget = async (embedId, sessionId, message) => {
 	try {
 		const apiBaseUrl = getApiBaseUrl();
 		const response = await fetch(`${apiBaseUrl}/messages`, {
@@ -1009,10 +1010,13 @@ const sendMessage = async (embedId, sessionId, message) => {
 			if (data.error || data.limitStatus) {
 				throw new Error(data.error || 'Chat is temporarily unavailable.')
 			}
+			if (data.handoffStatus === 'paused') {
+				return { status: 'waiting' }
+			}
 			if (typeof data.botResponse !== 'string' || !data.botResponse.trim()) {
 				throw new Error('Unexpected response format from server.')
 			}
-			return data.botResponse
+			return { status: 'agent', text: data.botResponse }
 		} else {
 			// Handle HTTP errors (e.g., 500, 404)
 			let errorData;
@@ -3429,6 +3433,34 @@ const SVG_ICONS = {
     <path d="M7.41 8.59L12 13.17l4.59-4.58L18 10l-6 6-6-6 1.41-1.41z" />
   </svg>`};
 
+// Localized UI Strings
+// Chrome the widget renders itself, as opposed to copy the Agent supplies.
+// Keyed by language so React and Vanilla render identical text for a visitor.
+const UI_STRINGS = {
+	en: {
+		inputPlaceholder: 'Type your message...',
+		predefinedQuestionsTitle: 'What would you like to know?',
+		sendFailure: 'Sorry, I could not answer. Please try again.',
+		handoffWaiting: 'A team member will reply soon.',
+		teamName: 'Team'
+	},
+	es: {
+		inputPlaceholder: 'Escribe tu mensaje...',
+		predefinedQuestionsTitle: '¿Qué te gustaría saber?',
+		sendFailure: 'Lo siento, no pude responder. Inténtalo de nuevo.',
+		handoffWaiting: 'Un miembro del equipo te responderá pronto.',
+		teamName: 'Equipo'
+	}
+};
+
+/**
+ * Get the widget's own UI strings for a language.
+ * Unknown languages fall back to English rather than rendering blanks.
+ * @param {string} [lang] - Language code ('en' or 'es')
+ * @returns {typeof UI_STRINGS.en} The localized string set
+ */
+const getUiStrings = lang => UI_STRINGS[lang] || UI_STRINGS.en;
+
 /**
  * Keyboard detection utility for handling mobile virtual keyboards
  * Provides cross-browser support for detecting keyboard open/close events
@@ -3694,12 +3726,172 @@ const isMobileDevice = () => {
 	return (hasTouch && isSmallScreen) || isMobileUserAgent || isMobileMediaQuery
 };
 
-const AndyChat = ({ embedId, tooltip, name, headline, description, welcomeMessage, bubbleLabel, theme, orientation, brandColor, bubbleStyle, useBrandColor, logoUrl, previewMode = false, initialOpen = false }) => {
+const identityKey = chatbotId => `andy-browser:${chatbotId}`;
+
+const randomIdentity = () => ({
+	sessionId: window.crypto.randomUUID(),
+	capability: btoa(String.fromCharCode(...(() => {
+		const bytes = new Uint8Array(32);
+		window.crypto.getRandomValues(bytes);
+		return bytes
+	})()))
+});
+
+const callConvex = async (convexUrl, kind, path, wireArgs, keepalive = false) => {
+	const response = await fetch(`${convexUrl}/api/${kind}`, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify({ path, format: 'convex_encoded_json', args: [wireArgs] }),
+		keepalive
+	});
+	if (!response.ok) throw new Error(`Browser handoff ${kind} failed: ${response.status}`)
+	const data = await response.json();
+	if (data.status !== 'success') throw new Error(data.errorMessage || `Browser handoff ${path} failed`)
+	return data.value
+};
+
+const sortMessages = messages => [...messages].sort((left, right) =>
+	left.createdAt - right.createdAt || String(left.id).localeCompare(String(right.id)));
+
+const createBrowserHandoff = (chatbotId, bootstrap, onProjection) => {
+	if (!bootstrap?.convexUrl || !bootstrap.surfaceKey || !bootstrap.surfaceProof) return null
+	const storageKey = identityKey(chatbotId);
+	let identity;
+	try {
+		const stored = JSON.parse(window.sessionStorage.getItem(storageKey) || 'null');
+		identity = stored?.sessionId && stored?.capability && stored.surfaceKey === bootstrap.surfaceKey
+			? { sessionId: stored.sessionId, capability: stored.capability }
+			: randomIdentity();
+		window.sessionStorage.setItem(storageKey, JSON.stringify({ ...identity, surfaceKey: bootstrap.surfaceKey }));
+	} catch {
+		identity = randomIdentity();
+	}
+	const wireArgs = () => ({ chatbotId, sessionId: identity.sessionId, capability: identity.capability, surfaceProof: bootstrap.surfaceProof });
+	let active = true;
+	let visible = document.visibilityState === 'visible';
+	let cursor;
+	let timer;
+	const pending = new Set();
+	const acknowledged = new Set();
+	const acknowledging = new Set();
+	const localMessages = new Map();
+	const emit = projection => {
+		if (!active) return
+		if (projection?.ok === false && projection.code === 'browser_presence_unavailable') {
+			onProjection({ offline: true, refreshBootstrap: Date.now() >= bootstrap.surfaceProofExpiresAt, identity, messages: [] });
+			return
+		}
+		if (!projection?.ok) return
+		cursor = projection.cursor || cursor;
+		const transcript = projection.transcript || [];
+		const projected = (projection.messages || []).map(message => ({ ...message, role: 'bot', sentByHuman: true }));
+		const byId = new Map(transcript.map(message => [String(message.id), message]));
+		for (const message of localMessages.values()) {
+			const persisted = transcript.some(candidate => candidate.role === 'user' && candidate.content === message.content && Math.abs(candidate.createdAt - message.createdAt) < 30000);
+			if (persisted) localMessages.delete(message.id);
+			else byId.set(message.id, message);
+		}
+		projected.forEach(message => byId.set(String(message.id), message));
+		const messages = sortMessages([...byId.values()]);
+		const pendingIds = projected.map(message => String(message.id)).filter(id => !acknowledged.has(id));
+		pendingIds.forEach(id => pending.add(id));
+		onProjection({ identity, control: projection.control, messages, pendingProjectionIds: pendingIds });
+	};
+	const project = async () => {
+		if (!active || !visible) return
+		if (Date.now() >= bootstrap.surfaceProofExpiresAt) {
+			emit({ ok: false, code: 'browser_presence_unavailable' });
+			return
+		}
+		try {
+			const result = await callConvex(bootstrap.convexUrl, 'query', 'browserHandoff:project', { ...wireArgs(), ...(cursor ? { cursor } : {}) });
+			emit(result);
+		} catch {
+			if (active) onProjection({ offline: true, identity, messages: [] });
+		}
+	};
+	const connect = async () => {
+		if (!active || Date.now() >= bootstrap.surfaceProofExpiresAt) {
+			emit({ ok: false, code: 'browser_presence_unavailable' });
+			return
+		}
+		try {
+			const result = await callConvex(bootstrap.convexUrl, 'mutation', 'browserHandoff:connect', wireArgs());
+			if (result?.ok === false) return emit(result)
+			await project();
+		} catch {
+			if (active) onProjection({ offline: true, identity, messages: [] });
+		}
+	};
+	const release = () => callConvex(bootstrap.convexUrl, 'mutation', 'browserHandoff:release', wireArgs(), true).catch(() => undefined);
+	const onVisibility = () => {
+		visible = document.visibilityState === 'visible';
+		if (visible) void connect();
+		else void release();
+	};
+	document.addEventListener('visibilitychange', onVisibility);
+	window.addEventListener('pagehide', release);
+	void connect();
+	timer = window.setInterval(async () => {
+		if (!active || !visible) return
+		if (Date.now() >= bootstrap.surfaceProofExpiresAt) {
+			window.clearInterval(timer);
+			emit({ ok: false, code: 'browser_presence_unavailable' });
+			return
+		}
+		try {
+			const result = await callConvex(bootstrap.convexUrl, 'mutation', 'browserHandoff:heartbeat', wireArgs());
+			if (result?.ok === false) emit(result);
+			else await project();
+		} catch {
+			if (active) onProjection({ offline: true, identity, messages: [] });
+		}
+	}, 15000);
+	return {
+		identity: { sessionId: identity.sessionId },
+		recordVisitorMessage: content => {
+			const id = `local-${window.crypto.randomUUID()}`;
+			localMessages.set(id, { id, role: 'user', content, createdAt: Date.now(), sentByHuman: false });
+		},
+		markRendered: async messageId => {
+			if (!active || !pending.has(messageId) || acknowledged.has(messageId) || acknowledging.has(messageId)) return
+			acknowledging.add(messageId);
+			try {
+				const result = await callConvex(bootstrap.convexUrl, 'mutation', 'browserHandoff:acknowledge', { ...wireArgs(), messageId });
+				if (result?.ok) {
+					acknowledged.add(messageId);
+					pending.delete(messageId);
+				}
+			} catch {
+				if (active) onProjection({ offline: true, identity, messages: [] });
+			} finally {
+				acknowledging.delete(messageId);
+			}
+		},
+		stop: () => {
+			if (!active) return
+			active = false;
+			window.clearInterval(timer);
+			document.removeEventListener('visibilitychange', onVisibility);
+			window.removeEventListener('pagehide', release);
+			void release();
+		}
+	}
+};
+
+const AndyChat = ({ embedId, tooltip, name, headline, description, welcomeMessage, bubbleLabel, lang, predefinedQuestions, theme, orientation, brandColor, bubbleStyle, useBrandColor, logoUrl, previewMode = false, initialOpen = false }) => {
     const [config, setConfig] = useState(null);
+    // The visitor's language wins over the Agent's own default: a Spanish Agent
+    // embedded on an English page must still render English chrome.
+    const uiLang = lang || config?.defaultLang || 'en';
+    const strings = getUiStrings(uiLang);
+    const activeQuestions = predefinedQuestions?.length ? predefinedQuestions : config?.predefinedQuestions;
     const [isOpen, setIsOpen] = useState(initialOpen);
     const [messages, setMessages] = useState([]);
     const [isLoading, setIsLoading] = useState(false);
     const [sessionId, setSessionId] = useState(() => generateSessionId());
+    const handoffRef = useRef(null);
+    const pendingHandoffIdsRef = useRef([]);
     const [shadowReady, setShadowReady] = useState(false);
     const [showPredefinedQuestions, setShowPredefinedQuestions] = useState(true);
     const [userInfoCollected, setUserInfoCollected] = useState(false);
@@ -3713,6 +3905,29 @@ const AndyChat = ({ embedId, tooltip, name, headline, description, welcomeMessag
     const messagesContainerRef = useRef(null);
     const welcomePopupShownRef = useRef(false);
     const welcomePopupTimeoutRef = useRef(null);
+    useEffect(() => {
+        if (!config?.bootstrap || !config.id)
+            return;
+        handoffRef.current?.stop();
+        const handoff = createBrowserHandoff(config.id, config.bootstrap, projection => {
+            if (projection.offline)
+                return;
+            setSessionId(projection.identity.sessionId);
+            pendingHandoffIdsRef.current = projection.pendingProjectionIds || [];
+            const projectedMessages = projection.messages.map(message => ({ id: message.id, content: message.content, sender: message.role === 'user' ? 'user' : 'bot', timestamp: new Date(message.createdAt).toISOString(), isHuman: message.sentByHuman }));
+            setMessages(projection.control === 'requested' || projection.control === 'human'
+                ? [...projectedMessages, { id: 'handoff-waiting', content: strings.handoffWaiting, sender: 'bot', timestamp: new Date().toISOString(), isWaiting: true }]
+                : projectedMessages);
+        });
+        handoffRef.current = handoff;
+        return () => {
+            handoff?.stop();
+            handoffRef.current = null;
+        };
+    }, [config?.bootstrap, config?.id]);
+    useEffect(() => {
+        pendingHandoffIdsRef.current.forEach(messageId => void handoffRef.current?.markRendered(messageId));
+    }, [messages]);
     // Create shadow DOM container on mount
     useEffect(() => {
         if (!containerRef.current)
@@ -3890,12 +4105,12 @@ const AndyChat = ({ embedId, tooltip, name, headline, description, welcomeMessag
                 bubbleStyle: bubbleStyle || 'icon',
                 bubbleLabel: bubbleLabel || null,
                 useBrandColor: useBrandColor !== undefined ? useBrandColor : true,
-                defaultLang: 'en',
+                defaultLang: uiLang,
                 showBranding: true,
                 showWelcomePopup: { enabled: false, seconds: 3, message: '' },
                 collectUserInfo: { enabled: false, message: '' },
                 welcomeMessage: welcomeMessage || 'Hi there! How can I help you today?',
-                predefinedQuestions: [],
+                predefinedQuestions: predefinedQuestions || [],
                 faqs: []
             };
             setConfig(previewConfig);
@@ -4039,16 +4254,21 @@ const AndyChat = ({ embedId, tooltip, name, headline, description, welcomeMessag
             sender: 'user',
             timestamp: new Date().toISOString()
         };
+        handoffRef.current?.recordVisitorMessage(messageText);
         setMessages(prev => [...prev, userMessage]);
         if (hidePredefined) {
             setShowPredefinedQuestions(false);
         }
         try {
             setIsLoading(true);
-            const response = await sendMessage(embedId, sessionId, messageText);
+            const response = await sendMessageForWidget(embedId, sessionId, messageText);
+            if (response.status === 'waiting') {
+                setMessages(prev => prev.some(message => message.isWaiting) ? prev : [...prev, { id: 'handoff-waiting', content: strings.handoffWaiting, sender: 'bot', timestamp: new Date().toISOString(), isWaiting: true }]);
+                return;
+            }
             const botMessage = {
                 id: timestamp + 1,
-                content: response,
+                content: response.text,
                 sender: 'bot',
                 timestamp: new Date().toISOString()
             };
@@ -4070,9 +4290,7 @@ const AndyChat = ({ embedId, tooltip, name, headline, description, welcomeMessag
             console.error('AndyChat: Message request failed.');
             const errorMessage = {
                 id: timestamp + 3,
-                content: config?.defaultLang === 'es'
-                    ? 'Lo siento, no pude responder. Inténtalo de nuevo.'
-                    : 'Sorry, I could not answer. Please try again.',
+                content: strings.sendFailure,
                 sender: 'bot',
                 timestamp: new Date().toISOString(),
                 isError: true
@@ -4188,7 +4406,7 @@ const AndyChat = ({ embedId, tooltip, name, headline, description, welcomeMessag
             bubble.addEventListener('click', () => setIsOpen(prev => !prev));
         }
         const isPillStyle = config?.bubbleStyle === 'pill';
-        const displayLabel = bubbleLabel || config?.bubbleLabel || (isPillStyle ? getDefaultBubbleLabel(config?.defaultLang || 'en') : null);
+        const displayLabel = bubbleLabel || config?.bubbleLabel || (isPillStyle ? getDefaultBubbleLabel(uiLang) : null);
         const bubbleLogoUrl = config?.logoUrl || CHAT_BUBBLE_DEFAULT_ICON_URL;
         if (bubble) {
             bubble.className = 'andy-chat-bubble';
@@ -4241,10 +4459,10 @@ const AndyChat = ({ embedId, tooltip, name, headline, description, welcomeMessag
                                     if (message.isLoading) {
                                         return (jsx("div", { className: 'andy-message-container andy-message-container--bot andy-message-container--loading', children: jsx("div", { className: 'andy-message andy-message--bot', children: jsxs("div", { className: 'andy-typing-indicator', children: [jsx("div", { className: 'andy-typing-indicator__dot' }), jsx("div", { className: 'andy-typing-indicator__dot' }), jsx("div", { className: 'andy-typing-indicator__dot' })] }) }) }, message.id));
                                     }
-                                    return (jsxs("div", { className: `andy-message-container andy-message-container--${message.sender}`, children: [message.sender === 'bot' && (jsxs("div", { className: `andy-message andy-message--bot ${message.isError ? 'andy-message--error' : ''}`, children: [jsxs("div", { className: 'andy-bot-header', children: [jsx("div", { className: 'andy-bot-header__icon', children: config?.logoUrl ? (jsx("img", { src: config.logoUrl, alt: 'Bot Avatar', className: 'andy-bot-header__icon-image' })) : (jsx("img", { src: CHAT_BUBBLE_DEFAULT_ICON_URL, alt: 'Bot Avatar', className: 'andy-bot-header__icon-image andy-bot-header__icon-image--default' })) }), jsx("span", { className: 'andy-bot-header__name', children: config?.name || 'Andy bot' })] }), jsx("div", { className: 'andy-message__content', children: jsx("div", { dangerouslySetInnerHTML: { __html: parseMarkdown(message.content) } }) })] })), message.sender === 'user' && (jsx("div", { className: 'andy-message andy-message--user', children: jsx("div", { className: 'andy-message__content', children: jsx("p", { children: message.content }) }) }))] }, message.id));
-                                }), isLoading && (jsx("div", { className: 'andy-message-container andy-message-container--bot andy-message-container--typing', children: jsx("div", { className: 'andy-message andy-message--bot andy-message--typing', children: jsxs("div", { className: 'andy-typing-indicator', children: [jsx("div", { className: 'andy-typing-indicator__dot' }), jsx("div", { className: 'andy-typing-indicator__dot' }), jsx("div", { className: 'andy-typing-indicator__dot' })] }) }) }))] }), jsxs("div", { className: 'andy-chat-window__bottom', children: [config?.predefinedQuestions &&
-                                    config.predefinedQuestions.length > 0 &&
-                                    showPredefinedQuestions && (jsxs("div", { className: 'andy-predefined-questions', id: 'andy-predefined-questions', children: [jsx("div", { className: 'andy-predefined-questions__header', children: jsx("p", { className: 'andy-predefined-questions__title', children: "What would you like to know?" }) }), jsx("div", { className: 'andy-predefined-questions__list', children: config.predefinedQuestions.map((q, index) => (jsxs("button", { type: 'button', className: 'andy-predefined-question', "data-question": q.question, disabled: isCollectingUserInfo || isLoading || !config, children: [jsx("span", { className: 'andy-predefined-question__icon', children: "\uD83D\uDCAC" }), jsx("span", { className: 'andy-predefined-question__text', children: q.question })] }, index))) })] })), jsx("div", { className: 'andy-chat-window__input', children: jsx("div", { className: 'andy-input-container', children: jsxs("div", { className: 'andy-input', children: [jsx("input", { type: 'text', className: 'andy-input__field', id: 'andy-message-input', placeholder: config ? 'Type your message...' : '...', "aria-label": 'Message input', onKeyDown: e => {
+                                    return (jsxs("div", { className: `andy-message-container andy-message-container--${message.sender} ${message.isWaiting ? 'andy-message-container--waiting' : ''}`, children: [message.sender === 'bot' && (jsxs("div", { className: `andy-message andy-message--bot ${message.isHuman ? 'andy-message--operator' : ''} ${message.isWaiting ? 'andy-message--waiting' : ''} ${message.isError ? 'andy-message--error' : ''}`, children: [jsxs("div", { className: 'andy-bot-header', children: [jsx("div", { className: 'andy-bot-header__icon', children: config?.logoUrl ? (jsx("img", { src: config.logoUrl, alt: 'Bot Avatar', className: 'andy-bot-header__icon-image' })) : (jsx("img", { src: CHAT_BUBBLE_DEFAULT_ICON_URL, alt: 'Bot Avatar', className: 'andy-bot-header__icon-image andy-bot-header__icon-image--default' })) }), jsx("span", { className: 'andy-bot-header__name', children: message.isHuman ? strings.teamName : config?.name || 'Andy bot' })] }), jsx("div", { className: 'andy-message__content', children: jsx("div", { dangerouslySetInnerHTML: { __html: parseMarkdown(message.content) } }) })] })), message.sender === 'user' && (jsx("div", { className: 'andy-message andy-message--user', children: jsx("div", { className: 'andy-message__content', children: jsx("p", { children: message.content }) }) }))] }, message.id));
+                                }), isLoading && (jsx("div", { className: 'andy-message-container andy-message-container--bot andy-message-container--typing', children: jsx("div", { className: 'andy-message andy-message--bot andy-message--typing', children: jsxs("div", { className: 'andy-typing-indicator', children: [jsx("div", { className: 'andy-typing-indicator__dot' }), jsx("div", { className: 'andy-typing-indicator__dot' }), jsx("div", { className: 'andy-typing-indicator__dot' })] }) }) }))] }), jsxs("div", { className: 'andy-chat-window__bottom', children: [activeQuestions &&
+                                    activeQuestions.length > 0 &&
+                                    showPredefinedQuestions && (jsxs("div", { className: 'andy-predefined-questions', id: 'andy-predefined-questions', children: [jsx("div", { className: 'andy-predefined-questions__header', children: jsx("p", { className: 'andy-predefined-questions__title', children: strings.predefinedQuestionsTitle }) }), jsx("div", { className: 'andy-predefined-questions__list', children: activeQuestions.map((q, index) => (jsxs("button", { type: 'button', className: 'andy-predefined-question', "data-question": q.question, disabled: isCollectingUserInfo || isLoading || !config, children: [jsx("span", { className: 'andy-predefined-question__icon', children: "\uD83D\uDCAC" }), jsx("span", { className: 'andy-predefined-question__text', children: q.question })] }, index))) })] })), jsx("div", { className: 'andy-chat-window__input', children: jsx("div", { className: 'andy-input-container', children: jsxs("div", { className: 'andy-input', children: [jsx("input", { type: 'text', className: 'andy-input__field', id: 'andy-message-input', placeholder: config ? strings.inputPlaceholder : '...', "aria-label": 'Message input', onKeyDown: e => {
                                                         if (e.key === 'Enter' && e.target.value.trim()) {
                                                             handleSendMessage(e.target.value);
                                                             e.target.value = '';
@@ -4346,7 +4564,7 @@ const useAndyChat = (embedId) => {
             return newIsOpen;
         });
     }, [config, welcomePopupShown, userInfoCollected]);
-    const sendMessage$1 = useCallback(async (messageText) => {
+    const sendMessage = useCallback(async (messageText) => {
         if (!messageText.trim() || !config || !sessionId) {
             return;
         }
@@ -4358,10 +4576,12 @@ const useAndyChat = (embedId) => {
         };
         setMessages(prev => [...prev, userMessage]);
         try {
-            const response = await sendMessage(embedId, sessionId, messageText);
+            const response = await sendMessageForWidget(embedId, sessionId, messageText);
+            if (response.status === 'waiting')
+                return response;
             const botMessage = {
                 id: Date.now() + 1,
-                content: response || 'I apologize, but I encountered an error processing your request.',
+                content: response.text || 'I apologize, but I encountered an error processing your request.',
                 sender: 'bot',
                 timestamp: new Date().toISOString()
             };
@@ -4458,7 +4678,7 @@ const useAndyChat = (embedId) => {
         error,
         initializeChatbot,
         toggleChat,
-        sendMessage: sendMessage$1,
+        sendMessage,
         showFaq,
         hideFaq,
         showWelcomePopup,