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

package/src/embed/ts-embed.ts

@@ -10,20 +10,26 @@ import isEqual from 'lodash/isEqual';
 import isEmpty from 'lodash/isEmpty';
 import isObject from 'lodash/isObject';
 import {
-    HostEventRequest,
-    TriggerPayload,
-    TriggerResponse,
     UIPassthroughArrayResponse,
     UIPassthroughEvent,
     UIPassthroughRequest,
-} from './hostEventClient/contracts';
+} from '../contracts/ui-passthrough-contracts';
+// Contract resolution comes from the shared contracts module (the single
+// source of truth for event payload shapes) rather than the legacy
+// UI-passthrough-only mapping.
+import {
+    HostEventRequest,
+    TriggerData,
+    TriggerResponse,
+} from '../contracts/host-event-contracts';
+import { EmbedEventPayload } from '../contracts/embed-event-payloads';
+import { isMessageFromIframe } from '../utils/transport/iframe-transport';
 import { logger } from '../utils/logger';
 import { getAuthenticationToken } from '../authToken';
 import { AnswerService } from '../utils/graphql/answerService/answerService';
 import {
     getEncodedQueryParamsString,
     getCssDimension,
-    getOffsetTop,
     embedEventStatus,
     setAttributes,
     getCustomisations,
@@ -110,6 +116,66 @@ const TS_EMBED_ID = '_thoughtspot-embed';
 const PRERENDER_CONTAINER_ORIGINAL_POSITION_KEY = 'tsEmbedOriginalPosition';
 const PRERENDER_WRAPPER_ID_PREFIX = 'tsEmbed-pre-render-wrapper-';
 
+// The container applies UpdateEmbedParams through React state, so a delivered
+// 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 {}.
+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
@@ -142,6 +208,8 @@ export class TsEmbed {
      */
     protected embedNodeKey = '__tsEmbed';
 
+    protected embedContainerLoadedKey = '__tsEmbedContainerLoaded';
+
     protected isAppInitialized = false;
 
     /**
@@ -439,7 +507,7 @@ export class TsEmbed {
         const eventType = this.getEventType(event);
         const eventPort = this.getEventPort(event);
         const eventData = this.formatEventData(event, eventType);
-        if (event.source === this.iFrame.contentWindow) {
+        if (isMessageFromIframe(event, this.iFrame, this.thoughtSpotHost)) {
             const processedEventData = processEventData(
                 eventType,
                 eventData,
@@ -720,7 +788,19 @@ export class TsEmbed {
             queryParams[key] = deserializeParam(queryParams[key]);
         });
         const appInitData = await this.getAppInitData();
-        return { ...this.viewConfig, ...queryParams, ...appInitData };
+        return {
+            ...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.
+            runtimeFilterParams:
+                getFilterQuery(this.viewConfig.runtimeFilters ?? []) || NO_RUNTIME_PARAMS,
+            runtimeParameterParams:
+                getRuntimeParameters(this.viewConfig.runtimeParameters ?? [])
+                || NO_RUNTIME_PARAMS,
+        };
     }
 
     /**
@@ -921,7 +1001,7 @@ export class TsEmbed {
     }
 
     protected getEmbedParams() {
-        const queryParams = this.getEmbedParamsObject();
+        const queryParams = this.getUrlQueryParamsObject();
         return getQueryParamString(queryParams);
     }
 
@@ -930,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);
@@ -1125,6 +1215,8 @@ export class TsEmbed {
         return preRenderWrapper;
     }
 
+    // TODO(SCAL-338011): move the pre-render code out to its own file, the way
+    // full height did. It is spread across this class and getting messy.
     protected preRenderWrapper: HTMLElement;
 
     protected preRenderChild: HTMLElement;
@@ -1470,41 +1562,6 @@ export class TsEmbed {
         return V1EventMap[eventType] || eventType;
     }
 
-    /**
-     * Calculates the iframe center for the current visible viewPort
-     * of iframe using Scroll position of Host App, offsetTop for iframe
-     * in Host app. ViewPort height of the tab.
-     * @returns iframe Center in visible viewport,
-     *  Iframe height,
-     *  View port height.
-     */
-    protected getIframeCenter() {
-        const offsetTopClient = getOffsetTop(this.iFrame);
-        const scrollTopClient = window.scrollY;
-        const viewPortHeight = window.innerHeight;
-        const iframeHeight = this.iFrame.offsetHeight;
-        const iframeScrolled = scrollTopClient - offsetTopClient;
-        let iframeVisibleViewPort;
-        let iframeOffset;
-
-        if (iframeScrolled < 0) {
-            iframeVisibleViewPort = viewPortHeight - (offsetTopClient - scrollTopClient);
-            iframeVisibleViewPort = Math.min(iframeHeight, iframeVisibleViewPort);
-            iframeOffset = 0;
-        } else {
-            iframeVisibleViewPort = Math.min(iframeHeight - iframeScrolled, viewPortHeight);
-            iframeOffset = iframeScrolled;
-        }
-        const iframeCenter = iframeOffset + iframeVisibleViewPort / 2;
-        return {
-            iframeCenter,
-            iframeScrolled,
-            iframeHeight,
-            viewPortHeight,
-            iframeVisibleViewPort,
-        };
-    }
-
     /**
      * Registers an event listener to trigger an alert when the ThoughtSpot app
      * sends an event of a particular message type to the host application.
@@ -1528,9 +1585,12 @@ export class TsEmbed {
      * });
      * ```
      */
-    public on(
-        messageType: EmbedEvent,
-        callback: MessageCallback,
+    public on<EmbedEventT extends EmbedEvent>(
+        messageType: EmbedEventT,
+        callback: (
+            payload: EmbedEventPayload<EmbedEventT>,
+            responder?: (data: any) => void,
+        ) => void,
         options: MessageOptions = { start: false },
         isRegisteredBySDK = false,
     ): typeof TsEmbed.prototype {
@@ -1608,14 +1668,35 @@ export class TsEmbed {
     protected getPreRenderObj<T extends TsEmbed>(): T {
         const embedObj = (this.preRenderWrapper as any)?.[this.embedNodeKey] as T;
         if (embedObj === (this as any)) {
-            logger.info('embedObj is same as this');
+            logger.debug('embedObj is same as this');
         }
         return embedObj;
     }
 
+    protected takeOverPreRender(): void {
+        if (!this.preRenderWrapper) return;
+        (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.
+    private markEmbedContainerLoaded() {
+        this.isEmbedContainerLoaded = true;
+        if (this.preRenderWrapper) {
+            (this.preRenderWrapper as any)[this.embedContainerLoadedKey] = true;
+        }
+    }
+
     private checkEmbedContainerLoaded() {
         if (this.isEmbedContainerLoaded) return true;
 
+        if ((this.preRenderWrapper as any)?.[this.embedContainerLoadedKey]) {
+            this.isEmbedContainerLoaded = true;
+            return true;
+        }
+
+        // Older builds stamped the flag on the instance, not the wrapper.
         const preRenderObj = this.getPreRenderObj<TsEmbed>();
         if (preRenderObj && preRenderObj.isEmbedContainerLoaded) {
             this.isEmbedContainerLoaded = true;
@@ -1648,24 +1729,32 @@ export class TsEmbed {
         (source: EmbedEvent.AuthInit | EmbedEvent.EmbedListenerReady) => () => {
             const processEmbedContainerReady = () => {
                 logger.debug('processEmbedContainerReady');
-                this.isEmbedContainerLoaded = true;
+                this.markEmbedContainerLoaded();
                 this.executeEmbedContainerReadyCallbacks();
             };
             if (source === EmbedEvent.AuthInit) {
                 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();
+                }
             }
         };
 
     /**
      * Triggers an event to the embedded app
+     *
+     * Payload typing: from SDK 1.52.0 (ThoughtSpot Cloud 26.9.0.cl), unknown fields
+     * on a known event's payload fail to compile. From SDK 1.54.0 (26.11.0.cl) the
+     * payload is checked strictly against the event contract — update call sites now.
      * @param {HostEvent} messageType The event type
-     * @param {any} data The payload to send with the message
+     * @param {TriggerData} data The payload, typed against the event's contract
      * @param {ContextType} context Optional context type to specify the context from which the event is triggered.
      * Use ContextType.Search for search answer context, ContextType.Answer for answer/explore context,
      * ContextType.Liveboard for liveboard context, or ContextType.Spotter for spotter context.
@@ -1688,7 +1777,10 @@ export class TsEmbed {
         ContextT extends ContextType = ContextType,
     >(
         messageType: HostEventT,
-        data: TriggerPayload<PayloadT, HostEventT> = {} as any,
+        // Contract shape is the contextual type: payload fields autocomplete
+        // and unknown fields on object literals are flagged. Strict checks
+        // land in SDK 1.54.0 — see TriggerData.
+        data: TriggerData<HostEventT> = {} as any,
         context?: ContextT,
     ): Promise<TriggerResponse<PayloadT, HostEventT, ContextT>> {
         uploadMixpanelEvent(`${MIXPANEL_EVENT.VISUAL_SDK_TRIGGER}-${messageType}`);
@@ -2015,24 +2107,49 @@ export class TsEmbed {
         return this.renderIFrame(prerenderFrameSrc);
     }
 
+    // Subclasses that navigate the pre-render on show must await this before
+    // 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
         // this.validatePreRenderViewConfig(this.viewConfig); removed in #517
         logger.debug('triggering UpdateEmbedParams', this.viewConfig);
-        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,
-                });
-            }
+        // Created synchronously: a queued navigation needs something to await
+        // whether the container is already loaded or not.
+        this.preRenderParamsApplied = new Promise<void>((resolve) => {
+            this.executeAfterEmbedContainerLoaded(async () => {
+                try {
+                    await this.triggerUpdateEmbedParams();
+                } finally {
+                    setTimeout(resolve, UPDATE_EMBED_PARAMS_SETTLE_MS);
+                }
+            });
         });
     }
 
@@ -2065,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;
@@ -2075,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);
@@ -2119,6 +2238,10 @@ export class TsEmbed {
             this.setupFullscreenChangeHandler();
         }
 
+        // Last, so everything above still sees the instance being taken over
+        // from.
+        this.takeOverPreRender();
+
         return this;
     }
 
@@ -2339,12 +2462,18 @@ export class V1Embed extends TsEmbed {
      * });
      * ```
      */
-    public on(
-        messageType: EmbedEvent,
-        callback: MessageCallback,
+    public on<EmbedEventT extends EmbedEvent>(
+        messageType: EmbedEventT,
+        callback: (
+            payload: EmbedEventPayload<EmbedEventT>,
+            responder?: (data: any) => void,
+        ) => void,
         options: MessageOptions = { start: false },
     ): typeof TsEmbed.prototype {
-        const eventType = this.getCompatibleEventType(messageType);
+        // Mirror the base TsEmbed.on generic signature so the enriched
+        // EmbedEventPayload (e.g. CustomAction's answerService) flows through
+        // the override too, and the class hierarchy stays assignable.
+        const eventType = this.getCompatibleEventType(messageType) as EmbedEventT;
         return super.on(eventType, callback, options);
     }
 

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',
 };