@cimulate/copilot-widget 1.22.0 → 1.23.0

package/dist/messaging.d.ts

@@ -62,7 +62,9 @@ export declare const AgentForceWidget: (props: CopilotWidgetProps) => JSX_2.Elem
  * UIStateContext >
  * MessagingProvider (Agentforce/SCRT2 SDK)
  */
-export declare const AgentforceWidgetProvider: ({ mode, apiKey, apiToken, baseUrl, logoUrl, headerText, headerConfig, theme, openLinksInNewTab, globalClassName, isDevelopment, componentType, componentConfig, entryType, entryMessage, disclaimerText, disclaimerMarkdown, clientContext, searchPlaceholder, searchButtonLabel, searchConfig, suggestionButtonConfig, messageAlignment, autoScroll, promptsConfig, resetConversationMessage, conversationHistory, messagingConfig, __features, children, }: CopilotWidgetProps & {
+export declare const AgentforceWidgetProvider: ({ mode, apiKey, apiToken, baseUrl, logoUrl, headerText, headerConfig, theme, openLinksInNewTab, globalClassName, isDevelopment, componentType, componentConfig, entryType, entryMessage, disclaimerText, disclaimerMarkdown, clientContext, searchPlaceholder, searchButtonLabel, searchConfig, suggestionButtonConfig, messageAlignment, autoScroll, promptsConfig, resetConversationMessage, conversationHistory, messagingConfig, overrides, overridesUrl, inlineOverrides, __features, children, }: CopilotWidgetProps & {
+    overridesUrl?: string;
+    inlineOverrides?: ComponentOverrides;
     children: ReactNode;
 }) => JSX_2.Element;
 
@@ -171,6 +173,28 @@ declare type ComparisonTableRow = {
     values: string[];
 };
 
+/**
+ * One flat map from override key to custom-element tag name.
+ *
+ * `ProductTile` and `ProductCarousel` are the only keys the widget consults for
+ * its built-in product UI: register one and the widget mounts your element in
+ * place of the default tile/carousel (leave it unset and the built-in renders).
+ * Every other key is matched against a `type:"tool_results"` block's top-level
+ * `output_name` (never a field inside the arbitrary `data` payload); an unmatched
+ * block renders nothing. All of them receive the same `OverrideProps`.
+ *
+ *   { ProductTile: "cx-product-card", recentOrders: "cx-recent-orders" }
+ *
+ * Widget chrome (header, search bar, follow-up suggestions) is intentionally NOT
+ * overridable: those keys are accepted by the open index signature but have no
+ * render path, so they are silently ignored.
+ */
+export declare interface ComponentOverrides {
+    ProductTile?: OverrideTagName;
+    ProductCarousel?: OverrideTagName;
+    [key: string]: OverrideTagName | undefined;
+}
+
 export declare type ComponentType = "chat" | "dialog" | "modal";
 
 declare interface CopilotWidgetProps extends CimCopilotSdkConfig {
@@ -245,6 +269,9 @@ declare interface CopilotWidgetProps extends CimCopilotSdkConfig {
      * Configuration for messaging mode. Required when mode is 'messaging'.
      */
     messagingConfig?: MessagingModeConfig;
+    overrides?: ComponentOverrides;
+    overridesUrl?: string;
+    inlineOverrides?: ComponentOverrides;
     /**
      *
      * Enables features not yet released. They may require additional backend support and are subject to change.
@@ -285,7 +312,7 @@ declare interface HeaderConfig {
     headerTextTextAlign?: "left" | "center" | "right";
 }
 
-export declare const injectMessagingWidget: ({ timeout, elementId, ...props }: InjectMessagingWidgetOptions) => void;
+export declare const injectMessagingWidget: ({ timeout, elementId, overridesUrl, overrides: inlineOverrides, ...props }: InjectMessagingWidgetOptions) => void;
 
 declare interface InjectMessagingWidgetOptions extends Omit<CopilotWidgetProps, "apiKey" | "apiToken" | "baseUrl" | "mode"> {
     /** ID of the DOM element to render the widget into */
@@ -294,6 +321,20 @@ declare interface InjectMessagingWidgetOptions extends Omit<CopilotWidgetProps,
     timeout?: number;
     /** SCRT2 messaging configuration (required) */
     messagingConfig: MessagingModeConfig;
+    /**
+     * URL to a hosted customer override script (the primary deploy path). The
+     * script must set `window.CimulateOverrides`. Loaded asynchronously in
+     * OverridesContext; the widget renders immediately while overrides load in
+     * the background.
+     */
+    overridesUrl?: string;
+    /**
+     * Inline overrides map, passed directly instead of via `overridesUrl` (no
+     * hosting / no round-trip). `overridesUrl` takes precedence when both are set.
+     *
+     * (Inherited from `CopilotWidgetProps`; re-declared here for documentation.)
+     */
+    overrides?: ComponentOverrides;
 }
 
 declare type MarkdownResponse = {
@@ -412,7 +453,7 @@ export declare interface MessagingModeConfig {
     /**
      * Shows a "Connect to a human agent" button in the messaging search bar that
      * asks the Agentforce agent to escalate the conversation to a human. Defaults
-     * to true; set to false to hide it. Requires the org's Agentforce agent to be
+     * to false; set to true to show it. Requires the org's Agentforce agent to be
      * configured with an escalation path/topic, otherwise the button is a no-op.
      */
     enableEscalationToAgent?: boolean;
@@ -504,6 +545,108 @@ declare type OrderDetails = {
     footerMessage: string | null;
 };
 
+/**
+ * Component Override Types
+ *
+ * Defines the contract between the Commerce Client widget and customer overrides.
+ * Each override is the tag name of a pre-registered custom element (a string).
+ * Every override — product or custom block — receives the same `OverrideProps`
+ * object on its element's `props` setter: the raw block payload plus an `api`.
+ */
+/**
+ * Widget capabilities handed to every override so it can be interactive — e.g. a
+ * product card, option picker, or warranty form that posts a message back to the
+ * agent via `sendMessage`.
+ */
+export declare interface OverrideApi {
+    sendMessage: (text: string) => void;
+    isLoading: boolean;
+    isConnected: boolean;
+    /**
+     * Widget presentation mode: `"chat"` (fullscreen), `"dialog"` (floating window),
+     * or `"modal"` (centered overlay). Use to adapt layout — e.g. expand details in
+     * `"chat"`, condense in `"dialog"`.
+     */
+    componentType: "chat" | "dialog" | "modal";
+    /**
+     * Widget integration mode: `"standalone"` (the only UI on the page) or
+     * `"embedded"` (coexists with storefront chrome). Use to adjust z-index,
+     * backdrop behavior, or whether to render a close button.
+     */
+    mode: "standalone" | "embedded";
+}
+
+/**
+ * Minimal base class for customer override custom elements.
+ * Handles the widget contract: props setter/getter and lifecycle.
+ *
+ * Subclasses implement render() to build their DOM. Use your own
+ * sanitization/escaping when building HTML (DOMPurify, framework
+ * built-ins, or manual escaping).
+ *
+ * Usage:
+ *   import { OverrideElement } from '@cimulate/copilot-widget/messaging';
+ *
+ *   class ProductCard extends OverrideElement {
+ *     render() {
+ *       const { payload, api } = this.props || {};
+ *       // Use your own escaping/sanitization here
+ *       const escaped = yourEscapeFunction(payload.data.name);
+ *       this.replaceChildren(document.createTextNode(escaped));
+ *     }
+ *   }
+ *   customElements.define("product-card", ProductCard);
+ */
+export declare class OverrideElement extends HTMLElement {
+    protected _props: Record<string, unknown> | null;
+    /**
+     * The widget assigns `element.props = {...}` on first mount and every
+     * re-render. Store and render here — the single entry point.
+     */
+    set props(value: Record<string, unknown> | null);
+    get props(): Record<string, unknown> | null;
+    /**
+     * Fires ONCE when inserted. The instance persists across widget re-renders,
+     * so this won't fire again per commit.
+     */
+    connectedCallback(): void;
+    /**
+     * Subclasses override this to build their DOM. Called on first mount and
+     * every props update.
+     */
+    protected render(): void;
+}
+
+/**
+ * The single props object every override receives. `payload` is the block's raw
+ * data, verbatim from the agent — the widget does not normalize it, so its shape
+ * depends on `name`:
+ *
+ *   - "ProductTile"      → one raw product ({ id, caption?, data: { name, price,
+ *                          currencyCode, imageUrl, … }, customProperties? })
+ *   - "ProductCarousel"  → { title?, products: RawProduct[] }
+ *   - any custom-block key → the `tool_results` block's raw `data`, your own shape
+ */
+export declare interface OverrideProps {
+    /** The resolved override key: "ProductTile"/"ProductCarousel" for the product slots, else the `tool_results` block's `output_name`. */
+    name: string;
+    payload: unknown;
+    api: OverrideApi;
+}
+
+/**
+ * A component override is the tag name of a pre-registered custom element
+ * (e.g. "product-card"). The widget creates the element via
+ * document.createElement(tagName) and assigns `OverrideProps` to its `props`
+ * setter. The element must be registered with customElements.define before the
+ * widget renders.
+ *
+ * The name must be a valid custom element name — it has to contain a hyphen and
+ * be all lowercase. Anything else (e.g. "ProductTile" or "div") is rejected with
+ * a console error and the slot renders blank.
+ */
+export declare type OverrideTagName = string;
+
 declare type ProductCarouselProduct = {
     id: string;
     caption?: string;
@@ -633,7 +776,7 @@ declare type PromptsExtensionState = {
 
 declare type PromptsParams = AskCimSuggestions | CopilotSearchSuggestions | CopilotBrowseSuggestions | ProductViewSuggestions;
 
-declare type ResponseItem = MarkdownResponse | ProductCarouselResponse | ProductTileResponse | ProductComparisonResponse | SuggestionsResponse | CartResponse | OrderConfirmationResponse;
+declare type ResponseItem = MarkdownResponse | ProductCarouselResponse | ProductTileResponse | ProductComparisonResponse | SuggestionsResponse | CartResponse | OrderConfirmationResponse | ToolResultsResponse;
 
 /**
  * A retryable message-send failure: the connection is live but the send itself
@@ -674,6 +817,20 @@ declare interface ThemeConfig {
     borderRadius?: string;
 }
 
+/**
+ * Escape hatch for agent-action outputs that don't map to any built-in block
+ * (e.g. order tracking, warranty registration, option pickers). Rendered via a
+ * customer-registered tag in the flat `overrides` map, keyed by `output_name`.
+ * `data` is the raw action output, handed to the override verbatim. An unmatched
+ * `output_name` renders nothing, same as an unknown block type.
+ */
+declare type ToolResultsResponse = {
+    type: "tool_results";
+    index: number;
+    output_name?: string;
+    data: unknown;
+};
+
 export declare function useMessaging(): MessagingContextType;
 
 declare interface WidgetComponentConfig {