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

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

@@ -10,7 +10,8 @@ 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));
@@ -44,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;

package/src/embed/liveboard.spec.ts

@@ -3054,8 +3054,8 @@ describe('LiveboardEmbed updatedSpotterExperience tests', () => {
 
     describe('trigger typing contracts (compile-time)', () => {
         // Enforced by ts-jest at compile time. LiveboardEmbed OVERRIDES
-        // TsEmbed.trigger, so its generic defaults must be asserted separately —
-        // a bare `PayloadT` on the override silently collapses no-payload
+        // TsEmbed.trigger, so its generic defaults must be asserted separately
+        // — a bare `PayloadT` on the override silently collapses no-payload
         // responses back to `any` for every LiveboardEmbed consumer.
         type IsAny<T> = 0 extends 1 & T ? true : false;
         type Extends<A, B> = A extends B ? true : false;
@@ -3073,7 +3073,8 @@ describe('LiveboardEmbed updatedSpotterExperience tests', () => {
                 { 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/liveboard.ts

@@ -37,8 +37,9 @@ import { SpotterChatViewConfig, StarterPromptsConfig } from './conversation';
 import { buildStarterPromptsAppInitData } from './spotter-utils';
 import { SpotterVizConfig, buildSpotterVizAppInitData } from './spotter-viz-utils';
 
-// Home unmounts the liveboard container, which is how its state gets cleared. The
-// settle window gives the container time to do it before we ask for the liveboard back.
+// Home unmounts the liveboard container, which is how its state gets cleared.
+// The settle window gives the container time to do it before we ask for the
+// liveboard back.
 const HOME_ROUTE = 'home';
 const HOME_SETTLE_MS = 200;
 
@@ -354,9 +355,10 @@ export interface LiveboardViewConfig
      */
     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}
@@ -952,22 +954,25 @@ export class LiveboardEmbed extends V1Embed {
     protected beforePrerenderVisible(): void {
         super.beforePrerenderVisible();
 
-        // Captured before showPreRender() hands the wrapper over to this instance.
-        // Itself means a hide/show, not a hand-over, so there is nothing stale to clear.
+        // Captured before showPreRender() hands the wrapper over to this
+        // instance. Itself means a hide/show, not a hand-over, so there is
+        // nothing stale to clear.
         const previous = this.getPreRenderObj<LiveboardEmbed>();
         const showing = previous === this ? undefined : previous?.currentLiveboardState;
 
         this.executeAfterEmbedContainerLoaded(async () => {
-            // Without this the params callback suspends on its await and Navigate
-            // goes out first, so the container loads with the previous config's filters.
+            // Without this the params callback suspends on its await and
+            // Navigate goes out first, so the container loads with the previous
+            // config's filters.
             await this.preRenderParamsApplied;
             if (this.isShowingLiveboardRoute(showing)) {
-                // Navigate to the route we are already on is a no-op, so the liveboard
-                // keeps its state. Home unmounts the container, which clears it.
+                // Navigate to the route we are already on is a no-op, so the
+                // liveboard keeps its state. Home unmounts the container, which
+                // clears it.
                 this.trigger(HostEvent.Navigate, HOME_ROUTE)
                     .catch((error) => logger.warn('Could not route via home', error));
-                // Not awaited above: the container never acks Navigate, so that promise
-                // only settles on the 30s trigger timeout.
+                // Not awaited above: the container never acks Navigate, so
+                // that promise only settles on the 30s trigger timeout.
                 await new Promise((resolve) => {
                     setTimeout(resolve, HOME_SETTLE_MS);
                 });
@@ -987,8 +992,9 @@ export class LiveboardEmbed extends V1Embed {
         });
     }
 
-    // The whole route, not just the liveboard id: the path is built from the viz, tab
-    // and view too, so a same-liveboard show onto another tab is a real navigation.
+    // The whole route, not just the liveboard id: the path is built from the
+    // viz, tab and view too, so a same-liveboard show onto another tab is a
+    // real navigation.
     private isShowingLiveboardRoute(showing?: LiveboardEmbed['currentLiveboardState']): boolean {
         if (!showing?.liveboardId) return false;
         const {

package/src/embed/spotter-utils.spec.ts

@@ -3,6 +3,7 @@ import {
     buildSpotterSidebarAppInitData,
     buildSpotterShareConversationAppInitData,
     buildStarterPromptsAppInitData,
+    buildSpotterAnalystAppInitData,
 } from './spotter-utils';
 import { ErrorDetailsTypes, EmbedErrorCodes } from '../types';
 import { ERROR_MESSAGE } from '../errors';
@@ -245,3 +246,31 @@ describe('buildStarterPromptsAppInitData', () => {
         expect(result.embedParams?.starterPrompts).toEqual({ enable: true, liveboard });
     });
 });
+
+describe('buildSpotterAnalystAppInitData', () => {
+    const base = { type: 'APP_INIT' } as any;
+
+    it('returns the payload unchanged when analystId is absent', () => {
+        expect(buildSpotterAnalystAppInitData(base, {})).toBe(base);
+        expect(buildSpotterAnalystAppInitData(base, { spotterAnalystConfig: {} })).toBe(base);
+    });
+
+    it('nests spotterAnalystConfig under embedParams', () => {
+        const result = buildSpotterAnalystAppInitData(base, {
+            spotterAnalystConfig: { analystId: 'analyst-id-1234' },
+        });
+        expect(result.embedParams?.spotterAnalystConfig).toEqual({ analystId: 'analyst-id-1234' });
+    });
+
+    it('preserves existing embedParams keys', () => {
+        const withExisting = {
+            ...base,
+            embedParams: { spotterSidebarConfig: { enablePastConversationsSidebar: true } },
+        } as any;
+        const result = buildSpotterAnalystAppInitData(withExisting, {
+            spotterAnalystConfig: { analystId: 'analyst-id-1234' },
+        });
+        expect(result.embedParams?.spotterSidebarConfig).toEqual({ enablePastConversationsSidebar: true });
+        expect(result.embedParams?.spotterAnalystConfig).toEqual({ analystId: 'analyst-id-1234' });
+    });
+});

package/src/embed/spotter-utils.ts

@@ -6,6 +6,7 @@ import type {
     SpotterShareConversationConfig,
     SpotterChatViewConfig,
     StarterPromptsConfig,
+    SpotterAnalystConfig,
 } from './conversation';
 import type { VisualizationOverrides } from '../types';
 
@@ -114,3 +115,18 @@ export function buildStarterPromptsAppInitData<T extends DefaultAppInitData>(
         },
     };
 }
+
+export function buildSpotterAnalystAppInitData<T extends DefaultAppInitData>(
+    initData: T,
+    viewConfig: { spotterAnalystConfig?: SpotterAnalystConfig },
+): T & { embedParams?: { spotterAnalystConfig?: SpotterAnalystConfig } } {
+    const { spotterAnalystConfig } = viewConfig;
+    if (!spotterAnalystConfig?.analystId) return initData;
+    return {
+        ...initData,
+        embedParams: {
+            ...((initData as T & { embedParams?: Record<string, unknown> }).embedParams || {}),
+            spotterAnalystConfig,
+        },
+    };
+}