@thoughtspot/visual-embed-sdk 1.52.0 → 1.52.1

package/src/utils/processTrigger.ts

@@ -1,8 +1,11 @@
-import { ERROR_MESSAGE } from '../errors';
-import { ContextType, HostEvent, MessagePayload } from '../types';
+import { ContextType, HostEvent } from '../types';
 import { logger } from '../utils/logger';
 import { handlePresentEvent } from '../utils';
 import { getEmbedConfig } from '../embed/embedConfig';
+import {
+    MESSAGE_RESPONSE_TIMEOUT,
+    sendMessageWithResponse,
+} from './transport/iframe-transport';
 
 /**
  * Reloads the ThoughtSpot iframe.
@@ -16,29 +19,12 @@ export const reload = (iFrame: HTMLIFrameElement) => {
     }, 100);
 };
 
-/**
- * Post iframe message.
- * @param iFrame
- * @param message
- * @param message.type
- * @param message.data
- * @param message.context
- * @param thoughtSpotHost
- * @param channel
- */
-function postIframeMessage(
-    iFrame: HTMLIFrameElement,
-    message: { type: HostEvent; data: any, context?: any },
-    thoughtSpotHost: string,
-    channel?: MessageChannel,
-) {
-    return iFrame.contentWindow?.postMessage(message, thoughtSpotHost, [channel?.port2]);
-}
-
-export const TRIGGER_TIMEOUT = 30000;
+export const TRIGGER_TIMEOUT = MESSAGE_RESPONSE_TIMEOUT;
 
 /**
- *
+ * Processes a host event trigger: handles SDK-local events (Reload,
+ * Present) and forwards everything else to the embedded app over the
+ * iframe transport.
  * @param iFrame
  * @param messageType
  * @param thoughtSpotHost
@@ -52,42 +38,26 @@ export function processTrigger(
     data: any,
     context?: ContextType,
 ): Promise<any> {
-    return new Promise<any>((res, rej) => {
-        if (messageType === HostEvent.Reload) {
-            reload(iFrame);
-            return res(null);
-        }
-        
-        if (messageType === HostEvent.Present) {
-            const embedConfig = getEmbedConfig();
-            const disableFullscreenPresentation = embedConfig?.disableFullscreenPresentation ?? true;
-            
-            if (!disableFullscreenPresentation) {
-                handlePresentEvent(iFrame);
-            } else {
-                logger.warn('Fullscreen presentation mode is disabled. Set disableFullscreenPresentation: false to enable this feature.');
-            }
-        }
-        
-        const channel = new MessageChannel();
+    if (messageType === HostEvent.Reload) {
+        reload(iFrame);
+        return Promise.resolve(null);
+    }
 
-        // Close the messageChannel and resolve the promise if timeout.
-        const timeoutId = setTimeout(() => {
-            channel.port1.close();
-            res(new Error(ERROR_MESSAGE.TRIGGER_TIMED_OUT));
-        }, TRIGGER_TIMEOUT);
+    if (messageType === HostEvent.Present) {
+        const embedConfig = getEmbedConfig();
+        const disableFullscreenPresentation = embedConfig?.disableFullscreenPresentation ?? true;
 
-        channel.port1.onmessage = ({ data: responseData }) => {
-            clearTimeout(timeoutId);
-            channel.port1.close();
-            const error = responseData?.error || responseData?.data?.error;
-            if (error) {
-                rej(error);
-            } else {
-                res(responseData);
-            }
-        };
+        if (!disableFullscreenPresentation) {
+            handlePresentEvent(iFrame);
+        } else {
+            logger.warn('Fullscreen presentation mode is disabled. Set disableFullscreenPresentation: false to enable this feature.');
+        }
+    }
 
-        return postIframeMessage(iFrame, { type: messageType, data, context }, thoughtSpotHost, channel);
-    });
+    return sendMessageWithResponse(
+        iFrame,
+        { type: messageType, data, context },
+        thoughtSpotHost,
+        TRIGGER_TIMEOUT,
+    );
 }

package/src/utils/transport/iframe-transport.spec.ts

@@ -0,0 +1,177 @@
+import {
+    MESSAGE_RESPONSE_TIMEOUT,
+    resolveMessageOrigin,
+    isMessageFromIframe,
+    postMessageToIframe,
+    sendMessageWithResponse,
+} from './iframe-transport';
+import { logger } from '../logger';
+import { ERROR_MESSAGE } from '../../errors';
+
+describe('iframe-transport', () => {
+    describe('resolveMessageOrigin', () => {
+        it('returns the origin (scheme://host[:port]) for a valid host URL', () => {
+            expect(resolveMessageOrigin('https://my.thoughtspot.com')).toBe(
+                'https://my.thoughtspot.com',
+            );
+            expect(
+                resolveMessageOrigin('https://host.example.com:8443/some/path'),
+            ).toBe('https://host.example.com:8443');
+        });
+
+        it('returns null when the host cannot be parsed', () => {
+            expect(resolveMessageOrigin('not-a-url')).toBeNull();
+            expect(resolveMessageOrigin('')).toBeNull();
+        });
+    });
+
+    describe('isMessageFromIframe', () => {
+        const host = 'https://ts.example.com';
+        const contentWindow = {} as Window;
+        const iFrame = { contentWindow } as HTMLIFrameElement;
+
+        it('rejects a message whose source is not the iframe window', () => {
+            const event = { source: {}, origin: host } as unknown as MessageEvent;
+            expect(isMessageFromIframe(event, iFrame, host)).toBe(false);
+        });
+
+        it('accepts a message from the iframe window with a matching origin', () => {
+            const event = { source: contentWindow, origin: host } as unknown as MessageEvent;
+            expect(isMessageFromIframe(event, iFrame, host)).toBe(true);
+        });
+
+        it('rejects (and warns) when the origin does not match the expected host', () => {
+            const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
+            const event = {
+                source: contentWindow,
+                origin: 'https://evil.example.com',
+            } as unknown as MessageEvent;
+
+            expect(isMessageFromIframe(event, iFrame, host)).toBe(false);
+            expect(warnSpy).toHaveBeenCalledTimes(1);
+            warnSpy.mockRestore();
+        });
+
+        it('fails open (accepts) when the expected origin cannot be resolved', () => {
+            const event = {
+                source: contentWindow,
+                origin: 'https://anything.example.com',
+            } as unknown as MessageEvent;
+            // 'garbage-host' is unparseable → origin check is skipped.
+            expect(isMessageFromIframe(event, iFrame, 'garbage-host')).toBe(true);
+        });
+
+        it('accepts when the message origin is empty', () => {
+            const event = { source: contentWindow, origin: '' } as unknown as MessageEvent;
+            expect(isMessageFromIframe(event, iFrame, host)).toBe(true);
+        });
+
+        it('rejects when the iframe is not set', () => {
+            const event = { source: contentWindow, origin: host } as unknown as MessageEvent;
+            expect(
+                isMessageFromIframe(event, null as unknown as HTMLIFrameElement, host),
+            ).toBe(false);
+        });
+    });
+
+    describe('postMessageToIframe', () => {
+        const host = 'https://ts.example.com';
+        const message = { type: 'someEvent', data: { a: 1 } };
+
+        it('posts with no transferables when no channel is provided', () => {
+            const postMessage = jest.fn();
+            const iFrame = { contentWindow: { postMessage } } as unknown as HTMLIFrameElement;
+
+            postMessageToIframe(iFrame, message, host);
+
+            expect(postMessage).toHaveBeenCalledWith(message, host, []);
+        });
+
+        it('transfers the channel port2 when a channel is provided', () => {
+            const postMessage = jest.fn();
+            const iFrame = { contentWindow: { postMessage } } as unknown as HTMLIFrameElement;
+            const port2 = {} as MessagePort;
+            const channel = { port2 } as MessageChannel;
+
+            postMessageToIframe(iFrame, message, host, channel);
+
+            expect(postMessage).toHaveBeenCalledWith(message, host, [port2]);
+        });
+
+        it('is a no-op when the iframe has no contentWindow', () => {
+            const iFrame = { contentWindow: null } as unknown as HTMLIFrameElement;
+            expect(() => postMessageToIframe(iFrame, message, host)).not.toThrow();
+        });
+    });
+
+    describe('sendMessageWithResponse', () => {
+        const host = 'https://ts.example.com';
+        const message = { type: 'trigger', data: {} };
+        let port1: { onmessage: ((e: { data: any }) => void) | null; close: jest.Mock };
+        let port2: MessagePort;
+        let postMessage: jest.Mock;
+        let iFrame: HTMLIFrameElement;
+        let OriginalMessageChannel: typeof MessageChannel;
+
+        beforeEach(() => {
+            port1 = { onmessage: null, close: jest.fn() };
+            port2 = {} as MessagePort;
+            OriginalMessageChannel = global.MessageChannel;
+            (global as any).MessageChannel = jest.fn(() => ({ port1, port2 }));
+            postMessage = jest.fn();
+            iFrame = { contentWindow: { postMessage } } as unknown as HTMLIFrameElement;
+        });
+
+        afterEach(() => {
+            global.MessageChannel = OriginalMessageChannel;
+        });
+
+        it('exposes the default response timeout', () => {
+            expect(MESSAGE_RESPONSE_TIMEOUT).toBe(30000);
+        });
+
+        it('posts the message with the channel port and resolves with the response', async () => {
+            const promise = sendMessageWithResponse(iFrame, message, host);
+
+            expect(postMessage).toHaveBeenCalledWith(message, host, [port2]);
+
+            // Simulate the app posting a response back on the channel — the
+            // handler resolves with the event's `data` payload.
+            port1.onmessage?.({ data: { value: 'ok' } });
+
+            await expect(promise).resolves.toEqual({ value: 'ok' });
+            expect(port1.close).toHaveBeenCalled();
+        });
+
+        it('rejects when the response carries a top-level error', async () => {
+            const promise = sendMessageWithResponse(iFrame, message, host);
+            port1.onmessage?.({ data: { error: 'boom' } });
+            await expect(promise).rejects.toBe('boom');
+        });
+
+        it('rejects when the error is nested under data', async () => {
+            const promise = sendMessageWithResponse(iFrame, message, host);
+            port1.onmessage?.({ data: { data: { error: 'nested-boom' } } });
+            await expect(promise).rejects.toBe('nested-boom');
+        });
+
+        it('resolves with an empty response when no data is returned', async () => {
+            const promise = sendMessageWithResponse(iFrame, message, host);
+            port1.onmessage?.({ data: undefined });
+            await expect(promise).resolves.toBeUndefined();
+        });
+
+        it('resolves with a timeout Error when no response arrives in time', async () => {
+            jest.useFakeTimers();
+            const promise = sendMessageWithResponse(iFrame, message, host, 100);
+
+            jest.advanceTimersByTime(100);
+
+            const result = await promise;
+            expect(result).toBeInstanceOf(Error);
+            expect((result as Error).message).toBe(ERROR_MESSAGE.TRIGGER_TIMED_OUT);
+            expect(port1.close).toHaveBeenCalled();
+            jest.useRealTimers();
+        });
+    });
+});

package/src/utils/transport/iframe-transport.ts

@@ -0,0 +1,122 @@
+/**
+ * Copyright (c) 2026
+ *
+ * Dedicated transport layer for SDK <-> ThoughtSpot iframe messaging.
+ *
+ * Owns the postMessage/MessageChannel mechanics and origin resolution so
+ * that embed/business logic (ts-embed.ts, hostEventClient) never touches
+ * the wire directly. The wire format is unchanged from the historical
+ * implementation — this layer is a pure structural extraction.
+ */
+import { ERROR_MESSAGE } from '../../errors';
+import { logger } from '../logger';
+
+/**
+ * Default time to wait for the app to respond to a request-response
+ * message before giving up and reclaiming the channel.
+ */
+export const MESSAGE_RESPONSE_TIMEOUT = 30000;
+
+/**
+ * Single implementation of origin resolution for the embedded app.
+ * Returns the origin (scheme://host[:port]) for a ThoughtSpot host URL,
+ * or null when it cannot be parsed.
+ * @param thoughtSpotHost
+ */
+export const resolveMessageOrigin = (thoughtSpotHost: string): string | null => {
+    try {
+        return new URL(thoughtSpotHost).origin;
+    } catch (e) {
+        return null;
+    }
+};
+
+/**
+ * Validates that an inbound window message came from the embedded
+ * ThoughtSpot app: the source window must be the embed iframe's window and,
+ * when the expected origin is resolvable, the message origin must match it.
+ *
+ * Fails open (returns true) on the origin check when the expected origin
+ * cannot be resolved, to avoid breaking unconventional-but-working setups;
+ * a warning is logged on mismatch either way.
+ * @param event The message event received on window.
+ * @param iFrame The embed iframe the message should originate from.
+ * @param thoughtSpotHost The configured ThoughtSpot host.
+ */
+export const isMessageFromIframe = (
+    event: MessageEvent,
+    iFrame: HTMLIFrameElement,
+    thoughtSpotHost: string,
+): boolean => {
+    if (event.source !== iFrame?.contentWindow) {
+        return false;
+    }
+    const expectedOrigin = resolveMessageOrigin(thoughtSpotHost);
+    if (expectedOrigin && event.origin && event.origin !== expectedOrigin) {
+        logger.warn(
+            `Dropped message from unexpected origin ${event.origin}; expected ${expectedOrigin}`,
+        );
+        return false;
+    }
+    return true;
+};
+
+/**
+ * Posts a one-way message to the embedded app's iframe, optionally
+ * transferring a MessageChannel port for the response.
+ * @param iFrame
+ * @param message
+ * @param thoughtSpotHost Used as the postMessage targetOrigin.
+ * @param channel
+ */
+export const postMessageToIframe = (
+    iFrame: HTMLIFrameElement,
+    message: { type: string; data: any; context?: any },
+    thoughtSpotHost: string,
+    channel?: MessageChannel,
+): void => iFrame.contentWindow?.postMessage(
+    message,
+    thoughtSpotHost,
+    channel ? [channel.port2] : [],
+);
+
+/**
+ * Sends a request-response message to the embedded app over a dedicated
+ * MessageChannel. Resolves with the response payload; rejects when the app
+ * responds with an error; resolves with a timeout Error object when no
+ * response arrives in time (historical behavior, preserved for backward
+ * compatibility).
+ * @param iFrame
+ * @param message
+ * @param thoughtSpotHost
+ * @param timeoutMs
+ */
+export function sendMessageWithResponse(
+    iFrame: HTMLIFrameElement,
+    message: { type: string; data: any; context?: any },
+    thoughtSpotHost: string,
+    timeoutMs: number = MESSAGE_RESPONSE_TIMEOUT,
+): Promise<any> {
+    return new Promise<any>((res, rej) => {
+        const channel = new MessageChannel();
+
+        // Close the messageChannel and resolve the promise if timeout.
+        const timeoutId = setTimeout(() => {
+            channel.port1.close();
+            res(new Error(ERROR_MESSAGE.TRIGGER_TIMED_OUT));
+        }, timeoutMs);
+
+        channel.port1.onmessage = ({ data: responseData }) => {
+            clearTimeout(timeoutId);
+            channel.port1.close();
+            const error = responseData?.error || responseData?.data?.error;
+            if (error) {
+                rej(error);
+            } else {
+                res(responseData);
+            }
+        };
+
+        postMessageToIframe(iFrame, message, thoughtSpotHost, channel);
+    });
+}

