@thoughtspot/visual-embed-sdk 1.50.0 → 1.51.0

package/src/embed/conversation.ts

@@ -1,8 +1,6 @@
-import isUndefined from 'lodash/isUndefined';
-import { ERROR_MESSAGE } from '../errors';
 import { Param, BaseViewConfig, RuntimeFilter, RuntimeParameter, ErrorDetailsTypes, EmbedErrorCodes, DefaultAppInitData, VisualizationOverrides, SpotterFileUploadFileTypes } from '../types';
 import { TsEmbed } from './ts-embed';
-import { buildSpotterSidebarAppInitData } from './spotter-utils';
+import { buildSpotterSidebarAppInitData, buildSpotterShareConversationAppInitData } from './spotter-utils';
 import { getQueryParamString, getFilterQuery, getRuntimeParameters, setParamIfDefined } from '../utils';
 
 /**
@@ -15,6 +13,47 @@ export interface SearchOptions {
     searchQuery: string;
 }
 
+/**
+ * The query mode Spotter uses when answering a question.
+ * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+ */
+export enum SpotterQueryMode {
+    FAST_SEARCH = 'fastSearch',
+    RESEARCH = 'research',
+}
+
+/**
+ * Configuration for the pin/unpin conversation feature in the Spotter sidebar.
+ * Grouped into one object because pin exposes several related settings
+ * (enable + label overrides), unlike single-item actions like rename or
+ * delete.
+ * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+ */
+export interface SpotterChatPinConfig {
+    /**
+     * Enables the pin/unpin conversation feature in embedded Spotter. Disabled
+     * by default — hosts must opt in. When off, the Pin/Unpin menu entry and
+     * the pin glyph are hidden and the PinSpotterConversation /
+     * UnpinSpotterConversation host events are no-ops. Native (non-embedded)
+     * Spotter is unaffected and ships pin enabled.
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Custom label text for the pin action in the conversation edit menu.
+     * Defaults to translated "Pin" text.
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     */
+    pinLabel?: string;
+    /**
+     * Custom label text for the unpin action in the conversation edit menu.
+     * Defaults to translated "Unpin" text.
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     */
+    unpinLabel?: string;
+}
+
 /**
  * Configuration for the Spotter sidebar.
  * Can be used in SpotterEmbed and AppEmbed.
@@ -52,6 +91,12 @@ export interface SpotterSidebarViewConfig {
      * @version SDK: 1.47.0 | ThoughtSpot: 26.4.0.cl
      */
     spotterChatDeleteLabel?: string;
+    /**
+     * Pin/unpin conversation feature config (enable + label overrides).
+     * Off by default in embed — hosts opt in via `enabled`.
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     */
+    spotterChatPinConfig?: SpotterChatPinConfig;
     /**
      * Custom title text for the delete conversation confirmation modal.
      * Defaults to translated "Delete chat" text.
@@ -103,6 +148,85 @@ export interface SpotterSidebarViewConfig {
     spotterAnalystsLabel?: string;
 }
 
+/**
+ * Configuration for the Spotter conversation sharing feature.
+ * Can be used in SpotterEmbed and AppEmbed.
+ * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+ * @group Embed components
+ */
+export interface SpotterShareConversationConfig {
+    /**
+     * Enables sharing of the conversation.
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @default false
+     */
+    enableShareConversation?: boolean;
+    /**
+     * Header Share button + sidebar Share item label.
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @default "Share"
+     */
+    spotterShareLabel?: string;
+    /**
+     * Share modal title.
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     */
+    spotterShareModalTitle?: string;
+    /**
+     * Modal confirm button label.
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @default "Share"
+     */
+    spotterShareConfirmLabel?: string;
+    /**
+     * Modal cancel button label.
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @default "Cancel"
+     */
+    spotterShareCancelLabel?: string;
+    /**
+     * "Add users or groups" label.
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     */
+    spotterShareAddUsersLabel?: string;
+    /**
+     * Empty-state title ("No users added yet").
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     */
+    spotterShareEmptyTitle?: string;
+    /**
+     * Empty-state subtitle ("Not shared with any user").
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     */
+    spotterShareEmptySubtitle?: string;
+    /**
+     * "Include new messages since last shared version" checkbox label.
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     */
+    spotterShareIncludeNewMessagesLabel?: string;
+    /**
+     * Footer note when the snapshot is current ("…up to the current moment…").
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     */
+    spotterShareUpToCurrentLabel?: string;
+    /**
+     * Stale-snapshot info banner text ("All added users and groups will receive…").
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     */
+    spotterShareStaleInfoLabel?: string;
+    /**
+     * Read-only shared-view data-access banner message.
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     */
+    spotterSharedConversationBannerMessage?: string;
+    /**
+     * Read-only shared-view Exit button label.
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @default "Exit"
+     */
+    spotterSharedConversationExitLabel?: string;
+}
+
 /**
  * Configuration for customizing Spotter chat UI branding.
  * @version SDK: 1.46.0 | ThoughtSpot: 26.4.0.cl
@@ -158,8 +282,27 @@ export interface SpotterEmbedViewConfig extends Omit<BaseViewConfig, 'primaryAct
     /**
      * The ID of the data source object. For example, Model, View, or Table. Spotter uses
      * this object to query data and generate Answers.
+     * This field is optional. If not provided, Spotter loads using the
+     * previously selected user data source.
+     */
+    worksheetId?: string;
+    /**
+     * The array of data source GUIDs to set on load. Spotter uses
+     * these GUIDs to query data and generate Answers.
+     * dataSources is preferred over worksheetId if both are provided.
+     * The feature is currently behind a feature flag.
+     *
+     * Supported embed types: `SpotterEmbed`
+     * @example
+     * ```js
+     * const embed = new SpotterEmbed('#tsEmbed', {
+     *     // ...other embed view config
+     *     dataSources: ['id-2345', 'id-2345'],
+     * });
+     * ```
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
      */
