@thoughtspot/visual-embed-sdk 1.45.1 → 1.45.3

package/src/embed/conversation.ts

@@ -2,7 +2,7 @@ import isUndefined from 'lodash/isUndefined';
 import { ERROR_MESSAGE } from '../errors';
 import { Param, BaseViewConfig, RuntimeFilter, RuntimeParameter, ErrorDetailsTypes, EmbedErrorCodes } from '../types';
 import { TsEmbed } from './ts-embed';
-import { getQueryParamString, getFilterQuery, getRuntimeParameters } from '../utils';
+import { getQueryParamString, getFilterQuery, getRuntimeParameters, validateHttpUrl, setParamIfDefined } from '../utils';
 
 /**
  * Configuration for search options
@@ -14,6 +14,106 @@ export interface SearchOptions {
     searchQuery: string;
 }
 
+/**
+ * Configuration for the Spotter sidebar.
+ * Can be used in SpotterEmbed and AppEmbed.
+ * @group Embed components
+ * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+ */
+export interface SpotterSidebarViewConfig {
+    /**
+     * Controls the visibility of the past conversations sidebar.
+     * @default false
+     * @version SDK: 1.45.0 | ThoughtSpot: 26.2.0.cl
+     */
+    enablePastConversationsSidebar?: boolean;
+    /**
+     * Custom title text for the sidebar header.
+     * Defaults to translated "Spotter" text.
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+     */
+    spotterSidebarTitle?: string;
+    /**
+     * Boolean to set the default expanded state of the sidebar.
+     * @default false
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+     */
+    spotterSidebarDefaultExpanded?: boolean;
+    /**
+     * Custom label text for the rename action in the conversation edit menu.
+     * Defaults to translated "Rename" text.
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+     */
+    spotterChatRenameLabel?: string;
+    /**
+     * Custom label text for the delete action in the conversation edit menu.
+     * Defaults to translated "DELETE" text.
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+     */
+    spotterChatDeleteLabel?: string;
+    /**
+     * Custom title text for the delete conversation confirmation modal.
+     * Defaults to translated "Delete chat" text.
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+     */
+    spotterDeleteConversationModalTitle?: string;
+    /**
+     * Custom message text for the past conversation banner alert.
+     * Defaults to translated alert message.
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+     */
+    spotterPastConversationAlertMessage?: string;
+    /**
+     * Custom URL for the documentation/best practices link.
+     * Defaults to ThoughtSpot docs URL based on release version.
+     * Note: URL must include the protocol (e.g., `https://www.example.com`).
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+     */
+    spotterDocumentationUrl?: string;
+    /**
+     * Custom label text for the best practices button in the footer.
+     * Defaults to translated "Best Practices" text.
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+     */
+    spotterBestPracticesLabel?: string;
+    /**
+     * Number of conversations to fetch per batch when loading conversation history.
+     * @default 30
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+     */
+    spotterConversationsBatchSize?: number;
+    /**
+     * Custom title text for the "New Chat" button in the sidebar.
+     * Defaults to translated "New Chat" text.
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+     */
+    spotterNewChatButtonTitle?: string;
+}
+
+/**
+ * Configuration for customizing Spotter chat UI branding.
+ * @group Embed components
+ * @version SDK: 1.46.0 | ThoughtSpot: 26.4.0.cl
+ */
+export interface SpotterChatViewConfig {
+    /**
+     * Hides the ThoughtSpot logo/icon in tool response
+     * cards. The branding label prefix is controlled
+     * separately via `toolResponseCardBrandingLabel`.
+     * External MCP tool branding is not affected.
+     * @default false
+     */
+    hideToolResponseCardBranding?: boolean;
+    /**
+     * Custom label to replace the "ThoughtSpot" prefix
+     * in tool response cards. Set to an empty string
+     * `''` to hide the prefix entirely. Works
+     * independently of `hideToolResponseCardBranding`.
+     * External MCP tool branding is not affected.
+     */
+    toolResponseCardBrandingLabel?: string;
+}
+
 /**
  * The configuration for the embedded spotterEmbed options.
  * @group Embed components
@@ -169,8 +269,7 @@ export interface SpotterEmbedViewConfig extends Omit<BaseViewConfig, 'primaryAct
      */
     excludeRuntimeParametersfromURL?: boolean;
     /**
-     * enablePastConversationsSidebar : Controls the visibility of the past conversations
-     * sidebar.
+     * updatedSpotterChatPrompt : Controls the updated spotter chat prompt.
      *
      * Supported embed types: `SpotterEmbed`
      * @default false
@@ -178,28 +277,48 @@ export interface SpotterEmbedViewConfig extends Omit<BaseViewConfig, 'primaryAct
      * ```js
      * const embed = new SpotterEmbed('#tsEmbed', {
      *    ... //other embed view config
-     *    enablePastConversationsSidebar : true,
+     *    updatedSpotterChatPrompt : true,
      * })
      * ```
      * @version SDK: 1.45.0 | ThoughtSpot: 26.2.0.cl
      */
