@thoughtspot/visual-embed-sdk 1.51.1 → 1.52.0

package/src/types.ts

@@ -899,9 +899,11 @@ export interface FrameParams {
 
 /**
  * Configuration for the pre-render wrapper element.
- * All properties here mirror the top-level preRender properties on
- * {@link BaseViewConfig} and take precedence over them when both are set,
- * so existing top-level usage continues to work without any changes.
+ * Each property here supersedes its deprecated top-level counterpart on
+ * {@link BaseViewConfig} — `id` over `preRenderId`, `containerSelector` over
+ * `preRenderContainer` and `doNotTrackSize` over `doNotTrackPreRenderSize` —
+ * and takes precedence when both are set, so existing top-level usage continues
+ * to work without any changes.
  *
  * @version SDK: 1.52.0
  * @example
@@ -909,9 +911,9 @@ export interface FrameParams {
  * init({ thoughtSpotHost: '...', authType: AuthType.None });
  * const embed = new LiveboardEmbed('#tsEmbed', {
  *   preRenderConfig: {
- *     preRenderId: 'my-liveboard',
- *     preRenderContainer: '#my-scroll-container',
- *     doNotTrackPreRenderSize: false,
+ *     id: 'my-liveboard',
+ *     containerSelector: '#my-scroll-container',
+ *     doNotTrackSize: false,
  *     zIndex: -10,
  *   },
  * });
@@ -932,7 +934,7 @@ export interface PreRenderConfig {
      *
      * @default undefined
      */
-    preRenderId?: string;
+    id?: string;
     /**
      * The DOM element or CSS selector string specifying the container into
      * which the pre-rendered wrapper is inserted.
@@ -948,7 +950,7 @@ export interface PreRenderConfig {
      *
      * @default document.body
      */
-    preRenderContainer?: string | HTMLElement;
+    containerSelector?: string | HTMLElement;
     /**
      * Disables the `ResizeObserver` that keeps the wrapper sized to the
      * placeholder element.
@@ -960,7 +962,7 @@ export interface PreRenderConfig {
      *
      * @default false
      */
-    doNotTrackPreRenderSize?: boolean;
+    doNotTrackSize?: boolean;
     /**
      * CSS `z-index` value applied to the pre-render wrapper when hidden.
      * Override this when the host page's stacking context does not reach `-1000`
@@ -1167,7 +1169,7 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      *
      * Supported embed types: `AppEmbed`, `LiveboardEmbed`, `SearchEmbed`, `SpotterAgentEmbed`, `SpotterEmbed`, `SearchBarEmbed`
      * @version SDK: 1.25.0 | ThoughtSpot: 9.6.0.cl, 9.8.0.sw
-     * @deprecated Use {@link PreRenderConfig.preRenderId} via `preRenderConfig` instead.
+     * @deprecated Use {@link PreRenderConfig.id} via `preRenderConfig` instead.
      * @example
      * ```js
      * // Replace <EmbedComponent> with embed component name. For example, AppEmbed, SearchEmbed, or LiveboardEmbed
@@ -1188,7 +1190,7 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      * @type {boolean}
      * @default false
      * @version SDK: 1.24.0 | ThoughtSpot: 9.4.0.cl, 9.4.0.sw
-     * @deprecated Use {@link PreRenderConfig.doNotTrackPreRenderSize} via `preRenderConfig` instead.
+     * @deprecated Use {@link PreRenderConfig.doNotTrackSize} via `preRenderConfig` instead.
      * @example
      * ```js
      * // Disable tracking PreRender size in the configuration
@@ -1230,7 +1232,7 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      *
      * @type {string | HTMLElement}
      * @version SDK: 1.49.2 | ThoughtSpot: *
-     * @deprecated Use {@link PreRenderConfig.preRenderContainer} via `preRenderConfig` instead.
+     * @deprecated Use {@link PreRenderConfig.containerSelector} via `preRenderConfig` instead.
      * @example
      * ```js
      * const embed = new LiveboardEmbed('#tsEmbed', {
@@ -1243,9 +1245,11 @@ export interface BaseViewConfig extends ApiInterceptFlags {
     preRenderContainer?: string | HTMLElement;
     /**
      * Configuration for the pre-render wrapper element.
-     * All properties here mirror the top-level preRender properties on
-     * `BaseViewConfig` and take precedence over them when both are set,
-     * so existing top-level usage continues to work without any changes.
+     * Each property here supersedes its deprecated top-level counterpart on
+     * `BaseViewConfig` — `id` over `preRenderId`, `containerSelector` over
+     * `preRenderContainer` and `doNotTrackSize` over `doNotTrackPreRenderSize` —
+     * and takes precedence when both are set, so existing top-level usage
+     * continues to work without any changes.
      * See {@link PreRenderConfig} for available options.
      *
      * @version SDK: 1.52.0
@@ -1253,7 +1257,7 @@ export interface BaseViewConfig extends ApiInterceptFlags {
      * ```js
      * const embed = new LiveboardEmbed('#tsEmbed', {
      *   preRenderConfig: {
-     *     preRenderId: 'my-liveboard',
+     *     id: 'my-liveboard',
      *     zIndex: -10,
      *   },
      * });
@@ -2035,7 +2039,7 @@ export interface LiveboardAppEmbedViewConfig {
      *
      * Supported embed types: `AppEmbed`, `LiveboardEmbed`
      * @type {boolean}
-     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     * @version SDK: 1.51.1 | ThoughtSpot Cloud: 26.8.0.cl
      * @default false
      * @example
      * ```js
@@ -2160,7 +2164,7 @@ export interface LiveboardAppEmbedViewConfig {
      *
      * Supported embed types: `AppEmbed`, `LiveboardEmbed`
      * @type {number}
-     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     * @version SDK: 1.51.1 | ThoughtSpot Cloud: 26.8.0.cl
      * @example
      * ```js
      * // Replace <EmbedComponent> with embed component name. For example, AppEmbed or LiveboardEmbed
@@ -3849,7 +3853,32 @@ export enum EmbedEvent {
      */
     OrgSwitched = 'orgSwitched',
     /**
-     * Emitted when the user intercepts a URL.
+     * Emitted before the embedded ThoughtSpot app sends a network request whose
+     * fully resolved URL matches one of the `interceptUrls` in the view config.
+     * The request is held until you call `responder`, which decides whether the
+     * real request goes out or a response you supply is used in its place.
+     *
+     * Setting `interceptUrls` is what enables this; there is no separate enable
+     * flag. If `responder` is not called within `interceptTimeout` (30000 ms by
+     * default) the request fails and `EmbedEvent.Error` is emitted.
+     *
+     * The payload is `{ input, init, urlType }`, where `input` is the request
+     * URL and `init` is the `fetch` init object, with `init.body` parsed into an
+     * object when it is valid JSON. `urlType` is the matching
+     * `InterceptedApiType`; it is `InterceptedApiType.ALL` for any URL outside
+     * the recognized API groups.
+     *
+     * Interception wraps the outermost layer of `fetch`, so `init` holds the
+     * request as the application composed it, before ThoughtSpot attaches its
+     * authentication headers. Those headers, and any token refresh and retry,
+     * are applied afterwards and only when you pass `execute: true`. Only
+     * requests made through `fetch` are intercepted.
+     *
+     * Pass `execute: true` to let the original request proceed untouched, in
+     * which case any `response` you supply alongside it is ignored. With
+     * `execute: false` the request is never sent, and your `response.body` is
+     * returned to the app as JSON, defaulting to status 200 and a
+     * `Content-Type: application/json` header.
      *
      * Supported on all embed types.
      *
@@ -4672,7 +4701,7 @@ export enum HostEvent {
      *
      * Unlike {@link HostEvent.OpenFilter}, which opens the panel of an
      * existing filter, this event starts the creation of a new filter.
-     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     * @version SDK: 1.51.1 | ThoughtSpot Cloud: 26.8.0.cl
      * @example
      * ```js
      * liveboardEmbed.trigger(HostEvent.OpenAddFilterModal);
@@ -4688,7 +4717,7 @@ export enum HostEvent {
      * Hiding the *Add parameter* button with `hiddenActions:
      * [Action.AddParameter]` does not block this event, but disabling it
      * with `disabledActions` does.
-     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
+     * @version SDK: 1.51.1 | ThoughtSpot Cloud: 26.8.0.cl
      * @example
      * ```js
      * liveboardEmbed.trigger(HostEvent.OpenAddParameterModal);
@@ -6567,7 +6596,13 @@ export enum HostEvent {
      */
     UpdateEmbedParams = 'updateEmbedParams',
     /**
-     * Triggered when the embed needs to be destroyed. This is used to clean up any embed-related resources internally.
+     * Notifies the embedded ThoughtSpot app that the embed is being torn down, so that
+     * it can release any resources it holds before the iframe is removed from the DOM.
+     *
+     * This is triggered for you by `embed.destroy()`; you rarely need to trigger it
+     * directly. If `waitForCleanupOnDestroy` is set in the embed config, `destroy()`
+     * waits for the app to acknowledge this event (up to `cleanupTimeout`) before
+     * removing the iframe.
      * @example
      * ```js
      * liveboardEmbed.trigger(HostEvent.DestroyEmbed);
@@ -8724,7 +8759,7 @@ export enum Action {
      * ```js
      * hiddenActions: [Action.QuickSearchPill]
      * ```
-     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
      */
     QuickSearchPill = 'quickSearchPill',
     /**
@@ -8739,7 +8774,7 @@ export enum Action {
      * ```js
      * hiddenActions: [Action.DeepAnalysisPill]
      * ```
-     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
      */
     DeepAnalysisPill = 'deepAnalysisPill',
     /**
@@ -8754,7 +8789,7 @@ export enum Action {
      * ```js
      * hiddenActions: [Action.DataLiteracyPill]
      * ```
-     * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.10.0.cl
      */
     DataLiteracyPill = 'dataLiteracyPill',
     /**
@@ -9375,10 +9410,42 @@ export interface EmbedErrorDetailsEvent {
     message: string | string[];
     /** Machine-readable error code for programmatic error handling */
     code: EmbedErrorCodes;
+    /** How badly the embed is affected. Defaults to {@link EmbedErrorSeverity.SEV3}. */
+    severity?: EmbedErrorSeverity;
     /** Additional context-specific for backward compatibility */
     [key: string]: any;
 }
 
