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

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

@@ -0,0 +1,48 @@
+import type { Dispatch, SetStateAction } from 'react';
+import { ChatMessage } from '../types';
+type SetMessages = Dispatch<SetStateAction<ChatMessage[]>>;
+export interface AgentStreamCallbacks {
+    /** The `start` event arrived, possibly carrying the server thread id. */
+    onStart: (threadId?: string) => void;
+    /** Fires once, on the first event with content, for load-started tracking. */
+    onLoadStart: (intentResultId?: string) => void;
+    /** The stream ended normally (not on a server error, a failure, or a cancel). */
+    onFinish: (result: {
+        searchResultCount: number;
+        intentResultId?: string;
+    }) => void;
+}
+export interface AgentStreamHandle {
+    /** The assistant message this stream writes into, so a cancel can settle the right one. */
+    assistantId: string;
+    /** Stop reading; the pending `done` settles without touching the assistant message. */
+    cancel: () => void;
+    done: Promise<void>;
+}
+/** Where a running answer goes: the chat showing its conversation, or the background. */
+export interface TurnOwner {
+    setMessages: SetMessages;
+    onStart: (threadId?: string) => void;
+    /** The stream ended, failed or was cancelled. */
+    onDone: () => void;
+}
+/** An answer being read; its owner can change mid-stream, so leaving the chat does not stop it. */
+export interface LiveTurn extends AgentStreamHandle {
+    owner: TurnOwner;
+    /** The assistant message as streamed so far, whoever shows it. */
+    assistant: ChatMessage;
+    /** From the `start` event. */
+    serverThreadId?: string;
+}
+/** Drains an agent stream into the assistant message identified by `assistantId`. */
+export declare function readAgentStream(stream: ReadableStream, assistantId: string, setMessages: SetMessages, callbacks: AgentStreamCallbacks): AgentStreamHandle;
+export interface TurnCallbacks {
+    onLoadStart: AgentStreamCallbacks['onLoadStart'];
+    /** As `AgentStreamCallbacks.onFinish`, with the server thread the answer belongs to. */
+    onFinish: (result: Parameters<AgentStreamCallbacks['onFinish']>[0] & {
+        threadId?: string;
+    }) => void;
+}
+/** Streams into `assistant`, reporting to the owner `createOwner` returns for the new turn. */
+export declare function startTurn(stream: ReadableStream, assistant: ChatMessage, createOwner: (turn: LiveTurn) => TurnOwner, callbacks: TurnCallbacks): LiveTurn;
+export {};

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

@@ -1,6 +1,7 @@
 import { Dispatch, SetStateAction } from 'react';
 import { ResultGroupMeta, ChatMessage } from '../types';
 export type MessageUpdater = Dispatch<SetStateAction<ChatMessage[]>>;
+export declare function updateMessageById(setMessages: MessageUpdater, id: string, patch: (msg: ChatMessage) => ChatMessage): void;
 export declare function handleSearchResult(data: any, pendingGroup: ResultGroupMeta | null, assistantId: string, setMessages: MessageUpdater): ResultGroupMeta | null;
 export declare function handleMessage(data: any, assistantId: string, setMessages: MessageUpdater): void;
 export declare function handleFollowUpRefinement(data: any, assistantId: string, setMessages: MessageUpdater): void;

package/lib/types/hooks/persistence/backgroundTurns.d.ts

@@ -0,0 +1,43 @@
+import type { ChatMessage, ChatPersistence } from '../../types';
+import type { LiveTurn, TurnOwner } from '../agentStream';
+import { ChatSession } from '../../utils/chatSession';
+/** An answer that went on after its conversation left the screen, until it is stored or shown again. */
+export declare class BackgroundTurn {
+    readonly turn: LiveTurn;
+    store: ChatPersistence;
+    /** The conversation's own session, forked from the chat that sent the message. */
+    readonly session: ChatSession;
+    messages: ChatMessage[];
+    streaming: boolean;
+    /** Whether the latest snapshot is known to be stored. */
+    saved: boolean;
+    /** Every id the conversation was stored under, so a list read before a re-key still finds it. */
+    readonly ids: Set<string>;
+    /** Its writes, in order; a chat that takes the turn back writes after them. */
+    writes: Promise<void>;
+    constructor(turn: LiveTurn, params: {
+        store: ChatPersistence;
+        session: ChatSession;
+        messages: ChatMessage[];
+        after: Promise<void>;
+    });
+    save(): Promise<void>;
+    /** Later writes go into `store`. */
+    moveTo(store: ChatPersistence): void;
+    /** Stores the conversation settled, without awaiting: the page is going away. */
+    flush(): void;
+}
+/**
+ * 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 declare function continueInBackground(turn: LiveTurn, params: ConstructorParameters<typeof BackgroundTurn>[1]): void;
+/**
+ * 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 declare function resumeBackgroundTurn(store: ChatPersistence, threadId: string, createOwner: (turn: LiveTurn) => TurnOwner): BackgroundTurn | null;
+/** Points the background turns of `from` at `to`; resolves once their writes into `from` settled. */
+export declare function moveBackgroundTurns(from: ChatPersistence, to: ChatPersistence): Promise<void>;
+/** Called whenever a background turn is stored or finishes. */
+export declare function subscribeBackgroundTurns(listener: () => void): () => void;

