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

package/lib/cjs/components/Button/Button.js

@@ -1,11 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-const react_1 = tslib_1.__importDefault(require("react"));
+const react_1 = tslib_1.__importStar(require("react"));
 const constructorio_ui_components_1 = require("@constructor-io/constructorio-ui-components");
 const icons_1 = require("../icons");
-function Button({ theme = 'dark', size = 'sm', onClick, label = 'Shopping assistant', }) {
-    return (react_1.default.createElement(constructorio_ui_components_1.Button, { className: `cio-asa-button cio-asa-button--${theme} cio-asa-button--${size}`, size: size === 'lg' ? 'default' : 'sm', onClick: onClick },
+const useCioAsaContext_1 = require("../../hooks/useCioAsaContext");
+const useAsaTracking_1 = tslib_1.__importDefault(require("../../hooks/useAsaTracking"));
+const AGENT_BUTTON_CLICK_MODE = 'chat';
+function Button({ theme = 'dark', size = 'sm', onClick, label = 'Shopping assistant', positionOnPage, pageType, instanceId, }) {
+    var _a, _b, _c;
+    const context = (0, useCioAsaContext_1.useCioAsaContext)();
+    const agentDomain = (_a = context === null || context === void 0 ? void 0 : context.staticRequestConfigs) === null || _a === void 0 ? void 0 : _a.domain;
+    const tracking = (0, useAsaTracking_1.default)({
+        tracker: (_c = (_b = context === null || context === void 0 ? void 0 : context.cioClient) === null || _b === void 0 ? void 0 : _b.tracker) !== null && _c !== void 0 ? _c : undefined,
+        section: context === null || context === void 0 ? void 0 : context.section,
+    });
+    const handleClick = (0, react_1.useCallback)(() => {
+        var _a, _b;
+        if (agentDomain) {
+            const payload = Object.assign(Object.assign(Object.assign({ mode: AGENT_BUTTON_CLICK_MODE, agentDomain }, (positionOnPage && { positionOnPage })), (pageType && { pageType })), (instanceId && { instanceId }));
+            tracking.trackAgentButtonClick(payload);
+            (_b = (_a = context === null || context === void 0 ? void 0 : context.callbacks) === null || _a === void 0 ? void 0 : _a.onAgentButtonClick) === null || _b === void 0 ? void 0 : _b.call(_a, payload);
+        }
+        onClick === null || onClick === void 0 ? void 0 : onClick();
+    }, [agentDomain, positionOnPage, pageType, instanceId, tracking, context, onClick]);
+    return (react_1.default.createElement(constructorio_ui_components_1.Button, { className: `cio-asa-button cio-asa-button--${theme} cio-asa-button--${size}`, size: size === 'lg' ? 'default' : 'sm', onClick: handleClick },
         theme === 'dark' ? react_1.default.createElement(icons_1.ChatBubbleDarkIcon, null) : react_1.default.createElement(icons_1.ChatBubbleLightIcon, null),
         react_1.default.createElement("span", { className: 'cio-asa-button__label' }, label)));
 }

package/lib/cjs/components/Chat/Chat.js

@@ -29,7 +29,7 @@ function getAnnouncement(messages, translations) {
     }
     return '';
 }
-const Chat = (0, react_1.forwardRef)(({ onClose, className, initialSuggestions, termsText, onProductClick, onViewMore, onAddToCart, aspectRatio, currency, normalizeItem, componentOverrides, translations, initialThreadId, onThreadsChange, showStopButton = false, }, ref) => {
+const Chat = (0, react_1.forwardRef)(({ onClose, className, initialSuggestions, termsText, onProductClick, onViewMore, onAddToCart, aspectRatio, currency, normalizeItem, componentOverrides, translations, initialThreadId, initialPrompt, onThreadsChange, showStopButton = false, }, ref) => {
     var _a;
     const { messages, sendMessage, isStreaming, canAbort, abort, clearHistory, isHydrating, threads, activeThreadId, newThread, switchThread, } = (0, useAsaResults_1.default)({
         initialThreadId,
@@ -49,12 +49,25 @@ const Chat = (0, react_1.forwardRef)(({ onClose, className, initialSuggestions,
     const showChatFrame = showChat || (isHydrating && lastViewRef.current === 'chat');
     const isModal = typeof onClose === 'function';
     const announcement = getAnnouncement(messages, translations);
-    (0, react_1.useImperativeHandle)(ref, () => ({ abort, clearHistory, newThread, switchThread }), [
+    (0, react_1.useImperativeHandle)(ref, () => ({
         abort,
         clearHistory,
         newThread,
         switchThread,
-    ]);
+        sendMessage: (text, options) => sendMessage(text, 'external', options),
+    }), [abort, clearHistory, newThread, switchThread, sendMessage]);
+    // Sent from a timer so StrictMode's mount, unmount, mount cannot cancel the stream it starts.
+    const initialPromptRef = (0, react_1.useRef)(initialPrompt);
+    (0, react_1.useEffect)(() => {
+        const prompt = initialPromptRef.current;
+        if (isHydrating || !prompt)
+            return undefined;
+        const timer = setTimeout(() => {
+            initialPromptRef.current = undefined;
+            sendMessage(prompt, 'external');
+        });
+        return () => clearTimeout(timer);
+    }, [isHydrating, sendMessage]);
     const hasPersistence = Boolean((_a = (0, useCioAsaContext_1.useCioAsaContext)()) === null || _a === void 0 ? void 0 : _a.persistence);
     const onThreadsChangeRef = (0, useLatest_1.default)(onThreadsChange);
     (0, react_1.useEffect)(() => {

package/lib/cjs/hooks/useAsaResults.js

@@ -8,6 +8,7 @@ const useChatPersistence_1 = tslib_1.__importDefault(require("./persistence/useC
 const agentStream_1 = require("./agentStream");
 const chatSession_1 = require("../utils/chatSession");
 const productNormalizer_1 = require("../utils/productNormalizer");
+const chatThreads_1 = require("../utils/chatThreads");
 const useLatest_1 = tslib_1.__importDefault(require("./useLatest"));
 function useAsaResults(options) {
     var _a;
@@ -58,13 +59,13 @@ function useAsaResults(options) {
     });
     const { beginTurn, screenOwner } = store;
     (0, react_1.useEffect)(() => cancelStream, [cancelStream]);
-    const sendMessage = (0, react_1.useCallback)((text, source = 'input') => {
+    const sendToCurrentThread = (0, react_1.useCallback)((text, source) => {
         var _a, _b;
         const intent = text.trim();
         if (!intent || session.isStreaming || session.foreignInFlight)
             return;
         beginTurn();
-        trackingRef.current.trackSubmit(intent);
+        trackingRef.current.trackSubmit(intent, source);
         (_b = (_a = callbacksRef.current) === null || _a === void 0 ? void 0 : _a.onAssistantSubmit) === null || _b === void 0 ? void 0 : _b.call(_a, { intent, source });
         const userMessage = {
             id: (0, chatSession_1.nextMessageId)(session),
@@ -113,6 +114,32 @@ function useAsaResults(options) {
         callbacksRef,
         staticRequestConfigsRef,
     ]);
+    const { newThread, switchThread } = store;
+    /**
+     * Sends `text`. With `threadId`, first moves to that conversation, loading it from storage
+     * when persistence has it and otherwise continuing it on the server with an empty screen.
+     */
+    const sendMessage = (0, react_1.useCallback)((text, source = 'input', { threadId } = {}) => {
+        if (!threadId ||
+            threadId === session.serverThreadId ||
+            threadId === session.storageThreadId) {
+            sendToCurrentThread(text, source);
+            return;
+        }
+        (() => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (persistence)
+                yield switchThread(threadId);
+            else
+                newThread();
+            // A turn that started meanwhile (or one still streaming in the background) owns the screen.
+            if (session.isStreaming || session.foreignInFlight)
+                return;
+            if (!session.serverThreadId && !(0, chatThreads_1.isLocalThreadId)(threadId)) {
+                session.serverThreadId = threadId;
+            }
+            sendToCurrentThread(text, source);
+        }))();
+    }, [session, persistence, newThread, switchThread, sendToCurrentThread]);
     /**
      * Cancels the in-flight request while keeping the conversation: the partial reply is
      * settled as `done` (so the typing indicator stops and streamed text survives) and the
@@ -159,8 +186,8 @@ function useAsaResults(options) {
         isHydrating: store.isHydrating,
         threads: store.threads,
         activeThreadId: store.activeThreadId,
-        newThread: store.newThread,
-        switchThread: store.switchThread,
+        newThread,
+        switchThread,
     };
 }
 exports.default = useAsaResults;

package/lib/cjs/hooks/useAsaTracking.js

@@ -1,7 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const react_1 = require("react");
+/** Beacon `source` values, aligned with the ones the behavioral-actions API documents. */
+const BEACON_SUBMIT_SOURCES = {
+    input: 'input',
+    suggestion: 'suggestion',
+    refinement: 'follow_up',
+    // A prompt the host page sent, typically a suggested question clicked outside the chat.
+    external: 'suggestion',
+};
 const NOOP_TRACKING = {
+    trackAgentButtonClick: () => { },
     trackSubmit: () => { },
     trackResultLoadStarted: () => { },
     trackResultLoadFinished: () => { },
@@ -15,37 +24,42 @@ const NOOP_TRACKING = {
  * Mirrors the tracking-hook pattern used by constructorio-ui-pia.
  */
 function useAsaTracking({ tracker, section, threadId, }) {
-    const assistant = tracker;
     const base = (0, react_1.useMemo)(() => (Object.assign(Object.assign({}, (section && { section })), (threadId && { threadId }))), [section, threadId]);
-    const trackSubmit = (0, react_1.useCallback)((intent) => {
-        assistant === null || assistant === void 0 ? void 0 : assistant.trackAssistantSubmit(Object.assign({ intent }, base));
-    }, [assistant, base]);
+    const trackAgentButtonClick = (0, react_1.useCallback)(({ mode, agentDomain, positionOnPage, pageType, instanceId }) => {
+        var _a;
+        (_a = tracker === null || tracker === void 0 ? void 0 : tracker.trackAgentButtonClick) === null || _a === void 0 ? void 0 : _a.call(tracker, Object.assign(Object.assign(Object.assign(Object.assign({ mode,
+            agentDomain }, (positionOnPage && { positionOnPage })), (pageType && { pageType })), (instanceId && { instanceId })), (section && { section })));
+    }, [tracker, section]);
+    const trackSubmit = (0, react_1.useCallback)((intent, source) => {
+        tracker === null || tracker === void 0 ? void 0 : tracker.trackAssistantSubmit(Object.assign(Object.assign({ intent }, (source && { source: BEACON_SUBMIT_SOURCES[source] })), base));
+    }, [tracker, base]);
     const trackResultLoadStarted = (0, react_1.useCallback)(({ intent, intentResultId }) => {
-        assistant === null || assistant === void 0 ? void 0 : assistant.trackAssistantResultLoadStarted(Object.assign(Object.assign({ intent }, (intentResultId && { intentResultId })), base));
-    }, [assistant, base]);
+        tracker === null || tracker === void 0 ? void 0 : tracker.trackAssistantResultLoadStarted(Object.assign(Object.assign({ intent }, (intentResultId && { intentResultId })), base));
+    }, [tracker, base]);
     const trackResultLoadFinished = (0, react_1.useCallback)(({ intent, searchResultCount, intentResultId, threadId: turnThreadId, }) => {
-        assistant === null || assistant === void 0 ? void 0 : assistant.trackAssistantResultLoadFinished(Object.assign(Object.assign(Object.assign({ intent,
+        tracker === null || tracker === void 0 ? void 0 : tracker.trackAssistantResultLoadFinished(Object.assign(Object.assign(Object.assign({ intent,
             searchResultCount }, (intentResultId && { intentResultId })), base), (turnThreadId && { threadId: turnThreadId })));
-    }, [assistant, base]);
+    }, [tracker, base]);
     const trackResultClick = (0, react_1.useCallback)(({ intent, searchResultId, intentResultId, itemId, itemName, variationId, }) => {
-        assistant === null || assistant === void 0 ? void 0 : assistant.trackAssistantResultClick(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ intent,
+        tracker === null || tracker === void 0 ? void 0 : tracker.trackAssistantResultClick(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ intent,
             searchResultId }, (intentResultId && { intentResultId })), (itemId && { itemId })), (itemName && { itemName })), (variationId && { variationId })), base));
-    }, [assistant, base]);
+    }, [tracker, base]);
     const trackResultView = (0, react_1.useCallback)(({ intent, searchResultId, numResultsViewed, intentResultId, items }) => {
-        assistant === null || assistant === void 0 ? void 0 : assistant.trackAssistantResultView(Object.assign(Object.assign(Object.assign({ intent,
+        tracker === null || tracker === void 0 ? void 0 : tracker.trackAssistantResultView(Object.assign(Object.assign(Object.assign({ intent,
             searchResultId,
             numResultsViewed }, (intentResultId && { intentResultId })), (items && items.length > 0 && { items })), base));
-    }, [assistant, base]);
+    }, [tracker, base]);
     const trackSearchSubmit = (0, react_1.useCallback)(({ intent, searchTerm, userInput, searchResultId, intentResultId, groupId, }) => {
-        assistant === null || assistant === void 0 ? void 0 : assistant.trackAssistantSearchSubmit(Object.assign(Object.assign(Object.assign({ intent,
+        tracker === null || tracker === void 0 ? void 0 : tracker.trackAssistantSearchSubmit(Object.assign(Object.assign(Object.assign({ intent,
             searchTerm,
             userInput,
             searchResultId }, (intentResultId && { intentResultId })), (groupId && { groupId })), base));
-    }, [assistant, base]);
+    }, [tracker, base]);
     return (0, react_1.useMemo)(() => {
-        if (!assistant)
+        if (!tracker)
             return NOOP_TRACKING;
         return {
+            trackAgentButtonClick,
             trackSubmit,
             trackResultLoadStarted,
             trackResultLoadFinished,
@@ -54,7 +68,8 @@ function useAsaTracking({ tracker, section, threadId, }) {
             trackSearchSubmit,
         };
     }, [
-        assistant,
+        tracker,
+        trackAgentButtonClick,
         trackSubmit,
         trackResultLoadStarted,
         trackResultLoadFinished,

package/lib/cjs/version.js

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = '1.8.0';
+exports.default = '1.9.0';

package/lib/mjs/components/Button/Button.js

@@ -1,8 +1,31 @@
-import React from 'react';
+import React, { useCallback } from 'react';
 import { Button as CioButton } from '@constructor-io/constructorio-ui-components';
 import { ChatBubbleDarkIcon, ChatBubbleLightIcon } from '../icons';
-export default function Button({ theme = 'dark', size = 'sm', onClick, label = 'Shopping assistant', }) {
-    return (React.createElement(CioButton, { className: `cio-asa-button cio-asa-button--${theme} cio-asa-button--${size}`, size: size === 'lg' ? 'default' : 'sm', onClick: onClick },
+import { useCioAsaContext } from '../../hooks/useCioAsaContext';
+import useAsaTracking from '../../hooks/useAsaTracking';
+const AGENT_BUTTON_CLICK_MODE = 'chat';
+export default function Button({ theme = 'dark', size = 'sm', onClick, label = 'Shopping assistant', positionOnPage, pageType, instanceId, }) {
+    const context = useCioAsaContext();
+    const agentDomain = context?.staticRequestConfigs?.domain;
+    const tracking = useAsaTracking({
+        tracker: context?.cioClient?.tracker ?? undefined,
+        section: context?.section,
+    });
+    const handleClick = useCallback(() => {
+        if (agentDomain) {
+            const payload = {
+                mode: AGENT_BUTTON_CLICK_MODE,
+                agentDomain,
+                ...(positionOnPage && { positionOnPage }),
+                ...(pageType && { pageType }),
+                ...(instanceId && { instanceId }),
+            };
+            tracking.trackAgentButtonClick(payload);
+            context?.callbacks?.onAgentButtonClick?.(payload);
+        }
+        onClick?.();
+    }, [agentDomain, positionOnPage, pageType, instanceId, tracking, context, onClick]);
+    return (React.createElement(CioButton, { className: `cio-asa-button cio-asa-button--${theme} cio-asa-button--${size}`, size: size === 'lg' ? 'default' : 'sm', onClick: handleClick },
         theme === 'dark' ? React.createElement(ChatBubbleDarkIcon, null) : React.createElement(ChatBubbleLightIcon, null),
         React.createElement("span", { className: 'cio-asa-button__label' }, label)));
 }

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

@@ -25,7 +25,7 @@ function getAnnouncement(messages, translations) {
     }
     return '';
 }
-const Chat = forwardRef(({ onClose, className, initialSuggestions, termsText, onProductClick, onViewMore, onAddToCart, aspectRatio, currency, normalizeItem, componentOverrides, translations, initialThreadId, onThreadsChange, showStopButton = false, }, ref) => {
+const Chat = forwardRef(({ onClose, className, initialSuggestions, termsText, onProductClick, onViewMore, onAddToCart, aspectRatio, currency, normalizeItem, componentOverrides, translations, initialThreadId, initialPrompt, onThreadsChange, showStopButton = false, }, ref) => {
     const { messages, sendMessage, isStreaming, canAbort, abort, clearHistory, isHydrating, threads, activeThreadId, newThread, switchThread, } = useAsaResults({
         initialThreadId,
         normalizeItem: (item) => (normalizeItem ?? normalizeItemToProduct)(item, {
@@ -44,12 +44,25 @@ const Chat = forwardRef(({ onClose, className, initialSuggestions, termsText, on
     const showChatFrame = showChat || (isHydrating && lastViewRef.current === 'chat');
     const isModal = typeof onClose === 'function';
     const announcement = getAnnouncement(messages, translations);
-    useImperativeHandle(ref, () => ({ abort, clearHistory, newThread, switchThread }), [
+    useImperativeHandle(ref, () => ({
         abort,
         clearHistory,
         newThread,
         switchThread,
-    ]);
+        sendMessage: (text, options) => sendMessage(text, 'external', options),
+    }), [abort, clearHistory, newThread, switchThread, sendMessage]);
+    // Sent from a timer so StrictMode's mount, unmount, mount cannot cancel the stream it starts.
+    const initialPromptRef = useRef(initialPrompt);
+    useEffect(() => {
+        const prompt = initialPromptRef.current;
+        if (isHydrating || !prompt)
+            return undefined;
+        const timer = setTimeout(() => {
+            initialPromptRef.current = undefined;
+            sendMessage(prompt, 'external');
+        });
+        return () => clearTimeout(timer);
+    }, [isHydrating, sendMessage]);
     const hasPersistence = Boolean(useCioAsaContext()?.persistence);
     const onThreadsChangeRef = useLatest(onThreadsChange);
     useEffect(() => {

package/lib/mjs/hooks/useAsaResults.js

@@ -5,6 +5,7 @@ import useChatPersistence from './persistence/useChatPersistence';
 import { startTurn } from './agentStream';
 import { createChatSession, nextMessageId } from '../utils/chatSession';
 import { normalizeItemToProduct } from '../utils/productNormalizer';
+import { isLocalThreadId } from '../utils/chatThreads';
 import useLatest from './useLatest';
 export default function useAsaResults(options) {
     const contextValue = useCioAsaContext();
@@ -53,12 +54,12 @@ export default function useAsaResults(options) {
     });
     const { beginTurn, screenOwner } = store;
     useEffect(() => cancelStream, [cancelStream]);
-    const sendMessage = useCallback((text, source = 'input') => {
+    const sendToCurrentThread = useCallback((text, source) => {
         const intent = text.trim();
         if (!intent || session.isStreaming || session.foreignInFlight)
             return;
         beginTurn();
-        trackingRef.current.trackSubmit(intent);
+        trackingRef.current.trackSubmit(intent, source);
         callbacksRef.current?.onAssistantSubmit?.({ intent, source });
         const userMessage = {
             id: nextMessageId(session),
@@ -108,6 +109,32 @@ export default function useAsaResults(options) {
         callbacksRef,
         staticRequestConfigsRef,
     ]);
+    const { newThread, switchThread } = store;
+    /**
+     * Sends `text`. With `threadId`, first moves to that conversation, loading it from storage
+     * when persistence has it and otherwise continuing it on the server with an empty screen.
+     */
+    const sendMessage = useCallback((text, source = 'input', { threadId } = {}) => {
+        if (!threadId ||
+            threadId === session.serverThreadId ||
+            threadId === session.storageThreadId) {
+            sendToCurrentThread(text, source);
+            return;
+        }
+        (async () => {
+            if (persistence)
+                await switchThread(threadId);
+            else
+                newThread();
+            // A turn that started meanwhile (or one still streaming in the background) owns the screen.
+            if (session.isStreaming || session.foreignInFlight)
+                return;
+            if (!session.serverThreadId && !isLocalThreadId(threadId)) {
+                session.serverThreadId = threadId;
+            }
+            sendToCurrentThread(text, source);
+        })();
+    }, [session, persistence, newThread, switchThread, sendToCurrentThread]);
     /**
      * Cancels the in-flight request while keeping the conversation: the partial reply is
      * settled as `done` (so the typing indicator stops and streamed text survives) and the
@@ -152,7 +179,7 @@ export default function useAsaResults(options) {
         isHydrating: store.isHydrating,
         threads: store.threads,
         activeThreadId: store.activeThreadId,
-        newThread: store.newThread,
-        switchThread: store.switchThread,
+        newThread,
+        switchThread,
     };
 }

package/lib/mjs/hooks/useAsaTracking.js

@@ -1,5 +1,14 @@
 import { useCallback, useMemo } from 'react';
+/** Beacon `source` values, aligned with the ones the behavioral-actions API documents. */
+const BEACON_SUBMIT_SOURCES = {
+    input: 'input',
+    suggestion: 'suggestion',
+    refinement: 'follow_up',
+    // A prompt the host page sent, typically a suggested question clicked outside the chat.
+    external: 'suggestion',
+};
 const NOOP_TRACKING = {
+    trackAgentButtonClick: () => { },
     trackSubmit: () => { },
     trackResultLoadStarted: () => { },
     trackResultLoadFinished: () => { },
@@ -13,32 +22,45 @@ const NOOP_TRACKING = {
  * Mirrors the tracking-hook pattern used by constructorio-ui-pia.
  */
 export default function useAsaTracking({ tracker, section, threadId, }) {
-    const assistant = tracker;
     const base = useMemo(() => ({
         ...(section && { section }),
         ...(threadId && { threadId }),
     }), [section, threadId]);
-    const trackSubmit = useCallback((intent) => {
-        assistant?.trackAssistantSubmit({ intent, ...base });
-    }, [assistant, base]);
+    const trackAgentButtonClick = useCallback(({ mode, agentDomain, positionOnPage, pageType, instanceId }) => {
+        tracker?.trackAgentButtonClick?.({
+            mode,
+            agentDomain,
+            ...(positionOnPage && { positionOnPage }),
+            ...(pageType && { pageType }),
+            ...(instanceId && { instanceId }),
+            ...(section && { section }),
+        });
+    }, [tracker, section]);
+    const trackSubmit = useCallback((intent, source) => {
+        tracker?.trackAssistantSubmit({
+            intent,
+            ...(source && { source: BEACON_SUBMIT_SOURCES[source] }),
+            ...base,
+        });
+    }, [tracker, base]);
     const trackResultLoadStarted = useCallback(({ intent, intentResultId }) => {
-        assistant?.trackAssistantResultLoadStarted({
+        tracker?.trackAssistantResultLoadStarted({
             intent,
             ...(intentResultId && { intentResultId }),
             ...base,
         });
-    }, [assistant, base]);
+    }, [tracker, base]);
     const trackResultLoadFinished = useCallback(({ intent, searchResultCount, intentResultId, threadId: turnThreadId, }) => {
-        assistant?.trackAssistantResultLoadFinished({
+        tracker?.trackAssistantResultLoadFinished({
             intent,
             searchResultCount,
             ...(intentResultId && { intentResultId }),
             ...base,
             ...(turnThreadId && { threadId: turnThreadId }),
         });
-    }, [assistant, base]);
+    }, [tracker, base]);
     const trackResultClick = useCallback(({ intent, searchResultId, intentResultId, itemId, itemName, variationId, }) => {
-        assistant?.trackAssistantResultClick({
+        tracker?.trackAssistantResultClick({
             intent,
             searchResultId,
             ...(intentResultId && { intentResultId }),
@@ -47,9 +69,9 @@ export default function useAsaTracking({ tracker, section, threadId, }) {
             ...(variationId && { variationId }),
             ...base,
         });
-    }, [assistant, base]);
+    }, [tracker, base]);
     const trackResultView = useCallback(({ intent, searchResultId, numResultsViewed, intentResultId, items }) => {
-        assistant?.trackAssistantResultView({
+        tracker?.trackAssistantResultView({
             intent,
             searchResultId,
             numResultsViewed,
@@ -57,9 +79,9 @@ export default function useAsaTracking({ tracker, section, threadId, }) {
             ...(items && items.length > 0 && { items }),
             ...base,
         });
-    }, [assistant, base]);
+    }, [tracker, base]);
     const trackSearchSubmit = useCallback(({ intent, searchTerm, userInput, searchResultId, intentResultId, groupId, }) => {
-        assistant?.trackAssistantSearchSubmit({
+        tracker?.trackAssistantSearchSubmit({
             intent,
             searchTerm,
             userInput,
@@ -68,11 +90,12 @@ export default function useAsaTracking({ tracker, section, threadId, }) {
             ...(groupId && { groupId }),
             ...base,
         });
-    }, [assistant, base]);
+    }, [tracker, base]);
     return useMemo(() => {
-        if (!assistant)
+        if (!tracker)
             return NOOP_TRACKING;
         return {
+            trackAgentButtonClick,
             trackSubmit,
             trackResultLoadStarted,
             trackResultLoadFinished,
@@ -81,7 +104,8 @@ export default function useAsaTracking({ tracker, section, threadId, }) {
             trackSearchSubmit,
         };
     }, [
-        assistant,
+        tracker,
+        trackAgentButtonClick,
         trackSubmit,
         trackResultLoadStarted,
         trackResultLoadFinished,

package/lib/mjs/version.js

@@ -1 +1 @@
-export default '1.8.0';
+export default '1.9.0';

package/lib/types/components/Button/Button.d.ts

@@ -1,5 +1,6 @@
 import React from 'react';
-export interface ButtonProps {
+import { AgentButtonClickPlacement } from '../../types';
+export interface ButtonProps extends AgentButtonClickPlacement {
     /** Color scheme: dark (for light backgrounds) or light (for dark backgrounds) */
     theme?: 'dark' | 'light';
     /** Button size: sm (small) or lg (large) */
@@ -9,4 +10,4 @@ export interface ButtonProps {
     /** Button label text */
     label?: string;
 }
-export default function Button({ theme, size, onClick, label, }: ButtonProps): React.JSX.Element;
+export default function Button({ theme, size, onClick, label, positionOnPage, pageType, instanceId, }: ButtonProps): React.JSX.Element;

package/lib/types/components/Chat/Chat.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { ChatComponentOverrides, ResultGroupMeta, ThreadSummary, Translations } from '../../types';
+import { ChatComponentOverrides, ResultGroupMeta, SendMessageOptions, ThreadSummary, Translations } from '../../types';
 import { Product, NormalizeOptions } from '../../utils/productNormalizer';
 import { AspectRatio } from '../ResultsBlock/ResultsBlock';
 export interface ChatHandle {
@@ -15,6 +15,12 @@ export interface ChatHandle {
     newThread: () => void;
     /** Load a stored conversation. No-op when persistence is off. */
     switchThread: (threadId: string) => Promise<void>;
+    /**
+     * Send a prompt from outside the chat, e.g. one the shopper clicked elsewhere on the page.
+     * Pass `threadId` to send it into that conversation instead of the one on screen. Skipped
+     * while an answer is streaming. Opening the chat stays with you, as with `onClose`.
+     */
+    sendMessage: (text: string, options?: SendMessageOptions) => void;
 }
 export interface ChatProps {
     /** Called when the close button (✕) is clicked. The consumer controls visibility. */
@@ -46,6 +52,12 @@ export interface ChatProps {
     translations?: Translations;
     /** Seed the thread id (e.g. loaded from browser storage) to resume a prior conversation. Read once on mount. */
     initialThreadId?: string;
+    /**
+     * A prompt sent once on mount, after any stored conversation loads, e.g. one the shopper
+     * clicked elsewhere before you opened the chat. Goes into `initialThreadId` when set.
+     * Read once on mount; use `sendMessage` on the ref once the chat is already open.
+     */
+    initialPrompt?: string;
     /** Fires with the stored conversations and the active one whenever either changes. Requires persistence. */
     onThreadsChange?: (threads: ThreadSummary[], activeThreadId: string | null) => void;
     /**

package/lib/types/hooks/useAsaTracking.d.ts

@@ -1,5 +1,5 @@
 import { Tracker } from '@constructor-io/constructorio-client-javascript/lib/types/constructorio';
-import { AssistantTrackedItem } from '../types';
+import { AgentButtonClickPayload, AssistantSubmitSource, AssistantTrackedItem } from '../types';
 export interface UseAsaTrackingProps {
     tracker?: Tracker;
     section?: string;
@@ -40,8 +40,10 @@ export interface TrackSearchSubmitArgs {
     intentResultId?: string;
     groupId?: string;
 }
+export type TrackAgentButtonClickArgs = AgentButtonClickPayload;
 export interface UseAsaTrackingReturn {
-    trackSubmit: (intent: string) => void;
+    trackAgentButtonClick: (args: TrackAgentButtonClickArgs) => void;
+    trackSubmit: (intent: string, source?: AssistantSubmitSource) => void;
     trackResultLoadStarted: (args: TrackResultLoadStartedArgs) => void;
     trackResultLoadFinished: (args: TrackResultLoadFinishedArgs) => void;
     trackResultClick: (args: TrackResultClickArgs) => void;

package/lib/types/index.d.ts

@@ -10,9 +10,9 @@ export type { ButtonProps } from './components/Button/Button';
 export { default as useAsaResults } from './hooks/useAsaResults';
 export { default as useAsaTracking } from './hooks/useAsaTracking';
 export { default as useCioAsaContext } from './hooks/useCioAsaContext';
-export type { UseAsaTrackingProps, UseAsaTrackingReturn } from './hooks/useAsaTracking';
+export type { UseAsaTrackingProps, UseAsaTrackingReturn, TrackAgentButtonClickArgs, } from './hooks/useAsaTracking';
 export { normalizeItemToProduct } from './utils/productNormalizer';
 export { clearPersistedConversations } from './utils/localStoragePersistence';
 export type { Product, NormalizeOptions } from './utils/productNormalizer';
 export { ConstructorIOClient } from './types';
-export type { Nullable, CioAsaProviderProps, PersistConversationOptions, AsaContextValue, CioClientOptions, RequestConfigs, Formatters, UrlHelpers, QueryParamEncodingOptions, DefaultQueryStringMap, Translations, ChatMessage, ChatMessageStatus, FollowUpRefinement, ResultGroup, ResultGroupMeta, SearchResultEventRequest, UseAsaResultsOptions, UseChatReturn, ClearPersistedConversationsOptions, ThreadSummary, AsaCallbacks, AssistantSubmitSource, AssistantTrackedItem, ChatComponentOverrides, WelcomeScreenOverrides, ChatInputOverrides, AiMessageOverrides, ResultsBlockOverrides, ComponentOverrideProps, IncludeComponentOverrides, ChatHeaderRenderProps, ChatInputRenderProps, WelcomeScreenTitleRenderProps, WelcomeScreenInputRenderProps, SuggestedQuestionsRenderProps, UserMessageRenderProps, AiMessageLoaderRenderProps, AiMessageTextRenderProps, FollowUpRefinementRenderProps, ResultsGroupTitleRenderProps, ResultsViewMoreRenderProps, } from './types';
+export type { Nullable, CioAsaProviderProps, PersistConversationOptions, AsaContextValue, CioClientOptions, RequestConfigs, Formatters, UrlHelpers, QueryParamEncodingOptions, DefaultQueryStringMap, Translations, ChatMessage, ChatMessageStatus, FollowUpRefinement, ResultGroup, ResultGroupMeta, SearchResultEventRequest, UseAsaResultsOptions, UseChatReturn, SendMessageOptions, ClearPersistedConversationsOptions, ThreadSummary, AsaCallbacks, AssistantSubmitSource, AssistantTrackedItem, AgentButtonClickMode, AgentButtonClickPayload, AgentButtonClickPageType, AgentButtonClickPlacement, ChatComponentOverrides, WelcomeScreenOverrides, ChatInputOverrides, AiMessageOverrides, ResultsBlockOverrides, ComponentOverrideProps, IncludeComponentOverrides, ChatHeaderRenderProps, ChatInputRenderProps, WelcomeScreenTitleRenderProps, WelcomeScreenInputRenderProps, SuggestedQuestionsRenderProps, UserMessageRenderProps, AiMessageLoaderRenderProps, AiMessageTextRenderProps, FollowUpRefinementRenderProps, ResultsGroupTitleRenderProps, ResultsViewMoreRenderProps, } from './types';

package/lib/types/types.d.ts

@@ -179,9 +179,18 @@ export interface ResultGroup {
     searchResultId?: string;
     intentResultId?: string;
 }
+export interface SendMessageOptions {
+    /**
+     * Conversation to send into, e.g. one started elsewhere on the page. The chat moves to it
+     * first: loaded from storage when persistence has it, otherwise continued on the server
+     * with an empty screen. Omit to send into the conversation on screen.
+     */
+    threadId?: string;
+}
 export interface UseChatReturn {
     messages: ChatMessage[];
-    sendMessage: (text: string, source?: AssistantSubmitSource) => void;
+    /** Skipped while another answer streams. */
+    sendMessage: (text: string, source?: AssistantSubmitSource, options?: SendMessageOptions) => void;
     /** True while an answer is streaming, here or, with persistence on, in another tab on the same thread. */
     isStreaming: boolean;
     /** True while this tab's own answer is streaming, the one `abort` can stop. */
@@ -289,20 +298,44 @@ export interface LocalStoragePersistenceOptions {
     /** Storage to use instead of the browser's; takes precedence over `storageArea`. */
     storage?: Storage;
 }
-/** How an intent was submitted: typed input, a welcome-screen suggestion chip, or a refinement chip. */
-export type AssistantSubmitSource = 'input' | 'suggestion' | 'refinement';
+/**
+ * How an intent was submitted: typed input, a welcome-screen suggestion chip, a refinement chip,
+ * or the host page (`ChatHandle.sendMessage` or the `initialPrompt` prop).
+ */
+export type AssistantSubmitSource = 'input' | 'suggestion' | 'refinement' | 'external';
 /** An item within a viewed/clicked search_result pod. */
 export interface AssistantTrackedItem {
     itemId?: string;
     itemName?: string;
     variationId?: string;
 }
+/** Agent mode a CTA opens or starts. */
+export type AgentButtonClickMode = 'chat' | 'search' | 'qna' | 'recommendations' | 'query_refinement';
+/** Page surface an agent CTA was clicked on. */
+export type AgentButtonClickPageType = 'home' | 'plp' | 'pdp' | 'search' | 'collection' | 'email_campaign' | 'cart';
+/** Where an agent CTA sits on the page. All fields are optional. */
+export interface AgentButtonClickPlacement {
+    /** Stable label describing where the CTA is placed, e.g. `'header'` or `'search_bar'`. */
+    positionOnPage?: string;
+    /** Page surface where the CTA was clicked. */
+    pageType?: AgentButtonClickPageType;
+    /** 1-based index distinguishing CTA instances with the same mode and position during one page view. */
+    instanceId?: number;
+}
+/** Fields sent with `ai_agent_button_click` and passed to `onAgentButtonClick`. */
+export interface AgentButtonClickPayload extends AgentButtonClickPlacement {
+    mode: AgentButtonClickMode;
+    /** Agent experience the CTA opens, sent as `agent_domain`. */
+    agentDomain: string;
+}
 /**
  * Optional consumer callbacks fired alongside the built-in behavioral tracking.
  * Each fires immediately after its corresponding `trackAssistant*` beacon is sent,
  * so consumers can mirror ASA analytics into their own systems. All are optional.
  */
 export interface AsaCallbacks {
+    /** A CTA that opens the assistant (the built-in `Button`) was clicked. */
+    onAgentButtonClick?: (payload: AgentButtonClickPayload) => void;
     /** User submitted an intent (typed) or clicked a suggestion / refinement chip. */
     onAssistantSubmit?: (payload: {
         intent: string;