@thoughtspot/visual-embed-sdk 1.50.0 → 1.51.0-test

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, buildStarterPromptsAppInitData } 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,170 @@ 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;
+}
+
+/**
+ * A single starter prompt question shown under a category pill.
+ * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+ * @group Embed components
+ */
+export interface StarterPromptQuestion {
+    /**
+     * Short label shown as a clickable suggestion. Falls back to `prompt` when
+     * omitted. ThoughtSpot truncates it beyond 80 characters.
+     */
+    label?: string;
+    /**
+     * Prompt text sent to Spotter on click. ThoughtSpot truncates it beyond
+     * 300 characters.
+     */
+    prompt: string;
+}
+
+/**
+ * Configuration for a starter prompt category with questions
+ * (`quick` and `research`).
+ * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+ * @group Embed components
+ */
+export interface StarterPromptCategory {
+    /**
+     * Overrides the default category pill label. ThoughtSpot truncates it
+     * beyond 30 characters.
+     */
+    label?: string;
+    /**
+     * Replaces the backend-generated prompts. ThoughtSpot renders the first 4
+     * and drops any entry without a `prompt`.
+     */
+    questions?: StarterPromptQuestion[];
+}
+
+/**
+ * Configuration for the Data Literacy starter prompt category.
+ * Only the label is customizable; the prompt text comes from the backend.
+ * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+ * @group Embed components
+ */
+export interface StarterPreviewDataCategory {
+    /**
+     * Overrides the default category pill label. ThoughtSpot truncates it
+     * beyond 30 characters.
+     */
+    label?: string;
+}
+
+/**
+ * Content configuration for the Spotter starter prompts.
+ * Keys are fixed: `quick` (Basic Search), `research` (Deep Analysis),
+ * `previewData` (Data Literacy) and `liveboard` (Liveboard chat panel).
+ *
+ * Note: this controls the Spotter chat interface only. The starter prompts on
+ * the Liveboard SpotterViz surface are configured separately through
+ * {@link SpotterVizConfig.customStarterPrompts}.
+ * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+ * @group Embed components
+ */
+export interface StarterPromptsConfig {
+    /**
+     * Turns the starter prompts surface on. Must be set explicitly, an
+     * unset flag leaves the surface off.
+     *
+     * Either this or `enableStarterPrompts` turns the surface on, so `false`
+     * here does not switch it off while `enableStarterPrompts` is `true`.
+     * @default false
+     */
+    enable?: boolean;
+    /** Basic Search category configuration. */
+    quick?: StarterPromptCategory;
+    /** Deep Analysis category configuration. */
+    research?: StarterPromptCategory;
+    /** Data Literacy category configuration. */
+    previewData?: StarterPreviewDataCategory;
+    /**
+     * Starter prompts for the Spotter chat panel on a Liveboard.
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     */
+    liveboard?: StarterPromptQuestion[];
+}
+
 /**
  * Configuration for customizing Spotter chat UI branding.
  * @version SDK: 1.46.0 | ThoughtSpot: 26.4.0.cl
@@ -143,11 +352,84 @@ export interface SpotterChatViewConfig {
     /**
      * Enables starter prompts in the Spotter chat interface.
      *
-     * Supported embed types: SpotterEmbed, LiveboardEmbed, AppEmbed
+     * Either this or `starterPrompts.enable` turns the surface on, so it stays
+     * on while this is `true` even if `starterPrompts.enable` is `false`.
+     *
+     * Supported embed types: `SpotterEmbed`, `LiveboardEmbed`, `AppEmbed`
      * @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl
      * @default false
      */
     enableStarterPrompts?: boolean;
