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

package/src/utils/filterConverter.ts

@@ -0,0 +1,304 @@
+/**
+ * Copyright (c) 2026
+ *
+ * Utility to convert the payload emitted by `EmbedEvent.FilterChanged`
+ * into the payload shape expected by `HostEvent.UpdateFilters`, so that
+ * the current filter state of a Liveboard can be captured and re-applied
+ * later without having to hand-parse the event payload.
+ * @summary Filter payload converter
+ */
+
+import isNil from 'lodash/isNil';
+import { RuntimeFilter, RuntimeFilterOp } from '../types';
+import { Applicability, ApplicabilityLevel } from '../contracts/ui-passthrough-contracts';
+
+export interface FilterChangedFilterContentValue {
+    key?: string | number | boolean | null;
+}
+
+export interface FilterChangedFilterContent {
+    filterType?: string;
+    negate?: boolean;
+    value?: FilterChangedFilterContentValue[];
+}
+
+export interface FilterChangedDateFilterValue {
+    type?: string;
+    op?: string;
+    // The payload is JSON from the embedded app, so absent fields can arrive
+    // as `null` rather than being omitted.
+    epoch?: string | number | null;
+    dateRange?: {
+        lowEpoch?: string | number | null;
+        highEpoch?: string | number | null;
+    };
+    monthName?: string;
+    quarterName?: string;
+    yearName?: string;
+    number?: number | null;
+    datePeriod?: string;
+    includeCurrentPeriod?: boolean | null;
+}
+
+export interface FilterChangedDateFilterContent {
+    negate?: boolean;
+    dateFilter?: FilterChangedDateFilterValue;
+}
+
+export interface FilterChangedFilter {
+    filterContent?: FilterChangedFilterContent[];
+    dateFilterContent?: FilterChangedDateFilterContent[];
+}
+
+export interface FilterChangedFilterGroup {
+    columnInfo?: {
+        name?: string;
+    };
+    filters?: FilterChangedFilter[];
+    /**
+     * Scope of the filter - `LIVEBOARD`, `TAB` or `GROUP`. Present from
+     * SDK 1.53.0 / ThoughtSpot 26.10.0.cl. Omitted means Liveboard level.
+     */
+    applicability?: Applicability;
+}
+
+/**
+ * Shape of the payload received via `LiveboardEmbed.on(EmbedEvent.FilterChanged, ...)`.
+ */
+export interface FilterChangedPayload {
+    liveboardFilters?: FilterChangedFilterGroup[];
+    runtimeFilters?: RuntimeFilter[];
+}
+
+export interface UpdateFiltersFilterParam {
+    columnName: string;
+    operator: string;
+    values: (string | number | boolean | bigint)[];
+    type?: string;
+    datePeriod?: string;
+    negate?: boolean;
+    includeCurrentPeriod?: boolean;
+    applicability?: Applicability;
+}
+
+/**
+ * Shape expected by `liveboardEmbed.trigger(HostEvent.UpdateFilters, ...)`.
+ */
+export interface UpdateFiltersPayload {
+    filters: UpdateFiltersFilterParam[];
+}
+
+type DateFilterValueExtractor = (dateFilter: FilterChangedDateFilterValue) => (string | number)[];
+
+/**
+ * Coerces an epoch/count field to a number, returning `null` when the value is
+ * absent or not a finite number. The payload arrives as JSON from the iframe,
+ * so a missing field can be `null` as well as `undefined`, and `Number(null)`
+ * or `Number('')` would otherwise silently become a valid-looking `0`
+ * (i.e. the Unix epoch, or a zero-length period).
+ * @param value Raw value from the date filter payload.
+ */
+function toFiniteNumber(value: string | number | undefined | null): number | null {
+    if (isNil(value) || value === '') return null;
+    const numericValue = Number(value);
+    return Number.isFinite(numericValue) ? numericValue : null;
+}
+
+const DATE_FILTER_VALUE_EXTRACTORS: Record<string, DateFilterValueExtractor> = {
+    EXACT_DATE: (dateFilter) => {
+        const epoch = toFiniteNumber(dateFilter.epoch);
+        return epoch === null ? [] : [epoch];
+    },
+    EXACT_DATE_RANGE: (dateFilter) => {
+        const { lowEpoch, highEpoch } = dateFilter.dateRange ?? {};
+        const low = toFiniteNumber(lowEpoch);
+        const high = toFiniteNumber(highEpoch);
+        return low === null || high === null ? [] : [low, high];
+    },
+    MONTH_YEAR: (dateFilter) => (
+        dateFilter.monthName && dateFilter.yearName
+            ? [dateFilter.monthName, dateFilter.yearName]
+            : []
+    ),
+    QUARTER_YEAR: (dateFilter) => (
+        dateFilter.quarterName && dateFilter.yearName
+            ? [dateFilter.quarterName, dateFilter.yearName]
+            : []
+    ),
+    YEAR_ONLY: (dateFilter) => (dateFilter.yearName ? [dateFilter.yearName] : []),
+    LAST_N_PERIOD: (dateFilter) => {
+        const count = toFiniteNumber(dateFilter.number);
+        return count === null ? [] : [count];
+    },
+    NEXT_N_PERIOD: (dateFilter) => {
+        const count = toFiniteNumber(dateFilter.number);
+        return count === null ? [] : [count];
+    },
+};
+
+// Date filter types with no `values` (e.g. TODAY needs no operand).
+const PERIOD_ONLY_DATE_FILTER_TYPES = new Set([
+    'THIS_PERIOD', 'PERIOD_TO_DATE', 'TODAY', 'YESTERDAY', 'TOMORROW',
+]);
+
+function convertDateFilterToParam(
+    columnName: string,
+    dateFilterContent: FilterChangedDateFilterContent,
+): UpdateFiltersFilterParam | null {
+    const dateFilter = dateFilterContent?.dateFilter;
+    if (!dateFilter?.type) return null;
+
+    let values: (string | number)[];
+    const getValues = DATE_FILTER_VALUE_EXTRACTORS[dateFilter.type];
+    if (getValues) {
+        values = getValues(dateFilter);
+        // Required fields (e.g. epoch, yearName) are missing - the source data
+        // can't be reconstructed faithfully, so skip rather than emit a filter
+        // that would clear/corrupt this column when re-applied.
+        if (values.length === 0) return null;
+    } else if (PERIOD_ONLY_DATE_FILTER_TYPES.has(dateFilter.type)) {
+        values = [];
+    } else {
+        // Unrecognized date filter type - skip rather than guess.
+        return null;
+    }
+
+    const param: UpdateFiltersFilterParam = {
+        columnName,
+        operator: dateFilter.op ?? RuntimeFilterOp.EQ,
+        values,
+        type: dateFilter.type,
+    };
+    if (dateFilter.datePeriod) {
+        param.datePeriod = dateFilter.datePeriod;
+    }
+    if (!isNil(dateFilter.includeCurrentPeriod)) {
+        param.includeCurrentPeriod = dateFilter.includeCurrentPeriod;
+    }
+    if (dateFilterContent.negate) {
+        param.negate = true;
+    }
+
+    return param;
+}
+
+function convertFilterContentToParam(
+    columnName: string,
+    filterContent: FilterChangedFilterContent,
+): UpdateFiltersFilterParam | null {
+    if (!filterContent?.filterType) return null;
+
+    const values = (filterContent.value ?? [])
+        .map((value) => value?.key)
+        .filter((value): value is string | number | boolean => !isNil(value));
+
+    const param: UpdateFiltersFilterParam = {
+        columnName,
+        operator: filterContent.filterType,
+        values,
+    };
+    if (filterContent.negate) {
+        param.negate = true;
+    }
+
+    return param;
+}
+
+function convertFilterToParams(columnName: string, filter: FilterChangedFilter): UpdateFiltersFilterParam[] {
+    const dateParams = (filter?.dateFilterContent ?? [])
+        .map((dateFilterContent) => convertDateFilterToParam(columnName, dateFilterContent));
+    const contentParams = (filter?.filterContent ?? [])
+        .map((filterContent) => convertFilterContentToParam(columnName, filterContent));
+
+    return [...dateParams, ...contentParams]
+        .filter((param): param is UpdateFiltersFilterParam => param !== null);
+}
+
+/**
+ * Runtime filters need no reshaping, but they still come off the wire as JSON,
+ * so a malformed entry is possible. Skip it rather than pass it through: an
+ * entry missing a column, operator or values array fails
+ * `isValidUpdateFiltersPayload`, and that rejects the *whole* `filters` array,
+ * so one bad runtime filter would drop every other converted filter with it.
+ * @param runtimeFilter A runtime filter from the `FilterChanged` payload.
+ */
+function convertRuntimeFilterToParam(runtimeFilter: RuntimeFilter): UpdateFiltersFilterParam | null {
+    const { columnName, operator, values } = runtimeFilter ?? {};
+    if (typeof columnName !== 'string' || !columnName) return null;
+    if (typeof operator !== 'string' || !operator) return null;
+    if (!Array.isArray(values)) return null;
+
+    return { columnName, operator, values };
+}
+
+/**
+ * Mirrors `isValidApplicability` in `hostEventClient/utils`: a `TAB` or `GROUP`
+ * scope is meaningless without a `targetId`, and `UpdateFilters` rejects the
+ * whole `filters` array when any entry carries a malformed `applicability`.
+ * @param applicability Scope taken from the `FilterChanged` payload.
+ */
+function isUsableApplicability(applicability: Applicability): boolean {
+    const levels: string[] = Object.values(ApplicabilityLevel);
+    if (!levels.includes(applicability.level)) return false;
+    if (applicability.level === ApplicabilityLevel.Liveboard) return true;
+    return typeof applicability.targetId === 'string' && applicability.targetId.trim().length > 0;
+}
+
+function convertFilterGroupToParams(filterGroup: FilterChangedFilterGroup): UpdateFiltersFilterParam[] {
+    const columnName = filterGroup?.columnInfo?.name;
+    if (!columnName) return [];
+
+    const { applicability } = filterGroup;
+    // A filter scoped to a tab or group has to keep that scope. Replaying it
+    // without `applicability` would silently widen it to the whole Liveboard,
+    // changing what every other tab shows. If a scope is present but unusable,
+    // skip the filter: widening is worse than dropping, and a malformed
+    // applicability would fail validation for every other filter alongside it.
+    if (!isNil(applicability) && !isUsableApplicability(applicability)) return [];
+
+    const params = (filterGroup.filters ?? [])
+        .flatMap((filter) => convertFilterToParams(columnName, filter));
+
+    return isNil(applicability) ? params : params.map((param) => ({ ...param, applicability }));
+}
+
+/**
+ * Converts the payload emitted by {@link EmbedEvent.FilterChanged} into the
+ * payload shape expected by {@link HostEvent.UpdateFilters}, so the same
+ * filter state can be captured and re-applied later, for example on a
+ * subsequent page load.
+ *
+ * Both the Liveboard filters and the runtime filters present in the
+ * `FilterChanged` payload are included in the returned `filters` array.
+ *
+ * Note: a column with multiple date-filter conditions (e.g. an OR of two
+ * date ranges) is not guaranteed to round-trip losslessly - `HostEvent.UpdateFilters`
+ * treats date filters as replace-not-merge per column, so only the last
+ * converted entry for such a column will apply.
+ * @param filterChangedPayload The filter state carried by the
+ * `EmbedEvent.FilterChanged` callback, which is `payload.data` - the
+ * callback argument is the event envelope, and the filters sit under its
+ * `data` key.
+ * @example
+ * ```js
+ * let savedFilters;
+ * liveboardEmbed.on(EmbedEvent.FilterChanged, (payload) => {
+ *     savedFilters = convertFilterChangedToUpdateFiltersPayload(payload.data);
+ * });
+ *
+ * // later, e.g. after a fresh page load
+ * liveboardEmbed.trigger(HostEvent.UpdateFilters, savedFilters);
+ * ```
+ */
+export function convertFilterChangedToUpdateFiltersPayload(
+    filterChangedPayload: FilterChangedPayload,
+): UpdateFiltersPayload {
+    const liveboardFilterParams = (filterChangedPayload?.liveboardFilters ?? [])
+        .flatMap(convertFilterGroupToParams);
+
+    const runtimeFilterParams = (filterChangedPayload?.runtimeFilters ?? [])
+        .map(convertRuntimeFilterToParam)
+        .filter((param): param is UpdateFiltersFilterParam => param !== null);
+
+    return { filters: [...liveboardFilterParams, ...runtimeFilterParams] };
+}

package/src/utils/processData.spec.ts

@@ -311,7 +311,8 @@ describe('Unit test for process data', () => {
         } as any);
         const el: any = {};
         processDataInstance.processEventData(e.type, e, '', el);
-        // isEmbeddedSSOInfoFailure=true so neither branch fires, innerHTML stays unset
+        // isEmbeddedSSOInfoFailure=true so neither branch fires, innerHTML
+        // stays unset
         expect(el.innerHTML).toBeUndefined();
         expect(base.notifyAuthFailure).not.toHaveBeenCalled();
     });

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();
+        });
+    });
+});