SCAL-236431 Add embed initialization state management

Author: shivam-kumar-ts

src/embed/ts-embed.spec.ts

@@ -28,6 +28,7 @@ import {
     ContextMenuTriggerOptions,
     CustomActionTarget,
     CustomActionsPosition,
+    InitState,
 } from '../types';
 import {
     executeAfterWait,
@@ -1908,14 +1909,67 @@ describe('Unit test case for ts embed', () => {
             });
         });
 
-        test('Error should be true', async () => {
+        test('Error should be false', async () => {
             spyOn(logger, 'error');
             const tsEmbed = new SearchEmbed(getRootEl(), {});
             await tsEmbed.render();
-            expect(tsEmbed['isError']).toBe(true);
-            expect(logger.error).toHaveBeenCalledWith(
-                'You need to init the ThoughtSpot SDK module first',
-            );
+            expect(tsEmbed['isError']).toBe(false);
+            expect(tsEmbed['getInitState']()).toBe(InitState.Ready);
+            expect(logger.error).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('Initialization State Management', () => {
+        let tsEmbed: SearchEmbed;
+        let mockInitPromise: Promise<any>;
+        let mockResolve: () => void;
+        let mockReject: (error: any) => void;
+    
+        beforeEach(() => {
+            mockInitPromise = new Promise<void>((resolve) => {
+                mockResolve = () => resolve();
+            });
+
+            jest.spyOn(config, 'getThoughtSpotHost').mockImplementation(() => '');
+            init({
+                thoughtSpotHost: '',
+                authType: AuthType.None,
+            });
+        });
+        test('Should initialize with correct state progression (NotStarted -> Initializing -> Ready)', async () => {
+            const initStateChangeCallback = jest.fn();
+            
+            tsEmbed = new SearchEmbed(getRootEl(), {});
+            
+            // Check initial state immediately after construction
+            expect(tsEmbed.getInitState()).toBe(InitState.Initializing);
+            
+            // Register callback for future state changes
+            tsEmbed.on(EmbedEvent.InitStateChange, initStateChangeCallback);
+    
+            // Resolve the init promise to trigger Ready state
+            mockResolve();
+            await mockInitPromise;
+            
+            // Wait a tick for the promise resolution to propagate
+            await new Promise(resolve => setTimeout(resolve, 0));
+    
+            // Should now be Ready
+            expect(tsEmbed.getInitState()).toBe(InitState.Ready);
+            
+            // Check that callback was called
+            expect(initStateChangeCallback).toHaveBeenCalledTimes(1);
+            
+            // Extract just the first argument (the data)
+            const [callData] = initStateChangeCallback.mock.calls[0];
+            expect(callData).toEqual({
+                state: InitState.Ready,
+                previousState: InitState.Initializing,
+                timestamp: expect.any(Number),
+            });
+    
+            // waitForInit should resolve
+            await expect(tsEmbed.waitForInit()).resolves.toBeUndefined();
         });
     });
 

src/embed/ts-embed.ts

@@ -57,6 +57,7 @@ import {
     ContextMenuTriggerOptions,
     DefaultAppInitData,
     AllEmbedViewConfig as ViewConfig,
+    InitState,
 } from '../types';
 import { uploadMixpanelEvent, MIXPANEL_EVENT } from '../mixpanel-service';
 import { processEventData, processAuthFailure } from '../utils/processData';
@@ -186,6 +187,63 @@ export class TsEmbed {
      */
     private fullscreenChangeHandler: (() => void) | null = null;
 
+    /**
+    * Current initialization state
+    */
+    private initState: InitState = InitState.NotStarted;
+    
+    /**
+    * Promise that resolves when initialization is complete
+    */
+    protected initPromise: Promise<void>;
+    
+    /**
+    * Resolve function for the init promise
+    */
+    private initPromiseResolve: () => void;
+
+    /**
+     * Sets the initialization state and emits events
+     */
+    private setInitState(newState: InitState): void {
+        const previousState = this.initState;
+        this.initState = newState;
+        
+        this.executeCallbacks(EmbedEvent.InitStateChange, {
+            state: newState,
+            previousState,
+            timestamp: Date.now(),
+        });
+        
+        if (newState === InitState.Ready) {
+            this.initPromiseResolve();
+        }
+    }
+
+    /**
+     * Gets the current initialization state
+     */
+    public getInitState(): InitState {
+        return this.initState;
+    }
+
+    /**
+     * Returns a promise that resolves when initialization is complete
+     */
+    public waitForInit(): Promise<void> {
+        return this.initPromise;
+    }
+
+    /**
+     * Waits for initialization if needed, otherwise returns immediately
+     */
+    private async ensureInitialized(): Promise<void> {
+        if (this.initState === InitState.Ready) {
+            return; 
+        }
+        await this.waitForInit();
+    }
+
     constructor(domSelector: DOMSelector, viewConfig?: ViewConfig) {
         this.el = getDOMNode(domSelector);
         this.eventHandlerMap = new Map();
@@ -203,23 +261,23 @@ export class TsEmbed {
         this.embedConfig = embedConfig;
 
         this.hostEventClient = new HostEventClient(this.iFrame);
+
+        this.initPromise = new Promise((resolve) => {
+            this.initPromiseResolve = resolve;
+        });
+        this.setInitState(InitState.Initializing);
+
         this.isReadyForRenderPromise = getInitPromise().then(async () => {
             if (!embedConfig.authTriggerContainer && !embedConfig.useEventForSAMLPopup) {
                 this.embedConfig.authTriggerContainer = domSelector;
             }
             this.thoughtSpotHost = getThoughtSpotHost(embedConfig);
             this.thoughtSpotV2Base = getV2BasePath(embedConfig);
             this.shouldEncodeUrlQueryParams = embedConfig.shouldEncodeUrlQueryParams;
+            this.setInitState(InitState.Ready);
         });
     }
 
-    /**
-     * Throws error encountered during initialization.
-     */
-    private throwInitError() {
-        this.handleError('You need to init the ThoughtSpot SDK module first');
-    }
-
     /**
      * Handles errors within the SDK
      * @param error The error message or object
@@ -814,8 +872,12 @@ export class TsEmbed {
         if (this.isError) {
             return null;
         }
-        if (!this.thoughtSpotHost) {
-            this.throwInitError();
+        // Wait for initialization instead of throwing error
+        try {
+            await this.ensureInitialized();
+        } catch (error) {
+            this.handleError('Cannot render: initialization failed');
+            return null;
         }
         if (url.length > URL_MAX_LENGTH) {
             // warn: The URL is too long

src/errors.ts

@@ -20,6 +20,7 @@ export const ERROR_MESSAGE = {
     RENDER_CALLED_BEFORE_INIT: 'Looks like render was called before calling init, the render won\'t start until init is called.\nFor more info check\n1. https://developers.thoughtspot.com/docs/Function_init#_init\n2.https://developers.thoughtspot.com/docs/getting-started#initSdk',
     SPOTTER_AGENT_NOT_INITIALIZED: 'SpotterAgent not initialized',
     OFFLINE_WARNING : 'Network not Detected. Embed is offline. Please reconnect and refresh',
+    EMBED_INITIALIZATION_FAILED: 'Embed initialization failed',
 };
 
 export const CUSTOM_ACTIONS_ERROR_MESSAGE = {

src/types.ts

@@ -2905,6 +2905,25 @@ export enum EmbedEvent {
      * @version SDK: 1.41.0 | ThoughtSpot: 10.12.0.cl
      */
     OrgSwitched = 'orgSwitched',
+
+    /**
+     * Embed initialization state has changed
+     * @returns state - The current initialization state
+     * @returns previousState - The previous initialization state  
+     * @version SDK: 1.42.1 | ThoughtSpot: 10.15.0.cl
+     * @example
+     * ```js
+     * liveboardEmbed.on(EmbedEvent.InitStateChange, (payload) => {
+     *   console.log(`Init state changed from ${payload.previousState} to ${payload.state}`);
+     *   if (payload.state === 'initializing') {
+     *     showLoader();
+     *   } else if (payload.state === 'ready') {
+     *     hideLoader();
+     *   }
+     * });
+     * ```
+     */
+    InitStateChange = 'initStateChange',
 }
 
 /**
@@ -5867,6 +5886,32 @@ export enum LogLevel {
     TRACE = 'TRACE',
 }
 
+/**
+ * Represents the initialization state of an embed instance
+ *
+ * @version SDK: 1.42.1 | ThoughtSpot: 10.15.0.cl
+ * @example
+ * ``` js
+ * NotStarted = 'not-started'
+ * Initializing = 'initializing'
+ * Ready = 'ready'
+ * ```
+ */
+export enum InitState {
+    /**
+     * Embed instance created but initialization not started
+     */
+    NotStarted = 'not-started',
+    /**
+     * SDK initialization in progress  
+     */
+    Initializing = 'initializing',
+    /**
+     * SDK initialization completed successfully
+     */
+    Ready = 'ready',
+}
+
 export interface DefaultAppInitData {
     customisations: CustomisationsInterface;
     authToken: string;