-    enablePastConversationsSidebar?: boolean;
-
+    updatedSpotterChatPrompt?: boolean;
     /**
-     * updatedSpotterChatPrompt : Controls the updated spotter chat prompt.
+     * Configuration for the Spotter sidebar UI customization.
+     *
+     * Supported embed types: `SpotterEmbed`, `AppEmbed`
+     * @example
+     * ```js
+     * const embed = new SpotterEmbed('#tsEmbed', {
+     *    ... //other embed view config
+     *    spotterSidebarConfig: {
+     *        enablePastConversationsSidebar: true,
+     *        spotterSidebarTitle: 'My Conversations',
+     *        spotterSidebarDefaultExpanded: true,
+     *    },
+     * })
+     * ```
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.3.0.cl
+     */
+    spotterSidebarConfig?: SpotterSidebarViewConfig;
+    /**
+     * Configuration for customizing Spotter chat UI
+     * branding in tool response cards.
      *
      * Supported embed types: `SpotterEmbed`
-     * @default false
      * @example
      * ```js
      * const embed = new SpotterEmbed('#tsEmbed', {
      *    ... //other embed view config
-     *    updatedSpotterChatPrompt : true,
+     *    spotterChatConfig: {
+     *        hideToolResponseCardBranding: true,
+     *        toolResponseCardBrandingLabel: 'MyBrand',
+     *    },
      * })
      * ```
-     * @version SDK: 1.45.0 | ThoughtSpot: 26.2.0.cl
+     * @version SDK: 1.46.0 | ThoughtSpot: 26.4.0.cl
      */
