@thoughtspot/visual-embed-sdk 1.47.3 → 1.49.0

package/lib/src/types.d.ts

@@ -888,9 +888,10 @@ export interface BaseViewConfig extends ApiInterceptFlags {
     styleSheet__unstable?: string;
     /**
      * The list of actions to disable from the primary menu, more menu
-     * (...), and the contextual menu. These actions will be disabled
-     * for the user.
-     * Use this to disable actions.
+     * (...), and the contextual menu. Disabled actions are grayed out
+     * and still visible to the user, but cannot be clicked.
+     * Use this when you want to disable an action (keep it visible but non-interactive).
+     * To completely remove an action from the UI, use {@link hiddenActions} instead.
      *
      * Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
      * @version SDK: 1.6.0 | ThoughtSpot: ts8.nov.cl, 8.4.1.sw
@@ -921,9 +922,10 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      */
     disabledActionReason?: string;
     /**
-     * The list of actions to hide from the embedded view.
-     * These actions will be hidden from the user.
-     * Use this to hide an action.
+     * The list of actions to completely remove from the embedded view.
+     * Hidden actions are not visible to the user at all (fully removed from the UI).
+     * Use this when you want to remove an action entirely.
+     * To keep an action visible but non-interactive (grayed out), use {@link disabledActions} instead.
      *
      * Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
      * @version SDK: 1.6.0 | ThoughtSpot: ts8.nov.cl, 8.4.1.sw
@@ -942,9 +944,8 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      * The list of actions to display from the primary menu, more menu
      * (...), and the contextual menu. These will be only actions that
      * are visible to the user.
-     * Use this to hide all actions except the ones you want to show.
-     *
-     * Use either this or hiddenActions.
+     * Use this as an allowlist — only the actions listed here will be shown.
+     * All other actions will be hidden. Use either this or {@link hiddenActions}, not both.
      *
      * Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
      * @version SDK: 1.6.0 | ThoughtSpot: ts8.nov.cl, 8.4.1.sw
@@ -1101,6 +1102,14 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      * This flag can be used to disable links inside the embedded app,
      * and disable redirection of links in a new tab.
      *
+     * Note: When set to `true`, this flag automatically disables
+     * {@link enableLinkOverridesV2} for the
+     * embed session. The two features are mutually exclusive — link
+     * overrides mutate anchors (delete `href`, attach a JS click handler),
+     * which breaks native browser behavior (Cmd/Ctrl+Click, middle-click,
+     * right-click "Open in new tab") when combined with the disable flag.
+     * The disable flag preserves native anchor semantics instead.
+     *
      * Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
      * @version SDK: 1.32.1 | ThoughtSpot: 10.3.0.cl
      * @example
@@ -1136,8 +1145,13 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      * Flag to override the *Open Link in New Tab* context
      * menu option.
      *
-     * For improved link override handling, use
-     * {@link enableLinkOverridesV2} instead.
+     * Note: Setting this flag implicitly enables
+     * {@link enableLinkOverridesV2}. V1 is auto-upgraded to
+     * V2 to ensure consistent link-override behavior; the
+     * legacy V1-only path is no longer used in isolation.
+     *
+     * Note: This flag is ignored when
+     * {@link disableRedirectionLinksInNewTab} is `true`.
      *
      * Supported embed types: `AppEmbed`, `LiveboardEmbed`,
      * `SearchEmbed`, `SpotterAgentEmbed`,
@@ -1163,6 +1177,9 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      * alongside this flag for backward compatibility with
      * older ThoughtSpot versions.
      *
+     * Note: This flag is ignored when
+     * {@link disableRedirectionLinksInNewTab} is `true`.
+     *
      * Supported embed types: `AppEmbed`, `LiveboardEmbed`,
      * `SearchEmbed`, `SpotterAgentEmbed`,
      * `SpotterEmbed`, `SearchBarEmbed`
@@ -1398,6 +1415,7 @@ export interface BaseViewConfig extends ApiInterceptFlags {
     /**
      * Refresh the auth token when the token is near expiry.
      * @version SDK: 1.45.2 | ThoughtSpot: 26.3.0.cl
+     * @default true
      * @example
      * ```js
      * const embed = new AppEmbed('#tsEmbed', {
@@ -1434,8 +1452,21 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      */
     useHostEventsV2?: boolean;
 }
