@thoughtspot/visual-embed-sdk 1.52.2-beta.1 → 1.53.0

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

@@ -1,6 +1,39 @@
 import { AutoMCPFrameRendererViewConfig, Param } from "../types";
 import { TsEmbed } from "./ts-embed";
 import { getQueryParamString } from "../utils";
+import { tokenizedFetch } from "../tokenizedFetch";
+import { logger } from "../utils/logger";
+
+/**
+ * Route the ThoughtSpot application uses to render a single conversational
+ * answer. Used when a replayed frame carries no route of its own.
+ */
+const CONV_ASSIST_ANSWER_ROUTE = '/embed/conv-assist-answer';
+
+/**
+ * Base path of the conversation service, proxied by the cluster's nginx as
+ * the `convex` upstream. These are the same handlers the public
+ * `/api/rest/2.0/ai/agent/conversations/...` endpoints proxy to, so the
+ * response shapes are identical, but calling them directly skips the prism
+ * hop and its error re-wrapping.
+ */
+const CONVERSATION_SERVICE_PATH = '/conversation/v2';
+
+const DEFAULT_STALE_ANSWER_NOTICE =
+    'This data may have changed since the last time you had a chat.';
+
+/**
+ * Hash parameters that locate a specific answer generation. These expire with
+ * the answer object (roughly 8 hours), which is why a host app replaying a
+ * stored conversation must not persist them - it stores the conversation
+ * identifier instead and lets the renderer resolve these afresh.
+ */
+interface AnswerSessionParams {
+    sessionId: string;
+    genNo: string;
+    acSessionId: string;
+    acGenNo: string;
+}
 
 
 /**
@@ -36,7 +69,7 @@ import { getQueryParamString } from "../utils";
  * // Later, stop watching
  * observer.disconnect();
  * ```
- * 
+ *
  * @example
  * Detailed example of how to use the auto-frame renderer:
  * [Python React Agent Simple UI](https://github.com/thoughtspot/developer-examples/tree/main/mcp/python-react-agent-simple-ui)
@@ -70,6 +103,122 @@ export function startAutoMCPFrameRenderer(viewConfig: AutoMCPFrameRendererViewCo
     return observer;
 }
 
+/**
+ * Writes resolved session parameters into the route's hash query string,
+ * preserving the route and any other hash params the source URL carried.
+ *
+ * @param sourceHash - The source URL's hash, with or without a leading `#`.
+ *   Falls back to the conversational-answer route when empty, so a host app
+ *   replaying a chat need only supply the conversation identifier.
+ */
+function buildAnswerHash(sourceHash: string, resolved: AnswerSessionParams): string {
+    const withoutHash = (sourceHash || '').replace('#', '');
+    const [route, existingQuery] = withoutHash.split('?');
+    const params = new URLSearchParams(existingQuery || '');
+    Object.entries(resolved).forEach(([key, value]) => params.set(key, value));
+    return `${route || CONV_ASSIST_ANSWER_ROUTE}?${params.toString()}`;
+}
+
+/**
+ * Reads {@link Param.TsmcpAnswerIndex} as a whole, non-negative array index.
+ *
+ * Anything else - absent, malformed, fractional, negative - falls back to the
+ * first answer rather than indexing with a value that can never match.
+ */
+function answerIndexFromParam(raw: string | null): number {
+    const parsed = Number(raw);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : 0;
+}
+
+/**
+ * In-flight answer-id list requests, keyed by conversation-service URL.
+ *
+ * Replaying a stored chat mounts every one of its frames at once, and each
+ * frame resolves on its own. Without this, N frames from one conversation make
+ * N identical list calls. Sharing the in-flight request collapses them to one.
+ *
+ * Only the id list is shared, and only while its request is in flight: the
+ * entry is dropped once the request settles, whether it succeeded or not. A
+ * failed response is therefore never reused, and a frame mounted later always
+ * reads a fresh list. The per-answer load call is never shared - it returns
+ * live session state with its own expiry.
+ */
+const answerIdListRequests = new Map<string, Promise<string[] | null>>();
+
+/**
+ * Lists a conversation's answer ids: its non-thinking `answer` items, in
+ * message order. The host app counts answers the same way, so the Nth id here
+ * is the Nth stored answer.
+ *
+ * @param conversationUrl - The conversation's base URL on the conversation
+ *   service, `{host}/conversation/v2/{encoded id}`.
+ * @param conversationId - The conversation identifier, used in log messages.
+ * @returns The ids, or `null` when the conversation cannot be read. Never
+ *   rejects, so callers sharing the request need no error handling of their own.
+ */
+async function fetchAnswerIds(conversationUrl: string, conversationId: string): Promise<string[] | null> {
+    try {
+        const messagesResponse = await tokenizedFetch(`${conversationUrl}/public`, {
+            credentials: 'include',
+            headers: { Accept: 'application/json' },
+        });
+        if (!messagesResponse.ok) {
+            logger.warn(
+                `[AutoFrameRenderer] Conversation fetch failed for ${conversationId}: ${messagesResponse.status}`,
+            );
+            return null;
+        }
+        const messagesBody = await messagesResponse.json();
+        const messages = messagesBody?.messages;
+
+        const answerIds: string[] = [];
+        for (const message of Array.isArray(messages) ? messages : []) {
+            for (const item of message?.response_items || []) {
+                if (item?.type === 'answer' && item?.is_thinking === false && item?.answer_id) {
+                    answerIds.push(item.answer_id);
+                }
+            }
+        }
+        return answerIds;
+    } catch (e) {
+        logger.warn(`[AutoFrameRenderer] Failed to list answers for ${conversationId}: ${e}`);
+        return null;
+    }
+}
+
+/**
+ * The answer-id list for a conversation, joining a request already in flight
+ * for it.
+ *
+ * @param conversationUrl - The conversation's base URL on the conversation
+ *   service. Also the key requests are shared under.
+ * @param conversationId - The conversation identifier, used in log messages.
+ * @param stale - A request the caller already read and found too short. It is
+ *   not reused; the first caller to pass it starts a new request, and the
+ *   others join that one.
+ * @returns The shared request: the ids, or `null` when the conversation cannot
+ *   be read. Never rejects.
+ */
+function getAnswerIds(
+    conversationUrl: string,
+    conversationId: string,
+    stale?: Promise<string[] | null>,
+): Promise<string[] | null> {
+    const inFlight = answerIdListRequests.get(conversationUrl);
+    if (inFlight && inFlight !== stale) {
+        return inFlight;
+    }
+    const request = fetchAnswerIds(conversationUrl, conversationId);
+    answerIdListRequests.set(conversationUrl, request);
+    const release = () => {
+        if (answerIdListRequests.get(conversationUrl) === request) {
+            answerIdListRequests.delete(conversationUrl);
+        }
+    };
+    request.then(release, release);
+    return request;
+}
+
 function isTSMCPIframe(iframe: HTMLIFrameElement) {
     try {
         const url = new URL(iframe.src);
@@ -105,22 +254,135 @@ class AutoFrameRenderer extends TsEmbed {
      * ThoughtSpot application.
      *
      * @param sourceSrc - The original iframe's `src` URL string.
+     * @param preserveSourceUrl - When true, return the source URL unchanged.
      * @returns The constructed URL to use for the ThoughtSpot embed iframe.
      */
-    private getMCPIframeSrc(sourceSrc: string) {
-        const queryParams = this.getEmbedParamsObject();
+    private getMCPIframeSrc(
+        sourceSrc: string,
+        resolved?: AnswerSessionParams,
+        preserveSourceUrl = false,
+    ) {
+        if (preserveSourceUrl) {
+            return sourceSrc;
+        }
+        const queryParams = this.getUrlQueryParamsObject();
         const sourceURL = new URL(sourceSrc);
         const existingQueryParams = sourceURL.searchParams;
         const existingQueryParamsObject = Object.fromEntries(existingQueryParams);
         delete existingQueryParamsObject[Param.Tsmcp];
+        // Replay markers address the SDK, not the ThoughtSpot application.
+        delete existingQueryParamsObject[Param.TsmcpConversationId];
+        delete existingQueryParamsObject[Param.TsmcpAnswerIndex];
 
         const mergedQueryParams = { ...queryParams, ...existingQueryParamsObject };
         const mergedQueryParamsString = getQueryParamString(mergedQueryParams, true);
         const queryString = mergedQueryParamsString ? `?${mergedQueryParamsString}` : '';
-        const frameSrc = `${this.getEmbedBasePath(queryString)}${sourceURL.hash.replace('#', '')}`;
+        const hash = resolved
+            ? buildAnswerHash(sourceURL.hash, resolved)
+            : sourceURL.hash.replace('#', '');
+        const frameSrc = `${this.getEmbedBasePath(queryString)}${hash}`;
         return frameSrc;
     }
 
+    /**
+     * Resolves the current session parameters for an answer stored only as a
+     * conversation identifier plus an ordinal position.
+     *
+     * The answer object behind `sessionId`/`genNo` expires (roughly 8 hours),
+     * so a host app replaying a stored chat cannot persist those values. It
+     * persists the conversation identifier instead, and this walks the two
+     * conversation-service APIs to rebuild them:
+     *
+     * 1. `GET {conv}/public` lists the conversation's messages; the
+     *    non-thinking `answer` items, in message order, give the answer ids.
+     *    Frames from the same conversation share one in-flight call - see
+     *    {@link getAnswerIds}.
+     * 2. `POST {conv}/message/{id}/load/public` turns the answer id at
+     *    `answerIndex` into a live session identifier, generation number and
+     *    agent-context state.
+     *
+     * @returns The resolved parameters, or `null` when resolution fails - the
+     *   caller then falls back to whatever the source URL already carried.
+     */
+    private async resolveAnswerSessionParams(
+        conversationId: string,
+        answerIndex: number,
+    ): Promise<AnswerSessionParams | null> {
+        const base = `${this.thoughtSpotHost}${CONVERSATION_SERVICE_PATH}/${encodeURIComponent(conversationId)}`;
+        try {
+            const listRequest = getAnswerIds(base, conversationId);
+            let answerIds = await listRequest;
+            if (answerIds && !answerIds[answerIndex]) {
+                // The list only grows, so a short one may predate this answer:
+                // a frame that joined a request started before it was added.
+                // Read the list once more before giving up.
+                answerIds = await getAnswerIds(base, conversationId, listRequest);
+            }
+            if (!answerIds) {
+                return null;
+            }
+
+            const answerId = answerIds[answerIndex];
+            if (!answerId) {
+                logger.warn(
+                    `[AutoFrameRenderer] No answer at index ${answerIndex} in conversation ${conversationId} (found ${answerIds.length}).`,
+                );
+                return null;
+            }
+
+            // The load handler is a POST upstream; the public REST endpoint
+            // exposed it as a GET and supplied this body on the caller's
+            // behalf.
+            const detailsResponse = await tokenizedFetch(
+                `${base}/message/${encodeURIComponent(answerId)}/load/public`,
+                {
+                    credentials: 'include',
+                    method: 'POST',
+                    headers: {
+                        Accept: 'application/json',
+                        'Content-Type': 'application/json',
+                        'x-requested-by': 'ThoughtSpot',
+                    },
+                    body: JSON.stringify({ type: 'TS_ANSWER' }),
+                },
+            );
+            if (!detailsResponse.ok) {
+                logger.warn(
+                    `[AutoFrameRenderer] Answer load failed for ${answerId}: ${detailsResponse.status}`,
+                );
+                return null;
+            }
+            const detailsBody = await detailsResponse.json();
+            const answer = detailsBody?.answer;
+            const acState = answer?.ac_state;
+            // All four are nullable in the load-answer response. A missing
+            // generation number is as unusable as a missing session id:
+            // stringifying it would put a literal "null" in the hash. Fail
+            // the resolve instead and let the caller fall back.
+            if (
+                !answer?.session_identifier
+                || !acState?.transaction_identifier
+                || !(Number.isInteger(answer.generation_number) && answer.generation_number > 0)
+                || !(Number.isInteger(acState.generation_number) && acState.generation_number > 0)
+            ) {
+                logger.warn(
+                    `[AutoFrameRenderer] Answer load returned incomplete session state for ${answerId}.`,
+                );
+                return null;
+            }
+
+            return {
+                sessionId: answer.session_identifier,
+                genNo: String(answer.generation_number),
+                acSessionId: acState.transaction_identifier,
+                acGenNo: String(acState.generation_number),
+            };
+        } catch (e) {
+            logger.warn(`[AutoFrameRenderer] Failed to resolve stored answer: ${e}`);
+            return null;
+        }
+    }
+
     /**
      * Overrides the base insertion behavior so the new embed iframe
      * replaces the original iframe in-place rather than being appended
@@ -149,9 +411,46 @@ class AutoFrameRenderer extends TsEmbed {
         if (this.shouldWaitForRenderPromise) {
             await this.isReadyForRenderPromise;
         }
-        const src = this.getMCPIframeSrc(iframe.src);
+
+        // Only frames that ask for it take the replay path. A frame straight
+        // from the MCP server carries its own session params and no
+        // conversation id, so it renders exactly as it always has.
+        const sourceParams = new URL(iframe.src).searchParams;
+        const conversationId = sourceParams.get(Param.TsmcpConversationId);
+        let resolved: AnswerSessionParams | null = null;
+        if (conversationId) {
+            resolved = await this.resolveAnswerSessionParams(
+                conversationId,
+                answerIndexFromParam(sourceParams.get(Param.TsmcpAnswerIndex)),
+            );
+        }
+
+        const src = this.getMCPIframeSrc(
+            iframe.src,
+            resolved ?? undefined,
+            Boolean(conversationId) && !resolved,
+        );
         await this.renderIFrame(src);
+
+        // Mark only answers actually re-resolved: their numbers were computed
+        // now, not when the conversation happened.
+        if (resolved && !this.viewConfig.suppressStaleAnswerNotice) {
+            this.markAsStaleAnswer();
+        }
         this.isRendered = true;
     }
-}
 
+    /**
+     * Adds the "data may have changed" notice to the rendered frame as a
+     * native tooltip, so it needs no stylesheet and cannot disturb the host
+     * app's layout.
+     */
+    private markAsStaleAnswer(): void {
+        if (!this.iFrame) {
+            return;
+        }
+        this.iFrame.title = this.viewConfig.staleAnswerNoticeText || DEFAULT_STALE_ANSWER_NOTICE;
+        // Exposed so a host app can style or replace the native tooltip.
+        this.iFrame.dataset.tsStaleAnswer = 'true';
+    }
+}

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

@@ -1,4 +1,10 @@
-import { SpotterEmbed, SpotterEmbedViewConfig, SpotterQueryMode, ConversationEmbed } from './conversation';
+import {
+    SpotterEmbed,
+    SpotterEmbedViewConfig,
+    SpotterQueryMode,
+    ConversationEmbed,
+} from './conversation';
+import { SpotterExperienceVersion } from './spotter-utils';
 import { TsEmbed } from './ts-embed';
 import * as authInstance from '../auth';
 import { Action, init } from '../index';
@@ -79,6 +85,93 @@ describe('ConversationEmbed', () => {
         );
     });
 
+    it('should use the conv-assist path when spotterExperienceVersion is not set', async () => {
+        const viewConfig: SpotterEmbedViewConfig = {
+            worksheetId: 'worksheetId',
+            searchOptions: {
+                searchQuery: 'searchQuery',
+            },
+        };
+
+        const conversationEmbed = new SpotterEmbed(getRootEl(), viewConfig);
+        await conversationEmbed.render();
+        expect(getIFrameSrc().split('#')[1].split('?')[0]).toBe(
+            '/embed/insights/conv-assist',
+        );
+    });
+
+    it('should use the spotter path when spotterExperienceVersion is SPOTTER_2026_11', async () => {
+        const viewConfig: SpotterEmbedViewConfig = {
+            worksheetId: 'worksheetId',
+            searchOptions: {
+                searchQuery: 'searchQuery',
+            },
+            spotterExperienceVersion: SpotterExperienceVersion.SPOTTER_2026_11,
+        };
+
+        const conversationEmbed = new SpotterEmbed(getRootEl(), viewConfig);
+        await conversationEmbed.render();
+        expect(getIFrameSrc().split('#')[1].split('?')[0]).toBe(
+            '/embed/insights/spotter',
+        );
+    });
+
+    it('should use the spotter reader-view path when spotterExperienceVersion is SPOTTER_2026_11 and sharedConversationId is set', async () => {
+        const viewConfig: SpotterEmbedViewConfig = {
+            worksheetId: 'worksheetId',
+            searchOptions: {
+                searchQuery: 'searchQuery',
+            },
+            sharedConversationId: 'conv-123',
+            spotterExperienceVersion: SpotterExperienceVersion.SPOTTER_2026_11,
+        };
+
+        const conversationEmbed = new SpotterEmbed(getRootEl(), viewConfig);
+        await conversationEmbed.render();
+        expect(getIFrameSrc().split('#')[1].split('?')[0]).toBe(
+            '/embed/insights/spotter/s/conv-123',
+        );
+    });
+
+    it('should keep the conv-assist path for an unrecognized spotterExperienceVersion value', async () => {
+        const viewConfig: SpotterEmbedViewConfig = {
+            worksheetId: 'worksheetId',
+            searchOptions: {
+                searchQuery: 'searchQuery',
+            },
+            spotterExperienceVersion: 'some_future_ui' as SpotterExperienceVersion,
+        };
+
+        const conversationEmbed = new SpotterEmbed(getRootEl(), viewConfig);
+        await conversationEmbed.render();
+        expect(getIFrameSrc().split('#')[1].split('?')[0]).toBe(
+            '/embed/insights/conv-assist',
+        );
+    });
+
+    it('should add the spotterExperienceVersion param when spotterExperienceVersion is set', async () => {
+        const viewConfig: SpotterEmbedViewConfig = {
+            worksheetId: 'worksheetId',
+            spotterExperienceVersion: SpotterExperienceVersion.SPOTTER_2026_11,
+        };
+
+        const conversationEmbed = new SpotterEmbed(getRootEl(), viewConfig);
+        await conversationEmbed.render();
+        expect(getIFrameSrc()).toContain(
+            `spotterExperienceVersion=${SpotterExperienceVersion.SPOTTER_2026_11}`,
+        );
+    });
+
+    it('should not add the spotterExperienceVersion param when spotterExperienceVersion is not set', async () => {
+        const viewConfig: SpotterEmbedViewConfig = {
+            worksheetId: 'worksheetId',
+        };
+
+        const conversationEmbed = new SpotterEmbed(getRootEl(), viewConfig);
+        await conversationEmbed.render();
+        expect(getIFrameSrc()).not.toContain('spotterExperienceVersion=');
+    });
+
     it('should render the conversation embed with worksheets disabled', async () => {
         const viewConfig: SpotterEmbedViewConfig = {
             worksheetId: 'worksheetId',

package/src/embed/conversation.ts

@@ -1,6 +1,12 @@
 import { Param, BaseViewConfig, RuntimeFilter, RuntimeParameter, ErrorDetailsTypes, EmbedErrorCodes, DefaultAppInitData, VisualizationOverrides, SpotterFileUploadFileTypes } from '../types';
 import { TsEmbed } from './ts-embed';
-import { buildSpotterSidebarAppInitData, buildSpotterShareConversationAppInitData, buildStarterPromptsAppInitData, buildSpotterAnalystAppInitData } from './spotter-utils';
+import {
+    buildSpotterSidebarAppInitData,
+    buildSpotterShareConversationAppInitData,
+    buildStarterPromptsAppInitData,
+    buildSpotterAnalystAppInitData,
+    SpotterExperienceVersion,
+} from './spotter-utils';
 import { getQueryParamString, getFilterQuery, getRuntimeParameters, setParamIfDefined } from '../utils';
 
 /**
@@ -437,6 +443,20 @@ export interface SpotterAnalystConfig {
  * @group Embed components
  */
 export interface SpotterEmbedViewConfig extends Omit<BaseViewConfig, 'primaryAction'> {
+    /**
+     * The Spotter experience version to load. When set to
+     * `SpotterExperienceVersion.SPOTTER_2026_11`, the embed loads the updated Spotter
+     * surface instead of the default conversation surface.
+     * @version SDK: 1.53.0 | ThoughtSpot Cloud: 26.11.0.cl
+     * @example
+     * ```js
+     * const embed = new SpotterEmbed('#tsEmbed', {
+     *    ... // other options
+     *    spotterExperienceVersion: SpotterExperienceVersion.SPOTTER_2026_11,
+     * });
+     * ```
+     */
+    spotterExperienceVersion?: SpotterExperienceVersion;
     /**
      * The ID of the data source object. For example, Model, View, or Table. Spotter uses
      * this object to query data and generate Answers.
@@ -909,6 +929,7 @@ export class SpotterEmbed extends TsEmbed {
         }
 
         setParamIfDefined(queryParams, Param.UpdatedSpotterExperience, updatedSpotterExperience, true);
+        setParamIfDefined(queryParams, Param.SpotterExperienceVersion, this.viewConfig.spotterExperienceVersion);
 
         return queryParams;
     }
@@ -923,15 +944,19 @@ export class SpotterEmbed extends TsEmbed {
             excludeRuntimeParametersfromURL,
             sharedConversationId,
             dataSources,
+            spotterExperienceVersion,
         } = this.viewConfig;
         // Deep-link into the read-only shared-conversation reader view when a
         // shared conversation id is supplied (e.g. a recipient landing from a
         // host-configured CONVERSATION_URL share link); otherwise the normal
         // Spotter conversation surface.
-        const path = sharedConversationId
+        let path = sharedConversationId
             ? `insights/conv-assist/s/${encodeURIComponent(sharedConversationId)}`
             : 'insights/conv-assist';
-        const queryParams = this.getEmbedParamsObject();
+        if (spotterExperienceVersion === SpotterExperienceVersion.SPOTTER_2026_11) {
+            path = path.replace('insights/conv-assist', 'insights/spotter');
+        }
+        const queryParams = this.getUrlQueryParamsObject();
 
         let query = '';
         const queryParamsString = getQueryParamString(queryParams, true);

package/src/embed/liveboard-override-utils.spec.ts

@@ -0,0 +1,38 @@
+import { buildLiveboardOverrideAppInitData, LiveboardOverride } from './liveboard-override-utils';
+
+describe('buildLiveboardOverrideAppInitData', () => {
+    const base = { type: 'APP_INIT' } as any;
+    const liveboardOverride: LiveboardOverride = {
+        dataSourceOverride: [{
+            dataSourceIdentifier: 'model-guid',
+            filterQuery: [{ tabName: 'Sales', groupName: 'Region', filterQueryToken: 'color = red' }],
+            parameterQuery: [{ parameterQueryToken: 'discount = 10' }],
+        }],
+    };
+
+    it('returns initData unchanged when liveboardOverride is not provided', () => {
+        const result = buildLiveboardOverrideAppInitData(base, {});
+        expect(result).toBe(base);
+    });
+
+    it('returns initData unchanged when dataSourceOverride is empty', () => {
+        const result = buildLiveboardOverrideAppInitData(base, {
+            liveboardOverride: { dataSourceOverride: [] },
+        });
+        expect(result).toBe(base);
+    });
+
+    it('nests liveboardOverride under embedParams.liveboardOverride', () => {
+        const result = buildLiveboardOverrideAppInitData(base, { liveboardOverride });
+        expect(result.embedParams?.liveboardOverride).toEqual(liveboardOverride);
+    });
+
+    it('preserves existing embedParams keys', () => {
+        const spotterVizConfig = { brandName: 'MyBrand' };
+        const result = buildLiveboardOverrideAppInitData(
+            { ...base, embedParams: { spotterVizConfig } },
+            { liveboardOverride },
+        );
+        expect(result.embedParams).toEqual({ spotterVizConfig, liveboardOverride });
+    });
+});

package/src/embed/liveboard-override-utils.ts

@@ -0,0 +1,71 @@
+import type { DefaultAppInitData } from '../types';
+
+/**
+ * A filter to apply to a Liveboard when it loads.
+ * @version SDK: 1.54.0 | ThoughtSpot Cloud: 26.11.0.cl
+ * @group Embed components
+ */
+export interface LiveboardFilterQuery {
+    /** Name of the Liveboard tab the filter applies to. */
+    tabName?: string;
+    /** Name of the group within the tab that the filter applies to. */
+    groupName?: string;
+    /**
+     * The filter condition, in search sentence form. For example, `color = red`.
+     */
+    filterQueryToken: string;
+}
+
+/**
+ * A Parameter value to apply to a Liveboard when it loads.
+ * @version SDK: 1.54.0 | ThoughtSpot Cloud: 26.11.0.cl
+ * @group Embed components
+ */
+export interface LiveboardParameterQuery {
+    /** Name of the Liveboard tab the Parameter applies to. */
+    tabName?: string;
+    /** Name of the group within the tab that the Parameter applies to. */
+    groupName?: string;
+    /** The Parameter assignment. */
+    parameterQueryToken: string;
+}
+
+/**
+ * Filter and Parameter overrides for one data source on the Liveboard.
+ * @version SDK: 1.54.0 | ThoughtSpot Cloud: 26.11.0.cl
+ * @group Embed components
+ */
+export interface LiveboardDataSourceOverride {
+    /** The data source (Model) the overrides apply to. */
+    dataSourceIdentifier?: string;
+    /** Filters to apply for this data source. */
+    filterQuery?: LiveboardFilterQuery[];
+    /** Parameter values to apply for this data source. */
+    parameterQuery?: LiveboardParameterQuery[];
+}
+
+/**
+ * Filter and Parameter overrides applied to a Liveboard when it loads.
+ * @version SDK: 1.54.0 | ThoughtSpot Cloud: 26.11.0.cl
+ * @group Embed components
+ */
+export interface LiveboardOverride {
+    /** One entry per data source to override. */
+    dataSourceOverride: LiveboardDataSourceOverride[];
+}
+
+export function buildLiveboardOverrideAppInitData<T extends DefaultAppInitData>(
+    initData: T,
+    viewConfig: { liveboardOverride?: LiveboardOverride },
+): T & { embedParams?: { liveboardOverride?: LiveboardOverride } } {
+    const { liveboardOverride } = viewConfig;
+    // ThoughtSpot ignores an override with no data source entries; skip it.
+    if (!liveboardOverride?.dataSourceOverride?.length) return initData;
+    return {
+        ...initData,
+        embedParams: {
+            ...((initData as T & { embedParams?: Record<string, unknown> }).embedParams || {}),
+            liveboardOverride,
+        },
+    };
+}