-    updatedSpotterChatPrompt?: boolean;
+    spotterChatConfig?: SpotterChatViewConfig;
 }
 
 /**
@@ -246,14 +365,30 @@ export class SpotterEmbed extends TsEmbed {
             dataPanelV2,
             showSpotterLimitations,
             hideSampleQuestions,
-            enablePastConversationsSidebar,
             runtimeFilters,
             excludeRuntimeFiltersfromURL,
             runtimeParameters,
             excludeRuntimeParametersfromURL,
             updatedSpotterChatPrompt,
+            spotterSidebarConfig,
+            spotterChatConfig,
         } = this.viewConfig;
 
+        // Extract sidebar config properties
+        const {
+            enablePastConversationsSidebar,
+            spotterSidebarTitle,
+            spotterSidebarDefaultExpanded,
+            spotterChatRenameLabel,
+            spotterChatDeleteLabel,
+            spotterDeleteConversationModalTitle,
+            spotterPastConversationAlertMessage,
+            spotterDocumentationUrl,
+            spotterBestPracticesLabel,
+            spotterConversationsBatchSize,
+            spotterNewChatButtonTitle,
+        } = spotterSidebarConfig || {};
+
         if (!worksheetId) {
             this.handleError({
                 errorType: ErrorDetailsTypes.VALIDATION_ERROR,
@@ -264,27 +399,50 @@ export class SpotterEmbed extends TsEmbed {
         }
         const queryParams = this.getBaseQueryParams();
         queryParams[Param.SpotterEnabled] = true;
-        if (!isUndefined(disableSourceSelection)) {
-            queryParams[Param.DisableSourceSelection] = !!disableSourceSelection;
-        }
-        if (!isUndefined(hideSourceSelection)) {
-            queryParams[Param.HideSourceSelection] = !!hideSourceSelection;
-        }
 
-        if (!isUndefined(dataPanelV2)) {
-            queryParams[Param.DataPanelV2Enabled] = !!dataPanelV2;
-        }
+        // Boolean params
+        setParamIfDefined(queryParams, Param.DisableSourceSelection, disableSourceSelection, true);
+        setParamIfDefined(queryParams, Param.HideSourceSelection, hideSourceSelection, true);
+        setParamIfDefined(queryParams, Param.DataPanelV2Enabled, dataPanelV2, true);
+        setParamIfDefined(queryParams, Param.ShowSpotterLimitations, showSpotterLimitations, true);
+        setParamIfDefined(queryParams, Param.HideSampleQuestions, hideSampleQuestions, true);
+        setParamIfDefined(queryParams, Param.UpdatedSpotterChatPrompt, updatedSpotterChatPrompt, true);
+        setParamIfDefined(queryParams, Param.SpotterSidebarDefaultExpanded, spotterSidebarDefaultExpanded, true);
 
-        if (!isUndefined(showSpotterLimitations)) {
-            queryParams[Param.ShowSpotterLimitations] = !!showSpotterLimitations;
-        }
+        // String params
+        setParamIfDefined(queryParams, Param.SpotterSidebarTitle, spotterSidebarTitle);
+        setParamIfDefined(queryParams, Param.SpotterChatRenameLabel, spotterChatRenameLabel);
+        setParamIfDefined(queryParams, Param.SpotterChatDeleteLabel, spotterChatDeleteLabel);
+        setParamIfDefined(queryParams, Param.SpotterDeleteConversationModalTitle, spotterDeleteConversationModalTitle);
+        setParamIfDefined(queryParams, Param.SpotterPastConversationAlertMessage, spotterPastConversationAlertMessage);
+        setParamIfDefined(queryParams, Param.SpotterBestPracticesLabel, spotterBestPracticesLabel);
+        setParamIfDefined(queryParams, Param.SpotterConversationsBatchSize, spotterConversationsBatchSize);
+        setParamIfDefined(queryParams, Param.SpotterNewChatButtonTitle, spotterNewChatButtonTitle);
 
-        if (!isUndefined(hideSampleQuestions)) {
-            queryParams[Param.HideSampleQuestions] = !!hideSampleQuestions;
+        // URL param with validation
+        if (spotterDocumentationUrl !== undefined) {
+            const [isValid, validationError] = validateHttpUrl(spotterDocumentationUrl);
+            if (isValid) {
+                queryParams[Param.SpotterDocumentationUrl] = spotterDocumentationUrl;
+            } else {
+                this.handleError({
+                    errorType: ErrorDetailsTypes.VALIDATION_ERROR,
+                    message: ERROR_MESSAGE.INVALID_SPOTTER_DOCUMENTATION_URL,
+                    code: EmbedErrorCodes.INVALID_URL,
+                    error: validationError?.message || ERROR_MESSAGE.INVALID_SPOTTER_DOCUMENTATION_URL,
+                });
+            }
         }
 
-        if (!isUndefined(updatedSpotterChatPrompt)) {
-            queryParams[Param.UpdatedSpotterChatPrompt] = !!updatedSpotterChatPrompt;
+        // Handle spotterChatConfig params
+        if (spotterChatConfig) {
+            const {
+                hideToolResponseCardBranding,
+                toolResponseCardBrandingLabel,
+            } = spotterChatConfig;
+
+            setParamIfDefined(queryParams, Param.HideToolResponseCardBranding, hideToolResponseCardBranding, true);
+            setParamIfDefined(queryParams, Param.ToolResponseCardBrandingLabel, toolResponseCardBrandingLabel);
         }
 
         return queryParams;
@@ -298,11 +456,12 @@ export class SpotterEmbed extends TsEmbed {
             excludeRuntimeFiltersfromURL,
             runtimeParameters,
             excludeRuntimeParametersfromURL,
-            enablePastConversationsSidebar,
+            spotterSidebarConfig,
         } = this.viewConfig;
         const path = 'insights/conv-assist';
         const queryParams = this.getEmbedParamsObject();
 
+        const enablePastConversationsSidebar = spotterSidebarConfig?.enablePastConversationsSidebar;
         if (!isUndefined(enablePastConversationsSidebar)) {
             queryParams[Param.EnablePastConversationsSidebar] = !!enablePastConversationsSidebar;
         }

package/src/embed/hostEventClient/contracts.ts

@@ -1,4 +1,4 @@
-import { HostEvent } from '../../types';
+import { ContextType, HostEvent } from '../../types';
 
 export enum UIPassthroughEvent {
   PinAnswerToLiveboard = 'addVizToPinboard',
@@ -103,7 +103,7 @@ export type HostEventRequest<HostEventT extends HostEvent> =
     ? UIPassthroughRequest<EmbedApiHostEventMapping[HostEventT]>
     : any;
 
-export type HostEventResponse<HostEventT extends HostEvent> =
+export type HostEventResponse<HostEventT extends HostEvent, ContextT extends ContextType> =
   HostEventT extends keyof EmbedApiHostEventMapping
     ? UIPassthroughResponse<EmbedApiHostEventMapping[HostEventT]>
     : any;
@@ -111,5 +111,5 @@ export type HostEventResponse<HostEventT extends HostEvent> =
 // trigger response and request
 export type TriggerPayload<PayloadT, HostEventT extends HostEvent> =
   PayloadT | HostEventRequest<HostEventT>;
-export type TriggerResponse<PayloadT, HostEventT extends HostEvent> =
-  PayloadT extends HostEventRequest<HostEventT> ? HostEventResponse<HostEventT> : any;
+export type TriggerResponse<PayloadT, HostEventT extends HostEvent, ContextT extends ContextType> =
+  PayloadT extends HostEventRequest<HostEventT> ? HostEventResponse<HostEventT, ContextT> : any;

package/src/embed/hostEventClient/host-event-client.spec.ts

@@ -54,6 +54,7 @@ describe('HostEventClient', () => {
                     type: apiName,
                     parameters,
                 },
+                undefined,
             );
             expect(result).toEqual(await triggerResponse);
         });
@@ -148,6 +149,7 @@ describe('HostEventClient', () => {
                 HostEvent.UIPassthrough,
                 'http://localhost',
                 { parameters: payload, type: UIPassthroughEvent.PinAnswerToLiveboard },
+                undefined,
             );
             expect(result).toEqual(mockResponse.value);
         });
@@ -185,6 +187,7 @@ describe('HostEventClient', () => {
                     parameters: payload,
                     type: 'saveAnswer',
                 },
+                undefined,
             );
             expect(result).toEqual({ answerId: 'newAnswer', ...mockResponse[0].value });
         });
@@ -198,7 +201,7 @@ describe('HostEventClient', () => {
 
             const result = await client.triggerHostEvent(hostEvent, payload);
 
-            expect(client.hostEventFallback).toHaveBeenCalledWith(hostEvent, payload);
+            expect(client.hostEventFallback).toHaveBeenCalledWith(hostEvent, payload, undefined);
             expect(result).toEqual(mockResponse);
         });
 
@@ -223,6 +226,7 @@ describe('HostEventClient', () => {
                 HostEvent.Pin,
                 mockThoughtSpotHost,
                 {},
+                undefined,
             );
             expect(result).toEqual([mockResponse]);
         });
@@ -248,6 +252,7 @@ describe('HostEventClient', () => {
                 HostEvent.Save,
                 mockThoughtSpotHost,
                 {},
+                undefined,
             );
             expect(result).toEqual([mockResponse]);
         });
@@ -303,6 +308,7 @@ describe('HostEventClient', () => {
                     parameters: { ...payload, pinboardId: 'test', newPinboardName: 'testLiveboard' },
                     type: 'addVizToPinboard',
                 },
+                undefined,
             );
             expect(result).toEqual({
                 pinboardId: 'testLiveboard',

package/src/embed/hostEventClient/host-event-client.ts

@@ -1,4 +1,4 @@
-import { HostEvent } from '../../types';
+import { ContextType, HostEvent } from '../../types';
 import { processTrigger as processTriggerService } from '../../utils/processTrigger';
 import { getEmbedConfig } from '../embedConfig';
 import {
@@ -23,7 +23,7 @@ export class HostEventClient {
    * @param {any} data Data to send with the host event
    * @returns {Promise<any>} - the response from the process trigger
    */