-export interface AutoMCPFrameRendererViewConfig extends BaseViewConfig {
-}
+/**
+ * Configuration for {@link startAutoMCPFrameRenderer}.
+ *
+ * Extends {@link BaseViewConfig} but omits params that are not applicable
+ * to the auto-frame renderer:
+ * - `preRenderId` / `usePrerenderedIfAvailable` / `doNotTrackPreRenderSize` —
+ *   the renderer always replaces a live iframe in-place; prerender pools are not used.
+ * - `insertAsSibling` — insertion is always a same-position `replaceWith`; the
+ *   container-append path is never taken.
+ * - `primaryAction` — a Liveboard/AppEmbed-specific feature; the renderer renders
+ *   whatever route the MCP server specifies.
+ * - `enableV2Shell_experimental` — the renderer always uses the v2 URL format;
+ *   this flag has no effect.
+ */
+export type AutoMCPFrameRendererViewConfig = Omit<BaseViewConfig, 'preRenderId' | 'usePrerenderedIfAvailable' | 'doNotTrackPreRenderSize' | 'insertAsSibling' | 'primaryAction' | 'enableV2Shell_experimental'>;
 /**
  * The configuration object for Home page embeds configs.
  */
@@ -2395,38 +2426,54 @@ export declare enum EmbedEvent {
      */
     VizPointClick = "vizPointClick",
     /**
-     * An error has occurred. This event is fired for the following error types:
+     * Fired when an error occurs in the embedded component.
      *
+     * **Important:** This event fires for many reasons — including internal
+     * validation warnings (e.g. `HOST_EVENT_VALIDATION`), configuration issues,
+     * and transient errors that ThoughtSpot already handles gracefully inside the
+     * iframe. **Do not call `embed.destroy()` or unmount the embed component on
+     * every error.** Doing so will tear down the iframe and abort all in-flight
+     * requests, causing the embed to fail entirely.
+     *
+     * Only treat the following codes as unrecoverable:
+     * - `INIT_ERROR` — SDK was not initialised before render
+     * - `LOGIN_FAILED` — authentication could not be completed
+     *
+     * All other error codes should be logged and inspected, not acted upon
+     * destructively.
+     *
+     * **Note:** There is currently no dedicated event for a true unrecoverable
+     * crash. A future `EmbedEvent.FatalError` event is planned to give customers
+     * a clean signal for when the embed cannot recover and needs to be torn down.
+     *
+     * Error types include:
      * `API` - API call failure.
-     * `FULLSCREEN` - Error when presenting a Liveboard or visualization in full screen
-     * mode. `SINGLE_VALUE_FILTER` - Error due to multiple values in the single value
-     * filter. `NON_EXIST_FILTER` - Error due to a non-existent filter.
-     * `INVALID_DATE_VALUE` - Invalid date value error.
-     * `INVALID_OPERATOR` - Use of invalid operator during filter application.
+     * `FULLSCREEN` - Error when presenting a Liveboard in full screen mode.
+     * `VALIDATION_ERROR` - Internal host event or configuration validation warning.
      *
      * For more information, see https://developers.thoughtspot.com/docs/events-app-integration#errorType
      * @returns error - An error object or message
      * @version SDK: 1.1.0 | ThoughtSpot: ts7.may.cl, 8.4.1.sw
      * @example
      * ```js
-     * // API error
-     * SearchEmbed.on(EmbedEvent.Error, (error) => {
-     *   console.log(error);
-     *  // { type: "Error", data: { errorType: "API", error: { message: '...', error: '...' } } }
-     *  // { errorType: "API", message: '...', code: '...' } new format
+     * // Recommended pattern — only destroy on truly fatal errors
+     * embed.on(EmbedEvent.Error, (error) => {
+     *   const FATAL_CODES = ['INIT_ERROR', 'LOGIN_FAILED'];
+     *   if (FATAL_CODES.includes(error.data?.code)) {
+     *     embed.destroy();
+     *     return;
+     *   }
+     *   // Log all other errors — do not destroy
+     *   console.warn('Embed error (non-fatal):', error);
      * });
      * ```
      * @example
      * ```js
-     * // Fullscreen error (Errors during presenting of a liveboard)
-     * LiveboardEmbed.on(EmbedEvent.Error, (error) => {
+     * // API error
+     * SearchEmbed.on(EmbedEvent.Error, (error) => {
      *   console.log(error);
-     *   // { type: "Error", data: { errorType: "FULLSCREEN", error: {
-     *   //   message: "Fullscreen API is not enabled",
-     *   //   stack: "..."
-     *   // } }}
-     *   // { errorType: "FULLSCREEN", message: "Fullscreen API is not enabled", code: '...' } new format
-     * })
+     *   // { errorType: "API", message: '...', code: '...' }
+     * });
      * ```
      */
     Error = "Error",
@@ -3627,7 +3674,103 @@ export declare enum EmbedEvent {
      * ```
      * @version SDK: 1.48.0 | ThoughtSpot Cloud: 26.5.0.cl
      */
-    SendTestScheduleEmail = "sendTestScheduleEmail"
+    SendTestScheduleEmail = "sendTestScheduleEmail",
+    /**
+     * Emitted when the SpotterViz panel mounts in embed mode.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * liveboardEmbed.on(EmbedEvent.SpotterVizInit, (payload) => {
+     *     console.log('SpotterViz initialized', payload);
+     *     // payload: { liveboardId: string }
+     * })
+     * ```
+     */
+    SpotterVizInit = "SpotterVizInit",
+    /**
+     * Emitted when the user submits a prompt in the SpotterViz panel.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * liveboardEmbed.on(EmbedEvent.SpotterVizQueryTriggered, (payload) => {
+     *     console.log('SpotterViz query triggered', payload);
+     *     // payload: { query: string, sessionId: string }
+     * })
+     * ```
+     */
+    SpotterVizQueryTriggered = "SpotterVizQueryTriggered",
+    /**
+     * Emitted when the SpotterViz agent finishes responding.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * liveboardEmbed.on(EmbedEvent.SpotterVizResponseComplete, (payload) => {
+     *     console.log('SpotterViz response complete', payload);
+     *     // payload: { sessionId: string, messageId: string }
+     * })
+     * ```
+     */
+    SpotterVizResponseComplete = "SpotterVizResponseComplete",
+    /**
+     * Emitted when a checkpoint is created in the SpotterViz panel.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * liveboardEmbed.on(EmbedEvent.SpotterVizCheckpointCreated, (payload) => {
+     *     console.log('SpotterViz checkpoint created', payload);
+     *     // payload: { checkpointId: string, source: string, label: string }
+     * })
+     * ```
+     */
+    SpotterVizCheckpointCreated = "SpotterVizCheckpointCreated",
+    /**
+     * Emitted when a checkpoint is restored in the SpotterViz panel.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * liveboardEmbed.on(EmbedEvent.SpotterVizCheckpointRestored, (payload) => {
+     *     console.log('SpotterViz checkpoint restored', payload);
+     *     // payload: { checkpointId: string, newGenNumber: number }
+     * })
+     * ```
+     */
+    SpotterVizCheckpointRestored = "SpotterVizCheckpointRestored",
+    /**
+     * Emitted when an error occurs in the SpotterViz panel.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * liveboardEmbed.on(EmbedEvent.SpotterVizError, (payload) => {
+     *     console.log('SpotterViz error', payload);
+     * })
+     * ```
+     */
+    SpotterVizError = "SpotterVizError",
+    /**
+     * Emitted when the SpotterViz panel is closed.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * liveboardEmbed.on(EmbedEvent.SpotterVizClosed, (payload) => {
+     *     console.log('SpotterViz panel closed', payload);
+     * })
+     * ```
+     */
+    SpotterVizClosed = "SpotterVizClosed",
+    /**
+     * Emitted when a user clicks the **Refresh** button in the
+     * Liveboard header. Requires `enableLiveboardDataCache`
+     * to be enabled.
+     * @example
+     * ```js
+     * liveboardEmbed.on(EmbedEvent.RefreshLiveboardBrowserCache, (payload) => {
+     *     console.log('Liveboard browser cache refreshed', payload);
+     *     // payload: { liveboardId: string }
+     * })
+     * ```
+     * @version SDK: 1.49.0 | ThoughtSpot Cloud: 26.6.0.cl
+     */
+    RefreshLiveboardBrowserCache = "refreshLiveboardBrowserCache"
 }
 /**
  * Event types that can be triggered by the host application
@@ -5697,7 +5840,38 @@ export declare enum HostEvent {
      * ```
      * @version SDK: 1.48.0 | ThoughtSpot Cloud: 26.5.0.cl
      */
-    SendTestScheduleEmail = "sendTestScheduleEmail"
+    SendTestScheduleEmail = "sendTestScheduleEmail",
+    /**
+     * Sends a user message (prompt) to the SpotterViz panel programmatically.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @param query - the prompt text to send.
+     * @example
+     * ```js
+     * liveboardEmbed.trigger(HostEvent.SpotterVizSendUserMessage, {
+     *     query: 'Show me revenue by region',
+     * });
+     * ```
+     */
+    SpotterVizSendUserMessage = "SpotterVizSendUserMessage",
+    /**
+     * Initializes a new SpotterViz conversation.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * liveboardEmbed.trigger(HostEvent.InitSpotterVizConversation);
+     * ```
+     */
+    InitSpotterVizConversation = "InitSpotterVizConversation",
+    /**
+     * Clears browser cache and fetches new data for liveboard ChartViz Containers.
+     * Requires `enableLiveboardDataCache` to be enabled.
+     * @example
+     * ```js
+     * liveboardEmbed.trigger(HostEvent.RefreshLiveboardBrowserCache);
+     * ```
+     * @version SDK: 1.49.0 | ThoughtSpot Cloud: 26.6.0.cl
+     */
+    RefreshLiveboardBrowserCache = "refreshLiveboardBrowserCache"
 }
 /**
  * The different visual modes that the data sources panel within
@@ -5736,6 +5910,7 @@ export declare enum Param {
     HostAppUrl = "hostAppUrl",
     EnableVizTransformations = "enableVizTransform",
     EnableSearchAssist = "enableSearchAssist",
+    EnableConnectionNewExperience = "newConnectionsExperience",
     EnablePendoHelp = "enablePendoHelp",
     HideResult = "hideResult",
     UseLastSelectedDataSource = "useLastSelectedSources",
@@ -5865,15 +6040,28 @@ export declare enum Param {
     HideToolResponseCardBranding = "hideToolResponseCardBranding",
     ToolResponseCardBrandingLabel = "toolResponseCardBrandingLabel",
     EnableHomepageAnnouncement = "enableHomepageAnnouncement",
-    EnableLiveboardDataCache = "enableLiveboardDataCache"
+    EnableLiveboardDataCache = "enableLiveboardDataCache",
+    SpotterFileUploadEnabled = "spotterFileUploadEnabled",
+    SpotterFileUploadFileTypes = "spotterFileUploadFileTypes"
 }
+/**
+ * Configuration for allowed file types in Spotter file upload.
+ * @group Embed components
+ */
+export type SpotterFileUploadFileTypes = {
+    types?: string[];
+};
 /**
  * ThoughtSpot application pages include actions and menu commands
  * for various user-initiated operations. These actions are represented
- * as enumeration members in the SDK. To show, hide, or disable
- * specific actions in the embedded view, define the Action
- * enumeration members in the `disabledActions`, `visibleActions`,
- * or `hiddenActions` array.
+ * as enumeration members in the SDK. To control actions in the embedded view:
+ * - disabledActions — the action is grayed out and still visible, but non-interactive (user can see but not click).
+ * - hiddenActions — the action is completely removed from the UI (user cannot see it at all).
+ * - visibleActions — allowlist, only these actions are shown; all others are hidden.
+ *
+ * Use disabledActions to disable (gray out) an action.
+ * Use hiddenActions to hide (fully remove) an action.
+ * Use visibleActions to show only specific actions.
  * @example
  * ```js
  * const embed = new LiveboardEmbed('#tsEmbed', {
@@ -6199,6 +6387,20 @@ export declare enum Action {
      * @version SDK: 1.48.0 | ThoughtSpot: 26.5.0.cl
      */
     DownloadLiveboardAsContinuousPDF = "downloadLiveboardAsContinuousPDF",
