@thoughtspot/visual-embed-sdk 1.53.0 → 1.53.1

package/src/types.ts

@@ -5462,6 +5462,17 @@ export enum HostEvent {
      * @version SDK: 1.54.0 | ThoughtSpot Cloud: 26.11.0.cl
      */
     EditVisualization = 'editVisualization',
+    /**
+     * Exits Liveboard edit mode , equivalent to clicking the
+     * *Cancel* button in the Liveboard edit header. The Liveboard returns to
+     * view mode and the embedded app emits the {@link EmbedEvent.Cancel} event.
+     * @version SDK: 1.55.0 | ThoughtSpot Cloud: 26.12.0.cl
+     * @example
+     * ```js
+     * liveboardEmbed.trigger(HostEvent.ExitEditMode);
+     * ```
+     */
+    ExitEditMode = 'exitEditMode',
     /**
      * Trigger the **Copy link** action on a Liveboard or visualization
      * Payload: {@link VizScopedRequest}.
@@ -7006,6 +7017,40 @@ export enum HostEvent {
      * @version SDK: 1.49.0 | ThoughtSpot Cloud: 26.6.0.cl
      */
     RefreshLiveboardBrowserCache = 'refreshLiveboardBrowserCache',
+
+    /**
+     * Switch the embed between dark appearance and its default appearance
+     * while it is open, without reloading it.
+     * Payload: {@link UpdateThemeRequest}.
+     *
+     * Use it to keep the embed in step with a theme switch in your
+     * application; the appearance the embed loads with is set by `isDarkMode`.
+     * The event resolves with the applied value, such as `{ isDarkMode: true }`.
+     * When dark appearance is not available in the embed, the embed does not
+     * change and the event rejects with an error message instead.
+     * @version SDK: 1.55.0 | ThoughtSpot Cloud: 26.12.0.cl
+     * @param - `isDarkMode` - `true` for dark appearance, `false` for the
+     * default appearance.
+     * @example
+     * ```js
+     * appEmbed.trigger(HostEvent.UpdateTheme, { isDarkMode: true });
+     * ```
+     * @example
+     * ```js
+     * // Follow a theme switch in your application
+     * const themeSwitch = document.querySelector('#theme-switch');
+     * themeSwitch.addEventListener('change', async (event) => {
+     *   try {
+     *     await appEmbed.trigger(HostEvent.UpdateTheme, {
+     *       isDarkMode: event.target.checked,
+     *     });
+     *   } catch (error) {
+     *     console.warn(error);
+     *   }
+     * });
+     * ```
+     */
+    UpdateTheme = 'UpdateTheme',
 }
 
 /**
@@ -9515,6 +9560,29 @@ export enum Action {
      * ```
      */
     CustomizeHomepage = 'customizeHomepage',
