@thoughtspot/visual-embed-sdk 1.20.0 → 1.20.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thoughtspot/visual-embed-sdk",
-    "version": "1.20.0",
+    "version": "1.20.2",
     "description": "ThoughtSpot Embed SDK",
     "module": "lib/src/index.js",
     "main": "dist/tsembed.js",
@@ -135,8 +135,7 @@
         "ts-jest": "^26.5.5",
         "ts-loader": "8.0.4",
         "typedoc": "0.21.6",
-        "typedoc-neo-theme": "^1.1.0",
-        "typedoc-plugin-toc-group": "0.0.5",
+        "typedoc-plugin-toc-group": "thoughtspot/typedoc-plugin-toc-group",
         "typescript": "^4.9.4",
         "url-search-params-polyfill": "^8.1.0",
         "util": "^0.12.4"

package/src/auth.ts

@@ -39,6 +39,11 @@ export const EndPoints = {
     LOGOUT: '/callosum/v1/session/logout',
 };
 
+/**
+ * Enum for auth failure types. This is the parameter passed to the listner
+ * of {@link AuthStatus.FAILURE}.
+ * @group Authentication / Init
+ */
 export enum AuthFailureType {
     SDK = 'SDK',
     NO_COOKIE_ACCESS = 'NO_COOKIE_ACCESS',
@@ -46,6 +51,10 @@ export enum AuthFailureType {
     OTHER = 'OTHER',
 }
 
+/**
+ * Enum for auth status emitted by the emitter returned from {@link init}.
+ * @group Authentication / Init
+ */
 export enum AuthStatus {
     /**
      * Emits when the SDK fails to authenticate
@@ -72,20 +81,56 @@ export enum AuthStatus {
     WAITING_FOR_POPUP = 'WAITING_FOR_POPUP',
 }
 
+/**
+ * Event emitter returned from {@link init}.
+ * @group Authentication / Init
+ */
+export interface AuthEventEmitter {
+    /**
+     * Registed a listener on Auth failure.
+     * @param event
+     * @param listener
+     */
+    on(
+        event: AuthStatus.FAILURE,
+        listener: (failureType: AuthFailureType) => void,
+    ): this;
+    on(
+        event:
+            | AuthStatus.SDK_SUCCESS
+            | AuthStatus.LOGOUT
+            | AuthStatus.WAITING_FOR_POPUP,
+        listener: () => void,
+    ): this;
+    on(event: AuthStatus.SUCCESS, listener: (sessionInfo: any) => void): this;
+    /**
+     * Trigger an event on the emitter returned from init.
+     * @param {@link AuthEvent}
+     */
+    emit(event: AuthEvent): void;
+}
+
+/**
+ * Events which can be triggered on the emitter returned from {@link init}.
+ * @group Authentication / Init
+ */
 export enum AuthEvent {
     /**
-     * Manually trigger the SSO popup.
+     * Manually trigger the SSO popup. This is useful with
+     * authStatus: SAMLRedirect/OIDCRedicre and inPopup: true
      */
     TRIGGER_SSO_POPUP = 'TRIGGER_SSO_POPUP',
 }
 
-let authEE: EventEmitter;
+let authEE: EventEmitter<AuthStatus | AuthEvent>;
 
-export function getAuthEE(): EventEmitter {
+export function getAuthEE(): EventEmitter<AuthStatus | AuthEvent> {
     return authEE;
 }
 
-export function setAuthEE(eventEmitter: EventEmitter): void {
+export function setAuthEE(
+    eventEmitter: EventEmitter<AuthStatus | AuthEvent>,
+): void {
     authEE = eventEmitter;
 }
 
@@ -146,8 +191,9 @@ export function getReleaseVersion() {
 }
 
 /**
- * Return a promise that resolves with the session info when authentication is
+ * Return a promise that resolves with the session information when authentication is
  * successful. And info is available.
+ * @group Global methods
  */
 export function getSessionInfo(): Promise<any> {
     return sessionInfoPromise;

package/src/embed/app.ts

@@ -56,7 +56,7 @@ export enum Page {
 
 /**
  * The view configuration for full app embedding.
- * @Category App Embed
+ * @group Embed components
  */
 export interface AppViewConfig extends ViewConfig {
     /**
@@ -105,7 +105,7 @@ export interface AppViewConfig extends ViewConfig {
 
 /**
  * Embeds full ThoughtSpot experience in a host application.
- * @Category App Embed
+ * @group Embed components
  */
 export class AppEmbed extends V1Embed {
     protected viewConfig: AppViewConfig;

package/src/embed/base.spec.ts

@@ -20,7 +20,7 @@ describe('Base TS Embed', () => {
         authEE = index.init({
             thoughtSpotHost,
             authType: index.AuthType.None,
-        });
+        }) as EventEmitter;
     });
 
     beforeEach(() => {
@@ -148,9 +148,9 @@ describe('Base TS Embed', () => {
         });
 
         authEmitter.on(auth.AuthStatus.FAILURE, failureCallback);
-        authEmitter.on(auth.AuthStatus.SDK_SUCCESS, (reason) => {
+        authEmitter.on(auth.AuthStatus.SDK_SUCCESS, (...args) => {
             expect(failureCallback).not.toBeCalled();
-            expect(reason).toBe(undefined);
+            expect(args.length).toBe(0);
             done();
         });
     });

package/src/embed/base.ts

@@ -16,11 +16,13 @@ import {
     logout as _logout,
     AuthFailureType,
     AuthStatus,
+    AuthEvent,
     notifyAuthFailure,
     notifyAuthSDKSuccess,
     notifyAuthSuccess,
     notifyLogout,
     setAuthEE,
+    AuthEventEmitter,
 } from '../auth';
 import { uploadMixpanelEvent, MIXPANEL_EVENT } from '../mixpanel-service';
 
@@ -32,7 +34,13 @@ const CONFIG_DEFAULTS: Partial<EmbedConfig> = {
 };
 
 export let authPromise: Promise<boolean>;
-
+/**
+ * Gets the configuration embed was initialized with.
+ *
+ * @returns {@link EmbedConfig} The configuration embed was initialized with.
+ * @version SDK: 1.19.0 | ThoughtSpot: *
+ * @group Global methods
+ */
 export const getEmbedConfig = (): EmbedConfig => config;
 
 export const getAuthPromise = (): Promise<boolean> => authPromise;
@@ -76,6 +84,7 @@ const hostUrlToFeatureUrl = {
  * @param url The URL provided for prefetch
  * @param prefetchFeatures Specify features which needs to be prefetched.
  * @version SDK: 1.4.0 | ThoughtSpot: ts7.sep.cl, 7.2.1
+ * @group Global methods
  */
 export const prefetch = (
     url?: string,
@@ -136,15 +145,26 @@ function backwardCompat(embedConfig: EmbedConfig): EmbedConfig {
 
 /**
  * Initializes the Visual Embed SDK globally and perform
- * authentication if applicable.
+ * authentication if applicable. This function needs to be called before any ThoughtSpot
+ * component like liveboard etc can be embedded. But need not wait for AuthEvent.SUCCESS
+ * to actually embed. That is handled internally.
  * @param embedConfig The configuration object containing ThoughtSpot host,
  * authentication mechanism and so on.
- * example: authStatus = init(config);
- * authStatus.on(AuthStatus.FAILURE, (reason) => { // do something here });
- * @returns event emitter which emits events on authentication success, failure and logout. See {@link AuthStatus}
+ *
+ * @example
+ * ```js
+ *   const authStatus = init({
+ *     thoughtSpotHost: 'https://my.thoughtspot.cloud',
+ *     authType: AuthType.None,
+ *   });
+ *   authStatus.on(AuthStatus.FAILURE, (reason) => { // do something here });
+ * ```
+ *
+ * @returns {@link AuthEventEmitter} event emitter which emits events on authentication success, failure and logout. See {@link AuthStatus}
  * @version SDK: 1.0.0 | ThoughtSpot ts7.april.cl, 7.2.1
+ * @group Authentication / Init
  */
-export const init = (embedConfig: EmbedConfig): EventEmitter => {
+export const init = (embedConfig: EmbedConfig): AuthEventEmitter => {
     sanity(embedConfig);
     config = {
         ...CONFIG_DEFAULTS,
@@ -152,7 +172,7 @@ export const init = (embedConfig: EmbedConfig): EventEmitter => {
         thoughtSpotHost: getThoughtSpotHost(embedConfig),
     };
     config = backwardCompat(config);
-    const authEE = new EventEmitter();
+    const authEE = new EventEmitter<AuthStatus | AuthEvent>();
     setAuthEE(authEE);
     handleAuth();
 
@@ -175,7 +195,7 @@ export const init = (embedConfig: EmbedConfig): EventEmitter => {
     if (config.callPrefetch) {
         prefetch(config.thoughtSpotHost);
     }
-    return authEE;
+    return authEE as AuthEventEmitter;
 };
 
 export function disableAutoLogin(): void {
@@ -192,6 +212,7 @@ export function disableAutoLogin(): void {
  * @param doNotDisableAutoLogin This flag when passed will not disable autoLogin
  * @returns Promise which resolves when logout completes.
  * @version SDK: 1.10.1 | ThoughtSpot: 8.2.0.cl, 8.4.1-sw
+ * @group Global methods
  */
 export const logout = (doNotDisableAutoLogin = false): Promise<boolean> => {
     if (!doNotDisableAutoLogin) {
@@ -218,7 +239,7 @@ export const renderInQueue = (
         return renderQueue;
     }
     // Sending an empty function to keep it consistent with the above usage.
-    return fn(() => {}); // eslint-disable-line @typescript-eslint/no-empty-function
+    return fn(() => { }); // eslint-disable-line @typescript-eslint/no-empty-function
 };
 
 // For testing purposes only

package/src/embed/liveboard.ts

@@ -24,7 +24,7 @@ import { V1Embed } from './ts-embed';
 
 /**
  * The configuration for the embedded Liveboard or visualization page view.
- * @Category Liveboards and Charts
+ * @group Embed components
  */
 export interface LiveboardViewConfig extends ViewConfig {
     /**
@@ -91,8 +91,18 @@ export interface LiveboardViewConfig extends ViewConfig {
 }
 
 /**
- * Embed a ThoughtSpot Liveboard or visualization
- * @Category Liveboards and Charts
+ * Embed a ThoughtSpot Liveboard or a Thoughtspot visualization. When rendered it already
+ * waits for the authentication to complete, so no need to wait for AuthStatus.SUCCESS.
+ * @example
+ * ```js
+ * import { .. } from '@thoughtspot/visual-embed-sdk';
+ * init({ ... });
+ * const embed = new LiveboardEmbed("#container", {
+ *   liveboardId: <your-id-here>,
+ * // .. other params here.
+ * })
+ * ```
+ * @group Embed components
  */
 export class LiveboardEmbed extends V1Embed {
     protected viewConfig: LiveboardViewConfig;

package/src/embed/search-bar.tsx

@@ -3,6 +3,9 @@ import { getQueryParamString } from '../utils';
 import { TsEmbed } from './ts-embed';
 import { SearchOptions } from './search';
 
+/**
+ * @group Embed components
+ */
 export interface SearchBarViewConfig
     extends Omit<ViewConfig, 'runtimeFilters' | 'showAlerts'> {
     /**
@@ -25,8 +28,8 @@ export interface SearchBarViewConfig
 /**
  * Embed ThoughtSpot search bar
  *
- * @Category Search Embed
  * @version: SDK: 1.18.0 | ThoughtSpot: 8.10.0.cl, 9.0.1-sw
+ * @group Embed components
  */
 export class SearchBarEmbed extends TsEmbed {
     /**

package/src/embed/search.ts

@@ -45,7 +45,7 @@ export interface SearchOptions {
 /**
  * The configuration attributes for the embedded search view.
  *
- * @Category Search Embed
+ * @group Embed components
  */
 export interface SearchViewConfig extends ViewConfig {
     /**
@@ -120,7 +120,7 @@ export const HiddenActionItemByDefaultForSearchEmbed = [
 /**
  * Embed ThoughtSpot search
  *
- * @Category Search Embed
+ * @group Embed components
  */
 export class SearchEmbed extends TsEmbed {
     /**

package/src/embed/ts-embed.ts

@@ -692,6 +692,20 @@ export class TsEmbed {
      * @param messageType The message type
      * @param callback A callback as a function
      * @param options The message options
+     * @example
+     * ```js
+     * tsEmbed.on(EmbedEvent.Error, (data) => {
+     *   console.error(data);
+     * });
+     * ```
+     * @example
+     * ```js
+     * tsEmbed.on(EmbedEvent.Save, (data) => {
+     *   console.log("Answer save clicked", data);
+     * }, {
+     *   start: true // This will trigger the callback on start of save
+     * });
+     * ```
      */
     public on(
         messageType: EmbedEvent,
@@ -806,6 +820,8 @@ export class TsEmbed {
  * Base class for embedding v1 experience
  * Note: The v1 version of ThoughtSpot Blink works on the AngularJS stack
  * which is currently under migration to v2
+ *
+ * @inheritdoc
  */
 export class V1Embed extends TsEmbed {
     protected viewConfig: ViewConfig;
@@ -816,14 +832,31 @@ export class V1Embed extends TsEmbed {
     }
 
     /**
-     * Render the app in an iframe and set up event handlers
+     * Render the ap    p in an iframe and set up event handlers
      * @param iframeSrc
      */
     protected renderV1Embed(iframeSrc: string): any {
         return this.renderIFrame(iframeSrc, this.viewConfig.frameParams);
     }
 
-    // @override
+    /**
+     * @inheritdoc TsEmbed.on
+     *
+     * @example
+     * ```js
+     * tsEmbed.on(EmbedEvent.Error, (data) => {
+     *   console.error(data);
+     * });
+     * ```
+     * @example
+     * ```js
+     * tsEmbed.on(EmbedEvent.Save, (data) => {
+     *   console.log("Answer save clicked", data);
+     * }, {
+     *   start: true // This will trigger the callback on start of save
+     * });
+     * ```
+     */
     public on(
         messageType: EmbedEvent,
         callback: MessageCallback,

package/src/index.ts

@@ -7,7 +7,6 @@
  * @summary ThoughtSpot Visual Embed SDK
  * @author Ayon Ghosh <ayon.ghosh@thoughtspot.com>
  */
-
 import { AppEmbed, Page, AppViewConfig } from './embed/app';
 import { init, prefetch, logout, getEmbedConfig } from './embed/base';
 import {
@@ -17,7 +16,13 @@ import {
 } from './embed/liveboard';
 import { SearchEmbed, SearchViewConfig } from './embed/search';
 import { SearchBarEmbed, SearchBarViewConfig } from './embed/search-bar';
-import { AuthFailureType, AuthStatus, AuthEvent, getSessionInfo } from './auth';
+import {
+    AuthFailureType,
+    AuthStatus,
+    AuthEvent,
+    AuthEventEmitter,
+    getSessionInfo,
+} from './auth';
 import {
     AuthType,
     RuntimeFilter,
@@ -28,6 +33,14 @@ import {
     Action,
     EmbedConfig,
     PrefetchFeatures,
+    FrameParams,
+    DOMSelector,
+    MessageOptions,
+    MessageCallback,
+    MessagePayload,
+    CustomisationsInterface,
+    CustomStyles,
+    customCssInterface,
 } from './types';
 
 export {
@@ -44,6 +57,7 @@ export {
     AuthFailureType,
     AuthStatus,
     AuthEvent,
+    AuthEventEmitter,
     // types
     Page,
     AuthType,
@@ -59,4 +73,12 @@ export {
     LiveboardViewConfig,
     AppViewConfig,
     PrefetchFeatures,
+    FrameParams,
+    DOMSelector,
+    MessageOptions,
+    MessageCallback,
+    MessagePayload,
+    CustomisationsInterface,
+    CustomStyles,
+    customCssInterface,
 };

package/src/react/index.spec.tsx

@@ -41,7 +41,9 @@ describe('React Components', () => {
             await waitFor(() => getIFrameEl(container));
 
             expect(
-                getIFrameEl(container).classList.contains('embedClass'),
+                getIFrameEl(container).parentElement.classList.contains(
+                    'embedClass',
+                ),
             ).toBe(true);
             expect(getIFrameSrc(container)).toBe(
                 `http://${thoughtSpotHost}/?hostAppUrl=local-host&viewPortHeight=768&viewPortWidth=1024&sdkVersion=${version}&authType=None&hideAction=[%22${Action.ReportError}%22,%22editACopy%22,%22saveAsView%22,%22updateTSL%22,%22editTSL%22,%22onDeleteAnswer%22]&dataSourceMode=hide&useLastSelectedSources=false&isSearchEmbed=true#/embed/answer`,
@@ -141,6 +143,35 @@ describe('React Components', () => {
                 'col1=revenue&op1=EQ&val1=100',
             );
         });
+
+        it('Should have the correct container element', async () => {
+            const { container } = render(
+                <LiveboardEmbed liveboardId="abcd" className="def" />,
+            );
+
+            await waitFor(() => getIFrameEl(container));
+            expect(container.querySelector('div')).not.toBe(null);
+            expect(
+                container.querySelector('div').classList.contains('def'),
+            ).toBe(true);
+
+            const { container: containerSibling } = render(
+                <LiveboardEmbed
+                    liveboardId="abcd"
+                    className="def"
+                    insertAsSibling={true}
+                />,
+            );
+            await waitFor(() => getIFrameEl(containerSibling));
+            expect(containerSibling.querySelector('span')).not.toBe(null);
+            expect(containerSibling.querySelector('span').style.position).toBe(
+                'absolute',
+            );
+            expect(
+                getIFrameEl(containerSibling).classList.contains('def'),
+            ).toBe(true);
+            expect(containerSibling.querySelector('div')).toBe(null);
+        });
     });
 
     describe('SearchBarEmbed', () => {
@@ -159,7 +190,9 @@ describe('React Components', () => {
             await waitFor(() => getIFrameEl(container));
 
             expect(
-                getIFrameEl(container).classList.contains('embedClass'),
+                getIFrameEl(container).parentElement.classList.contains(
+                    'embedClass',
+                ),
             ).toBe(true);
             expect(getIFrameSrc(container)).toBe(
                 `http://${thoughtSpotHost}/?hostAppUrl=local-host&viewPortHeight=768&viewPortWidth=1024&sdkVersion=${version}&authType=None&hideAction=[%22${Action.ReportError}%22]&dataSources=[%22test%22]&searchTokenString=%5Brevenue%5D&executeSearch=true&useLastSelectedSources=false&isSearchEmbed=true#/embed/search-bar-embed`,

package/src/react/index.tsx

@@ -38,7 +38,9 @@ const componentFactory = <
                         {
                             insertAsSibling: viewConfig.insertAsSibling,
                             frameParams: {
-                                class: className || '',
+                                class: viewConfig.insertAsSibling
+                                    ? className || ''
+                                    : '',
                             },
                         },
                         viewConfig,
@@ -60,12 +62,18 @@ const componentFactory = <
                 };
             }, [viewConfig, listeners]);
 
-            return (
+            return viewConfig.insertAsSibling ? (
                 <span
                     data-testid="tsEmbed"
                     ref={ref}
                     style={{ position: 'absolute' }}
                 ></span>
+            ) : (
+                <div
+                    data-testid="tsEmbed"
+                    ref={ref}
+                    className={className}
+                ></div>
             );
         },
     );