-    worksheetId: string;
+    dataSources?: string[];
     /**
      * Ability to pass a starting search query to the conversation.
      */
@@ -319,6 +462,39 @@ export interface SpotterEmbedViewConfig extends Omit<BaseViewConfig, 'primaryAct
      * ```
      */
     updatedSpotterChatPrompt?: boolean;
+    /**
+     * showSpotterRadiance : Controls the radiance on the Spotter page.
+     *
+     * Supported embed types: `SpotterEmbed`
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @default false
+     * @example
+     * ```js
+     * const embed = new SpotterEmbed('#tsEmbed', {
+     *    ... //other embed view config
+     *    showSpotterRadiance : true,
+     * })
+     * ```
+     */
+    showSpotterRadiance?: boolean;
+    /**
+     * Sets the default query mode when Spotter loads — Fast Search or
+     * Research Mode. Applies fresh on every new session for this embed
+     * instance only; it does not persist as a user preference and does
+     * not affect other embeds or native ThoughtSpot usage.
+     *
+     * Supported embed types: `SpotterEmbed`, `AppEmbed`
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @default SpotterQueryMode.FAST_SEARCH
+     * @example
+     * ```js
+     * const embed = new SpotterEmbed('#tsEmbed', {
+     *    ... //other embed view config
+     *    defaultQueryMode: SpotterQueryMode.RESEARCH,
+     * })
+     * ```
+     */
+    defaultQueryMode?: SpotterQueryMode;
     /**
      * Enables the stop answer generation button in the Spotter embed UI,
      * allowing users to interrupt an ongoing answer generation.
@@ -377,6 +553,59 @@ export interface SpotterEmbedViewConfig extends Omit<BaseViewConfig, 'primaryAct
      * ```
      */
     spotterChatConfig?: SpotterChatViewConfig;
