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

package/lib/types/types.d.ts

@@ -179,12 +179,24 @@ 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. */
+    /**
+     * True while `abort` can stop the answer: this tab's own, or, when the store can reach it, one
+     * streaming in another tab.
+     */
     canAbort: boolean;
     /**
      * Cancel the in-flight request, keeping the conversation. The partial reply is settled
@@ -261,6 +273,18 @@ export interface ChatPersistence {
      * Returns an unsubscribe function.
      */
     subscribe?(listener: () => void): () => void;
+    /** Optional. Ask the tab streaming `messageId` into `threadId` to stop it. */
+    requestAbort?(threadId: string, messageId: string): void;
+    /**
+     * Optional. Notify when another tab asks to stop an answer, see `requestAbort`. Returns an
+     * unsubscribe function. Without both, an answer streaming in another tab cannot be stopped.
+     */
+    subscribeAbort?(listener: (request: AbortRequest) => void): () => void;
+}
+/** Another tab asks to stop the answer `messageId` streaming into `threadId`. */
+export interface AbortRequest {
+    threadId: string;
+    messageId: string;
 }
 /** Which stored history `clearPersistedConversations` deletes; mirror what the provider was given. */
 export interface ClearPersistedConversationsOptions {
@@ -289,20 +313,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;
@@ -383,12 +431,13 @@ export interface ChatInputRenderProps {
     onSubmit: () => void;
     placeholder: string;
     isDisabled: boolean;
+    /** Whether a reply is currently streaming, here or in another tab; for status and disabled state. */
+    isStreaming: boolean;
     /**
-     * Whether a reply is currently streaming. Pair it with `onAbort` to offer a cancel
-     * control while it is true — the built-in stop button is off by default, so an override
-     * is often the only way a user can cancel.
+     * Whether `onAbort` can stop the reply streaming now; show a cancel control only then. The
+     * built-in stop button is off by default, so an override is often the only way a user can cancel.
      */
-    isStreaming: boolean;
+    canAbort: boolean;
     /** Cancel the in-flight reply. Keeps the conversation and the thread. */
     onAbort: () => void;
 }

package/lib/types/utils/chatThreads.d.ts

@@ -8,6 +8,8 @@ export declare const DEFAULT_PERSISTENCE_KEY = "cio-asa:chat";
 export declare const DEFAULT_PERSISTENCE_TTL_MS: number;
 /** How long a stored answer written by another tab is still shown as "typing" before it is settled. */
 export declare const IN_FLIGHT_GRACE_MS: number;
+/** How long to wait for the tab streaming an answer to store it stopped, before settling it here. */
+export declare const FOREIGN_ABORT_TIMEOUT_MS: number;
 /** Random token for the ids that must not collide between tabs: threads, tabs and messages. */
 export declare function randomId(): string;
 /** Client-side thread id for a conversation the server has not named yet. */
@@ -28,6 +30,8 @@ export declare function nextMessageCounter(messages: ChatMessage[]): number;
 export declare function isInFlight(messages: ChatMessage[]): boolean;
 /** Settles answers stored mid-stream: `done` when they have content, an interrupted `error` otherwise. */
 export declare function normalizeHydratedMessages(messages: ChatMessage[]): ChatMessage[];
+/** `messages` with the cancelled reply settled: `done` when it has content, dropped otherwise. */
+export declare function settleCancelledReply(messages: ChatMessage[], assistantId: string): ChatMessage[];
 /** Makes the product card for a raw search-result item. */
 export type ItemNormalizer = (item: Record<string, unknown>) => Product;
 /** Messages as stored: raw items replaced by the cards `normalize` makes; a restored group keeps its cards. */

package/lib/types/utils/markdown.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Turns the agent's markdown into sanitized HTML: paragraphs, bold, links, lists and tables.
+ * Links to other sites become plain text. Browser only: without a DOM to sanitize with (server
+ * rendering) it returns `''`, so render the plain text instead.
+ */
+export declare function renderMarkdown(markdown: string): string;
+/** The agent's markdown as plain text, one space between blocks and table cells, for screen readers. */
+export declare function markdownToText(markdown: string): string;

package/lib/types/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.8.0";
+declare const _default: "1.10.0";
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-asa",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Constructor.io AI Shopping Agent UI library for web applications",
   "author": "constructor.io",
   "license": "MIT",
@@ -82,7 +82,7 @@
     "@babel/preset-env": "^7.28.3",
     "@babel/preset-react": "^7.27.1",
     "@babel/preset-typescript": "^7.27.1",
-    "@constructor-io/constructorio-client-javascript": "2.93.1",
+    "@constructor-io/constructorio-client-javascript": "2.94.0",
     "@constructor-io/constructorio-ui-components": "^1.6.0",
     "@cspell/eslint-plugin": "^6.18.1",
     "@storybook/addon-a11y": "^8.6.14",
@@ -148,5 +148,9 @@
   "volta": {
     "node": "22.18.0",
     "npm": "10.9.3"
+  },
+  "dependencies": {
+    "dompurify": "3.4.17",
+    "marked": "15.0.12"
   }
 }