+/**
+ * How badly an error affects the embed, so the host can decide whether it is
+ * worth surfacing to the end user.
+ *
+ * Mirrors the severity that ThoughtSpot itself stamps on errors raised inside
+ * the embedded app, so a host can apply one rule to both sources.
+ *
+ * @version SDK: 1.52.0 | ThoughtSpot Cloud: 26.9.0.cl
+ * @group Error Handling
+ *
+ * @example
+ * Only surface errors that took the embed down
+ *
+ * ```js
+ * embed.on(EmbedEvent.Error, (error) => {
+ *   if (error.severity === EmbedErrorSeverity.SEV1) {
+ *     showBanner(error.message);
+ *   }
+ * });
+ * ```
+ */
+export enum EmbedErrorSeverity {
+    /** The embed cannot render. Nothing usable is on screen. */
+    SEV1 = 1,
+    /** Something is degraded but the embed still works. */
+    SEV2 = 2,
+    /** Everything else, including validation of the embedder's own input. */
+    SEV3 = 3,
+}
+
 /**
  * Context types for specifying the page context when triggering host events.
  * Used as the third parameter in the `trigger` method to help ThoughtSpot
@@ -9439,26 +9506,41 @@ export interface DefaultAppInitData {
 }
 
 /**
- * Enum for the type of API intercepted
+ * Named groups of ThoughtSpot APIs that can be intercepted, for use in
+ * `interceptUrls`. Each group expands to the underlying request URLs, so you do
+ * not have to list them individually.
  */
 export enum InterceptedApiType {
     /**
-     * The apis that are use to get the data for the embed
+     * The APIs that fetch the data backing an Answer, including its chart,
+     * table, and headline data.
      */
     AnswerData = 'AnswerData',
     /**
-     * This will intercept all the apis
+     * Intercepts every `fetch` request the embedded application makes, not only
+     * the data APIs. This includes authentication, session, and metadata calls,
+     * so the handler must respond to requests it does not recognize by passing
+     * `execute: true`. Listing this alongside other entries in `interceptUrls`
+     * supersedes them.
      */
     ALL = 'ALL',
     /**
-     * The apis that are use to get the data for the liveboard
+     * The APIs that fetch the data backing a Liveboard.
      */
     LiveboardData = 'LiveboardData',
 }
 
 export type ApiInterceptFlags = {
     /**
-     * Flag that allows using `EmbedEvent.OnBeforeGetVizDataIntercept`.
+     * Emits `EmbedEvent.OnBeforeGetVizDataIntercept` before the Answer data
+     * APIs are called. This is the earlier, narrower form of interception, kept
+     * for backward compatibility and implemented on top of
+     * `EmbedEvent.ApiIntercept`. Prefer `interceptUrls` with
+     * `InterceptedApiType.AnswerData` in new code.
+     *
+     * Setting this also intercepts the Answer data APIs, so both
+     * `EmbedEvent.OnBeforeGetVizDataIntercept` and `EmbedEvent.ApiIntercept`
+     * are emitted for those requests.
      *
      * Can be used for Search and App Embed from SDK 1.29.0
      *
@@ -9466,14 +9548,21 @@ export type ApiInterceptFlags = {
      */
     isOnBeforeGetVizDataInterceptEnabled?: boolean;
     /**
-     * This allows to intercept the urls passed, once intercepted the api will only
-     * run based on the response from the responder of ApiIntercept event.
+     * The requests to intercept, given as `InterceptedApiType` groups, absolute
+     * URLs, or paths beginning with `/` that are resolved against the
+     * ThoughtSpot host. Setting this is what turns interception on.
+     *
+     * A URL matches only on exact equality with the request's fully resolved
+     * URL, query string included, so prefer an `InterceptedApiType` group where
+     * one covers the API you need.
+     *
+     * Each intercepted request pauses and emits `EmbedEvent.ApiIntercept`, then
+     * proceeds according to the response passed to that event's responder.
      *
      * @example
      * ```js
      * const embed = new LiveboardEmbed('#embed', {
      *   ...viewConfig,
-     *   enableApiIntercept: true,
      *   interceptUrls: [InterceptedApiType.LiveboardData],
      * })
      * ```
@@ -9482,14 +9571,14 @@ export type ApiInterceptFlags = {
      */
     interceptUrls?: (string | InterceptedApiType)[];
     /**
-     * The timeout for the intercept, default is 30000ms
-     * the api will error out if the timeout is reached
+     * How long, in milliseconds, an intercepted request waits for the
+     * `EmbedEvent.ApiIntercept` responder before it is abandoned. Defaults to
+     * 30000. On timeout the request fails and `EmbedEvent.Error` is emitted.
      *
      * @example
      * ```js
      * const embed = new LiveboardEmbed('#embed', {
      *   ...viewConfig,
-     *   enableApiIntercept: true,
      *   interceptUrls: [InterceptedApiType.ALL],
      *   interceptTimeout: 1000,
      * })

package/src/utils.spec.ts

@@ -1,5 +1,6 @@
 import {
     getQueryParamString,
+    deserializeParam,
     getFilterQuery,
     getCssDimension,
     getEncodedQueryParamsString,
@@ -349,7 +350,50 @@ describe('unit test for utils', () => {
     });
 });
 
+describe('deserializeParam', () => {
+    // Inverse of URL param serialization — must mirror the app's URL parser.
+    test('parses a JSON-string array back to a real array (SCAL-334713)', () => {
+        expect(deserializeParam('["4dd30af7-9ed7-4847-8f28-b65b44a841d8"]')).toEqual([
+            '4dd30af7-9ed7-4847-8f28-b65b44a841d8',
+        ]);
+    });
+
+    test('does not URI-decode strings — raw %xx content must survive', () => {
+        expect(deserializeParam('%5Bcommit%20date%5D%5Brevenue%5D')).toBe(
+            '%5Bcommit%20date%5D%5Brevenue%5D',
+        );
+    });
+
+    test('parses JSON objects and booleans', () => {
+        expect(deserializeParam('{"a":1}')).toEqual({ a: 1 });
+        expect(deserializeParam('true')).toBe(true);
+    });
+
+    test('keeps numeric strings as strings, matching the app URL parser', () => {
+        expect(deserializeParam('123')).toBe('123');
+        expect(deserializeParam('1.5')).toBe('1.5');
+    });
+
+    test('keeps plain non-JSON strings unchanged', () => {
+        expect(deserializeParam('local-host')).toBe('local-host');
+        expect(deserializeParam('AuthServerCookieless')).toBe('AuthServerCookieless');
+    });
+
+    test('keeps a malformed percent-sequence string as-is', () => {
+        expect(deserializeParam('100% legit')).toBe('100% legit');
+    });
+
+    test('passes non-string values through untouched', () => {
+        const arr = ['a'];
+        expect(deserializeParam(arr)).toBe(arr);
+        expect(deserializeParam(true)).toBe(true);
+        expect(deserializeParam(42)).toBe(42);
+        expect(deserializeParam(undefined)).toBeUndefined();
+    });
+});
+
 describe('Fullscreen Utility Functions', () => {
+
     let originalExitFullscreen: any;
     let mockIframe: HTMLIFrameElement;
 

package/src/utils.ts

@@ -85,6 +85,22 @@ const serializeParam = (value: any) => {
     return JSON.stringify(value);
 };
 
+/**
+ * Inverse of serializeParam: JSON.parse with fallback to the raw string,
+ * matching how the app parses the same values from the iframe URL.
+ */
+export const deserializeParam = (value: unknown): unknown => {
+    if (typeof value !== 'string') return value;
+    try {
+        const parsed = JSON.parse(value);
+        // Numeric strings stay strings ('123' !== 123), same as the app's
+        // URL parser — param consumers expect string ids/versions.
+        return typeof parsed === 'number' ? value : parsed;
+    } catch (e) {
+        return value;
+    }
+};
+
 /**
  * Convert a value to a string:
  * in case of an array, we convert it to CSV.