package/src/utils.spec.ts

@@ -32,6 +32,7 @@ import {
     deepMerge,
     getHostEventsConfig,
     isWindowUndefined,
+    calculateElementCenter,
     getOffsetTop,
     getDOMNode,
     getOperationNameFromQuery,
@@ -1319,6 +1320,76 @@ describe('isWindowUndefined', () => {
 // ---------------------------------------------------------------------------
 // getOffsetTop
 // ---------------------------------------------------------------------------
+describe('calculateElementCenter', () => {
+    const setViewport = (scrollY: number, innerHeight: number) => {
+        Object.defineProperty(window, 'scrollY', { value: scrollY, configurable: true });
+        Object.defineProperty(window, 'innerHeight', { value: innerHeight, configurable: true });
+    };
+
+    const mockElement = (offsetTop: number, offsetHeight: number) => ({
+        getBoundingClientRect: () => ({ top: offsetTop - window.scrollY }),
+        offsetHeight,
+    }) as unknown as HTMLElement;
+
+    test('centers on the element when it is shorter than the viewport', () => {
+        setViewport(0, 1000);
+        // Element sits at the top of the page and is 400px tall, fully visible.
+        const result = calculateElementCenter(mockElement(0, 400));
+        expect(result).toEqual({
+            iframeCenter: 200,
+            iframeScrolled: 0,
+            iframeHeight: 400,
+            viewPortHeight: 1000,
+            iframeVisibleViewPort: 400,
+        });
+    });
+
+    test('centers on the visible slice when the element is taller than the viewport', () => {
+        setViewport(0, 600);
+        // 2000px element, only the top 600px is on screen.
+        const result = calculateElementCenter(mockElement(0, 2000));
+        expect(result.iframeVisibleViewPort).toBe(600);
+        expect(result.iframeCenter).toBe(300);
+        expect(result.iframeScrolled).toBe(0);
+    });
+
+    test('tracks the center as the page scrolls into the element', () => {
+        setViewport(500, 600);
+        // Scrolled 500px into a 2000px element that starts at the page top.
+        const result = calculateElementCenter(mockElement(0, 2000));
+        expect(result.iframeScrolled).toBe(500);
+        // 600px still visible, offset by the 500px already scrolled past.
+        expect(result.iframeVisibleViewPort).toBe(600);
+        expect(result.iframeCenter).toBe(800);
+    });
+
+    test('clamps the visible slice to what is left of the element', () => {
+        setViewport(1800, 600);
+        // Only the last 200px of the 2000px element remains below the fold.
+        const result = calculateElementCenter(mockElement(0, 2000));
+        expect(result.iframeVisibleViewPort).toBe(200);
+        expect(result.iframeCenter).toBe(1900);
+    });
+
+    test('measures only the on-screen part when the element starts below the fold', () => {
+        setViewport(0, 1000);
+        // Element begins 800px down, so 200px of it is visible.
+        const result = calculateElementCenter(mockElement(800, 400));
+        expect(result.iframeScrolled).toBe(-800);
+        expect(result.iframeVisibleViewPort).toBe(200);
+        expect(result.iframeCenter).toBe(100);
+    });
+
+    test('never reports more visible height than the element has', () => {
+        setViewport(0, 1000);
+        // Element is 100px tall and starts 200px down: the viewport has room to
+        // spare, so the visible slice is the element itself, not the gap.
+        const result = calculateElementCenter(mockElement(200, 100));
+        expect(result.iframeVisibleViewPort).toBe(100);
+        expect(result.iframeCenter).toBe(50);
+    });
+});
+
 describe('getOffsetTop', () => {
     test('returns rect.top + window.scrollY', () => {
         const mockElement = {

package/src/utils.ts

@@ -776,3 +776,41 @@ export const setParamIfDefined = <T>(
         queryParams[param] = asBoolean ? !!value : value;
     }
 };
+
+/**
+ * Calculates the element center for the currently visible viewport of the
+ * element, using the scroll position of the host app, the offsetTop of the
+ * element in the host app, and the viewport height of the tab.
+ *
+ * The returned keys are sent to the ThoughtSpot app over postMessage, so they
+ * are named after the iframe and must not be renamed.
+ * @param element The element to measure
+ * @returns The element center within the visible viewport, the element height,
+ * and the viewport height.
+ */
+export const calculateElementCenter = (element: HTMLElement) => {
+    const offsetTopClient = getOffsetTop(element);
+    const scrollTopClient = window.scrollY;
+    const viewPortHeight = window.innerHeight;
+    const iframeHeight = element.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,
+    };
+};