@constructor-io/constructorio-ui-asa 1.7.2 → 1.8.0

package/lib/mjs/components/Chat/Chat.js

@@ -1,6 +1,9 @@
 import React, { useRef, useEffect, useImperativeHandle, forwardRef } from 'react';
 import useAsaResults from '../../hooks/useAsaResults';
+import { useCioAsaContext } from '../../hooks/useCioAsaContext';
 import useFocusTrap from '../../hooks/useFocusTrap';
+import useLatest from '../../hooks/useLatest';
+import { normalizeItemToProduct } from '../../utils/productNormalizer';
 import translate from '../../utils/translate';
 import ChatHeader from './ChatHeader';
 import WelcomeScreen from './WelcomeScreen';
@@ -22,20 +25,41 @@ function getAnnouncement(messages, translations) {
     }
     return '';
 }
-const Chat = forwardRef(({ onClose, className, initialSuggestions, termsText, onProductClick, onViewMore, onAddToCart, aspectRatio, currency, normalizeItem, componentOverrides, translations, initialThreadId, showStopButton = false, }, ref) => {
-    const { messages, sendMessage, isStreaming, abort, clearHistory } = useAsaResults({
+const Chat = forwardRef(({ onClose, className, initialSuggestions, termsText, onProductClick, onViewMore, onAddToCart, aspectRatio, currency, normalizeItem, componentOverrides, translations, initialThreadId, onThreadsChange, showStopButton = false, }, ref) => {
+    const { messages, sendMessage, isStreaming, canAbort, abort, clearHistory, isHydrating, threads, activeThreadId, newThread, switchThread, } = useAsaResults({
         initialThreadId,
+        normalizeItem: (item) => (normalizeItem ?? normalizeItemToProduct)(item, {
+            saleBadgeText: translate('CioAsa.results.saleBadge', translations),
+        }),
     });
     const chatViewRef = useRef(null);
     const containerRef = useRef(null);
     const isWelcome = messages.length === 0;
+    // While another thread loads, keep the chat frame (header, close button) instead of a blank body.
+    const lastViewRef = useRef(null);
+    if (!isHydrating)
+        lastViewRef.current = isWelcome ? 'welcome' : 'chat';
+    const showWelcome = !isHydrating && isWelcome;
+    const showChat = !isHydrating && !isWelcome;
+    const showChatFrame = showChat || (isHydrating && lastViewRef.current === 'chat');
     const isModal = typeof onClose === 'function';
     const announcement = getAnnouncement(messages, translations);
-    useImperativeHandle(ref, () => ({
+    useImperativeHandle(ref, () => ({ abort, clearHistory, newThread, switchThread }), [
         abort,
         clearHistory,
-    }));
+        newThread,
+        switchThread,
+    ]);
+    const hasPersistence = Boolean(useCioAsaContext()?.persistence);
+    const onThreadsChangeRef = useLatest(onThreadsChange);
     useEffect(() => {
+        if (!hasPersistence || isHydrating)
+            return;
+        onThreadsChangeRef.current?.(threads, activeThreadId);
+    }, [threads, activeThreadId, isHydrating, hasPersistence, onThreadsChangeRef]);
+    useEffect(() => {
+        if (isHydrating)
+            return;
         const root = isWelcome ? containerRef.current : chatViewRef.current;
         const input = root?.querySelector('input');
         if (input) {
@@ -48,15 +72,17 @@ const Chat = forwardRef(({ onClose, className, initialSuggestions, termsText, on
                 input.focus();
             }
         }
-    }, [isWelcome]);
+    }, [isWelcome, isHydrating]);
     useFocusTrap(containerRef, { onEscape: onClose, trapFocus: isModal });
     return (React.createElement("div", { className: ['cio-asa', 'cio-asa-chat', className].filter(Boolean).join(' '), ref: containerRef, role: 'dialog', "aria-modal": isModal ? 'true' : undefined, "aria-label": translate(isWelcome ? 'CioAsa.welcome.title' : 'CioAsa.header.title', translations) },
         React.createElement("div", { className: 'cio-sr-only', role: 'status' }, announcement),
-        React.createElement("div", { className: 'cio-asa-chat-body' }, isWelcome ? (React.createElement("div", { className: 'cio-asa-chat-view cio-asa-chat-view--welcome' },
-            React.createElement(WelcomeScreen, { suggestions: initialSuggestions, onSend: sendMessage, onClose: onClose, termsText: termsText, translations: translations, componentOverrides: componentOverrides?.welcomeScreen }))) : (React.createElement("div", { className: 'cio-asa-chat-view cio-asa-chat-view--chat', ref: chatViewRef },
-            React.createElement(ChatHeader, { onClose: onClose, translations: translations, componentOverrides: componentOverrides?.header }),
-            React.createElement(ChatMessageList, { messages: messages, onProductClick: onProductClick, onViewMore: onViewMore, onAddToCart: onAddToCart, aspectRatio: aspectRatio, currency: currency, normalizeItem: normalizeItem, addToCartText: translate('CioAsa.results.addToCart', translations), viewMoreText: translate('CioAsa.results.viewMore', translations), aiMessageOverrides: componentOverrides?.aiMessage, userMessageOverrides: componentOverrides?.userMessage, resultsBlockOverrides: componentOverrides?.resultsBlock, translations: translations, onSend: sendMessage, isStreaming: isStreaming }),
-            React.createElement(ChatInput, { onSubmit: sendMessage, isDisabled: isStreaming, isStreaming: isStreaming, onAbort: abort, showStopButton: showStopButton, translations: translations, componentOverrides: componentOverrides?.input }))))));
+        React.createElement("div", { className: 'cio-asa-chat-body' },
+            showWelcome && (React.createElement("div", { className: 'cio-asa-chat-view cio-asa-chat-view--welcome' },
+                React.createElement(WelcomeScreen, { suggestions: initialSuggestions, onSend: sendMessage, onClose: onClose, termsText: termsText, translations: translations, componentOverrides: componentOverrides?.welcomeScreen }))),
+            showChatFrame && (React.createElement("div", { className: 'cio-asa-chat-view cio-asa-chat-view--chat', ref: chatViewRef },
+                React.createElement(ChatHeader, { onClose: onClose, translations: translations, componentOverrides: componentOverrides?.header }),
+                React.createElement(ChatMessageList, { messages: messages, onProductClick: onProductClick, onViewMore: onViewMore, onAddToCart: onAddToCart, aspectRatio: aspectRatio, currency: currency, normalizeItem: normalizeItem, addToCartText: translate('CioAsa.results.addToCart', translations), viewMoreText: translate('CioAsa.results.viewMore', translations), aiMessageOverrides: componentOverrides?.aiMessage, userMessageOverrides: componentOverrides?.userMessage, resultsBlockOverrides: componentOverrides?.resultsBlock, translations: translations, onSend: sendMessage, isStreaming: isStreaming }),
+                React.createElement(ChatInput, { onSubmit: sendMessage, isDisabled: isStreaming || isHydrating, isStreaming: isStreaming, onAbort: canAbort ? abort : undefined, showStopButton: showStopButton, translations: translations, componentOverrides: componentOverrides?.input }))))));
 });
 Chat.displayName = 'Chat';
 export default Chat;

package/lib/mjs/components/CioAsa/CioAsa.js

@@ -12,8 +12,12 @@ import Chat from '../Chat/Chat';
 const CioAsa = React.forwardRef((props, ref) => {
     const { 
     // Provider configuration — everything else belongs to Chat.
-    apiKey, cioClient, testCells, staticRequestConfigs, formatters, urlHelpers, callbacks, section, ...chatProps } = props;
-    return (React.createElement(CioAsaProvider, { apiKey: apiKey, cioClient: cioClient, testCells: testCells, staticRequestConfigs: staticRequestConfigs, formatters: formatters, urlHelpers: urlHelpers, callbacks: callbacks, section: section },
+    apiKey, cioClient, testCells, staticRequestConfigs, formatters, urlHelpers, callbacks, section, persistConversation, userId = null, ...chatProps } = props;
+    // Split so TypeScript can match the pair against the provider's props.
+    const persistenceProps = persistConversation
+        ? { persistConversation, userId }
+        : { userId };
+    return (React.createElement(CioAsaProvider, { apiKey: apiKey, cioClient: cioClient, testCells: testCells, staticRequestConfigs: staticRequestConfigs, formatters: formatters, urlHelpers: urlHelpers, callbacks: callbacks, section: section, ...persistenceProps },
         React.createElement(Chat, { ...chatProps, ref: ref })));
 });
 CioAsa.displayName = 'CioAsa';

package/lib/mjs/components/CioAsaProvider/CioAsaProvider.js

@@ -1,17 +1,43 @@
-import React, { useMemo, useState } from 'react';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
 import useCioClient from '../../hooks/useCioClient';
 import { AsaContext } from '../../hooks/useCioAsaContext';
 import * as defaultFormatters from '../../utils/formatters';
 import * as defaultUrlHelpers from '../../utils/urlHelpers';
+import { readClientOptions } from '../../utils/clientOptions';
+import { persistenceNamespace, sharedLocalStoragePersistence, shopperId, storageAreaFor, } from '../../utils/localStoragePersistence';
 export default function CioAsaProvider(props) {
-    const { apiKey, formatters, urlHelpers, staticRequestConfigs = { domain: 'chatbot' }, cioClient: customCioClient, testCells, callbacks, section = 'Products', children, } = props;
+    const { apiKey, formatters, urlHelpers, staticRequestConfigs = { domain: 'chatbot' }, cioClient: customCioClient, testCells, callbacks, section = 'Products', persistConversation: persistOptions, userId: userIdProp, children, } = props;
+    // Read field by field: an inline options object is a new reference on every render.
+    const persistenceEnabled = Boolean(persistOptions?.enabled);
     const [cioClientOptions, setCioClientOptions] = useState({});
+    const initialUserId = useRef(userIdProp).current;
+    const clientInit = useMemo(() => initialUserId === undefined
+        ? cioClientOptions
+        : { ...cioClientOptions, userId: shopperId(initialUserId) }, [cioClientOptions, initialUserId]);
     const cioClient = useCioClient({
         apiKey,
         cioClient: customCioClient,
-        cioClientOptions,
+        cioClientOptions: clientInit,
         testCells,
     });
+    const userId = shopperId(userIdProp);
+    const syncUserId = persistenceEnabled || userIdProp !== undefined;
+    useEffect(() => {
+        if (customCioClient || !cioClient || !syncUserId)
+            return;
+        cioClient.setClientOptions({ userId });
+    }, [cioClient, customCioClient, syncUserId, userId]);
+    const resolvedApiKey = apiKey ?? readClientOptions(cioClient)?.apiKey;
+    const { domain } = staticRequestConfigs;
+    const persistence = useMemo(() => {
+        if (!persistenceEnabled || resolvedApiKey === undefined)
+            return undefined;
+        return sharedLocalStoragePersistence(persistenceNamespace({ apiKey: resolvedApiKey, domain, userId }), storageAreaFor(userId));
+    }, [persistenceEnabled, resolvedApiKey, domain, userId]);
+    const persistenceScope = persistence && (userId === undefined ? 'guest' : 'user');
+    const persistenceIndex = persistence && resolvedApiKey !== undefined
+        ? persistenceNamespace({ apiKey: resolvedApiKey, domain })
+        : undefined;
     const contextValue = useMemo(() => ({
         cioClient,
         cioClientOptions,
@@ -21,6 +47,20 @@ export default function CioAsaProvider(props) {
         urlHelpers: { ...defaultUrlHelpers, ...urlHelpers },
         callbacks,
         section,
-    }), [cioClient, cioClientOptions, formatters, urlHelpers, staticRequestConfigs, callbacks, section]);
+        persistence,
+        persistenceScope,
+        persistenceIndex,
+    }), [
+        cioClient,
+        cioClientOptions,
+        formatters,
+        urlHelpers,
+        staticRequestConfigs,
+        callbacks,
+        section,
+        persistence,
+        persistenceScope,
+        persistenceIndex,
+    ]);
     return (React.createElement(AsaContext.Provider, { value: contextValue }, typeof children === 'function' ? children(contextValue) : children));
 }

package/lib/mjs/components/ResultsBlock/ResultsGroup.js

@@ -18,7 +18,8 @@ function NextButton() {
  */
 export default function ResultsGroup({ groupData, label, slidesToShow, gap, showTitle, viewMoreText, addToCartText, saleBadgeText, currency, intent, intentResultId, normalizeItem, onProductClick, onAddToCart, onViewMore, componentOverrides, tracking, callbacks, }) {
     const { searchResultId } = groupData;
-    const products = groupData.searchResults.map((item) => normalizeItem(item, { saleBadgeText }));
+    const products = groupData.products ??
+        groupData.searchResults.map((item) => normalizeItem(item, { saleBadgeText }));
     const canTrack = !!intent && !!searchResultId;
     const { ref: viewRef } = useViewportTracking({
         enabled: canTrack,

package/lib/mjs/hooks/agentStream.js

@@ -0,0 +1,106 @@
+import { handleFollowUpRefinement, handleMessage, handleSearchResult, handleServerError, handleStreamEnd, handleStreamError, updateMessageById, } from './asaStreamHandlers';
+/** Drains an agent stream into the assistant message identified by `assistantId`. */
+export function readAgentStream(stream, assistantId, setMessages, callbacks) {
+    const reader = stream.getReader();
+    let cancelled = false;
+    let pendingGroup = null;
+    let intentResultId;
+    let loadStartFired = false;
+    let groupCount = 0;
+    const patchAssistant = (patch) => {
+        updateMessageById(setMessages, assistantId, (m) => ({ ...m, ...patch }));
+    };
+    const fireLoadStart = () => {
+        if (loadStartFired)
+            return;
+        loadStartFired = true;
+        callbacks.onLoadStart(intentResultId);
+    };
+    const done = (async () => {
+        try {
+            while (!cancelled) {
+                // eslint-disable-next-line no-await-in-loop
+                const res = await reader.read();
+                if (cancelled)
+                    break;
+                if (res.done) {
+                    handleStreamEnd(assistantId, setMessages);
+                    callbacks.onFinish({ searchResultCount: groupCount, intentResultId });
+                    break;
+                }
+                const { type, data } = res.value;
+                if (!intentResultId && data?.intent_result_id) {
+                    intentResultId = data.intent_result_id;
+                    patchAssistant({ intentResultId });
+                }
+                if (type === 'start') {
+                    if (data?.thread_id)
+                        patchAssistant({ threadId: data.thread_id });
+                    callbacks.onStart(data?.thread_id);
+                    fireLoadStart();
+                }
+                else if (type === 'group') {
+                    pendingGroup = {
+                        display_name: data?.display_name ?? data?.group ?? '',
+                        value: data?.value ?? data?.group ?? '',
+                    };
+                }
+                else if (type === 'search_result') {
+                    fireLoadStart();
+                    groupCount += 1;
+                    pendingGroup = handleSearchResult(data, pendingGroup, assistantId, setMessages);
+                }
+                else if (type === 'message') {
+                    fireLoadStart();
+                    handleMessage(data, assistantId, setMessages);
+                }
+                else if (type === 'follow_up_refinement') {
+                    fireLoadStart();
+                    handleFollowUpRefinement(data, assistantId, setMessages);
+                }
+                else if (type === 'server_error') {
+                    handleServerError(assistantId, setMessages);
+                    break;
+                }
+            }
+        }
+        catch {
+            if (!cancelled)
+                handleStreamError(assistantId, setMessages);
+        }
+        finally {
+            // Cancelling an errored stream rejects with the stored error; nothing here needs it.
+            if (!cancelled)
+                reader.cancel().catch(() => { });
+        }
+    })();
+    return {
+        assistantId,
+        done,
+        cancel: () => {
+            cancelled = true;
+            reader.cancel().catch(() => { });
+        },
+    };
+}
+/** Streams into `assistant`, reporting to the owner `createOwner` returns for the new turn. */
+export function startTurn(stream, assistant, createOwner, callbacks) {
+    const turn = { assistant };
+    turn.owner = createOwner(turn);
+    const handle = readAgentStream(stream, assistant.id, (action) => {
+        if (typeof action === 'function')
+            [turn.assistant] = action([turn.assistant]);
+        turn.owner.setMessages(action);
+    }, {
+        onLoadStart: callbacks.onLoadStart,
+        onFinish: (result) => callbacks.onFinish({ ...result, threadId: turn.serverThreadId }),
+        onStart: (threadId) => {
+            if (threadId)
+                turn.serverThreadId = threadId;
+            turn.owner.onStart(threadId);
+        },
+    });
+    Object.assign(turn, handle);
+    handle.done.then(() => turn.owner.onDone());
+    return turn;
+}

package/lib/mjs/hooks/asaStreamHandlers.js

@@ -8,7 +8,7 @@ const INTERNAL_REQUEST_FIELDS = ['features', 'feature_variants'];
 function omitInternalRequestFields(request) {
     return Object.fromEntries(Object.entries(request).filter(([key]) => !INTERNAL_REQUEST_FIELDS.includes(key)));
 }
-function updateMessageById(setMessages, id, patch) {
+export function updateMessageById(setMessages, id, patch) {
     setMessages((prev) => prev.map((msg) => (msg.id === id ? patch(msg) : msg)));
 }
 export function handleSearchResult(data, pendingGroup, assistantId, setMessages) {

package/lib/mjs/hooks/persistence/backgroundTurns.js

@@ -0,0 +1,120 @@
+import { prepareSnapshot } from '../../utils/chatSession';
+import { normalizeHydratedMessages, saveThreadAndRetireStale } from '../../utils/chatThreads';
+const turns = new Set();
+const listeners = new Set();
+const notify = () => listeners.forEach((listener) => listener());
+/** An answer that went on after its conversation left the screen, until it is stored or shown again. */
+export class BackgroundTurn {
+    turn;
+    store;
+    /** The conversation's own session, forked from the chat that sent the message. */
+    session;
+    messages;
+    streaming = true;
+    /** Whether the latest snapshot is known to be stored. */
+    saved = false;
+    /** Every id the conversation was stored under, so a list read before a re-key still finds it. */
+    ids = new Set();
+    /** Its writes, in order; a chat that takes the turn back writes after them. */
+    writes;
+    constructor(turn, params) {
+        this.turn = turn;
+        this.store = params.store;
+        this.session = params.session;
+        this.messages = params.messages;
+        this.writes = params.after;
+        if (this.session.storageThreadId)
+            this.ids.add(this.session.storageThreadId);
+        this.turn.owner = {
+            setMessages: (action) => {
+                this.messages = typeof action === 'function' ? action(this.messages) : action;
+            },
+            onStart: (threadId) => {
+                if (threadId)
+                    this.session.serverThreadId = threadId;
+                this.save().then(notify);
+            },
+            onDone: () => {
+                this.streaming = false;
+                this.messages = normalizeHydratedMessages(this.messages);
+                this.save().then(() => {
+                    if (this.saved)
+                        turns.delete(this);
+                    notify();
+                });
+            },
+        };
+    }
+    save() {
+        const { snapshot, staleIds } = prepareSnapshot(this.session, this.messages);
+        const { store } = this;
+        this.ids.add(snapshot.threadId);
+        this.saved = false;
+        this.writes = this.writes
+            .then(() => saveThreadAndRetireStale(store, snapshot, staleIds))
+            .then(({ saved, leftover }) => {
+            if (leftover.length > 0) {
+                this.session.orphanIds = Array.from(new Set([...this.session.orphanIds, ...leftover]));
+            }
+            if (this.session.lastSyncedAt === snapshot.updatedAt)
+                this.saved = saved;
+        })
+            .catch(() => { });
+        return this.writes;
+    }
+    /** Later writes go into `store`. */
+    moveTo(store) {
+        this.store = store;
+    }
+    /** Stores the conversation settled, without awaiting: the page is going away. */
+    flush() {
+        if (!this.streaming && this.saved)
+            return;
+        const { snapshot, staleIds } = prepareSnapshot(this.session, normalizeHydratedMessages(this.messages));
+        if (this.store.saveThreadSync)
+            this.store.saveThreadSync(snapshot, staleIds);
+        else
+            this.store.saveThread(snapshot).catch(() => { });
+    }
+}
+let listeningForPagehide = false;
+/**
+ * Keeps `turn` streaming with no chat showing it. It is saved into `store` at once, on `start`
+ * and when done, each write queued behind `after`, and is dropped from here once the last one landed.
+ */
+export function continueInBackground(turn, params) {
+    const bg = new BackgroundTurn(turn, params);
+    turns.add(bg);
+    if (!listeningForPagehide && typeof window !== 'undefined') {
+        listeningForPagehide = true;
+        window.addEventListener('pagehide', () => turns.forEach((t) => t.flush()));
+    }
+    bg.save().then(notify);
+}
+/**
+ * Takes back the background turn stored in `store` under `threadId` for a chat to show, handing an
+ * unfinished one to `createOwner`; `null` if there is none.
+ */
+export function resumeBackgroundTurn(store, threadId, createOwner) {
+    const bg = Array.from(turns).find((t) => t.store === store && t.ids.has(threadId));
+    if (!bg)
+        return null;
+    turns.delete(bg);
+    if (bg.streaming)
+        bg.turn.owner = createOwner(bg.turn);
+    return bg;
+}
+/** Points the background turns of `from` at `to`; resolves once their writes into `from` settled. */
+export function moveBackgroundTurns(from, to) {
+    const moving = Array.from(turns).filter((bg) => bg.store === from);
+    const settled = Promise.all(moving.map((bg) => bg.writes)).then(() => { });
+    moving.forEach((bg) => bg.moveTo(to));
+    return settled;
+}
+/** Called whenever a background turn is stored or finishes. */
+export function subscribeBackgroundTurns(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}