package/lib/types/hooks/persistence/useChatPersistence.d.ts

@@ -0,0 +1,34 @@
+import { Dispatch, MutableRefObject, SetStateAction } from 'react';
+import { ChatMessage, ChatPersistence, PersistenceScope } from '../../types';
+import type { LiveTurn, TurnOwner } from '../agentStream';
+import { ChatSession } from '../../utils/chatSession';
+interface Params {
+    store: ChatPersistence | undefined;
+    /** Whose store it is; a switch from `'guest'` to `'user'` carries the conversation over. */
+    scope?: PersistenceScope;
+    /** Api key and domain of `store`; a login into another index does not carry anything over. */
+    index?: string;
+    session: ChatSession;
+    initialThreadId?: string;
+    messages: ChatMessage[];
+    setMessages: Dispatch<SetStateAction<ChatMessage[]>>;
+    isStreaming: boolean;
+    setIsStreaming: (value: boolean) => void;
+    /** This tab's answer streaming into the conversation on screen, if any. */
+    turnRef: MutableRefObject<LiveTurn | null>;
+    /** Stop the answer currently streaming in this tab, if any. */
+    cancelStream: () => void;
+}
+/** Restores, saves and syncs the conversation with `store`; inert when `store` is undefined. */
+export default function useChatPersistence(params: Params): {
+    isHydrating: boolean;
+    threads: import("../../types").ThreadSummary[];
+    activeThreadId: string | null;
+    foreignInFlight: boolean;
+    beginTurn: () => void;
+    screenOwner: (turn: LiveTurn) => TurnOwner;
+    clearHistory: () => void;
+    newThread: () => void;
+    switchThread: (threadId: string) => Promise<void>;
+};
+export {};

package/lib/types/hooks/persistence/useForeignStream.d.ts

@@ -0,0 +1,9 @@
+import { ChatSession } from '../../utils/chatSession';
+/** An answer streaming in another tab: blocks sending and settles after the grace period. */
+export default function useForeignStream(session: ChatSession): {
+    foreignInFlight: boolean;
+    setForeignInFlight: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    watch: (remainingMs: number, onExpire: () => void) => void;
+    stop: () => void;
+    clearTimer: () => void;
+};

package/lib/types/hooks/persistence/useThreadList.d.ts

@@ -0,0 +1,9 @@
+import { MutableRefObject } from 'react';
+import { ChatPersistence, ThreadSummary } from '../../types';
+/** The stored thread list, re-read on demand; only the latest read may land. */
+export default function useThreadList(storeRef: MutableRefObject<ChatPersistence | undefined>): {
+    threads: ThreadSummary[];
+    setThreads: import("react").Dispatch<import("react").SetStateAction<ThreadSummary[]>>;
+    refreshThreads: () => Promise<void>;
+    invalidate: () => void;
+};

package/lib/types/hooks/persistence/useWriteQueue.d.ts

