@thoughtspot/visual-embed-sdk
Version:
ThoughtSpot Embed SDK
1,392 lines (1,354 loc) • 288 kB
text/typescript
/**
* Copyright (c) 2023
*
* TypeScript type definitions for ThoughtSpot Visual Embed SDK
* @summary Type definitions for Embed SDK
* @author Ayon Ghosh <ayon.ghosh@thoughtspot.com>
*/
import { CustomCssVariables } from './css-variables';
import type { SessionInterface } from './utils/graphql/answerService/answerService';
/**
* The authentication mechanism for allowing access to
* the embedded app
* @group Authentication / Init
*/
export enum AuthType {
/**
* No authentication on the SDK. Pass-through to the embedded App. Alias for
* `Passthrough`.
* @example
* ```js
* init({
* // ...
* authType: AuthType.None,
* });
* ```
*/
None = 'None',
/**
* Passthrough SSO to the embedded application within the iframe. Requires least
* configuration, but may not be supported by all IDPs. This will behave like `None`
* if SSO is not configured on ThoughtSpot.
*
* To use this:
* Your SAML or OpenID provider must allow iframe redirects.
* For example, if you are using Okta as IdP, you can enable iframe embedding.
* @version SDK: 1.15.0 | ThoughtSpot: 8.8.0.cl
* @example
* ```js
* init({
* // ...
* authType: AuthType.EmbeddedSSO,
* });
* ```
*/
EmbeddedSSO = 'EmbeddedSSO',
/**
* SSO using SAML, Use {@link SAMLRedirect} instead
* @deprecated This option is deprecated.
* @hidden
*/
SSO = 'SSO_SAML',
/**
* SSO using SAML, Use {@link SAMLRedirect} instead
* @deprecated This option is deprecated.
* @hidden
*/
// eslint-disable-next-line @typescript-eslint/no-duplicate-enum-values
SAML = 'SSO_SAML',
/**
* SSO using SAML
* Makes the host application redirect to the SAML IdP. Use this
* if your IdP does not allow itself to be embedded.
*
* This redirects the host application to the SAML IdP. The host application
* will be redirected back to the ThoughtSpot app after authentication.
* @example
* ```js
* init({
* // ...
* authType: AuthType.SAMLRedirect,
* });
* ```
*
* This opens the SAML IdP in a popup window. The popup is triggered
* when the user clicks the trigger button. The popup window will be
* closed automatically after authentication.
* @example
* ```js
* init({
* // ...
* authType: AuthType.SAMLRedirect,
* authTriggerText: 'Login with SAML',
* authTriggerContainer: '#tsEmbed',
* inPopup: true,
* });
* ```
*
* Can also use the event to trigger the popup flow. Works the same
* as the above example.
* @example
* ```js
* const authEE = init({
* // ...
* authType: AuthType.SAMLRedirect,
* inPopup: true,
* });
*
* someButtonOnYourPage.addEventListener('click', () => {
* authEE.emit(AuthEvent.TRIGGER_SSO_POPUP);
* });
* ```
*/
// eslint-disable-next-line @typescript-eslint/no-duplicate-enum-values
SAMLRedirect = 'SSO_SAML',
/**
* SSO using OIDC
* SSO using OIDC, Use {@link OIDCRedirect} instead
* @deprecated This option is deprecated.
* @hidden
*/
OIDC = 'SSO_OIDC',
/**
* SSO using OIDC
* Will make the host application redirect to the OIDC IdP.
* See code samples in {@link SAMLRedirect}.
*/
// eslint-disable-next-line @typescript-eslint/no-duplicate-enum-values
OIDCRedirect = 'SSO_OIDC',
/**
* Trusted authentication server
* Use {@link TrustedAuth} instead
* @deprecated This option is deprecated.
* @hidden
*/
AuthServer = 'AuthServer',
/**
* Trusted authentication server. Use your own authentication server
* which returns a bearer token, generated using the `secret_key` obtained
* from ThoughtSpot.
* @example
* ```js
* init({
* // ...
* authType: AuthType.TrustedAuthToken,
* getAuthToken: () => {
* return fetch('https://my-backend.app/ts-token')
* .then((response) => response.json())
* .then((data) => data.token);
* }
* });
* ```
*/
// eslint-disable-next-line @typescript-eslint/no-duplicate-enum-values
TrustedAuthToken = 'AuthServer',
/**
* Trusted authentication server Cookieless, Use your own authentication
* server which returns a bearer token, generated using the `secret_key`
* obtained from ThoughtSpot. This uses a cookieless authentication
* approach, recommended to bypass the third-party cookie-blocking restriction
* implemented by some browsers.
* @version SDK: 1.22.0 | ThoughtSpot: 9.3.0.cl, 9.5.1.sw
* @example
* ```js
* init({
* // ...
* authType: AuthType.TrustedAuthTokenCookieless,
* getAuthToken: () => {
* return fetch('https://my-backend.app/ts-token')
* .then((response) => response.json())
* .then((data) => data.token);
* }
* });
* ```
*/
TrustedAuthTokenCookieless = 'AuthServerCookieless',
/**
* Use the ThoughtSpot login API to authenticate to the cluster directly.
*
* Warning: This feature is primarily intended for developer testing. It is
* strongly advised not to use this authentication method in production.
*/
Basic = 'Basic',
}
/**
*
* **Note**: This attribute is not supported in the classic (V1) homepage experience.
*
*/
export enum HomeLeftNavItem {
/**
* The *Search data* option in
* the *Insights* left navigation panel.
* @version SDK: 1.28.0 | ThoughtSpot: 9.12.5.cl
*/
SearchData = 'search-data',
/**
* The *Home* menu option in
* the *Insights* left navigation panel.
* @version SDK: 1.28.0 | ThoughtSpot: 9.12.5.cl
*/
Home = 'insights-home',
/**
* The *Liveboards* menu option in
* the *Insights* left navigation panel.
* @version SDK: 1.28.0 | ThoughtSpot: 9.12.5.cl
*/
Liveboards = 'liveboards',
/**
* The *Answers* menu option in
* the *Insights* left navigation panel.
* @version SDK: 1.28.0 | ThoughtSpot: 9.12.5.cl
*/
Answers = 'answers',
/**
* The *Monitor subscriptions* menu option in
* the *Insights* left navigation panel.
* @version SDK: 1.28.0 | ThoughtSpot: 9.12.5.cl
*/
MonitorSubscription = 'monitor-alerts',
/**
* The *SpotIQ analysis* menu option in
* the *Insights* left navigation panel.
* @version SDK: 1.28.0 | ThoughtSpot: 9.12.5.cl
*/
SpotIQAnalysis = 'spotiq-analysis',
/**
* The *Liveboard schedules* menu option in
* the *Insights* left navigation panel.
* @version SDK: 1.34.0 | ThoughtSpot: 10.3.0.cl
*/
LiveboardSchedules = 'liveboard-schedules',
/**
* The create option in the *Insights*
* left navigation panel.
* Available in the V3 navigation experience.
* @version SDK: 1.40.0 | ThoughtSpot: 10.11.0.cl
*/
Create = 'create',
/**
* The *Spotter* menu option in the *Insights*
* left navigation panel.
* Available in the V3 navigation experience.
* @version SDK: 1.40.0 | ThoughtSpot: 10.11.0.cl
*/
Spotter = 'spotter',
/**
* The *Favorites* section in the *Insights*
* left navigation panel.
* Available in the V3 navigation experience.
* @version SDK: 1.41.0 | ThoughtSpot: 10.12.0.cl
*/
Favorites = 'favorites',
}
export type DOMSelector = string | HTMLElement;
/**
* inline customCSS within the {@link CustomisationsInterface}.
* Use {@link CustomCssVariables} or css rules.
*/
export interface customCssInterface {
/**
* The custom css variables, which can be set.
* The variables are available in the {@link CustomCssVariables}
* interface. For more information, see
* link:https://developers.thoughtspot.com/docs/css-variables-reference[CSS variable reference].
*/
variables?: CustomCssVariables;
/**
* Can be used to define a custom font face
* like:
* @example
* ```js
* rules_UNSTABLE?: {
* "@font-face": {
* "font-family": "custom-font",
* "src": url("/path/")
* };
* };
* ```
*
* Also, custom css rules outside of variables.
* @example
* ```js
* rules_UNSTABLE?: {
* ".thoughtspot_class_name": {
* "border-radius": "10px",
* margin: "20px"
* };
* };
* ```
*/
rules_UNSTABLE?: {
[selector: string]: {
[declaration: string]: string;
};
};
}
/**
* Styles within the {@link CustomisationsInterface}.
*/
export interface CustomStyles {
customCSSUrl?: string;
customCSS?: customCssInterface;
}
/**
* Configuration to define the customization on the Embedded
* ThoughtSpot components.
* You can customize styles, text strings, and icons.
* For more information, see link:https://developers.thoughtspot.com/docs/custom-css[CSS customization framework].
* @example
* ```js
* init({
* // ...
* customizations: {
* style: {
* customCSS: {
* variables: {},
* rules_UNSTABLE: {}
* }
* },
* content: {
* strings: {
* 'LIVEBOARDS': 'Dashboards',
* 'ANSWERS': 'Visualizations',
* 'Edit': 'Modify',
* 'Show underlying data': 'Show source data',
* 'SpotIQ': 'Insights',
* 'Monitor': 'Alerts',
* }
* },
* iconSpriteUrl: 'https://my-custom-icon-sprite.svg'
* }
* })
* ```
*/
export interface CustomisationsInterface {
style?: CustomStyles;
content?: {
/**
* @version SDK: 1.26.0 | 9.7.0.cl
*/
strings?: Record<string, any>;
stringIDs?: Record<string, string>;
stringIDsUrl?: string;
[key: string]: any;
};
iconSpriteUrl?: string;
}
/**
* The configuration object for embedding ThoughtSpot content.
* It includes the ThoughtSpot hostname or IP address,
* the type of authentication, and the authentication endpoint
* if a trusted authentication server is used.
* @group Authentication / Init
*/
export interface EmbedConfig {
/**
* The ThoughtSpot cluster hostname or IP address.
*/
thoughtSpotHost: string;
/**
* The authentication mechanism to use.
*/
authType: AuthType;
/**
* [AuthServer] The trusted authentication endpoint to use to get the
* authentication token. A `GET` request is made to the
* authentication API endpoint, which returns the token
* as a plaintext response. For trusted authentication,
* the `authEndpoint` or `getAuthToken` attribute is required.
*/
authEndpoint?: string;
/**
* [AuthServer] A function that invokes the trusted authentication endpoint
* and returns a Promise that resolves to the `auth token` string.
* For trusted authentication, the `authEndpoint` or `getAuthToken`
* attribute is required.
*
* It is advisable to fetch a new token inside this method and not
* reuse the old issued token. When auth expires this method is
* called again and if it is called with an older token, the authentication
* will not succeed.
*/
getAuthToken?: () => Promise<string>;
/**
* [AuthServer / Basic] The user name of the ThoughtSpot user. This
* attribute is required for trusted authentication.
*/
username?: string;
/**
* [Basic] The ThoughtSpot login password corresponding to the username
*
* Warning: This feature is primarily intended for developer testing. It is
* strongly advised not to use this authentication method in production.
*/
password?: string;
/**
* [SSO] For SSO Authentication, if `noRedirect` is set to true, it will
* open the SAML auth flow in a popup, instead of redirecting the browser in
* place.
* @deprecated This option is deprecated.
* @default false
*/
noRedirect?: boolean;
/**
* [SSO] For SSO Authentication, if `inPopup` is set to true, it will open
* the SAML auth flow in a popup, instead of redirecting the browser in place.
*
* Need to use this with `authTriggerContainer`. Or manually trigger
* the `AuthEvent.TRIGGER_SSO_POPUP` event on a user interaction.
* @version SDK: 1.18.0
* @default false
*/
inPopup?: boolean;
/**
* [SSO] For SSO Authentication, one can supply an optional path param;
* This will be the path on the host origin where the SAML flow will be
* terminated.
*
* Eg: "/dashboard", "#/foo" [Do not include the host]
* @version SDK: 1.10.2 | ThoughtSpot: 8.2.0.cl, 8.4.1.sw
*/
redirectPath?: string;
/** @internal */
basepath?: string;
/**
* Boolean to define if the query parameters in the ThoughtSpot URL
* should be encoded in base64. This provides additional security to
* ThoughtSpot clusters against cross-site scripting attacks.
* @default false
*/
shouldEncodeUrlQueryParams?: boolean;
/**
* Suppress cookie access alert when third-party cookies are blocked by the
* user's browser. Third-party cookie blocking is the default behaviour on
* some web browsers like Safari. If you set this attribute to `true`,
* you are encouraged to handle `noCookieAccess` event, to show your own treatment
* in this case.
* @default false
*/
suppressNoCookieAccessAlert?: boolean;
/**
* Ignore the cookie access alert when third-party cookies are blocked by the
* user's browser. If you set this to `true`, the embedded iframe behaviour
* persists even in the case of a non-logged-in user.
* @default false
*/
ignoreNoCookieAccess?: boolean;
/**
* Re-login a user with the previous login options
* when a user session expires.
* @default false
*/
autoLogin?: boolean;
/**
* Disable redirection to the login page when the embedded session expires
* This flag is typically used alongside the combination of authentication modes such
* as {@link AuthType.AuthServer} and auto-login behavior {@link
* EmbedConfig.autoLogin}
* @version SDK: 1.9.3 | ThoughtSpot: 8.1.0.cl, 8.4.1.sw
* @default false
*/
disableLoginRedirect?: boolean;
/**
* This message is displayed in the embedded view when a user login fails.
* @version SDK: 1.10.1 | ThoughtSpot: 8.2.0.cl, 8.4.1.sw
*/
loginFailedMessage?: string;
/**
* Calls the prefetch method internally when set to `true`
* @default false
*/
callPrefetch?: boolean;
/**
* When there are multiple objects embedded, queue the rendering of embedded objects
* to start after the previous embed's render is complete. This helps improve
* performance by decreasing the load on the browser.
* @version SDK: 1.5.0 | ThoughtSpot: ts7.oct.cl, 7.2.1
* @default false
*/
queueMultiRenders?: boolean;
/**
* [AuthServer|Basic] Detect if third-party cookies are enabled by doing an
* additional call. This is slower and should be avoided. Listen to the
* `NO_COOKIE_ACCESS` event to handle the situation.
*
* This is slightly slower than letting the browser handle the cookie check, as it
* involves an extra network call.
* @version SDK: 1.10.4 | ThoughtSpot: 8.2.0.cl, 8.4.1.sw
*/
detectCookieAccessSlow?: boolean;
/**
* Hide the `beta` alert warning message for SearchEmbed.
* @version SDK: 1.12.0 | ThoughtSpot: 8.4.0.cl, 8.4.1.sw
*/
suppressSearchEmbedBetaWarning?: boolean;
/**
* Custom style params for embed Config.
* @version SDK: 1.17.0 | ThoughtSpot: 8.9.0.cl, 9.0.1.sw
*/
customizations?: CustomisationsInterface;
/**
* For `inPopup` SAMLRedirect or OIDCRedirect authentication, we need a
* button that the user can click to trigger the flow.
* This attribute sets a containing element for that button.
* @version SDK: 1.17.0 | ThoughtSpot: 8.9.0.cl, 9.0.1.sw
* @example
* ```js
* init({
* authType: AuthType.SAMLRedirect,
* inPopup: true,
* authTriggerContainer: '#auth-trigger-container'
* })
* ```
*/
authTriggerContainer?: string | HTMLElement;
/**
* Specify that we want to use the `AuthEvent.TRIGGER_SSO_POPUP` event to trigger
* SAML popup. This is useful when you want to trigger the popup on a custom user
* action.
*
*/
useEventForSAMLPopup?: boolean;
/**
* Text to show in the button which triggers the popup auth flow.
* Default: `Authorize`.
* @version SDK: 1.17.0 | ThoughtSpot: 8.9.0.cl, 9.0.1.sw
*/
authTriggerText?: string;
/**
* Prevent embedded application users from accessing ThoughtSpot
* application pages outside of the iframe.
* @version SDK: 1.22.0 | ThoughtSpot: 9.3.0.cl, 9.5.1.sw
* @default true
*/
blockNonEmbedFullAppAccess?: boolean;
/**
* Host config in case embedded app is inside TS app itself
* @hidden
*/
hostConfig?: {
hostUserGuid: string;
hostClusterId: string;
hostClusterName: string;
};
/**
* Pendo API key to enable Pendo tracking to your own subscription, the key
* is added as an additional key to the embed, as per this link:https://support.pendo.io/hc/en-us/articles/360032201951-Send-data-to-multiple-subscriptions[document].
* @version SDK: 1.27.0 | ThoughtSpot: 9.8.0.cl
*/
pendoTrackingKey?: string;
/**
* If passed as true all alerts will be suppressed in the embedded app.
* @version SDK: 1.26.2 | ThoughtSpot: *
*/
suppressErrorAlerts?: boolean;
/**
* Suppress or show specific types of logs in the console output.
* For example, `LogLevel.ERROR` shows only Visual Embed SDK and
* ThoughtSpot application errors and suppresses
* other logs such as warnings, information alerts,
* and debug messages in the console output.
*
* @version SDK: 1.26.7 | ThoughtSpot: 9.10.0.cl
* @default LogLevel.ERROR
* @example
* ```js
* init({
* ...embedConfig,
* logLevel: LogLevel.SILENT
* })
* ```
*/
logLevel?: LogLevel;
/**
* Disables the Mixpanel tracking from the SDK.
* @version SDK: 1.27.9
* @hidden
*/
disableSDKTracking?: boolean;
/**
* Overrides default/user preferred locale for date formatting
* @version SDK: 1.28.4 | ThoughtSpot: 10.0.0.cl, 9.5.0.sw
*/
dateFormatLocale?: string;
/**
* Overrides default/user preferred locale for number formatting
* @version SDK: 1.28.4 | ThoughtSpot: 10.0.0.cl, 9.5.0.sw
*/
numberFormatLocale?: string;
/**
* Format to be used for currency when currency format is set to infer from browser
* @version SDK: 1.28.4 | ThoughtSpot: 10.0.0.cl, 9.5.0.sw
*/
currencyFormat?: string;
/**
* This flag is used to disable the token verification in the SDK.
* Enabling this flag will also disable the caching of the token.
* @hidden
* @version SDK: 1.28.5 | ThoughtSpot: 9.10.0.cl, 10.1.0.sw
* @example
* ```js
* init({
* ...embedConfig,
* disableTokenVerification : true
* })
* ```
*/
disableTokenVerification?: boolean;
/**
* This flag is used to disable showing the login failure page in the embedded app.
* @version SDK: 1.32.3 | ThoughtSpot: 10.1.0.cl, 10.1.0.sw
*/
disableLoginFailurePage?: boolean;
/**
* This is an object (key/val) of override flags which will be applied
* to the internal embedded object. This can be used to add any
* URL flag.
* Warning: This option is for advanced use only and is used internally
* to control embed behavior in non-regular ways. We do not publish the
* list of supported keys and values associated with each.
* @version SDK: 1.33.5 | ThoughtSpot: *
* @example
* ```js
* const embed = new LiveboardEmbed('#embed', {
* ... // other liveboard view config
* additionalFlags: {
* flag1: 'value1',
* flag2: 'value2'
* }
* });
* ```
*/
additionalFlags?: { [key: string]: string | number | boolean };
/**
* This is an object (key/val) for customVariables being
* used by the third party tool's script.
* @version SDK: 1.37.0 | ThoughtSpot: 10.8.0.cl
* @example
* ```js
* const embed = new LiveboardEmbed('#embed', {
* ... // other liveboard view config
* customVariablesForThirdPartyTools: {
* key1: 'value1',
* key2: 'value2'
* }
* });
* ```
*/
customVariablesForThirdPartyTools?: Record<string, any>;
disablePreauthCache?: boolean;
/**
* Disable fullscreen presentation mode functionality. When enabled, prevents entering
* and exiting fullscreen mode for embedded visualizations during presentations.
* @version SDK: 1.40.0 | ThoughtSpot: 10.11.0.cl
* @default true (feature is disabled by default)
* @example
* ```js
* init({
* ... // other embed config options
* disableFullscreenPresentation: false, // enables the feature
* })
* ```
*/
disableFullscreenPresentation?: boolean;
/**
* Custom Actions allows users to define interactive UI actions (like buttons or menu
* items) that appear in ThoughtSpot's visualizations, answers, and Liveboards. These
* actions enable users to trigger custom workflows — such as navigating to an
* external app, calling an API, or opening a modal — based on the data context of
* what they clicked can be used to trigger custom logic when the action is clicked.
* @version SDK: 1.43.0 | ThoughtSpot: 10.14.0.cl
* @example
* ```js
* import { CustomActionsPosition, CustomActionTarget } from '@thoughtspot/visual-embed-sdk';
* init({
* ... // other embed config options
* customActions: [
* {
* // Unique identifier for the custom action
* id: 'my-custom-action',
*
* // Display name shown to users in the UI
* name: 'My Custom Action',
*
* // Where the action appears in the UI
* // PRIMARY: Shows as a primary button (e.g., in the toolbar)
* // MENU: Shows in the "More" menu (three dots menu)
* // CONTEXTMENU: Shows in the right-click context menu
* position: CustomActionsPosition.PRIMARY,
*
* // What type of content this action applies to
* // ANSWER: Available on answer pages
* target: CustomActionTarget.ANSWER,
*
* // Optional: Restrict where this action appears based on data models
* // dataModelIds: {
* // // Restrict to specific data models
* // modelIds: ['model-id-1', 'model-id-2'],
* // // Restrict to specific columns within models
* // modelColumnNames: ['model-id::column-name']
* // },
*
* // Optional: Restrict where this action appears based on metadata
* // metadataIds: {
* // // Restrict to specific answers
* // answerIds: ['answer-id-1', 'answer-id-2'],
* // },
* // // Restrict to specific groups (for group-based access control)
* // groupIds: ['group-id-1', 'group-id-2'],
* // // Restrict to specific organizations (for multi-org deployments)
* // orgIds: ['org-id-1', 'org-id-2'],
* }
* ],
* })
* ```
* @example
* ```js
* import { CustomActionsPosition, CustomActionTarget } from '@thoughtspot/visual-embed-sdk';
* init({
* ... // other embed config options
* customActions: [
* {
* // Unique identifier for the custom action
* id: 'my-custom-action',
*
* // Display name shown to users in the UI
* name: 'My Custom Action',
*
* // Where the action appears in the UI
* // MENU: Shows in the "More" menu (three dots menu)
* // CONTEXTMENU: Shows in the right-click context menu
* position: CustomActionsPosition.MENU,
*
* // What type of content this action applies to
* // SPOTTER: Available in Spotter (AI-powered search)
* target: CustomActionTarget.SPOTTER,
*
* // Optional: Restrict where this action appears based on data models
* // dataModelIds: {
* // // Restrict to specific data models
* // modelIds: ['model-id-1', 'model-id-2'],
* // },
* // // Restrict to specific groups (for group-based access control)
* // groupIds: ['group-id-1'],
* // // Restrict to specific organizations (for multi-org deployments)
* // orgIds: ['org-id-1'],
* }
* ],
* })
* ```
* @example
* ```js
* import { CustomActionsPosition, CustomActionTarget } from '@thoughtspot/visual-embed-sdk';
* init({
* ... // other embed config options
* customActions: [
* {
* // Unique identifier for the custom action
* id: 'my-liveboard-custom-action',
*
* // Display name shown to users in the UI
* name: 'My Liveboard Custom Action',
*
* // Where the action appears in the UI
* // PRIMARY: Shows as a primary button (e.g., in the toolbar)
* // MENU: Shows in the "More" menu (three dots menu)
* position: CustomActionsPosition.PRIMARY,
*
* // What type of content this action applies to
* // LIVEBOARD: Available on liveboard pages
* target: CustomActionTarget.LIVEBOARD,
*
* // Optional: Restrict where this action appears based on metadata
* // metadataIds: {
* // // Restrict to specific liveboards
* // liveboardIds: ['liveboard-id-1', 'liveboard-id-2'],
* // },
* // // Restrict to specific groups (for group-based access control)
* // groupIds: ['group-id-1', 'group-id-2'],
* // // Restrict to specific organizations (for multi-org deployments)
* // orgIds: ['org-id-1', 'org-id-2'],
* },
* {
* // Unique identifier for the custom action
* id: 'my-viz-custom-action',
*
* // Display name shown to users in the UI
* name: 'My Viz Custom Action',
*
* // Where the action appears in the UI
* // PRIMARY: Shows as a primary button (e.g., in the toolbar)
* // MENU: Shows in the "More" menu (three dots menu)
* // CONTEXTMENU: Shows in the right-click context menu
* position: CustomActionsPosition.PRIMARY,
*
* // What type of content this action applies to
* // VIZ: Available on individual visualizations
* target: CustomActionTarget.VIZ,
*
* // Optional: Restrict where this action appears based on metadata
* // metadataIds: {
* // // Restrict to specific answers
* // answerIds: ['answer-id-1', 'answer-id-2'],
* // // Restrict to specific liveboard. If liveboardId is
* // // passed, custom actions will appear on all vizzes of liveboard
* // liveboardIds: ['liveboard-id-1'],
* // // Restrict to specific vizIds
* // vizIds: ['viz-id-1']
* // },
* // dataModelIds: {
* // // Restrict to specific data models
* // modelIds: ['model-id-1', 'model-id-2'],
* // // Restrict to specific columns within models
* // modelColumnNames: ['model-id::column-name']
* // },
* // // Restrict to specific groups (for group-based access control)
* // groupIds: ['group-id-1', 'group-id-2'],
* // // Restrict to specific organizations (for multi-org deployments)
* // orgIds: ['org-id-1', 'org-id-2'],
* }
* ],
* })
* ```
*/
customActions?: CustomAction[];
/**
* Wait for the cleanup to be completed before destroying the embed.
* @version SDK: 1.41.0 | ThoughtSpot: 10.12.0.cl
* @default false
*/
waitForCleanupOnDestroy?: boolean;
/**
* The timeout for the cleanup to be completed before destroying the embed.
* @version SDK: 1.41.0 | ThoughtSpot: 10.12.0.cl
* @default 5000
*/
cleanupTimeout?: number;
}
// eslint-disable-next-line @typescript-eslint/no-empty-object-type
export interface LayoutConfig {}
/**
* Embedded iframe configuration
* @group Embed components
*/
export interface FrameParams {
/**
* The width of the iframe (unit is pixels if numeric).
*/
width?: number | string;
/**
* The height of the iframe (unit is pixels if numeric).
*/
height?: number | string;
/**
* Set to 'lazy' to enable lazy loading of the embedded TS frame.
* This will defer loading of the frame until it comes into the
* viewport. This is useful for performance optimization.
*/
loading?: 'lazy' | 'eager' | 'auto';
/**
* These parameters will be passed to the iframe
* as is.
*/
[key: string]: string | number | boolean | undefined;
}
/**
* The common configuration object for an embedded view.
*/
export interface BaseViewConfig extends ApiInterceptFlags {
/**
* @hidden
*/
layoutConfig?: LayoutConfig;
/**
* The width and height dimensions to render an embedded
* object inside your app. Specify the values in pixels or percentage.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
* @version SDK: 1.1.0 | ThoughtSpot: ts7.may.cl, 7.2.1
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* frameParams: {
* width: '500px' | '50%',
* height: '400px' | '60%',
* },
* })
* ```
*/
frameParams?: FrameParams;
/**
* @hidden
*/
theme?: string;
/**
* @hidden
*/
styleSheet__unstable?: string;
/**
* The list of actions to disable from the primary menu, more menu
* (...), 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
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* disabledActions: [Action.Download, Action.Save],
* });
* ```
*/
disabledActions?: Action[];
/**
* The tooltip to display for disabled actions.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
* @version SDK: 1.6.0 | ThoughtSpot: ts8.nov.cl, 8.4.1.sw
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* disabledActions: [Action.Download, Action.Save],
* disabledActionReason: "Reason for disabling",
* });
* ```
*/
disabledActionReason?: string;
/**
* 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
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* hiddenActions: [Action.Download, Action.Export],
* });
* ```
* @important
*/
hiddenActions?: Action[];
/**
* 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 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
* @important
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* visibleActions: [Action.Download, Action.Export],
* });
* ```
*/
visibleActions?: Action[];
/**
* The locale settings to apply to the embedded view.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
* @version SDK: 1.9.4 | ThoughtSpot: 8.1.0.cl, 8.4.1.sw
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* locale:'en',
* })
* ```
*/
locale?: string;
/**
* This is an object (key/val) of override flags which will be applied
* to the internal embedded object. This can be used to add any
* URL flag.
* If the same flags are passed in init, they will be overridden by the values here.
* Warning: This option is for advanced use only and is used internally
* to control embed behavior in non-regular ways. We do not publish the
* list of supported keys and values associated with each.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
* @version SDK: 1.9.0 | ThoughtSpot: 8.1.0.cl, 8.4.1.sw
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* additionalFlags: {
* flag1: 'value1',
* flag2: 'value2'
* },
* });
* ```
*/
additionalFlags?: { [key: string]: string | number | boolean };
/**
* Dynamic CSSUrl and customCSS to be injected in the loaded application.
* You would also need to set `style-src` in the CSP settings.
* @version SDK: 1.17.2 | ThoughtSpot: 8.4.1.sw, 8.4.0.cl
* @default ''
*/
customizations?: CustomisationsInterface;
/**
* Insert as a sibling of the target container, instead of appending to a
* child inside it.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
* @version SDK: 1.2.0 | ThoughtSpot: 9.0.0.cl, 9.0.0.sw
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* insertAsSibling:true,
* })
* ```
*/
insertAsSibling?: boolean;
/**
* Use a pre-rendered iframe from a pool of pre-rendered iframes
* if available and matches the configuration.
* @version SDK: 1.22.0
* @hidden
*
* See [docs]() on how to create a prerender pool.
*/
usePrerenderedIfAvailable?: boolean;
/**
* PreRender id to be used for PreRendering the embed.
* Use PreRender to render the embed in the background and then
* show or hide the rendered embed using showPreRender or hidePreRender respectively.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
* @version SDK: 1.25.0 | ThoughtSpot: 9.6.0.cl, 9.8.0.sw
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* preRenderId: "preRenderId-123",
* });
* embed.showPreRender();
* ```
*/
preRenderId?: string;
/**
* Determines if the PreRender component should dynamically track the size
* of its embedding element and adjust its own size accordingly.
* Enabling this option allows the PreRender component to automatically adapt
* its dimensions based on changes to the size of the embedding element.
* @type {boolean}
* @default false
* @version SDK: 1.24.0 | ThoughtSpot: 9.4.0.cl, 9.4.0.sw
* @example
* ```js
* // Disable tracking PreRender size in the configuration
* const config = {
* doNotTrackPreRenderSize: true,
* };
*
* // Instantiate an object with the configuration
* const myComponent = new MyComponent(config);
* ```
*/
doNotTrackPreRenderSize?: boolean;
/**
* Enable the V2 shell. This can provide performance benefits
* due to a lighter-weight shell.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
* @version SDK: 1.31.2 | ThoughtSpot: 10.0.0.cl
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* enableV2Shell_experimental: true,
* });
* ```
*/
enableV2Shell_experimental?: boolean;
/**
* For internal tracking of the embed component type.
* @hidden
*/
embedComponentType?: string;
/**
* This flag can be used to expose translation IDs on the embedded app.
* @default false
* @version SDK: 1.37.0 | ThoughtSpot: 10.9.0.cl
*/
exposeTranslationIDs?: boolean;
/**
* This flag can be used to disable links inside the embedded app,
* and disable redirection of links in a new tab.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
* @version SDK: 1.32.1 | ThoughtSpot: 10.3.0.cl
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* disableRedirectionLinksInNewTab: true,
* });
* ```
*/
disableRedirectionLinksInNewTab?: boolean;
/**
* Overrides an Org context for embedding application users.
* This parameter allows a user authenticated to one Org to view the
* objects from another Org.
* The `overrideOrgId` setting is honoured only if the
* Per Org URL feature is enabled on your ThoughtSpot instance.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
* @version SDK: 1.35.0 | ThoughtSpot: 10.5.0.cl
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* overrideOrgId: 142536,
* });
* ```
*/
overrideOrgId?: number;
/**
* Flag to override the *Open Link in New Tab* context
* menu option.
*
* For improved link override handling, use
* {@link enableLinkOverridesV2} instead.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`,
* `SearchEmbed`, `SpotterAgentEmbed`,
* `SpotterEmbed`, `SearchBarEmbed`
* @version SDK: 1.21.0 | ThoughtSpot: 9.2.0.cl
* @example
* ```js
* const embed = new LiveboardEmbed('#tsEmbed', {
* ... // other embed view config
* linkOverride: true,
* })
* ```
*/
linkOverride?: boolean;
/**
* Enables the V2 link override mechanism with improved
* handling. When enabled, navigation links within the
* embedded ThoughtSpot app are intercepted and routed
* through the SDK via the `EmbedEvent.DialogOpen`
* event.
*
* The SDK automatically sends {@link linkOverride}
* alongside this flag for backward compatibility with
* older ThoughtSpot versions.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`,
* `SearchEmbed`, `SpotterAgentEmbed`,
* `SpotterEmbed`, `SearchBarEmbed`
* @version SDK: 1.46.0 | ThoughtSpot: 26.2.0.cl
* @example
* ```js
* const embed = new LiveboardEmbed('#tsEmbed', {
* ... // other embed view config
* enableLinkOverridesV2: true,
* });
*
* embed.on(EmbedEvent.DialogOpen, (payload) => {
* console.log('Link clicked:', payload);
* });
* ```
*/
enableLinkOverridesV2?: boolean;
/**
* The primary action to display on top of the viz for Liveboard and App Embed.
* Use this to set the primary action.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`
* @version SDK: 1.39.0 | ThoughtSpot: 10.11.0.cl
* @example
* ```js
* // Replace <EmbedComponent> with embed component name. For example, AppEmbed or LiveboardEmbed
* const embed = new <EmbedComponent>('#tsEmbed', {
* ... // other embed view config
* primaryAction: Action.Download
* });
* ```
*/
primaryAction?: Action | string;
/**
* flag to enable insert into slides action
* @hidden
* @private
*/
insertInToSlide?: boolean;
/**
* Show alert messages and toast messages in the embed.
* Supported in all embed types.
*
* @version SDK: 1.11.0 | ThoughtSpot: 8.3.0.cl, 8.4.1.sw
* @example
* ```js
* const embed = new AppEmbed('#tsEmbed', {
* ... // other embed view config
* showAlerts:true,
* })
* ```
*/
showAlerts?: boolean;
/**
* Custom Actions allows users to define interactive UI actions (like buttons or menu
* items) that appear in ThoughtSpot's visualizations, answers, and Liveboards. These
* actions enable users to trigger custom workflows — such as navigating to an
* external app, calling an API, or opening a modal — based on the data context of
* what they clicked can be used to trigger custom logic when the action is clicked.
*
* Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterEmbed`
* @version SDK: 1.43.0 | ThoughtSpot: 10.14.0.cl
* @example
* ```ts
* import {
* CustomActionPayload,
* CustomActionsPosition,
* CustomActionTarget,
* } from '@thoughtspot/visual-embed-sdk';
* // Use supported embed types such as AppEmbed or LiveboardEmbed
* const embed = new LiveboardEmbed('#tsEmbed', {
* ... // other embed config options
* customActions: [
* {
* // Unique identifier for the custom action
* id: 'my-custom-action',
*
* // Display name shown to users in the UI
* name: 'My Custom Action',
*
* // Where the action appears in the UI
* // PRIMARY: Shows as a primary button (e.g., in the toolbar)
* // MENU: Shows in the "More" menu (three dots menu)
* // CONTEXTMENU: Shows in the right-click context menu
* position: CustomActionsPosition.PRIMARY,
*
* // What type of content this action applies to
* // ANSWER: Available on answer pages
* target: CustomActionTarget.ANSWER,
*
* // Optional: Restrict where this action appears based on data models
* // dataModelIds: {
* // // Restrict to specific data models
* // modelIds: ['model-id-1', 'model-id-2'],
* // // Restrict to specific columns within models
* // modelColumnNames: ['model-id::column-name']
* // },
*
* // Optional: Restrict where this action appears based on metadata
* // metadataIds: {
* // // Restrict to specific answers
* // answerIds: ['answer-id-1', 'answer-id-2'],
* // },
* // // Restrict to specific groups (for group-based access control)
* // groupIds: ['group-id-1', 'group-id-2'],
* // // Restrict to specific organizations (for multi-org deployments)
* // orgIds: ['org-id-1', 'org-id-2'],
* }
* ],
* })
*
* // to trigger a custom flow on custom action click listen to Custom action embed event
* embed.on(EmbedEvent.CustomAction, (payload: CustomActionPayload) => {
* console.log('Custom Action event:', payload);
* })
* ```
* @example
* ```ts
* import {
* CustomActionsPosition,
* CustomActionTarget,
* } from '@thoughtspot/visual-embed-sdk';
* const embed = new LiveboardEmbed('#tsEmbed', {
* ... // other embed config options
* customActions: [
* {
* // Unique identifier for the custom action
* id: 'my-custom-action',
*
* // Display name shown to users in the UI
* name: 'My Custom Action',
*
* // Where the action appears in the UI
* // MENU: Shows in the "More" menu (three dots menu)
* // CONTEXTMENU: Shows in the right-click context menu
* position: CustomActionsPosition.MENU,
*
* // What type of content this action applies to
* // SPOTTER: Available in Spotter (AI-powered search)
* target: CustomActionTarget.SPOTTER,
*
* // Optional: Restrict where this action appears based on data models
* // dataModelIds: {
* // // Restrict to specific data models
* // modelIds: ['model-id-1', 'model-id-2'],
* // },
* // // Restrict to specific groups (for group-based access control)
* // groupIds: ['group-id-1'],
* // // Restrict to specific organizations (for multi-org deployments)
* // orgIds: ['org-id-1'],
* }
* ],
* })
* ```
* @example
* ```ts
* import {
* CustomActionsPosition,
* CustomActionTarget,
* } from '@thoughtspot/visual-embed-sdk';
* const embed = new LiveboardEmbed('#tsEmbed', {
* ... // other embed config options
* customActions: [
* {
* // Unique identifier for the custom action
* id: 'my-liveboard-custom-action',
*
* // Display name shown to users in the UI
* name: 'My Liveboard Custom Action',
*
* // Where the action appears in the UI
* // PRIMARY: Shows as a primary button (e.g., in the toolbar)
* // MENU: Shows in the "More" menu (three dots menu)
* position: CustomActionsPosition.PRIMARY,
*
* // What type of content this action applies to
* // LIVEBOARD: Available on liveboard pages
* target: CustomActionTarget.LIVEBOARD,
*
* // Optional: Restrict where this action appears based on metadata
* // metadataIds: {
* // // Restrict to specific liveboards
* // liveboardIds: ['liveboard-id-1', 'liveboard-id-2'],
* // },
* // // Restrict to specific groups (for group-based access control)
* // groupIds: ['group-id-1', 'group-id-2'],
* // // Restrict to specific organizations (for multi-org deployments)
* // orgIds: ['org-id-1', 'o