+    /**
+     * The Download Liveboard as A4 PDF menu action on a Liveboard.
+     * Allows downloading the entire Liveboard as an A4 PDF.
+     * Requires {@link Action.DownloadLiveboard} as a parent action when
+     * {@link LiveboardViewConfig.isLiveboardXLSXCSVDownloadEnabled} or
+     * {@link LiveboardViewConfig.isContinuousLiveboardPDFEnabled} flags are enabled.
+     * Use this instead of {@link Action.DownloadAsPdf} when either flag is on.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * disabledActions: [Action.DownloadLiveboardAsA4Pdf]
+     * ```
+     */
+    DownloadLiveboardAsA4Pdf = "downloadLiveboardAsA4Pdf",
     /**
      * The **Download Liveboard as XLSX** menu action on a Liveboard.
      * Allows downloading the entire Liveboard as an XLSX file.
@@ -6720,6 +6922,26 @@ export declare enum Action {
      * @version SDK: 1.21.0 | ThoughtSpot: 9.2.0.cl, 9.5.1.sw
      */
     AxisMenuRemove = "axisMenuRemove",
+    /**
+     * The **Compare with** action in the chart axis customization menu.
+     * Allows comparing data across dimensions or measures.
+     * @example
+     * ```js
+     * disabledActions: [Action.AxisMenuCompare]
+     * ```
+     * @version SDK: 1.50.0 | ThoughtSpot: 26.7.0.cl
+     */
+    AxisMenuCompare = "axisMenuCompare",
+    /**
+     * The **Merge with** action in the chart axis customization menu.
+     * Allows merging data across dimensions or measures.
+     * @example
+     * ```js
+     * disabledActions: [Action.AxisMenuMerge]
+     * ```
+     * @version SDK: 1.50.0 | ThoughtSpot: 26.7.0.cl
+     */
+    AxisMenuMerge = "axisMenuMerge",
     /**
      * @hidden
      */