+    /**
+     * Customizes the labels and questions of the Spotter starter prompts.
+     * Individual pills are hidden or shown with `hiddenActions` /
+     * `visibleActions` using `Action.QuickSearchPill`,
+     * `Action.DeepAnalysisPill` and `Action.DataLiteracyPill`.
+     *
+     * Supported embed types: `SpotterEmbed`, `LiveboardEmbed`, `AppEmbed`
+     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @example
+     * ```js
+     * const embed = new SpotterEmbed('#tsEmbed', {
+     *    worksheetId: 'worksheet-id',
+     *    hiddenActions: [Action.DeepAnalysisPill],
+     *    spotterChatConfig: {
+     *        starterPrompts: {
+     *            enable: true,
+     *            quick: {
+     *                label: 'Quick questions',
+     *                questions: [
+     *                    { label: 'Top products', prompt: 'What are the top products by revenue?' },
+     *                ],
+     *            },
+     *            previewData: { label: 'Explore your data' },
+     *        },
+     *    },
+     * })
+     * ```
+     */
+    starterPrompts?: StarterPromptsConfig;
+    /**
+     * Opens the Spotter chat panel when the Liveboard loads.
+     *
+     * Supported embed types: `LiveboardEmbed`, `AppEmbed`
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     * @default true
+     * @example
+     * ```js
+     * const embed = new LiveboardEmbed('#tsEmbed', {
+     *    liveboardId: 'liveboard-id',
+     *    spotterChatConfig: {
+     *        openSpotterOnLiveboardByDefault: false,
+     *    },
+     * })
+     * ```
+     */
+    openSpotterOnLiveboardByDefault?: boolean;
+}
+
+/**
+ * Configuration for the Spotter Analyst experience.
+ * Can be used in SpotterEmbed.
+ * @group Embed components
+ * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+ * @example
+ * ```js
+ * const embed = new SpotterEmbed('#tsEmbed', {
+ *    ... //other embed view config
+ *    spotterAnalystConfig: {
+ *        analystId: 'analyst-id-1234',
+ *    },
+ * })
+ * ```
+ */
+export interface SpotterAnalystConfig {
+    /**
+     * Pins the embed to a single spotter analyst. Implies no default Spotter
+     * and no "Show all".
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     */
+    analystId?: string;
 }
 
 /**
@@ -158,8 +440,43 @@ 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;
+    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
+     */
+    dataSources?: string[];
+    /**
+     * Configuration for the Spotter Analyst experience.
+     *
+     * Supported embed types: `SpotterEmbed`
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     * @example
+     * ```js
+     * const embed = new SpotterEmbed('#tsEmbed', {
+     *    ... //other embed view config
+     *    spotterAnalystConfig: {
+     *        analystId: 'analyst-id-1234',
+     *    },
+     * })
+     * ```
+     */
+    spotterAnalystConfig?: SpotterAnalystConfig;
     /**
      * Ability to pass a starting search query to the conversation.
      */
@@ -319,6 +636,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 +727,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,7 +798,9 @@ export interface ConversationViewConfig extends SpotterEmbedViewConfig {}
 export interface SpotterAppInitData extends DefaultAppInitData {
     embedParams?: {
         spotterSidebarConfig?: SpotterSidebarViewConfig;
+        spotterShareConversationConfig?: SpotterShareConversationConfig;
         visualOverridesParams?: VisualizationOverrides | null;
+        starterPrompts?: StarterPromptsConfig;
     };
 }
 
@@ -439,16 +844,22 @@ 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),
+        );
+        const shareInitData = buildSpotterShareConversationAppInitData(sidebarInitData, this.viewConfig);
+        return buildStarterPromptsAppInitData(shareInitData, this.viewConfig);
     }
 
     protected getEmbedParamsObject() {
         const {
-            worksheetId,
             searchOptions,
             disableSourceSelection,
             hideSourceSelection,
             dataPanelV2,
+            updatedSpotterExperience,
             showSpotterLimitations,
             hideSampleQuestions,
             runtimeFilters,
@@ -456,18 +867,13 @@ export class SpotterEmbed extends TsEmbed {
             runtimeParameters,
             excludeRuntimeParametersfromURL,
             updatedSpotterChatPrompt,
+            showSpotterRadiance,
+            defaultQueryMode,
             enableStopAnswerGenerationEmbed,
             spotterChatConfig,
+            spotterAnalystConfig,
         } = 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,7 +884,10 @@ 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);
+        setParamIfDefined(queryParams, Param.AnalystId, spotterAnalystConfig?.analystId);
 
         // Handle spotterChatConfig params
         if (spotterChatConfig) {
@@ -499,6 +908,8 @@ export class SpotterEmbed extends TsEmbed {
             }
         }
 
+        setParamIfDefined(queryParams, Param.UpdatedSpotterExperience, updatedSpotterExperience, true);
+
         return queryParams;
     }
 
@@ -510,8 +921,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 +950,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}`;
     }