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

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/events.spec.ts

@@ -9,6 +9,7 @@ import {
     LiveboardEmbed,
     AppEmbed,
     HostEvent,
+    MessageCallback,
 } from '../index';
 import {
     EVENT_WAIT_TIME,
@@ -139,7 +140,7 @@ describe('test communication between host app and ThoughtSpot', () => {
         searchEmbed.render();
         setTimeout(() => {
             searchEmbed.trigger(HostEvent.Search, {
-                body: PAYLOAD,
+                searchQuery: PAYLOAD,
             });
         }, EVENT_WAIT_TIME);
         executeAfterWait(() => {
@@ -147,12 +148,23 @@ describe('test communication between host app and ThoughtSpot', () => {
 
             iframe.contentWindow.addEventListener('message', (e) => {
                 expect(e.data.type).toBe(HostEvent.Search);
-                expect(e.data.data.body).toBe(PAYLOAD);
+                expect(e.data.data.searchQuery).toBe(PAYLOAD);
                 done();
             });
         });
     });
 
+    test('accepts a MessageCallback-typed handler for typed and untyped events', () => {
+        // Guardrail: on()/off() must accept the public MessageCallback type, or
+        // existing customer handlers stop compiling (checked non-strict here).
+        const legacy: MessageCallback = jest.fn();
+        const searchEmbed = new SearchEmbed(getRootEl(), {});
+        searchEmbed.on(EmbedEvent.CustomAction, legacy); // typed event
+        searchEmbed.on(EmbedEvent.Data, legacy); // untyped event
+        searchEmbed.off(EmbedEvent.Data, legacy);
+        expect(legacy).not.toHaveBeenCalled();
+    });
+
     test('should execute multiple event handlers if registered', async () => {
         const handlerOne = jest.fn();
         const handlerTwo = jest.fn();

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

@@ -6,8 +6,8 @@ import {
     UIPassthroughEvent,
     UIPassthroughRequest,
     UIPassthroughArrayResponse,
-    HostEventRequest,
-} from './contracts';
+} from '../../contracts/ui-passthrough-contracts';
+import { HostEventRequest } from '../../contracts/host-event-contracts';
 import { HostEventClient } from './host-event-client';
 
 jest.mock('../../utils/processTrigger');
@@ -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,
@@ -12,18 +13,23 @@ import {
 import {
     UIPassthroughArrayResponse,
     UIPassthroughEvent,
-    HostEventRequest,
-    HostEventResponse,
     UIPassthroughRequest,
     UIPassthroughResponse,
+} from '../../contracts/ui-passthrough-contracts';
+// Contract resolution from the shared contracts module — see
+// src/contracts/host-event-contracts.ts (single source of truth).
+import {
+    HostEventRequest,
+    HostEventResponse,
     TriggerPayload,
     TriggerResponse,
-} from './contracts';
+} from '../../contracts/host-event-contracts';
 
 /**
  * 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)
@@ -244,7 +250,20 @@ export class HostEventClient {
       throwUpdateFiltersValidationError();
     }
 
-    return this.handleHostEventWithParam(UIPassthroughEvent.UpdateFilters, payload, context as ContextType);
+    // The shared contract accepts both current (columnName/operator) and
+    // 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,
+        resolvedPayload as UIPassthroughRequest<UIPassthroughEvent.UpdateFilters>,
+        context as ContextType,
+    );
   }
 
   protected handleUpdateParametersEvent(
@@ -255,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);
   }
 
@@ -272,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
@@ -287,11 +307,12 @@ export class HostEventClient {
       hostEvent: HostEventT,
       payload?: TriggerPayload<PayloadT, HostEventT>,
       context?: ContextT,
-  ): Promise<TriggerResponse<PayloadT, HostEventT, ContextType>> {
+  ): Promise<TriggerResponse<PayloadT, HostEventT, ContextT>> {
       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();
+        });
+    });
+});

package/src/embed/hostEventClient/utils.ts

@@ -4,12 +4,14 @@ import isString from 'lodash/isString';
 import isUndefined from 'lodash/isUndefined';
 import { EmbedErrorCodes, EmbedEvent, ErrorDetailsTypes, HostEvent } from '../../types';
 import { ERROR_MESSAGE } from '../../errors';
-import { ApplicabilityLevel, HostEventRequest } from './contracts';
+import { ApplicabilityLevel } from '../../contracts/ui-passthrough-contracts';
+import { HostEventRequest } from '../../contracts/host-event-contracts';
 import { embedEventStatus } from '../../utils';
 
 const isValidApplicability = (a?: { level?: string; targetId?: string }) => {
   if (isUndefined(a)) return true;
-  // targetId is not required at LIVEBOARD level, since the filter applies to the whole Liveboard
+  // targetId is not required at LIVEBOARD level, since the filter applies to
+  // the whole Liveboard
   return isPlainObject(a)
       && Object.values(ApplicabilityLevel).includes(a.level as ApplicabilityLevel)
       && (a.level === ApplicabilityLevel.Liveboard || (isString(a.targetId) && a.targetId.trim().length > 0));
@@ -43,8 +45,56 @@ export function isValidUpdateFiltersPayload(
   return !!(hasValidFilter || hasValidFilters);
 }
 
+/**
+ * Rewrites one filter's `columnName`/`operator` to `column`/`oper`.
+ *
+ * Callers may use either spelling: `columnName`/`operator` match
+ * {@link RuntimeFilter} and the `EmbedEvent.FilterChanged` payload, so a
+ * converted payload can be replayed as-is. But the payload is forwarded to the
+ * embedded app unchanged, and only `column`/`oper` are known to be understood
+ * there - so the alias must be swapped here, or it would pass validation and
+ * then be silently ignored.
+ *
+ * If a caller supplies both spellings of a field - which TypeScript rejects,
+ * but JavaScript callers can still do - the documented `columnName`/`operator`
+ * wins. Deferring to the deprecated spelling would quietly discard the value
+ * the rest of the SDK tells people to use.
+ * @param filter One entry from the UpdateFilters payload.
+ */
+function resolveFilterAliases<T extends { column?: string; columnName?: string; oper?: string; operator?: string }>(
+  filter: T,
+): T {
+  if (!isPlainObject(filter)) return filter;
+
+  const column = filter.columnName ?? filter.column;
+  const oper = filter.operator ?? filter.oper;
+  const { columnName, operator, ...rest } = filter;
+
+  return {
+    ...rest,
+    ...(isUndefined(column) ? {} : { column }),
+    ...(isUndefined(oper) ? {} : { oper }),
+  } as T;
+}
+
+/**
+ * Rewrites every filter in an UpdateFilters payload to use `column`/`oper`,
+ * whichever spelling the caller supplied. Call after validation.
+ * @param payload The UpdateFilters host event payload.
+ */
+export function resolveUpdateFiltersAliases<T extends { filter?: any; filters?: any[] }>(payload: T): T {
+  if (!isPlainObject(payload)) return payload;
+
+  return {
+    ...payload,
+    ...(payload.filter ? { filter: resolveFilterAliases(payload.filter) } : {}),
+    ...(Array.isArray(payload.filters) ? { filters: payload.filters.map(resolveFilterAliases) } : {}),
+  };
+}
+
 export function isValidUpdateParametersPayload(payload: unknown): boolean {
-  // Only validates the applicability of each parameter (null treated as absent); the rest is forwarded as-is for backward compatibility.
+  // Only validates the applicability of each parameter (null treated as
+  // absent); the rest is forwarded as-is for backward compatibility.
   if (!Array.isArray(payload)) return true;
   return payload.every((p) => {
       if (!isPlainObject(p)) return true;