@@ -7490,7 +7712,51 @@ export declare enum Action {
      * ```
      * @version SDK: 1.48.0 | ThoughtSpot Cloud: 26.5.0.cl
      */
-    SendTestScheduleEmail = "sendTestScheduleEmail"
+    SendTestScheduleEmail = "sendTestScheduleEmail",
+    /**
+     * The thumbs up/down feedback buttons in the SpotterViz panel.
+     * Visible by default.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * hiddenActions: [Action.SpotterVizFeedback]
+     * disabledActions: [Action.SpotterVizFeedback]
+     * ```
+     */
+    SpotterVizFeedback = "spotterVizFeedback",
+    /**
+     * The version restore button on checkpoint cards in the SpotterViz panel.
+     * Visible by default.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * hiddenActions: [Action.SpotterVizCheckpointRestore]
+     * disabledActions: [Action.SpotterVizCheckpointRestore]
+     * ```
+     */
+    SpotterVizCheckpointRestore = "spotterVizCheckpointRestore",
+    /**
+     * The **SpotterViz** button in the top edit header.
+     * Visible by default.
+     * @version SDK: 1.50.0 | ThoughtSpot Cloud: 26.7.0.cl
+     * @example
+     * ```js
+     * hiddenActions: [Action.SpotterViz]
+     * disabledActions: [Action.SpotterViz]
+     * ```
+     */
+    SpotterViz = "spotterViz",
+    /**
+     * Clears browser cache and fetches new data for liveboard ChartViz Containers.
+     * Requires `enableLiveboardDataCache` to be enabled.
+     * @example
+     * ```js
+     * disabledActions: [Action.RefreshLiveboardBrowserCache]
+     * hiddenActions: [Action.RefreshLiveboardBrowserCache]
+     * ```
+     * @version SDK: 1.49.0 | ThoughtSpot Cloud: 26.6.0.cl
+     */
+    RefreshLiveboardBrowserCache = "refreshLiveboardBrowserCache"
 }
 export interface AnswerServiceType {
     getAnswer?: (offset: number, batchSize: number) => any;
@@ -7945,6 +8211,9 @@ export interface DefaultAppInitData {
     customActions: CustomAction[];
     interceptTimeout: number | undefined;
     interceptUrls: (string | InterceptedApiType)[];
+    embedExpiryInAuthToken: boolean;
+    shouldBypassPayloadValidation?: boolean;
+    useHostEventsV2?: boolean;
 }
 /**
  * Enum for the type of API intercepted