+    /**
+     * Configuration for the Spotter conversation sharing feature.
+     *
+     * Supported embed types: `SpotterEmbed`, `AppEmbed`
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @example
+     * ```js
+     * const embed = new SpotterEmbed('#tsEmbed', {
+     *    ... //other embed view config
+     *    spotterShareConversationConfig: {
+     *        enableShareConversation: true,
+     *    },
+     * })
+     * ```
+     */
+    spotterShareConversationConfig?: SpotterShareConversationConfig;
+    /**
+     * The ID of a shared Spotter conversation to open directly in the read-only
+     * reader view. Use this to land a share recipient in the shared conversation
+     * when they open a host-configured `CONVERSATION_URL` share link: read the
+     * `{conversation-id}` from your page URL and pass it here.
+     *
+     * Requires the Spotter conversation-sharing feature to be enabled
+     * (`spotterShareConversationConfig.enableShareConversation`). The recipient
+     * must be an authorized sharee — the server returns access-denied otherwise.
+     *
+     * Supported embed types: `SpotterEmbed`
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @example
+     * ```js
+     * const convId = new URLSearchParams(window.location.search).get('conversation-id');
+     * const embed = new SpotterEmbed('#tsEmbed', {
+     *    ... //other embed view config
+     *    sharedConversationId: convId,
+     * })
+     * ```
+     */
+    sharedConversationId?: string;
+    /**
+     * updatedSpotterExperience : Controls the updated Spotter experience.
+     *
+     * Supported embed types: `SpotterEmbed`
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @default false
+     * @example
+     * ```js
+     * const embed = new SpotterEmbed('#tsEmbed', {
+     *    ... //other embed view config
+     *    updatedSpotterExperience : true,
+     * })
+     * ```
+     */
+    updatedSpotterExperience?: boolean;
 }
 
 /**
@@ -395,6 +624,7 @@ export interface ConversationViewConfig extends SpotterEmbedViewConfig {}
 export interface SpotterAppInitData extends DefaultAppInitData {
     embedParams?: {
         spotterSidebarConfig?: SpotterSidebarViewConfig;
+        spotterShareConversationConfig?: SpotterShareConversationConfig;
         visualOverridesParams?: VisualizationOverrides | null;
     };
 }
@@ -439,16 +669,21 @@ export class SpotterEmbed extends TsEmbed {
      */
     protected async getAppInitData(): Promise<SpotterAppInitData> {
         const defaultAppInitData = await super.getAppInitData();
-        return buildSpotterSidebarAppInitData(defaultAppInitData, this.viewConfig, this.handleError.bind(this));
+        const sidebarInitData = buildSpotterSidebarAppInitData(
+            defaultAppInitData,
+            this.viewConfig,
+            this.handleError.bind(this),
+        );
+        return buildSpotterShareConversationAppInitData(sidebarInitData, this.viewConfig);
     }
 
     protected getEmbedParamsObject() {
         const {
-            worksheetId,
             searchOptions,
             disableSourceSelection,
             hideSourceSelection,
             dataPanelV2,
+            updatedSpotterExperience,
             showSpotterLimitations,
             hideSampleQuestions,
             runtimeFilters,
@@ -456,18 +691,12 @@ export class SpotterEmbed extends TsEmbed {
             runtimeParameters,
             excludeRuntimeParametersfromURL,
             updatedSpotterChatPrompt,
+            showSpotterRadiance,
+            defaultQueryMode,
             enableStopAnswerGenerationEmbed,
             spotterChatConfig,
         } = this.viewConfig;
 
-        if (!worksheetId) {
-            this.handleError({
-                errorType: ErrorDetailsTypes.VALIDATION_ERROR,
-                message: ERROR_MESSAGE.SPOTTER_EMBED_WORKSHEED_ID_NOT_FOUND,
-                code: EmbedErrorCodes.WORKSHEET_ID_NOT_FOUND,
-                error: ERROR_MESSAGE.SPOTTER_EMBED_WORKSHEED_ID_NOT_FOUND,
-            });
-        }
         const queryParams = this.getBaseQueryParams();
         queryParams[Param.SpotterEnabled] = true;
 
@@ -478,6 +707,8 @@ export class SpotterEmbed extends TsEmbed {
         setParamIfDefined(queryParams, Param.ShowSpotterLimitations, showSpotterLimitations, true);
         setParamIfDefined(queryParams, Param.HideSampleQuestions, hideSampleQuestions, true);
         setParamIfDefined(queryParams, Param.UpdatedSpotterChatPrompt, updatedSpotterChatPrompt, true);
+        setParamIfDefined(queryParams, Param.ShowSpotterRadiance, showSpotterRadiance, true);
+        setParamIfDefined(queryParams, Param.DefaultQueryMode, defaultQueryMode);
         setParamIfDefined(queryParams, Param.EnableStopAnswerGenerationEmbed, enableStopAnswerGenerationEmbed, true);
 
         // Handle spotterChatConfig params
@@ -499,6 +730,8 @@ export class SpotterEmbed extends TsEmbed {
             }
         }
 
+        setParamIfDefined(queryParams, Param.UpdatedSpotterExperience, updatedSpotterExperience, true);
+
         return queryParams;
     }
 
@@ -510,8 +743,16 @@ export class SpotterEmbed extends TsEmbed {
             excludeRuntimeFiltersfromURL,
             runtimeParameters,
             excludeRuntimeParametersfromURL,
+            sharedConversationId,
+            dataSources,
         } = this.viewConfig;
-        const path = 'insights/conv-assist';
+        // Deep-link into the read-only shared-conversation reader view when a
+        // shared conversation id is supplied (e.g. a recipient landing from a
+        // host-configured CONVERSATION_URL share link); otherwise the normal
+        // Spotter conversation surface.
+        const path = sharedConversationId
+            ? `insights/conv-assist/s/${encodeURIComponent(sharedConversationId)}`
+            : 'insights/conv-assist';
         const queryParams = this.getEmbedParamsObject();
 
         let query = '';
@@ -531,8 +772,12 @@ export class SpotterEmbed extends TsEmbed {
         }
 
         const tsPostHashParams = this.getThoughtSpotPostUrlParams({
-            worksheet: worksheetId,
-            query: searchOptions?.searchQuery || '',
+            ...(!(Array.isArray(dataSources) && dataSources.length > 0) && worksheetId
+                && { worksheet: worksheetId }),
+            ...(searchOptions?.searchQuery && { query: searchOptions.searchQuery }),
+            ...(Array.isArray(dataSources)
+                && dataSources.length > 0
+                && { dataSources: JSON.stringify(dataSources) }),
         });
         return `${this.getEmbedBasePath(query)}/embed/${path}${tsPostHashParams}`;
     }