-  protected async processTrigger(message: HostEvent, data: any): Promise<any> {
+  protected async processTrigger(message: HostEvent, data: any, context?: ContextType): Promise<any> {
       if (!this.iFrame) {
           throw new Error('Iframe element is not set');
       }
@@ -34,14 +34,16 @@ export class HostEventClient {
           message,
           thoughtspotHost,
           data,
+          context,
       );
   }
 
   public async handleHostEventWithParam<UIPassthroughEventT extends UIPassthroughEvent>(
       apiName: UIPassthroughEventT,
       parameters: UIPassthroughRequest<UIPassthroughEventT>,
+      context?: ContextType,
   ): Promise<UIPassthroughResponse<UIPassthroughEventT>> {
-      const response = (await this.triggerUIPassthroughApi(apiName, parameters))
+      const response = (await this.triggerUIPassthroughApi(apiName, parameters, context))
           ?.filter?.((r) => r.error || r.value)[0];
 
       if (!response) {
@@ -65,8 +67,9 @@ export class HostEventClient {
   public async hostEventFallback(
       hostEvent: HostEvent,
       data: any,
+      context?: ContextType,
   ): Promise<any> {
-      return this.processTrigger(hostEvent, data);
+      return this.processTrigger(hostEvent, data, context);
   }
 
   /**
@@ -80,20 +83,22 @@ export class HostEventClient {
   public async triggerUIPassthroughApi<UIPassthroughEventT extends UIPassthroughEvent>(
       apiName: UIPassthroughEventT,
       parameters: UIPassthroughRequest<UIPassthroughEventT>,
+      context?: ContextType,
   ): Promise<UIPassthroughArrayResponse<UIPassthroughEventT>> {
       const res = await this.processTrigger(HostEvent.UIPassthrough, {
           type: apiName,
           parameters,
-      });
+      }, context);
 
       return res;
   }
 
   protected async handlePinEvent(
       payload: HostEventRequest<HostEvent.Pin>,
-  ): Promise<HostEventResponse<HostEvent.Pin>> {
+      context?: ContextType,
+  ): Promise<HostEventResponse<HostEvent.Pin, ContextType>> {
       if (!payload || !('newVizName' in payload)) {
-          return this.hostEventFallback(HostEvent.Pin, payload);
+          return this.hostEventFallback(HostEvent.Pin, payload, context);
       }
 
       const formattedPayload = {
@@ -104,6 +109,7 @@ export class HostEventClient {
 
       const data = await this.handleHostEventWithParam(
           UIPassthroughEvent.PinAnswerToLiveboard, formattedPayload,
+          context as ContextType,
       );
 
       return {
@@ -114,14 +120,16 @@ export class HostEventClient {
 
   protected async handleSaveAnswerEvent(
       payload: HostEventRequest<HostEvent.SaveAnswer>,
+      context?: ContextType,
   ): Promise<any> {
       if (!payload || !('name' in payload) || !('description' in payload)) {
           // Save is the fallback for SaveAnswer
-          return this.hostEventFallback(HostEvent.Save, payload);
+          return this.hostEventFallback(HostEvent.Save, payload, context);
       }
 
       const data = await this.handleHostEventWithParam(
           UIPassthroughEvent.SaveAnswer, payload,
+          context as ContextType,
       );
       return {
           ...data,
@@ -132,19 +140,22 @@ export class HostEventClient {
   public async triggerHostEvent<
     HostEventT extends HostEvent,
     PayloadT,
+    ContextT extends ContextType,
   >(
       hostEvent: HostEventT,
       payload?: TriggerPayload<PayloadT, HostEventT>,
-  ): Promise<TriggerResponse<PayloadT, HostEventT>> {
+      context?: ContextT,
+  ): Promise<TriggerResponse<PayloadT, HostEventT, ContextType>> {
       switch (hostEvent) {
           case HostEvent.Pin:
-              return this.handlePinEvent(payload as HostEventRequest<HostEvent.Pin>) as any;
+              return this.handlePinEvent(payload as HostEventRequest<HostEvent.Pin>, context as ContextType) as any;
           case HostEvent.SaveAnswer:
               return this.handleSaveAnswerEvent(
                   payload as HostEventRequest<HostEvent.SaveAnswer>,
+                  context as ContextType,
               ) as any;
           default:
-              return this.hostEventFallback(hostEvent, payload);
+              return this.hostEventFallback(hostEvent, payload, context);
       }
   }
 }