@thoughtspot/visual-embed-sdk 1.45.3 → 1.46.1

package/src/types.ts

@@ -690,18 +690,154 @@ export interface EmbedConfig {
      * @version SDK: 1.43.0 | ThoughtSpot: 10.14.0.cl
      * @example
      * ```js
-     * import { CustomActionPosition, CustomActionTarget } from '@thoughtspot/visual-embed-sdk';
+     * import { CustomActionsPosition, CustomActionTarget } from '@thoughtspot/visual-embed-sdk';
      * init({
      *   ... // other embed config options
      *   customActions: [
      *     {
-     *       name: 'customAction',
-     *       id: 'customAction',
+     *       // 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,
-     *       position: CustomActionPosition.PRIMARY,
-     *       }
+     *
+     *       // 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'],
      *     }
-     *   ]
+     *   ],
      * })
      * ```
      */
@@ -1096,7 +1232,7 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      * ```ts
      * import {
      *   CustomActionPayload,
-     *   CustomActionPosition,
+     *   CustomActionsPosition,
      *   CustomActionTarget,
      * } from '@thoughtspot/visual-embed-sdk';
      * // Use supported embed types such as AppEmbed or LiveboardEmbed
@@ -1104,13 +1240,41 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      *   ... // other embed config options
      *   customActions: [
      *     {
-     *       name: 'customAction',
-     *       id: 'customAction',
-     *       target: CustomActionTarget.VIZ,
-     *       position: CustomActionPosition.PRIMARY,
-     *       }
+     *       // 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
@@ -1118,6 +1282,120 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      *   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', '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[];
 
@@ -1361,7 +1639,7 @@ export interface SearchLiveboardCommonViewConfig {
      *
      * Supported embed types: `SageEmbed`, `AppEmbed`, `SearchBarEmbed`, `LiveboardEmbed`, `SearchEmbed`
      * @default true
-     * @version SDK: 1.41.1 | ThoughtSpot Cloud: 10.14.0.cl
+     * @deprecated from SDK 1.46.0 | ThoughtSpot Cloud: 26.3.0.cl
      * @example
      * ```js
      * // Replace <EmbedComponent> with embed component name. For example, SageEmbed, AppEmbed, or SearchBarEmbed
@@ -2859,65 +3137,67 @@ export enum EmbedEvent {
     Rename = 'rename',
     /**
      *
-     * This event can be emitted to intercept search execution initiated by
-     * users and implement logic to allow or restrict search execution.
-     * You can also show custom error text if the search query must be
-     * restricted due to your application or business requirements.
-
-     * Prerequisite: Set `isOnBeforeGetVizDataInterceptEnabled` to `true`
-     * for this embed event to get emitted.
-     * @param - Includes the following event listener parameters:
+     * This event allows developers to intercept search execution
+     * and implement logic that decides whether Search Data should return
+     * data or block the search operation.
+     *
+     * **Prerequisite**: Set`isOnBeforeGetVizDataInterceptEnabled` to `true`
+     * to ensure that `EmbedEvent.OnBeforeGetVizDataIntercept` is emitted
+     * when the embedding application user tries to run a search query.
+     * 
+     * This framework applies only to `AppEmbed` and `SearchEmbed`.
+     * @param - Includes the following parameters:
      * - `payload`: The payload received from the embed related to the Data API call.
      * - `responder`: Contains elements that let developers define whether ThoughtSpot
-     *   should run the search, and if not, what error message
-     *   should be shown to the user.
-     *
-     * `execute` - When `execute` returns `true`, the search will be run.
-     * When `execute` returns `false`, the search will not be executed.
-     *
-     * `error` - Developers can customize the error message text when `execute`
-     * is `false` using the `errorText` and `errorDescription` parameters in responder.
-     *
-     * `errorText` - The error message text to be shown to the user.
-     * `errorDescription (ThoughtSpot: 10.15.0.cl and above)` - The error description to be shown to the user.
+     *   will run or block the search operation, and if blocked, which error message to provide.
+     * - `execute` - When `execute` returns `true`, the search is run.
+     * When `execute` returns `false`, the search is not executed.
+     * - `error` - Developers can customize the user-facing error message when `execute`
+     * is `false` by using the `error` parameters in `responder`.
+     * - `errorText` - The error message text shown to the user.
      * @version SDK : 1.29.0 | ThoughtSpot: 10.3.0.cl
      * @example
-     *```js
-     * embed.on(EmbedEvent.OnBeforeGetVizDataIntercept,
-     * (payload, responder) => {
-     *  responder({
-     *      data: {
-     *          execute:false,
-     *          error: {
-     *          //Provide a custom error message to explain to your end user
-     *          //why their search did not run
-     *          errorText: "This search query cannot be run.
-     *          Please contact your administrator for more details."
-     *          }
-     *  }})
+     *
+     * This example blocks search operation and returns a custom error message:
+     * ```js
+     * embed.on(EmbedEvent.OnBeforeGetVizDataIntercept, (payload, responder) => {
+     *   responder({
+     *     data: {
+     *       execute: false,
+     *       error: {
+     *         // Provide a custom error message to explain why the search did not run.
+     *         errorText: 'This search query cannot be run. Please contact your administrator for more details.',
+     *       },
+     *     },
+     *   });
      * })
      * ```
+     * @example
      *
-     *```js
-     * embed.on(EmbedEvent.OnBeforeGetVizDataIntercept,
-     * (payload, responder) => {
-     * const query = payload.data.data.answer.search_query
-     * responder({
-     *  data: {
-     *      // returns true as long as the query does not include
-     *      // both the 'sales' AND the 'county' column
-     *      execute: !(query.includes("sales")&&query.includes("county")),
-     *      error: {
-     *      //Provide a custom error message to explain to your end user
-     *      // why their search did not run, and which searches are accepted by your custom logic.
-     *      errorText: "Error Occurred",
-     *      errorDescription: "You can't use this query :" + query + ".
-     *      The 'sales' measures can never be used at the 'county' level.
-     *      Please try another measure, or remove 'county' from your search."
-     *      }
-     *  }})
+     * This example allows the search operation to run
+     * unless the query contains both `sales` and `county`,
+     * and returns a custom error message if the query is rejected:
+     * ```js
+     * embed.on(EmbedEvent.OnBeforeGetVizDataIntercept, (payload, responder) => {
+     *   // Record the search query submitted by the end user.
+     *   const query = payload.data.data.answer.search_query;
+     *
+     *   responder({
+     *     data: {
+     *       // Returns true as long as the query does not include both `sales` and `county`.
+     *       execute: !(query.includes('sales') && query.includes('county')),
+     *       error: {
+     *         // Provide a custom error message when the query is blocked by your logic.
+     *         errorText:
+     *           "You can't use this query: "
+     *           + query
+     *           + ". The 'sales' measure can never be used at the 'county' level. "
+     *           + "Please try another measure or remove 'county' from your search.",
+     *       },
+     *     },
+     *   });
      * })
-     *```
+     * ```
      */
     OnBeforeGetVizDataIntercept = 'onBeforeGetVizDataIntercept',
     /**
@@ -6459,18 +6739,80 @@ export interface CustomAction {
  * positions in the application.
  */
 export enum CustomActionsPosition {
+    /**
+     * Shows the action as a primary button
+     * in the toolbar area of the embed.
+     */
     PRIMARY = 'PRIMARY',
+    /**
+     * Shows the action inside the "More" menu
+     * (three-dot overflow menu).
+     */
     MENU = 'MENU',
+    /**
+     * Shows the action in the right-click
+     * context menu. Only supported for
+     * {@link CustomActionTarget.VIZ},
+     * {@link CustomActionTarget.ANSWER}, and
+     * {@link CustomActionTarget.SPOTTER} targets.
+     */
     CONTEXTMENU = 'CONTEXTMENU',
 }
 
 /**
- * Enum options to mention the target of the custom action.
+ * Enum options to mention the target of the code-based custom action.
+ * The target determines which type of ThoughtSpot object the action is
+ * associated with, and also controls which positions and scoping options
+ * are available.
  */
 export enum CustomActionTarget {
+    /**
+     * Action applies at the Liveboard level.
+     * Supported positions:
+     * {@link CustomActionsPosition.PRIMARY},
+     * {@link CustomActionsPosition.MENU}.
+     * Can be scoped with
+     * `metadataIds.liveboardIds`,
+     * `orgIds`, and `groupIds`.
+     */
     LIVEBOARD = 'LIVEBOARD',
+    /**
+     * Action applies to individual
+     * visualizations (charts/tables).
+     * Supported positions:
+     * {@link CustomActionsPosition.PRIMARY},
+     * {@link CustomActionsPosition.MENU},
+     * {@link CustomActionsPosition.CONTEXTMENU}.
+     * Can be scoped with `metadataIds`
+     * (answerIds, liveboardIds, vizIds),
+     * `dataModelIds` (modelIds,
+     * modelColumnNames), `orgIds`,
+     * and `groupIds`.
+     */
     VIZ = 'VIZ',
+    /**
+     * Action applies to saved or unsaved
+     * Answers. Supported positions:
+     * {@link CustomActionsPosition.PRIMARY},
+     * {@link CustomActionsPosition.MENU},
+     * {@link CustomActionsPosition.CONTEXTMENU}.
+     * Can be scoped with
+     * `metadataIds.answerIds`,
+     * `dataModelIds` (modelIds,
+     * modelColumnNames), `orgIds`,
+     * and `groupIds`.
+     */
     ANSWER = 'ANSWER',
+    /**
+     * Action applies to Spotter
+     * (AI-powered search).
+     * Supported positions:
+     * {@link CustomActionsPosition.MENU},
+     * {@link CustomActionsPosition.CONTEXTMENU}.
+     * Can be scoped with
+     * `dataModelIds.modelIds`,
+     * `orgIds`, and `groupIds`.
+     */
     SPOTTER = 'SPOTTER',
 }
 
@@ -6907,4 +7249,4 @@ export interface ContextObject {
     type: ContextType;
     objectIds: ObjectIds;
    }
-}
+}