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

package/src/contracts/host-event-contracts.ts

@@ -168,23 +168,67 @@ export interface UpdateCrossFilterRequest {
 }
 
 /**
- * A single filter entry for {@link HostEvent.UpdateFilters}. Supports both
- * the current (columnName/operator) and legacy (column/oper) field names.
+ * The column to filter on. Supply `columnName`. A filter with no column is
+ * rejected at runtime, and passing both spellings silently discards the
+ * `column` one.
+ *
+ * When several columns share a name, qualify it as
+ * `WORKSHEET_NAME::COLUMN_NAME`, for example
+ * `"(Sample) Retail - Apparel::city"`.
  */
-export interface HostFilterUpdate {
-    columnName?: string;
+export type HostFilterUpdateColumn =
+    | {
+        /**
+         * Name of the column to filter on, optionally qualified as
+         * `WORKSHEET_NAME::COLUMN_NAME`.
+         */
+        columnName: string;
+        column?: never;
+    }
+    | {
+        /**
+         * @deprecated Use `columnName`, which matches {@link RuntimeFilter} and
+         * the rest of the SDK. Still accepted, but not alongside `columnName`.
+         */
+        column: string;
+        columnName?: never;
+    };
+
+/**
+ * The filter operator. Supply `operator`. A filter with no operator is
+ * rejected at runtime, and passing both spellings silently discards the
+ * `oper` one.
+ */
+export type HostFilterUpdateOperator =
+    | {
+        /** Filter operator, for example EQ, IN, CONTAINS. */
+        operator: string;
+        oper?: never;
+    }
+    | {
+        /**
+         * @deprecated Use `operator`, which matches {@link RuntimeFilter} and
+         * the rest of the SDK. Still accepted, but not alongside `operator`.
+         */
+        oper: string;
+        operator?: never;
+    };
+
+/**
+ * A single filter entry for {@link HostEvent.UpdateFilters}.
+ *
+ * Use `columnName` and `operator` - the spelling used by
+ * {@link RuntimeFilter} and by the payload
+ * `convertFilterChangedToUpdateFiltersPayload` produces.
+ */
+export type HostFilterUpdate = HostFilterUpdateColumn & HostFilterUpdateOperator & {
     columnId?: string;
-    operator?: string;
-    values: Array<string | number | boolean>;
+    values: Array<string | number | boolean | bigint>;
     type?: string;
     datePeriod?: string;
     negate?: boolean;
-    /** Legacy field name for columnName. */
-    column?: string;
-    /** Legacy field name for operator. */
-    oper?: string;
     applicability?: Applicability;
-}
+};
 
 /**
  * Request payload for {@link HostEvent.UpdateFilters} (singular or plural

package/src/embed/app.spec.ts

@@ -375,6 +375,21 @@ describe('App embed tests', () => {
         });
     });
 
+    test('should hide the Customize homepage button via hiddenActions', async () => {
+        const appEmbed = new AppEmbed(getRootEl(), {
+            ...defaultViewConfig,
+            hiddenActions: [Action.CustomizeHomepage],
+        } as AppViewConfig);
+
+        appEmbed.render();
+        await executeAfterWait(() => {
+            expectUrlMatchesWithParams(
+                getIFrameSrc(),
+                `http://${thoughtSpotHost}/?embedApp=true&primaryNavHidden=true&profileAndHelpInNavBarHidden=false&hideHomepageLeftNav=false&navigationVersion=v3&homepageVersion=v3&${defaultParamsWithoutHiddenActions}&hideAction=[%22${Action.ReportError}%22,%22customizeHomepage%22]${defaultParamsPost}#/home`,
+            );
+        });
+    });
+
     test('should set enable2ColumnLayout to true in url', async () => {
         const appEmbed = new AppEmbed(getRootEl(), {
             ...defaultViewConfig,

package/src/embed/app.ts

@@ -608,9 +608,10 @@ export interface AppViewConfig extends AllEmbedViewConfig, FullHeightViewConfig
     isPNGInScheduledEmailsEnabled?: boolean;
 
     /**
-     * Enables the 'what you see is what you get' PDF export for Liveboards. Each tab is rendered on a single page
-     * following the exact UI layout, instead of splitting visualizations across multiple A4 pages.
-     * This feature is GA from SDK version 1.51.0 and ThoughtSpot version 26.8.0.cl.
+     * Enables the 'what you see is what you get' PDF export for Liveboards. Each tab is
+     * rendered on a single page following the exact UI layout, instead of splitting
+     * visualizations across multiple A4 pages. This feature is GA from SDK version
+     * 1.51.0 and ThoughtSpot version 26.8.0.cl.
      *
      * Supported embed types: `AppEmbed`, `LiveboardEmbed`
      * @type {boolean}

package/src/embed/auto-frame-renderer.spec.ts

@@ -45,7 +45,8 @@ describe('startAutoMCPFrameRenderer', () => {
         getEmbedBasePathSpy.mockRestore();
     });
 
-    // ─── helpers ──────────────────────────────────────────────────────────────
+    // ─── helpers
+    // ──────────────────────────────────────────────────────────────
 
     /** Capture the src passed to renderIFrame for the first tsmcp iframe added */
     async function captureRenderedSrc(viewConfig: AutoMCPFrameRendererViewConfig = {}): Promise<string> {
@@ -96,7 +97,8 @@ describe('startAutoMCPFrameRenderer', () => {
         return mockPort.postMessage.mock.calls[0]?.[0];
     }
 
-    // ─── MutationObserver setup ───────────────────────────────────────────────
+    // ─── MutationObserver setup
+    // ───────────────────────────────────────────────
 
     describe('MutationObserver setup', () => {
         test('should return a MutationObserver', () => {
@@ -117,7 +119,8 @@ describe('startAutoMCPFrameRenderer', () => {
         });
     });
 
-    // ─── iframe detection via tsmcp param ─────────────────────────────────────
+    // ─── iframe detection via tsmcp param
+    // ─────────────────────────────────────
 
     describe('iframe detection via tsmcp param', () => {
         test('should process directly-added iframes with tsmcp=true', async () => {
@@ -209,7 +212,8 @@ describe('startAutoMCPFrameRenderer', () => {
         });
     });
 
-    // ─── handleInsertionIntoDOM override ──────────────────────────────────────
+    // ─── handleInsertionIntoDOM override
+    // ──────────────────────────────────────
 
     describe('handleInsertionIntoDOM override', () => {
         test('should replace the original iframe when renderIFrame inserts DOM', async () => {
@@ -233,7 +237,8 @@ describe('startAutoMCPFrameRenderer', () => {
         });
     });
 
-    // ─── URL params forwarding ────────────────────────────────────────────────
+    // ─── URL params forwarding
+    // ────────────────────────────────────────────────
 
     describe('URL params forwarding', () => {
         test('should accept empty viewConfig', () => {
@@ -394,7 +399,8 @@ describe('startAutoMCPFrameRenderer', () => {
         });
     });
 
-    // ─── frameParams forwarding ───────────────────────────────────────────────
+    // ─── frameParams forwarding
+    // ───────────────────────────────────────────────
 
     describe('frameParams forwarding', () => {
         test('frameParams.height and .width applied to the replacement iframe element', async () => {
@@ -441,7 +447,8 @@ describe('startAutoMCPFrameRenderer', () => {
         });
     });
 
-    // ─── APP_INIT postMessage params forwarding ───────────────────────────────
+    // ─── APP_INIT postMessage params forwarding
+    // ───────────────────────────────
     //
     // These params are not in the iframe src URL — they travel via the APP_INIT
     // postMessage channel. AutoFrameRenderer inherits the TsEmbed APP_INIT
@@ -497,9 +504,10 @@ describe('startAutoMCPFrameRenderer', () => {
         });
 
         test('interceptUrls forwarded via APP_INIT', async () => {
-            // The SDK expands InterceptedApiType enum values into resolved prism endpoint URLs.
-            // Assert that the interceptUrls array is non-empty (i.e. the config was forwarded
-            // and processed) rather than checking the resolved strings directly.
+            // The SDK expands InterceptedApiType enum values into resolved
+            // prism endpoint URLs. Assert that the interceptUrls array is
+            // non-empty (i.e. the config was forwarded and processed) rather
+            // than checking the resolved strings directly.
             const response = await getAppInitResponse({
                 interceptUrls: [InterceptedApiType.AnswerData],
             });
@@ -513,7 +521,8 @@ describe('startAutoMCPFrameRenderer', () => {
         });
     });
 
-    // ─── getMCPIframeSrc URL construction ─────────────────────────────────────
+    // ─── getMCPIframeSrc URL construction
+    // ─────────────────────────────────────
 
     describe('getMCPIframeSrc URL construction', () => {
         test('should strip tsmcp param and merge embed params into rendered src', async () => {
@@ -569,7 +578,8 @@ describe('startAutoMCPFrameRenderer', () => {
             document.body.appendChild(iframe);
             await new Promise((r) => setTimeout(r, 50));
 
-            // At minimum the base embed params (hostAppUrl, sdkVersion, etc.) are always present
+            // At minimum the base embed params (hostAppUrl, sdkVersion, etc.)
+            // are always present
             expect(capturedSrc).toMatch(/\?[^#]+#/);
             observer.disconnect();
         });
@@ -594,7 +604,8 @@ describe('startAutoMCPFrameRenderer', () => {
         });
     });
 
-    // ─── URL serialization parity with normal embeds ──────────────────────────
+    // ─── URL serialization parity with normal embeds
+    // ──────────────────────────
     //
     // These tests verify that array-typed params (hideAction, disableAction,
     // visibleAction) are serialized identically by startAutoMCPFrameRenderer

package/src/embed/conversation.spec.ts

@@ -537,7 +537,7 @@ describe('ConversationEmbed', () => {
         );
     });
 
-    it('should render the conversation embed with spotterAnalystConfig.analystId in the url', async () => {
+    it('should not add analystId to the url, it is sent over APP_INIT instead', async () => {
         const viewConfig: SpotterEmbedViewConfig = {
             worksheetId: 'worksheetId',
             searchOptions: {
@@ -549,37 +549,13 @@ describe('ConversationEmbed', () => {
         };
         const conversationEmbed = new SpotterEmbed(getRootEl(), viewConfig);
         await conversationEmbed.render();
+        expect(getIFrameSrc()).not.toContain('analystId');
         expectUrlMatchesWithParams(
             getIFrameSrc(),
-            `http://${thoughtSpotHost}/v2/?${defaultParams}&isSpotterExperienceEnabled=true&analystId=analyst-id-1234#/embed/insights/conv-assist?worksheet=worksheetId&query=searchQuery`,
+            `http://${thoughtSpotHost}/v2/?${defaultParams}&isSpotterExperienceEnabled=true#/embed/insights/conv-assist?worksheet=worksheetId&query=searchQuery`,
         );
     });
 
-    it('should not add analystId to the url when spotterAnalystConfig is not provided', async () => {
-        const viewConfig: SpotterEmbedViewConfig = {
-            worksheetId: 'worksheetId',
-            searchOptions: {
-                searchQuery: 'searchQuery',
-            },
-        };
-        const conversationEmbed = new SpotterEmbed(getRootEl(), viewConfig);
-        await conversationEmbed.render();
-        expect(getIFrameSrc()).not.toContain('analystId');
-    });
-
-    it('should not add analystId to the url when spotterAnalystConfig is empty', async () => {
-        const viewConfig: SpotterEmbedViewConfig = {
-            worksheetId: 'worksheetId',
-            searchOptions: {
-                searchQuery: 'searchQuery',
-            },
-            spotterAnalystConfig: {},
-        };
-        const conversationEmbed = new SpotterEmbed(getRootEl(), viewConfig);
-        await conversationEmbed.render();
-        expect(getIFrameSrc()).not.toContain('analystId');
-    });
-
     describe('spotter chat hiddenActions', () => {
         it.each([
             ['SpotterChatConnectorResources', Action.SpotterChatConnectorResources],
@@ -1057,4 +1033,39 @@ describe('SpotterEmbed APP_INIT starterPrompts', () => {
             quick: { questions: [{ label: 'Q1', prompt: 'P1' }] },
         });
     });
+
+    it('should include spotterAnalystConfig in embedParams when analystId is provided', async () => {
+        const response = await getAppInitResponse({
+            worksheetId: 'ws1',
+            spotterAnalystConfig: { analystId: 'analyst-id-1234' },
+        });
+        expect(response.data.embedParams.spotterAnalystConfig).toEqual({
+            analystId: 'analyst-id-1234',
+        });
+    });
+
+    it('should include spotterAnalystConfig alongside the other spotter embedParams', async () => {
+        const response = await getAppInitResponse({
+            worksheetId: 'ws1',
+            spotterSidebarConfig: { enablePastConversationsSidebar: true },
+            spotterAnalystConfig: { analystId: 'analyst-id-1234' },
+        });
+        expect(response.data.embedParams.spotterSidebarConfig.enablePastConversationsSidebar).toBe(true);
+        expect(response.data.embedParams.spotterAnalystConfig).toEqual({
+            analystId: 'analyst-id-1234',
+        });
+    });
+
+    it('should not include spotterAnalystConfig in embedParams when not configured', async () => {
+        const response = await getAppInitResponse({ worksheetId: 'ws1' });
+        expect(response.data.embedParams?.spotterAnalystConfig).toBeUndefined();
+    });
+
+    it('should not include spotterAnalystConfig in embedParams when analystId is absent', async () => {
+        const response = await getAppInitResponse({
+            worksheetId: 'ws1',
+            spotterAnalystConfig: {},
+        });
+        expect(response.data.embedParams?.spotterAnalystConfig).toBeUndefined();
+    });
 });

package/src/embed/conversation.ts

@@ -1,6 +1,6 @@
 import { Param, BaseViewConfig, RuntimeFilter, RuntimeParameter, ErrorDetailsTypes, EmbedErrorCodes, DefaultAppInitData, VisualizationOverrides, SpotterFileUploadFileTypes } from '../types';
 import { TsEmbed } from './ts-embed';
-import { buildSpotterSidebarAppInitData, buildSpotterShareConversationAppInitData, buildStarterPromptsAppInitData } from './spotter-utils';
+import { buildSpotterSidebarAppInitData, buildSpotterShareConversationAppInitData, buildStarterPromptsAppInitData, buildSpotterAnalystAppInitData } from './spotter-utils';
 import { getQueryParamString, getFilterQuery, getRuntimeParameters, setParamIfDefined } from '../utils';
 
 /**
@@ -801,6 +801,7 @@ export interface SpotterAppInitData extends DefaultAppInitData {
         spotterShareConversationConfig?: SpotterShareConversationConfig;
         visualOverridesParams?: VisualizationOverrides | null;
         starterPrompts?: StarterPromptsConfig;
+        spotterAnalystConfig?: SpotterAnalystConfig;
     };
 }
 
@@ -850,7 +851,8 @@ export class SpotterEmbed extends TsEmbed {
             this.handleError.bind(this),
         );
         const shareInitData = buildSpotterShareConversationAppInitData(sidebarInitData, this.viewConfig);
-        return buildStarterPromptsAppInitData(shareInitData, this.viewConfig);
+        const starterPromptsInitData = buildStarterPromptsAppInitData(shareInitData, this.viewConfig);
+        return buildSpotterAnalystAppInitData(starterPromptsInitData, this.viewConfig);
     }
 
     protected getEmbedParamsObject() {
@@ -871,7 +873,6 @@ export class SpotterEmbed extends TsEmbed {
             defaultQueryMode,
             enableStopAnswerGenerationEmbed,
             spotterChatConfig,
-            spotterAnalystConfig,
         } = this.viewConfig;
 
         const queryParams = this.getBaseQueryParams();
@@ -887,7 +888,6 @@ export class SpotterEmbed extends TsEmbed {
         setParamIfDefined(queryParams, Param.ShowSpotterRadiance, showSpotterRadiance, true);
         setParamIfDefined(queryParams, Param.DefaultQueryMode, defaultQueryMode);
         setParamIfDefined(queryParams, Param.EnableStopAnswerGenerationEmbed, enableStopAnswerGenerationEmbed, true);
-        setParamIfDefined(queryParams, Param.AnalystId, spotterAnalystConfig?.analystId);
 
         // Handle spotterChatConfig params
         if (spotterChatConfig) {

package/src/embed/embedConfig.spec.ts

@@ -3,7 +3,8 @@ import { storeValueInWindow, resetValueFromWindow } from '../utils';
 
 describe('embedConfig', () => {
     beforeEach(() => {
-        // Ensure the SDK window namespace exists before resetting individual keys
+        // Ensure the SDK window namespace exists before resetting individual
+        // keys
         storeValueInWindow('embedConfig', undefined);
         resetValueFromWindow('embedConfig');
     });

package/src/embed/hostEventClient/host-event-client.spec.ts

@@ -979,11 +979,14 @@ describe('HostEventClient', () => {
             const { client } = createHostEventClient();
             mockProcessTrigger.mockReset();
 
-            // Flow per triggerHostEvent call when GetAvailableUIPassthroughs rejects:
-            //   1. getAvailableUIPassthroughKeys → processTrigger(UIPassthrough, GetAvailableUIPassthroughs) → rejects → returns []
-            //   2. keys=[] so getDataWithPassthroughFallback is called →
-            //      triggerUIPassthroughApi(GetAnswerSession) → processTrigger(UIPassthrough) → null → hostEventFallback called
-            //   3. hostEventFallback → processTrigger(GetAnswerSession) → legacy result
+            // Flow per triggerHostEvent call when GetAvailableUIPassthroughs
+            // rejects: 1. getAvailableUIPassthroughKeys →
+            // processTrigger(UIPassthrough, GetAvailableUIPassthroughs) →
+            // rejects → returns [] 2. keys=[] so getDataWithPassthroughFallback
+            // is called → triggerUIPassthroughApi(GetAnswerSession) →
+            // processTrigger(UIPassthrough) → null → hostEventFallback called
+            // 3. hostEventFallback → processTrigger(GetAnswerSession) → legacy
+            // result
 
             // First triggerHostEvent: 3 calls
             mockProcessTrigger.mockRejectedValueOnce(new Error('network error')); // call 1
@@ -992,14 +995,16 @@ describe('HostEventClient', () => {
 
             await client.triggerHostEvent(HostEvent.GetAnswerSession, { vizId: '1' });
 
-            // Second triggerHostEvent: cache was NOT set, so GetAvailableUIPassthroughs is retried: 3 more calls
+            // Second triggerHostEvent: cache was NOT set, so
+            // GetAvailableUIPassthroughs is retried: 3 more calls
             mockProcessTrigger.mockRejectedValueOnce(new Error('network error')); // call 4
             mockProcessTrigger.mockResolvedValueOnce(null);                       // call 5
             mockProcessTrigger.mockResolvedValueOnce({ session: 'leg2' });        // call 6
 
             await client.triggerHostEvent(HostEvent.GetAnswerSession, { vizId: '2' });
 
-            // 6 total calls: GetAvailableUIPassthroughs was called TWICE (cache not set after catch)
+            // 6 total calls: GetAvailableUIPassthroughs was called TWICE
+            // (cache not set after catch)
             expect(mockProcessTrigger).toHaveBeenCalledTimes(6);
             const availableCallsCount = mockProcessTrigger.mock.calls.filter(
                 (call) => call[3]?.type === UIPassthroughEvent.GetAvailableUIPassthroughs,
@@ -1175,7 +1180,8 @@ describe('HostEventClient', () => {
                 { numberOfTabs: number; orderedTabIds: string[] }
             > = true;
             const probeUnknownField = (r: TabsResponse) =>
-                // @ts-expect-error — field not on the GetTabs contract (was silent when `any`)
+                // @ts-expect-error — field not on the GetTabs contract (was
+                // silent when `any`)
                 r.tabCount;
             void probeUnknownField;
 

package/src/embed/hostEventClient/host-event-client.ts

@@ -3,6 +3,7 @@ import { processTrigger as processTriggerService } from '../../utils/processTrig
 import { getEmbedConfig } from '../embedConfig';
 import {
     isValidUpdateFiltersPayload,
+    resolveUpdateFiltersAliases,
     isValidUpdateParametersPayload,
     isValidDrillDownPayload,
     throwUpdateFiltersValidationError,
@@ -27,7 +28,8 @@ import {
 /**
  * Maps HostEvent to its corresponding UIPassthroughEvent.
  * Includes both custom-handler events (Pin, SaveAnswer, UpdateFilters, DrillDown)
- * and getter events (GetAnswerSession, GetFilters, etc.) that use getDataWithPassthroughFallback.
+ * and getter events (GetAnswerSession, GetFilters, etc.) that use
+ * getDataWithPassthroughFallback.
  */
 const PASSTHROUGH_MAP: Partial<Record<HostEvent, UIPassthroughEvent>> = {
     // Custom handlers (setters with special logic)
@@ -249,13 +251,17 @@ export class HostEventClient {
     }
 
     // The shared contract accepts both current (columnName/operator) and
-    // legacy (column/oper) filter field names — as does the validation
-    // above and the app at runtime. The UIPassthrough FilterUpdate type
-    // still requires the legacy names; bridge until that contract is
-    // audited.
+    // legacy (column/oper) filter field names, but only the legacy pair is
+    // understood downstream, so the payload is rewritten before it is
+    // forwarded — otherwise a columnName/operator filter passes validation
+    // here and is then silently ignored by the app. The cast bridges the
+    // UIPassthrough FilterUpdate type, which still declares only the legacy
+    // names.
+    const resolvedPayload = resolveUpdateFiltersAliases(payload);
+
     return this.handleHostEventWithParam(
         UIPassthroughEvent.UpdateFilters,
-        payload as UIPassthroughRequest<UIPassthroughEvent.UpdateFilters>,
+        resolvedPayload as UIPassthroughRequest<UIPassthroughEvent.UpdateFilters>,
         context as ContextType,
     );
   }
@@ -268,7 +274,8 @@ export class HostEventClient {
       throwUpdateParametersValidationError();
     }
 
-    // UpdateParameters has no UI passthrough contract; dispatch over the legacy channel
+    // UpdateParameters has no UI passthrough contract; dispatch over the
+    // legacy channel
     return this.hostEventFallback(HostEvent.UpdateParameters, payload, context);
   }
 
@@ -285,8 +292,8 @@ export class HostEventClient {
 
   /**
    * Dispatches a host event using the appropriate channel:
-   * 1. If the embedded app supports UI passthrough for this event, use it (custom handler or getter).
-   * 2. Otherwise fall back to the legacy host event channel.
+   * 1. If the embedded app supports UI passthrough for this event, use it (custom
+   * handler or getter). 2. Otherwise fall back to the legacy host event channel.
    *
    * @param hostEvent - The host event to trigger
    * @param payload - Optional payload for the event
@@ -304,7 +311,8 @@ export class HostEventClient {
       const customHandler = this.customHandlers[hostEvent];
       const passthroughEvent = PASSTHROUGH_MAP[hostEvent];
 
-      // If embedded app supports passthrough but not this event, use legacy channel
+      // If embedded app supports passthrough but not this event, use legacy
+      // channel
       const keys = passthroughEvent ? await this.getAvailableUIPassthroughKeys(context as ContextType) : [];
       if (passthroughEvent && keys.length > 0 && !keys.includes(passthroughEvent)) {
           return this.hostEventFallback(hostEvent, payload, context) as any;