@thoughtspot/visual-embed-sdk 1.52.1 → 1.52.2-beta

package/src/embed/ts-embed.ts

@@ -120,10 +120,62 @@ const PRERENDER_WRAPPER_ID_PREFIX = 'tsEmbed-pre-render-wrapper-';
 // post is not the same as the params being in effect.
 const UPDATE_EMBED_PARAMS_SETTLE_MS = 200;
 
-// The container ignores runtimeFilterParams/runtimeParameterParams unless truthy, so
-// null or '' leaves the previous embed's values in place. '&' is truthy and parses to {}.
+// The container ignores runtimeFilterParams/runtimeParameterParams unless
+// truthy, so null or '' leaves the previous embed's values in place. '&' is
+// truthy and parses to {}.
 const NO_RUNTIME_PARAMS = '&';
 
+/**
+ * Query parameters that stay on the iframe `src` while config is excluded from
+ * the URL, which is the default unless the embed sets the
+ * `excludeConfigFromURL` additional flag to `false`. These are the parameters the
+ * application shell needs before it can receive a postMessage at all: the
+ * embed marker, the host application URL used to validate the message origin,
+ * the SDK version, the flags that pick the authentication flow, and the
+ * boot-time settings that would otherwise be applied a frame late (viewport,
+ * log level, locale, formatting and org). Everything else is delivered over
+ * `HostEvent.UpdateEmbedParams`.
+ * @internal
+ */
+const BOOTSTRAP_URL_PARAMS: ReadonlySet<string> = new Set<string>([
+    Param.EmbedApp,
+    Param.HostAppUrl,
+    Param.Version,
+    Param.AuthType,
+    Param.AutoLogin,
+    Param.DisableLoginRedirect,
+    Param.ForceSAMLAutoRedirect,
+    Param.cookieless,
+    Param.preAuthCache,
+    Param.blockNonEmbedFullAppAccess,
+    Param.OverrideOrgId,
+    Param.ViewPortHeight,
+    Param.ViewPortWidth,
+    Param.ClientLogLevel,
+    Param.OverrideNativeConsole,
+    Param.PendoTrackingKey,
+    Param.NumberFormatLocale,
+    Param.DateFormatLocale,
+    Param.CurrencyFormat,
+    Param.Locale,
+    Param.searchEmbed,
+    Param.livedBoardEmbed,
+    Param.isSpotterAgentEmbed,
+    Param.SpotterEnabled,
+    Param.IsFullAppEmbed,
+    Param.IsOnBeforeGetVizDataInterceptEnabled,
+    Param.LinkOverride,
+    Param.EnableLinkOverridesV2,
+    Param.DisableRedirectionLinksInNewTab,
+    Param.OverrideHistoryState,
+    Param.ForceTable,
+    Param.StringIDsUrl,
+    Param.DataSources,
+    Param.ExposeTranslationIDs,
+    Param.IconSpriteUrl,
+    Param.Tag,
+]);
+
 /**
  * The event id map from v2 event names to v1 event id
  * v1 events are the classic embed events implemented in Blink v1
@@ -740,8 +792,9 @@ export class TsEmbed {
             ...this.viewConfig,
             ...queryParams,
             ...appInitData,
-            // A show cycle has no URL to carry these, so the payload always states them
-            // — including "none", which is the case that leaks the previous filters.
+            // A show cycle has no URL to carry these, so the payload always
+            // states them — including "none", which is the case that leaks the
+            // previous filters.
             runtimeFilterParams:
                 getFilterQuery(this.viewConfig.runtimeFilters ?? []) || NO_RUNTIME_PARAMS,
             runtimeParameterParams:
@@ -948,7 +1001,7 @@ export class TsEmbed {
     }
 
     protected getEmbedParams() {
-        const queryParams = this.getEmbedParamsObject();
+        const queryParams = this.getUrlQueryParamsObject();
         return getQueryParamString(queryParams);
     }
 
@@ -957,6 +1010,16 @@ export class TsEmbed {
         return params;
     }
 
+    protected getUrlQueryParamsObject(): Record<any, any> {
+        const queryParams = this.getEmbedParamsObject();
+        if (!this.isConfigExcludedFromUrl()) {
+            return queryParams;
+        }
+        return Object.fromEntries(
+            Object.entries(queryParams).filter(([key]) => BOOTSTRAP_URL_PARAMS.has(key)),
+        );
+    }
+
     protected getRootIframeSrc() {
         const query = this.getEmbedParams();
         return this.getEmbedBasePath(query);
@@ -1615,8 +1678,9 @@ export class TsEmbed {
         (this.preRenderWrapper as any)[this.embedNodeKey] = this;
     }
 
-    // The flag lives on the wrapper because it describes the iframe: an instance
-    // hidden when the container announced itself would otherwise report false forever.
+    // The flag lives on the wrapper because it describes the iframe: an
+    // instance hidden when the container announced itself would otherwise
+    // report false forever.
     private markEmbedContainerLoaded() {
         this.isEmbedContainerLoaded = true;
         if (this.preRenderWrapper) {
@@ -1672,10 +1736,14 @@ export class TsEmbed {
                 const AUTH_INIT_FALLBACK_DELAY = 1000;
                 // Wait for 1 second to ensure the embed container is loaded
                 // This is a workaround to ensure the embed container is loaded
-                // this is needed until all clusters have EmbedListenerReady event
+                // this is needed until all clusters have EmbedListenerReady
+                // event
                 setTimeout(processEmbedContainerReady, AUTH_INIT_FALLBACK_DELAY);
             } else if (source === EmbedEvent.EmbedListenerReady) {
                 processEmbedContainerReady();
+                if (this.isConfigExcludedFromUrl()) {
+                    this.triggerUpdateEmbedParams();
+                }
             }
         };
 
@@ -2040,9 +2108,33 @@ export class TsEmbed {
     }
 
     // Subclasses that navigate the pre-render on show must await this before
-    // triggering Navigate. Resolves even on failure, so navigation is never blocked.
+    // triggering Navigate. Resolves even on failure, so navigation is never
+    // blocked.
     protected preRenderParamsApplied: Promise<void> = Promise.resolve();
 
+    protected isConfigExcludedFromUrl(): boolean {
+        const flag =
+            this.viewConfig.additionalFlags?.excludeConfigFromURL ??
+            this.embedConfig.additionalFlags?.excludeConfigFromURL;
+        // Enabled by default; only an explicit false opts out.
+        return flag !== false && flag !== 'false';
+    }
+
+    protected async triggerUpdateEmbedParams(): Promise<void> {
+        try {
+            const params = await this.getUpdateEmbedParamsObject();
+            this.trigger(HostEvent.UpdateEmbedParams, params);
+        } catch (error) {
+            logger.error(ERROR_MESSAGE.UPDATE_PARAMS_FAILED, error);
+            this.handleError({
+                errorType: ErrorDetailsTypes.API,
+                message: error?.message || ERROR_MESSAGE.UPDATE_PARAMS_FAILED,
+                code: EmbedErrorCodes.UPDATE_PARAMS_FAILED,
+                error: error?.message || error,
+            });
+        }
+    }
+
     protected beforePrerenderVisible(): void {
         // We can ignore this as its a bit expensive and the newer customers
         // have moved on to UpdateEmbedParams supported clusters
@@ -2053,16 +2145,7 @@ export class TsEmbed {
         this.preRenderParamsApplied = new Promise<void>((resolve) => {
             this.executeAfterEmbedContainerLoaded(async () => {
                 try {
-                    const params = await this.getUpdateEmbedParamsObject();
-                    this.trigger(HostEvent.UpdateEmbedParams, params);
-                } catch (error) {
-                    logger.error(ERROR_MESSAGE.UPDATE_PARAMS_FAILED, error);
-                    this.handleError({
-                        errorType: ErrorDetailsTypes.API,
-                        message: error?.message || ERROR_MESSAGE.UPDATE_PARAMS_FAILED,
-                        code: EmbedErrorCodes.UPDATE_PARAMS_FAILED,
-                        error: error?.message || error,
-                    });
+                    await this.triggerUpdateEmbedParams();
                 } finally {
                     setTimeout(resolve, UPDATE_EMBED_PARAMS_SETTLE_MS);
                 }
@@ -2099,8 +2182,9 @@ export class TsEmbed {
         if (this.hostElement) {
             this.insertedDomEl = this.createPreRenderPlaceholder();
             if ((this.viewConfig as { fullHeight: boolean }).fullHeight) {
-                // If fullHeight has already sized the wrapper, seed the placeholder
-                // with the same height so syncPreRenderStyle gets an accurate rect.
+                // If fullHeight has already sized the wrapper, seed the
+                // placeholder with the same height so syncPreRenderStyle gets
+                // an accurate rect.
                 const existingHeight = this.preRenderWrapper.style.height;
                 if (existingHeight) {
                     (this.insertedDomEl as HTMLDivElement).style.height = existingHeight;
@@ -2109,12 +2193,13 @@ export class TsEmbed {
 
             const placeHolderId = this.getPreRenderIds().placeHolder;
             // Remove any stale placeholder from a previous cycle. It is located
-            // via a subtree-wide querySelector, so it may be nested deeper than a
-            // direct child (E.g.: with fullHeight the host app can wrap it). Use
-            // Element.remove() — which detaches from whatever the real parent is —
-            // rather than hostElement.removeChild(), which throws NotFoundError
-            // when the match is not a direct child. Mirrors the wrapper/child
-            // cleanup in createPreRenderWrapper()/createPreRenderChild().
+            // via a subtree-wide querySelector, so it may be nested deeper
+            // than a direct child (E.g.: with fullHeight the host app can wrap
+            // it). Use Element.remove() — which detaches from whatever the real
+            // parent is — rather than hostElement.removeChild(), which throws
+            // NotFoundError when the match is not a direct child. Mirrors the
+            // wrapper/child cleanup in
+            // createPreRenderWrapper()/createPreRenderChild().
             this.hostElement.querySelector(`#${placeHolderId}`)?.remove();
 
             this.hostElement.appendChild(this.insertedDomEl);
@@ -2153,7 +2238,8 @@ export class TsEmbed {
             this.setupFullscreenChangeHandler();
         }
 
-        // Last, so everything above still sees the instance being taken over from.
+        // Last, so everything above still sees the instance being taken over
+        // from.
         this.takeOverPreRender();
 
         return this;

package/src/errors.ts

@@ -29,7 +29,7 @@ export const ERROR_MESSAGE = {
     SSR_ENVIRONMENT_ERROR: 'SSR environment detected. This function cannot be called in SSR environment.',
     UPDATE_PARAMS_FAILED: 'Failed to update embed parameters',
     INVALID_SPOTTER_DOCUMENTATION_URL: 'Invalid spotterDocumentationUrl. Please provide a valid http or https URL.',
-    UPDATEFILTERS_INVALID_PAYLOAD: 'UpdateFilters requires a valid filter or filters array. Expected: { filter: { column, oper, values } } or { filters: [{ column, oper, values }, ...] }',
+    UPDATEFILTERS_INVALID_PAYLOAD: 'UpdateFilters requires a valid filter or filters array. Expected: { filter: { columnName, operator, values } } or { filters: [{ columnName, operator, values }, ...] }',
     DRILLDOWN_INVALID_PAYLOAD: 'DrillDown requires a valid points object. Expected: { points: { clickedPoint?, selectedPoints? }, autoDrillDown?, vizId? }',
     UPDATEPARAMETERS_INVALID_PAYLOAD: 'UpdateParameters received an invalid applicability. Expected: { level: LIVEBOARD | TAB | GROUP, targetId } where targetId is required for TAB and GROUP levels',
 };

package/src/index.ts

@@ -151,6 +151,12 @@ import {
     NavigateRequest,
     SetActiveTabRequest,
 } from './contracts/host-event-contracts';
+import {
+    convertFilterChangedToUpdateFiltersPayload,
+    FilterChangedPayload,
+    UpdateFiltersFilterParam,
+    UpdateFiltersPayload,
+} from './utils/filterConverter';
 
 export {
     init,
@@ -318,6 +324,10 @@ export {
     DataLabelFilterOperator,
     TableTheme,
     TableContentDensity,
+    convertFilterChangedToUpdateFiltersPayload,
+    FilterChangedPayload,
+    UpdateFiltersFilterParam,
+    UpdateFiltersPayload,
 };
 
 export { resetCachedAuthToken } from './authToken';

package/src/react/all-types-export.ts

@@ -128,4 +128,8 @@ export {
     StarterPromptCategory,
     StarterPreviewDataCategory,
     StarterPromptQuestion,
+    convertFilterChangedToUpdateFiltersPayload,
+    FilterChangedPayload,
+    UpdateFiltersFilterParam,
+    UpdateFiltersPayload,
 } from '../index';

package/src/types.ts

@@ -5918,6 +5918,12 @@ export enum HostEvent {
      * ```js
      * const data = await liveboardEmbed.trigger(HostEvent.GetFilters);
      *     console.log('data', data);
+     * // {
+     * //   liveboardFilters: [ ... ],
+     * //   runtimeFilters: [
+     * //     { columnName: "Region", operator: "IN", values: ["West"] }
+     * //   ]
+     * // }
      * ```
      * @example
      * ```js
@@ -5942,9 +5948,9 @@ export enum HostEvent {
      *
      * Each filter object must include the following attributes:
      *
-     * `column` - Name of the column to filter on.
+     * `columnName` - Name of the column to filter on.
      *
-     * `oper`  - Filter operator, for example, EQ, IN, CONTAINS.
+     * `operator`  - Filter operator, for example, EQ, IN, CONTAINS.
      *  For information about the supported filter operators,
      *  see link:https://developers.thoughtspot.com/docs/runtime-filters#rtOperator[Developer Documentation].
      *
@@ -5971,8 +5977,8 @@ export enum HostEvent {
      *
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *     filter: {
-     *         column: "item type",
-     *         oper: "IN",
+     *         columnName: "item type",
+     *         operator: "IN",
      *         values: ["bags","shirts"]
      *        }
      *    });
@@ -5982,8 +5988,8 @@ export enum HostEvent {
      *
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *     filter: {
-     *         column: "date",
-     *         oper: "EQ",
+     *         columnName: "date",
+     *         operator: "EQ",
      *         values: ["JULY","2023"],
      *         type: "MONTH_YEAR"
      *        }
@@ -5994,18 +6000,18 @@ export enum HostEvent {
      * ```js
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *  filters: [{
-     *      column: "Item Type",
-     *      oper: 'IN',
+     *      columnName: "Item Type",
+     *      operator: 'IN',
      *      values: ["bags","shirts"]
      *  },
      *    {
-     *      column: "Region",
-     *      oper: 'IN',
+     *      columnName: "Region",
+     *      operator: 'IN',
      *      values: ["West","Midwest"]
      *  },
      *    {
-     *      column: "Date",
-     *      oper: 'EQ',
+     *      columnName: "Date",
+     *      operator: 'EQ',
      *      values: ["2023-07-31"],
      *      type: "EXACT_DATE"
      *    }]
@@ -6019,13 +6025,13 @@ export enum HostEvent {
      * ```js
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *  filters: [{
-     *      column: "(Sample) Retail - Apparel::city",
-     *      oper: 'IN',
+     *      columnName: "(Sample) Retail - Apparel::city",
+     *      operator: 'IN',
      *      values: ["atlanta"]
      *  },
      *  {
-     *      column: "(Sample) Retail - Apparel::Region",
-     *      oper: 'IN',
+     *      columnName: "(Sample) Retail - Apparel::Region",
+     *      operator: 'IN',
      *      values: ["West","Midwest"]
      *  }]
      * });
@@ -6036,8 +6042,8 @@ export enum HostEvent {
      * import { ContextType } from '@thoughtspot/visual-embed-sdk';
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *     filter: {
-     *         column: "item type",
-     *         oper: "IN",
+     *         columnName: "item type",
+     *         operator: "IN",
      *         values: ["shoes", "boots"]
      *     }
      * }, ContextType.Liveboard);
@@ -6047,8 +6053,8 @@ export enum HostEvent {
      * // Scope the filter to a specific Liveboard tab
      * liveboardEmbed.trigger(HostEvent.UpdateFilters, {
      *     filter: {
-     *         column: "item type",
-     *         oper: "IN",
+     *         columnName: "item type",
+     *         operator: "IN",
      *         values: ["bags", "shirts"],
      *         applicability: {
      *             level: "TAB",
@@ -6057,6 +6063,12 @@ export enum HostEvent {
      *     }
      * });
      * ```
+     * Use `columnName` and `operator` - the same spelling as
+     * {@link RuntimeFilter}. The older `column` and `oper` spellings are
+     * deprecated; they are still accepted, but pass only one spelling of each
+     * field, never both. To reapply the filter state captured from
+     * {@link EmbedEvent.FilterChanged}, use `convertFilterChangedToUpdateFiltersPayload`
+     * to convert its payload into the shape expected here.
      * @version SDK: 1.23.0 | ThoughtSpot: 9.4.0.cl
      */
     UpdateFilters = 'updateFilters',