+    /**
+     * Controls the visibility and disabled state of the *Cancel* button in the
+     * Liveboard edit header, the button that discards the changes made in edit
+     * mode and returns the Liveboard to view mode. The button is shown only
+     * while the Liveboard is in edit mode.
+     * @version SDK: 1.55.0 | ThoughtSpot Cloud: 26.12.0.cl
+     * @example
+     * ```js
+     * const liveboardEmbed = new LiveboardEmbed('#tsEmbed', {
+     *     ... // other embed view config
+     *     hiddenActions: [Action.Cancel],
+     * });
+     * ```
+     * @example
+     * ```js
+     * const liveboardEmbed = new LiveboardEmbed('#tsEmbed', {
+     *     ... // other embed view config
+     *     disabledActions: [Action.Cancel],
+     *     disabledActionReason: 'Save your changes to leave edit mode',
+     * });
+     * ```
+     */
+    Cancel = 'cancel',
 }
 export interface AnswerServiceType {
     getAnswer?: (offset: number, batchSize: number) => any;

package/src/utils/runtimeTelemetry.spec.ts

@@ -0,0 +1,148 @@
+import {
+    describeRuntimeFilters,
+    describeRuntimeParameters,
+    summarizeRuntimeDataForTelemetry,
+} from './runtimeTelemetry';
+import { RuntimeFilter, RuntimeFilterOp, RuntimeParameter } from '../types';
+import { ApplicabilityLevel } from '../contracts/ui-passthrough-contracts';
+
+const customerFilters: RuntimeFilter[] = [
+    {
+        columnName: 'Patient SSN',
+        operator: RuntimeFilterOp.EQ,
+        values: ['123-45-6789'],
+    },
+    {
+        columnName: 'Revenue',
+        operator: RuntimeFilterOp.BW,
+        values: [1000, 5000],
+    },
+];
+
+const customerParameters: RuntimeParameter[] = [
+    {
+        name: 'Sales Region',
+        value: 'EMEA',
+        applicability: { level: ApplicabilityLevel.Tab, targetId: 'tab-guid' },
+    },
+];
+
+describe('describeRuntimeFilters', () => {
+    test('reports the count and the operators used', () => {
+        expect(describeRuntimeFilters(customerFilters)).toEqual({
+            count: 2,
+            operators: ['EQ', 'BW'],
+        });
+    });
+
+    test('de-duplicates repeated operators', () => {
+        const filters = [
+            { columnName: 'a', operator: RuntimeFilterOp.EQ, values: ['x'] },
+            { columnName: 'b', operator: RuntimeFilterOp.EQ, values: ['y'] },
+        ];
+        expect(describeRuntimeFilters(filters).operators).toEqual(['EQ']);
+    });
+
+    test('drops an operator that is not a RuntimeFilterOp member', () => {
+        const filters = [
+            { columnName: 'a', operator: 'a-customer-value' as any, values: ['x'] },
+        ];
+        expect(describeRuntimeFilters(filters)).toEqual({ count: 1, operators: [] });
+    });
+
+    test('tolerates a filter with no operator', () => {
+        expect(describeRuntimeFilters([undefined as any, {} as any])).toEqual({
+            count: 2,
+            operators: [],
+        });
+    });
+
+    test('reports an empty list', () => {
+        expect(describeRuntimeFilters([])).toEqual({ count: 0, operators: [] });
+    });
+});
+
+describe('describeRuntimeParameters', () => {
+    test('reports the count and the applicability levels used', () => {
+        expect(describeRuntimeParameters(customerParameters)).toEqual({
+            count: 1,
+            applicabilityLevels: ['TAB'],
+        });
+    });
+
+    test('reports no level when the parameter has no applicability', () => {
+        expect(describeRuntimeParameters([{ name: 'Region', value: 'EMEA' }])).toEqual({
+            count: 1,
+            applicabilityLevels: [],
+        });
+    });
+
+    test('drops a level that is not an ApplicabilityLevel member', () => {
+        const parameters = [
+            { name: 'Region', value: 'EMEA', applicability: { level: 'EVERYWHERE' as any } },
+        ];
+        expect(describeRuntimeParameters(parameters).applicabilityLevels).toEqual([]);
+    });
+});
+
+describe('summarizeRuntimeDataForTelemetry', () => {
+    test('never returns a column name, a parameter name or an operand', () => {
+        const props = summarizeRuntimeDataForTelemetry({
+            liveboardId: 'lb-guid',
+            runtimeFilters: customerFilters,
+            runtimeParameters: customerParameters,
+        });
+
+        const serialised = JSON.stringify(props);
+        ['Patient SSN', '123-45-6789', 'Revenue', '1000', '5000', 'Sales Region', 'EMEA', 'tab-guid'].forEach(
+            (customerValue) => {
+                expect(serialised).not.toContain(customerValue);
+            },
+        );
+    });
+
+    test('replaces both arrays with their summaries', () => {
+        expect(
+            summarizeRuntimeDataForTelemetry({
+                runtimeFilters: customerFilters,
+                runtimeParameters: customerParameters,
+            }),
+        ).toEqual({
+            runtimeFilters: { count: 2, operators: ['EQ', 'BW'] },
+            runtimeParameters: { count: 1, applicabilityLevels: ['TAB'] },
+        });
+    });
+
+    test('leaves every other view config property untouched', () => {
+        expect(
+            summarizeRuntimeDataForTelemetry({
+                liveboardId: 'lb-guid',
+                fullHeight: true,
+                hiddenActions: ['download'],
+            }),
+        ).toEqual({
+            liveboardId: 'lb-guid',
+            fullHeight: true,
+            hiddenActions: ['download'],
+        });
+    });
+
+    test('omits the keys entirely when they are absent', () => {
+        const props = summarizeRuntimeDataForTelemetry({ liveboardId: 'lb-guid' });
+        expect(props).not.toHaveProperty('runtimeFilters');
+        expect(props).not.toHaveProperty('runtimeParameters');
+    });
+
+    test('drops a non-array value rather than passing it through', () => {
+        const props = summarizeRuntimeDataForTelemetry({
+            runtimeFilters: { columnName: 'Patient SSN' } as any,
+            runtimeParameters: 'Sales Region' as any,
+        });
+        expect(props).not.toHaveProperty('runtimeFilters');
+        expect(props).not.toHaveProperty('runtimeParameters');
+    });
+
+    test('tolerates an undefined view config', () => {
+        expect(summarizeRuntimeDataForTelemetry(undefined as any)).toEqual({});
+    });
+});

package/src/utils/runtimeTelemetry.ts

@@ -0,0 +1,50 @@
+import { RuntimeFilter, RuntimeFilterOp, RuntimeParameter } from '../types';
+import { ApplicabilityLevel } from '../contracts/ui-passthrough-contracts';
+
+// Membership is checked, not just the key: a bare key allowlist would upload an
+// arbitrary customer string sitting under `operator` verbatim.
+const isEnumMember = (enumObject: Record<string, string>, value: unknown): boolean =>
+    typeof value === 'string' && Object.values(enumObject).includes(value);
+
+const uniqueEnumMembers = (
+    enumObject: Record<string, string>,
+    values: unknown[],
+): string[] => Array.from(new Set(values.filter((v) => isEnumMember(enumObject, v)))) as string[];
+
+export const describeRuntimeFilters = (
+    runtimeFilters: RuntimeFilter[],
+): { count: number; operators: string[] } => ({
+    count: runtimeFilters.length,
+    operators: uniqueEnumMembers(
+        RuntimeFilterOp as unknown as Record<string, string>,
+        runtimeFilters.map((filter) => filter?.operator),
+    ),
+});
+
+export const describeRuntimeParameters = (
+    runtimeParameters: RuntimeParameter[],
+): { count: number; applicabilityLevels: string[] } => ({
+    count: runtimeParameters.length,
+    applicabilityLevels: uniqueEnumMembers(
+        ApplicabilityLevel as unknown as Record<string, string>,
+        runtimeParameters.map((parameter) => parameter?.applicability?.level),
+    ),
+});
+
+// Column names, parameter names and operands are customer data and must never
+// reach Mixpanel; an unrecognized shape is dropped rather than forwarded.
+export const summarizeRuntimeDataForTelemetry = <T extends Record<string, any>>(
+    viewConfig: T,
+): Record<string, any> => {
+    const { runtimeFilters, runtimeParameters, ...rest } = viewConfig ?? ({} as T);
+    const telemetryProps: Record<string, any> = { ...rest };
+
+    if (Array.isArray(runtimeFilters)) {
+        telemetryProps.runtimeFilters = describeRuntimeFilters(runtimeFilters);
+    }
+    if (Array.isArray(runtimeParameters)) {
+        telemetryProps.runtimeParameters = describeRuntimeParameters(runtimeParameters);
+    }
+
+    return telemetryProps;
+};