@@ -0,0 +1,5 @@
+/** Runs storage writes one after another, in the order they were issued. */
+export default function useWriteQueue(): {
+    enqueue: (run: () => Promise<void>) => Promise<void>;
+    reset: () => 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;
@@ -14,6 +14,8 @@ export interface TrackResultLoadFinishedArgs {
     intent: string;
     searchResultCount: number;
     intentResultId?: string;
+    /** Thread the answer belongs to, when it can differ from the hook's `threadId`. */
+    threadId?: string;
 }
 export interface TrackResultClickArgs {
     intent: string;
@@ -38,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/hooks/useIsMounted.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="react" />
+/** A ref that is `true` while mounted, for async work that must not land after unmount. */
+export default function useIsMounted(): import("react").MutableRefObject<boolean>;

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

@@ -0,0 +1,3 @@
+/// <reference types="react" />
+/** A ref that always holds the latest `value`, for async code that must not read stale props. */
+export default function useLatest<T>(value: T): import("react").MutableRefObject<T>;

package/lib/types/index.d.ts

@@ -10,8 +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, AsaContextValue, CioClientOptions, RequestConfigs, Formatters, UrlHelpers, QueryParamEncodingOptions, DefaultQueryStringMap, Translations, ChatMessage, ChatMessageStatus, FollowUpRefinement, ResultGroup, ResultGroupMeta, SearchResultEventRequest, UseAsaResultsOptions, UseChatReturn, 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

@@ -21,6 +21,12 @@ export interface AsaContextValue {
     urlHelpers: UrlHelpers;
     callbacks?: AsaCallbacks;
     section?: string;
+    /** Resolved chat persistence store, or `undefined` when persistence is off. */
+    persistence?: ChatPersistence;
+    /** Whose store `persistence` is: the guest's (per tab) or a signed-in shopper's (per browser). */
+    persistenceScope?: PersistenceScope;
+    /** Api key and domain `persistence` is scoped to; a login carries a conversation over only within one. */
+    persistenceIndex?: string;
 }
 export interface RequestConfigs extends IAgentParameters {
     intent?: string;
@@ -35,7 +41,7 @@ export interface UrlHelpers {
     getUrlFromState: (state: RequestConfigs, options: QueryParamEncodingOptions) => string;
     defaultQueryStringMap: Readonly<DefaultQueryStringMap>;
 }
-export interface CioAsaProviderProps extends Omit<Partial<AsaContextValue>, 'setCioClientOptions' | 'cioClientOptions'> {
+interface CioAsaProviderBaseProps extends Omit<Partial<AsaContextValue>, 'setCioClientOptions' | 'cioClientOptions' | 'persistence' | 'persistenceScope' | 'persistenceIndex'> {
     apiKey?: string;
     /**
      * A/B test cells to attach to tracking events, as `{ [testName]: cellName }`. Each entry is
@@ -49,6 +55,32 @@ export interface CioAsaProviderProps extends Omit<Partial<AsaContextValue>, 'set
      */
     testCells?: Record<string, string>;
 }
+/** How conversations are kept in the browser. */
+export interface PersistConversationOptions {
+    /**
+     * Keep conversations across page loads: a signed-in shopper's in `localStorage` for 7 days,
+     * keyed by api key + domain + user id; a guest's in `sessionStorage`, ending with the tab.
+     */
+    enabled: boolean;
+}
+interface PersistentProviderProps {
+    persistConversation: PersistConversationOptions;
+    /**
+     * Whose history it is: the signed-in shopper's stable, non-personal id, or `null` for a guest.
+     * Change it on login and logout. With `apiKey` it is also set on the client.
+     */
+    userId: string | null;
+}
+interface EphemeralProviderProps {
+    /** Off, or omitted: the conversation lives in memory and is gone on the next page load. */
+    persistConversation?: PersistConversationOptions & {
+        enabled: false;
+    };
+    /** The shopper's id; with `apiKey` it is set on the client. `null` for a guest. */
+    userId?: string | null;
+}
+export type CioAsaPersistenceProps = PersistentProviderProps | EphemeralProviderProps;
+export type CioAsaProviderProps = CioAsaProviderBaseProps & CioAsaPersistenceProps;
 export interface UseCioClientProps {
     apiKey?: string;
     cioClient?: Nullable<ConstructorIOClient>;
@@ -84,6 +116,8 @@ export interface ChatMessage {
     threadId?: string;
     /** Narrowing question the agent asked at the end of this turn, from a `follow_up_refinement` event. */
     refinement?: FollowUpRefinement;
+    /** The answer never arrived: the page was left or the shopper logged out mid-answer. Unset on a failure. */
+    interrupted?: boolean;
 }
 /** A narrowing question with selectable options, emitted by the agent as a `follow_up_refinement` event. */
 export interface FollowUpRefinement {
@@ -138,14 +172,29 @@ export interface ResultGroupMeta {
 }
 export interface ResultGroup {
     group: ResultGroupMeta;
+    /** Raw items as the agent sent them; empty on a conversation restored from storage. */
     searchResults: Record<string, unknown>[];
+    /** The cards as `normalizeItem` made them; set on a conversation restored from storage. */
+    products?: Product[];
     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. */
+    canAbort: boolean;
     /**
      * Cancel the in-flight request, keeping the conversation. The partial reply is settled
      * as `done` and the thread id is kept, so the next message continues the same
@@ -153,25 +202,140 @@ export interface UseChatReturn {
      */
     abort: () => void;
     clearHistory: () => void;
+    /** True while a persisted conversation is being loaded. Always `false` when persistence is off. */
+    isHydrating: boolean;
+    /** Stored conversations, most recent first. Empty when persistence is off. */
+    threads: ThreadSummary[];
+    /** Id of the stored conversation currently shown, or `null` for an unsaved one. */
+    activeThreadId: string | null;
+    /** Start an empty conversation, keeping the current one in storage when persistence is on. */
+    newThread: () => void;
+    /** Load a stored conversation and continue it. No-op when persistence is off. */
+    switchThread: (threadId: string) => Promise<void>;
 }
 export interface UseAsaResultsOptions {
-    /** Seed the thread id (e.g. loaded from browser storage) to resume a prior conversation. Read once on mount. */
+    /**
+     * Seed the thread id to resume a prior conversation. Read once on mount. With persistence
+     * enabled, the matching stored transcript is restored too when one exists.
+     */
     initialThreadId?: string;
+    /** Makes the card stored for each product: the function `Chat` renders with. Defaults to `normalizeItemToProduct`. */
+    normalizeItem?: (item: any) => Product;
+}
+/** Where conversations live: `'session'` ends with the tab, `'local'` survives it. */
+export type StorageArea = 'local' | 'session';
+/** Whose conversations a store holds. */
+export type PersistenceScope = 'guest' | 'user';
+/** A stored conversation. `threadId` is the server thread id, or a `local-` id for non-conversational domains. */
+export interface PersistedChat {
+    version: 1;
+    threadId: string;
+    messages: ChatMessage[];
+    createdAt: number;
+    updatedAt: number;
+    /**
+     * Id of the browser tab that last wrote the record. Lets a reloaded tab tell its own
+     * interrupted answer (settled at once) from one still streaming in another tab.
+     */
+    owner?: string;
+}
+export interface ThreadSummary {
+    threadId: string;
+    /** First user message, truncated. */
+    title: string;
+    createdAt: number;
+    updatedAt: number;
+    /** True while the latest answer is still streaming (possibly in another tab). */
+    inFlight: boolean;
+}
+/** Storage contract the chat hook talks to; implemented by `createLocalStoragePersistence`. */
+export interface ChatPersistence {
+    /** Most recently updated first. */
+    listThreads(): Promise<ThreadSummary[]>;
+    getThread(threadId: string): Promise<PersistedChat | null>;
+    saveThread(chat: PersistedChat): Promise<void>;
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * Optional. Whether `threadId` was explicitly deleted (or the whole store was cleared), as
+     * opposed to expired or evicted. Without it, a thread that has gone missing is treated as deleted.
+     */
+    isThreadDeleted?(threadId: string): Promise<boolean>;
+    /**
+     * Optional. Write `chat` synchronously, retiring `staleIds` in the same step, for use while the
+     * page is unloading: an async write cannot finish there. Falls back to `saveThread` when absent.
+     */
+    saveThreadSync?(chat: PersistedChat, staleIds?: string[]): void;
+    /**
+     * Optional. Notify when stored threads change outside this hook instance (another tab).
+     * Returns an unsubscribe function.
+     */
+    subscribe?(listener: () => void): () => void;
+}
+/** Which stored history `clearPersistedConversations` deletes; mirror what the provider was given. */
+export interface ClearPersistedConversationsOptions {
+    /** The provider's `apiKey`, or the api key of the `cioClient` given to it. */
+    apiKey: string;
+    /** The `domain` from `staticRequestConfigs`. Default `'chatbot'`, the provider's default. */
+    domain?: string;
+    /** The shopper whose history to delete. Omit or pass `null` for the guest history. */
+    userId?: string | null;
+    /** Storage to clear instead of the default: `localStorage` for a shopper, `sessionStorage` for the guest. */
+    storage?: Storage;
+}
+export interface LocalStoragePersistenceOptions {
+    /** Storage key prefix. Default `'cio-asa:chat'`. */
+    key?: string;
+    /** Appended to the key to isolate conversations, e.g. per api key + domain. */
+    namespace?: string;
+    /** Threads idle longer than this are dropped on read. Default 7 days, matching server retention. */
+    ttlMs?: number;
+    /** Cap on user/assistant turns kept per thread. Unlimited by default. */
+    maxTurns?: number;
+    /** Cap on threads kept. Unlimited by default. */
+    maxThreads?: number;
+    /** Which browser storage to use. Default `'local'`. */
+    storageArea?: StorageArea;
+    /** 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;
@@ -240,6 +404,7 @@ export type Translations = {
     'CioAsa.results.saleBadge'?: string;
     'CioAsa.refinement.ariaLabel'?: string;
     'CioAsa.error.message'?: string;
+    'CioAsa.error.interrupted'?: string;
 };
 export interface ChatHeaderRenderProps {
     title: string;

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

@@ -0,0 +1,2 @@
+import type { PersistedChat } from '../types';
+export default function isPersistedChat(value: unknown): value is PersistedChat;

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

@@ -0,0 +1,45 @@
+import { ChatMessage, PersistedChat } from '../types';
+import { ItemNormalizer } from './chatThreads';
+/** Conversation state that async work must always see current; one object so a reset is one call. */
+export interface ChatSession {
+    /** Server thread id, sent with the next request. Never a `local-` id. */
+    serverThreadId: string | null;
+    /** Id the conversation is stored under: the server id, or a `local-` one before it exists. */
+    storageThreadId: string | null;
+    /** Local ids whose re-keyed replacement could not be verified yet; deleted on a later save. */
+    orphanIds: string[];
+    createdAt: number | null;
+    /** `updatedAt` of the last snapshot written or applied; newer stored records win over it. */
+    lastSyncedAt: number;
+    /** There are changes since the last write. */
+    dirty: boolean;
+    /** The user acted; a load that was still running must not overwrite the result. */
+    interacted: boolean;
+    /** Bumped to invalidate loads started before the conversation changed. */
+    loadRequest: number;
+    isStreaming: boolean;
+    /** The thread is streaming in another tab; sending is blocked meanwhile. */
+    foreignInFlight: boolean;
+    idCounter: number;
+    /** Per-instance suffix so two tabs cannot mint the same message id in the same millisecond. */
+    idSuffix: string;
+    /** Makes the card stored for a raw item: the one the conversation is rendered with. */
+    normalizeItem: ItemNormalizer;
+}
+export declare function createChatSession(initialThreadId?: string, normalizeItem?: ItemNormalizer): ChatSession;
+/** Forget the current conversation. Returns the id it was stored under, if any. */
+export declare function resetConversation(session: ChatSession): string | null;
+export declare function nextMessageId(session: ChatSession): string;
+/** Whether `messageId` was minted by this session rather than by another tab. */
+export declare function isOwnMessage(session: ChatSession, messageId: string): boolean;
+/** Makes a stored conversation the one this session continues. */
+export declare function adoptStoredChat(session: ChatSession, chat: PersistedChat): void;
+/** A copy that keeps the conversation `session` holds while `session` itself moves on. */
+export declare function forkSession(session: ChatSession): ChatSession;
+/** Makes `session` continue the conversation `from` kept, showing `messages`. */
+export declare function adoptSession(session: ChatSession, from: ChatSession, messages: ChatMessage[]): void;
+/** Builds the record to write and moves the session onto its key; `staleIds` are the records to retire once stored. */
+export declare function prepareSnapshot(session: ChatSession, messages: ChatMessage[], now?: number): {
+    snapshot: PersistedChat;
+    staleIds: string[];
+};

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

@@ -0,0 +1,63 @@
+import type { ChatMessage, ChatPersistence, PersistedChat } from '../types';
+import type { Product } from './productNormalizer';
+/** Stored record format; records with another version are ignored on read. */
+export declare const PERSISTED_CHAT_VERSION = 1;
+/** Prefix of the `localStorage` key; the api key, domain and user id are appended to it. */
+export declare const DEFAULT_PERSISTENCE_KEY = "cio-asa:chat";
+/** One week, matching how long the agent itself remembers a thread. */
+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;
+/** 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. */
+export declare function createLocalThreadId(): string;
+/**
+ * Per-tab id: survives a reload, differs between tabs, `undefined` on the server. A duplicated tab
+ * copies `sessionStorage`, so the id is read back on a reload only, and is kept there only while
+ * the page is hidden.
+ */
+export declare function getTabId(): string | undefined;
+/** Whether `threadId` was made by `createLocalThreadId` rather than by the server. */
+export declare function isLocalThreadId(threadId: string | null | undefined): boolean;
+/** Title for a thread list: the first user message, truncated with an ellipsis. */
+export declare function getThreadTitle(messages: ChatMessage[]): string;
+/** Counter to continue message ids from after a restore, so new ids never collide with restored ones. */
+export declare function nextMessageCounter(messages: ChatMessage[]): number;
+/** Whether the latest answer in `messages` has not finished streaming. */
+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[];
+/** 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. */
+export declare function compactMessages(messages: ChatMessage[], normalize: ItemNormalizer): ChatMessage[];
+/**
+ * Both lists in stored order; a shared message takes the incoming version unless `preferStored`.
+ * A settled incoming version still replaces a stored one mid-stream: it is the later one by definition.
+ */
+export declare function mergeMessages(stored: ChatMessage[], incoming: ChatMessage[], preferStored?: boolean): ChatMessage[];
+/**
+ * Saves `snapshot`, then deletes `staleIds` once the new record is read back. Stores may fail
+ * without throwing, so both steps are checked by reading: `saved` is whether the snapshot landed,
+ * `leftover` the stale ids still stored.
+ */
+export declare function saveThreadAndRetireStale(store: ChatPersistence, snapshot: PersistedChat, staleIds: string[]): Promise<{
+    saved: boolean;
+    leftover: string[];
+}>;
+/** Finds the server-keyed record another tab re-keyed a local thread into, by its first message. */
+export declare function findRekeyedThread(store: ChatPersistence, firstMessageId: string | undefined): Promise<PersistedChat | null>;
+/** Whether a stored thread still reads as streaming: this tab's own always, another tab's only within the grace. */
+export declare function isThreadStreaming(chat: PersistedChat, now?: number): boolean;
+/** Ms left to show a stored answer as streaming in another tab; `0` when it should be settled. */
+export declare function foreignStreamRemainingMs(chat: PersistedChat, now?: number): number;
+/**
+ * Moves every thread of `from` into `to`; copies of the chat on screen are not copied, its owner
+ * saves it. A source record is deleted only once `to` holds it after every copy was made, so one
+ * copy evicting another, or a save that did not land, leaves the source in place.
+ */
+export declare function moveThreads(from: ChatPersistence, to: ChatPersistence, onScreen?: {
+    threadIds?: string[];
+    firstMessageId?: string;
+}): Promise<void>;

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

@@ -0,0 +1,5 @@
+import type ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
+import type { ConstructorClientOptions } from '@constructor-io/constructorio-client-javascript/lib/types';
+export type ClientIdentity = Pick<ConstructorClientOptions, 'apiKey' | 'userId'>;
+/** `options` is private in the client's typings; read it here only, so a client bump fails a test, not storage keys. */
+export declare function readClientOptions(client: ConstructorIOClient | null | undefined): ClientIdentity | undefined;

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

@@ -0,0 +1,26 @@
+import type { ChatPersistence, ClearPersistedConversationsOptions, LocalStoragePersistenceOptions, StorageArea } from '../types';
+/** No user id, or an empty one: the conversation belongs to a guest. */
+export declare const isGuest: (userId: string | number | null | undefined) => boolean;
+/** The id the client and storage use: `undefined` for a guest (no id, `null` or empty). */
+export declare const shopperId: (userId: string | number | null | undefined) => string | undefined;
+/** Guests live in `sessionStorage`, so their history ends with the tab; shoppers keep theirs in `localStorage`. */
+export declare function storageAreaFor(userId: string | null | undefined): StorageArea;
+/** Namespace the provider stores under: api key, domain and, for a signed-in shopper, the user id. */
+export declare function persistenceNamespace(parts: {
+    apiKey: string;
+    domain?: string;
+    userId?: string | null;
+}): string;
+/**
+ * Deletes every stored conversation of one shopper, or of the guest without `userId`; open tabs
+ * follow. Resolves once the deletion is recorded.
+ */
+export declare function clearPersistedConversations(options: ClearPersistedConversationsOptions): Promise<void>;
+/** Conversation store on top of `localStorage`; one key per namespace, merged across tabs. */
+export declare function createLocalStoragePersistence(options?: LocalStoragePersistenceOptions): ChatPersistence;
+/**
+ * One store per namespace and area for the page, so a chat mounted again finds the answers still
+ * streaming into it. Not shared on the server, where the map would outlive the request.
+ */
+export declare function sharedLocalStoragePersistence(namespace: string, storageArea: StorageArea): ChatPersistence;
+export default createLocalStoragePersistence;

package/lib/types/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.7.2";
+declare const _default: "1.9.0";
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-asa",
-  "version": "1.7.2",
+  "version": "1.9.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",