@@ -7053,7 +7065,6 @@ export enum Param {
     IsStarterPromptsEnabled = 'enableStarterPrompts',
     UpdatedSpotterExperience = 'updatedSpotterExperience',
     SpotterDataSources = 'spotterDataSources',
-    AnalystId = 'analystId',
     OpenSpotterOnLiveboardByDefault = 'openSpotterOnLiveboardByDefault',
     ShowAnswerEditPanel = 'showAnswerEditPanel',
 }
@@ -9311,6 +9322,18 @@ export enum Action {
      * ```
      */
     DeleteCollection = 'deleteCollection',
+    /**
+     * Controls the visibility of the "Customize homepage" button on the
+     * embedded home page.
+     * @version SDK: 1.55.0 | ThoughtSpot Cloud: 26.12.0.cl
+     * @example
+     * ```js
+     * {
+     *     hiddenActions: [Action.CustomizeHomepage],
+     * }
+     * ```
+     */
+    CustomizeHomepage = 'customizeHomepage',
 }
 export interface AnswerServiceType {
     getAnswer?: (offset: number, batchSize: number) => any;

package/src/utils/authService/tokenizedAuthService.spec.ts

@@ -79,7 +79,8 @@ describe('fetchPreauthInfoService', () => {
     });
     it('fetchPreauthInfoService if fetch fails', async () => {
         const mockFetch = jest.spyOn(tokenizedFetchModule, 'tokenizedFetch');
-        // Prevent logger.error from reaching console.error (which throws in test env)
+        // Prevent logger.error from reaching console.error (which throws in
+        // test env)
         jest.spyOn(logger, 'error').mockImplementation(() => {});
 
         mockFetch.mockResolvedValueOnce({

package/src/utils/custom-actions.spec.ts

@@ -439,7 +439,8 @@ describe('getCustomActions function', () => {
                 metadataIds: { liveboardIds: ['lb-1'] },
             } as any;
             const result = getCustomActions([action]);
-            // Expect an error containing 'none' for unsupported metadataIds on SPOTTER
+            // Expect an error containing 'none' for unsupported metadataIds on
+            // SPOTTER
             expect(result.errors.some((e) => e.includes('none'))).toBe(true);
         });
 
@@ -452,7 +453,8 @@ describe('getCustomActions function', () => {
                 dataModelIds: { modelIds: ['model-1'] },
             } as any;
             const result = getCustomActions([action]);
-            // Expect an error containing 'none' for unsupported dataModelIds on LIVEBOARD
+            // Expect an error containing 'none' for unsupported dataModelIds
+            // on LIVEBOARD
             expect(result.errors.some((e) => e.includes('none'))).toBe(true);
         });
     });