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

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}
@@ -990,7 +991,7 @@ export class AppEmbed extends V1Embed {
      * embedded Liveboard or visualization.
      */
     protected getEmbedParams() {
-        const params = this.getEmbedParamsObject();
+        const params = this.getUrlQueryParamsObject();
         return getQueryParamString(params, true);
     }
 

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/auto-frame-renderer.ts

@@ -108,7 +108,7 @@ class AutoFrameRenderer extends TsEmbed {
      * @returns The constructed URL to use for the ThoughtSpot embed iframe.
      */
     private getMCPIframeSrc(sourceSrc: string) {
-        const queryParams = this.getEmbedParamsObject();
+        const queryParams = this.getUrlQueryParamsObject();
         const sourceURL = new URL(sourceSrc);
         const existingQueryParams = sourceURL.searchParams;
         const existingQueryParamsObject = Object.fromEntries(existingQueryParams);

package/src/embed/bodyless-conversation.ts

@@ -56,7 +56,7 @@ export class ConversationMessage extends TsEmbed {
             messageId,
         } = this.viewConfig;
         const path = 'conv-assist-answer';
-        const queryParams = this.getEmbedParamsObject();
+        const queryParams = this.getUrlQueryParamsObject();
 
         let query = '';
         const queryParamsString = getQueryParamString(queryParams, true);

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) {
@@ -931,7 +931,7 @@ export class SpotterEmbed extends TsEmbed {
         const path = sharedConversationId
             ? `insights/conv-assist/s/${encodeURIComponent(sharedConversationId)}`
             : 'insights/conv-assist';
-        const queryParams = this.getEmbedParamsObject();
+        const queryParams = this.getUrlQueryParamsObject();
 
         let query = '';
         const queryParamsString = getQueryParamString(queryParams, true);

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;

package/src/embed/hostEventClient/utils.spec.ts

@@ -1,5 +1,6 @@
 import {
     isValidUpdateFiltersPayload,
+    resolveUpdateFiltersAliases,
     isValidUpdateParametersPayload,
     isValidDrillDownPayload,
     createValidationError,
@@ -7,6 +8,7 @@ import {
     throwUpdateParametersValidationError,
     throwDrillDownValidationError,
 } from './utils';
+import { HostFilterUpdate as FilterUpdate } from '../../contracts/host-event-contracts';
 import { ERROR_MESSAGE } from '../../errors';
 import { EmbedEvent } from '../../types';
 import { embedEventStatus } from '../../utils';
@@ -426,4 +428,177 @@ describe('hostEventClient utils', () => {
                 .toThrow(ERROR_MESSAGE.DRILLDOWN_INVALID_PAYLOAD);
         });
     });
-});
+    // =========================
+    // FilterUpdate type shape
+    // =========================
+    // The @ts-expect-error assertions below are enforced by tsc: an unused one
+    // is itself an error, so re-loosening the type fails the build.
+    describe('FilterUpdate type', () => {
+        it('accepts the documented columnName/operator spelling', () => {
+            const filter: FilterUpdate = { columnName: 'region', operator: 'EQ', values: ['west'] };
+            expect(isValidUpdateFiltersPayload({ filter })).toBe(true);
+        });
+
+        it('still accepts the deprecated column/oper aliases', () => {
+            const filter: FilterUpdate = { column: 'region', oper: 'EQ', values: ['west'] };
+            expect(isValidUpdateFiltersPayload({ filter })).toBe(true);
+        });
+
+        it('accepts a mix of documented and deprecated spellings', () => {
+            const filter: FilterUpdate = { columnName: 'region', oper: 'EQ', values: ['west'] };
+            expect(isValidUpdateFiltersPayload({ filter })).toBe(true);
+        });
+
+        it('accepts a worksheet-qualified column name', () => {
+            const filter: FilterUpdate = {
+                columnName: '(Sample) Retail - Apparel::city',
+                operator: 'IN',
+                values: ['atlanta'],
+            };
+            expect(isValidUpdateFiltersPayload({ filter })).toBe(true);
+        });
+
+        it('rejects a filter with no column at compile time and at runtime', () => {
+            // @ts-expect-error one of columnName/column is required
+            const filter: FilterUpdate = { operator: 'EQ', values: ['west'] };
+            expect(isValidUpdateFiltersPayload({ filter })).toBe(false);
+        });
+
+        it('rejects a filter with no operator at compile time and at runtime', () => {
+            // @ts-expect-error one of operator/oper is required
+            const filter: FilterUpdate = { columnName: 'region', values: ['west'] };
+            expect(isValidUpdateFiltersPayload({ filter })).toBe(false);
+        });
+
+        it('rejects both column spellings at compile time', () => {
+            // @ts-expect-error columnName and column are mutually exclusive
+            const filter: FilterUpdate = {
+                columnName: 'region', column: 'region', operator: 'EQ', values: ['west'],
+            };
+            // The runtime validator is laxer than the type - it reads whichever
+            // spelling is present - so this still passes at runtime. The point
+            // of the type is to stop the ambiguity reaching it.
+            expect(isValidUpdateFiltersPayload({ filter })).toBe(true);
+        });
+
+        it('rejects both operator spellings at compile time', () => {
+            // @ts-expect-error operator and oper are mutually exclusive
+            const filter: FilterUpdate = {
+                columnName: 'region', operator: 'EQ', oper: 'EQ', values: ['west'],
+            };
+            expect(isValidUpdateFiltersPayload({ filter })).toBe(true);
+        });
+
+        // The fields SCAL-325540 added to the host-event contract have to keep
+        // working alongside the exclusive alias pairs - the union must widen
+        // the column and operator halves only, and leave the rest of the
+        // filter shape alone.
+        it('accepts the fields added by the host-event contract', () => {
+            const filter: FilterUpdate = {
+                columnName: 'date',
+                columnId: 'col-guid',
+                operator: 'EQ',
+                values: ['2023-07-31'],
+                type: 'EXACT_DATE',
+                datePeriod: 'DAY',
+                negate: true,
+                applicability: { level: 'TAB', targetId: 'tab-guid' },
+            };
+            expect(isValidUpdateFiltersPayload({ filter })).toBe(true);
+        });
+
+        it('accepts non-string values alongside the documented spelling', () => {
+            const filter: FilterUpdate = {
+                columnName: 'quantity', operator: 'GE', values: [5, true],
+            };
+            expect(isValidUpdateFiltersPayload({ filter })).toBe(true);
+        });
+
+        it('accepts the request-level scoping fields', () => {
+            const payload = {
+                filters: [{ columnName: 'region', operator: 'IN', values: ['west'] }],
+                visualizationId: 'viz-guid',
+                liveboardId: 'lb-guid',
+            };
+            expect(isValidUpdateFiltersPayload(payload)).toBe(true);
+        });
+    });
+    describe('resolveUpdateFiltersAliases', () => {
+        it('rewrites columnName/operator to column/oper on a single filter', () => {
+            const out = resolveUpdateFiltersAliases({
+                filter: { columnName: 'region', operator: 'EQ', values: ['west'] },
+            } as any);
+
+            expect(out.filter).toEqual({ column: 'region', oper: 'EQ', values: ['west'] });
+            expect(out.filter).not.toHaveProperty('columnName');
+            expect(out.filter).not.toHaveProperty('operator');
+        });
+
+        it('rewrites every entry in a filters array', () => {
+            const out = resolveUpdateFiltersAliases({
+                filters: [
+                    { columnName: 'region', operator: 'EQ', values: ['west'] },
+                    { columnName: 'item type', operator: 'IN', values: ['bags'] },
+                ],
+            } as any);
+
+            expect(out.filters).toEqual([
+                { column: 'region', oper: 'EQ', values: ['west'] },
+                { column: 'item type', oper: 'IN', values: ['bags'] },
+            ]);
+        });
+
+        it('leaves a payload that already uses column/oper untouched', () => {
+            const payload = { filter: { column: 'region', oper: 'EQ', values: ['west'] } } as any;
+
+            expect(resolveUpdateFiltersAliases(payload)).toEqual(payload);
+        });
+
+        it('prefers columnName/operator when both spellings are present', () => {
+            const out = resolveUpdateFiltersAliases({
+                filter: {
+                    column: 'from-column', columnName: 'from-columnName',
+                    oper: 'EQ', operator: 'IN',
+                    values: ['x'],
+                },
+            } as any);
+
+            // The value survives under the wire name, but it is the documented
+            // spelling's value that survives.
+            expect(out.filter).toEqual({ column: 'from-columnName', oper: 'IN', values: ['x'] });
+        });
+
+        it('preserves the other filter fields, including applicability', () => {
+            const out = resolveUpdateFiltersAliases({
+                filter: {
+                    columnName: 'date',
+                    operator: 'EQ',
+                    values: [1700000000],
+                    type: 'EXACT_DATE',
+                    applicability: { level: 'TAB', targetId: 'tab-guid' },
+                },
+            } as any);
+
+            expect(out.filter).toEqual({
+                column: 'date',
+                oper: 'EQ',
+                values: [1700000000],
+                type: 'EXACT_DATE',
+                applicability: { level: 'TAB', targetId: 'tab-guid' },
+            });
+        });
+
+        it('produces a payload that still passes validation', () => {
+            const out = resolveUpdateFiltersAliases({
+                filters: [{ columnName: 'region', operator: 'EQ', values: ['west'] }],
+            } as any);
+
+            expect(isValidUpdateFiltersPayload(out as any)).toBe(true);
+        });
+
+        it('is a no-op on a non-object payload', () => {
+            expect(resolveUpdateFiltersAliases(undefined as any)).toBeUndefined();
+            expect(resolveUpdateFiltersAliases(null as any)).toBeNull();
+        });
+    });
+});