@thoughtspot/visual-embed-sdk 1.46.4 → 1.46.5

package/src/embed/spotter-utils.ts

@@ -0,0 +1,65 @@
+import { DefaultAppInitData, ErrorDetailsTypes, EmbedErrorCodes } from '../types';
+import { validateHttpUrl } from '../utils';
+import { ERROR_MESSAGE } from '../errors';
+import type { SpotterSidebarViewConfig } from './conversation';
+
+/**
+ * Resolves enablePastConversationsSidebar with
+ * spotterSidebarConfig taking precedence over the
+ * standalone flag.
+ */
+export const resolveEnablePastConversationsSidebar = (params: {
+    spotterSidebarConfigValue?: boolean;
+    standaloneValue?: boolean;
+}): boolean | undefined => (
+    params.spotterSidebarConfigValue !== undefined
+        ? params.spotterSidebarConfigValue
+        : params.standaloneValue
+);
+
+export function buildSpotterSidebarAppInitData<T extends DefaultAppInitData>(
+    defaultAppInitData: T,
+    viewConfig: {
+        spotterSidebarConfig?: SpotterSidebarViewConfig;
+        enablePastConversationsSidebar?: boolean;
+    },
+    handleError: (err: any) => void,
+): T & { embedParams?: { spotterSidebarConfig?: SpotterSidebarViewConfig } } {
+    const { spotterSidebarConfig, enablePastConversationsSidebar } = viewConfig;
+
+    const resolvedEnablePastConversations = resolveEnablePastConversationsSidebar({
+        spotterSidebarConfigValue: spotterSidebarConfig?.enablePastConversationsSidebar,
+        standaloneValue: enablePastConversationsSidebar,
+    });
+
+    const hasConfig = spotterSidebarConfig || resolvedEnablePastConversations !== undefined;
+    if (!hasConfig) return defaultAppInitData;
+
+    const resolvedSidebarConfig: SpotterSidebarViewConfig = {
+        ...spotterSidebarConfig,
+        ...(resolvedEnablePastConversations !== undefined && {
+            enablePastConversationsSidebar: resolvedEnablePastConversations,
+        }),
+    };
+
+    if (resolvedSidebarConfig.spotterDocumentationUrl !== undefined) {
+        const [isValid, validationError] = validateHttpUrl(resolvedSidebarConfig.spotterDocumentationUrl);
+        if (!isValid) {
+            handleError({
+                errorType: ErrorDetailsTypes.VALIDATION_ERROR,
+                message: ERROR_MESSAGE.INVALID_SPOTTER_DOCUMENTATION_URL,
+                code: EmbedErrorCodes.INVALID_URL,
+                error: validationError?.message || ERROR_MESSAGE.INVALID_SPOTTER_DOCUMENTATION_URL,
+            });
+            delete resolvedSidebarConfig.spotterDocumentationUrl;
+        }
+    }
+
+    return {
+        ...defaultAppInitData,
+        embedParams: {
+            ...((defaultAppInitData as any).embedParams || {}),
+            spotterSidebarConfig: resolvedSidebarConfig,
+        },
+    };
+}

package/src/embed/ts-embed.ts

@@ -34,7 +34,8 @@ import {
     setStyleProperties,
     removeStyleProperties,
     isUndefined,
- getHostEventsConfig } from '../utils';
+    getHostEventsConfig,
+} from '../utils';
 import { getCustomActions } from '../utils/custom-actions';
 import {
     getThoughtSpotHost,
@@ -1392,7 +1393,21 @@ export class TsEmbed {
      * Triggers an event to the embedded app
      * @param {HostEvent} messageType The event type
      * @param {any} data The payload to send with the message
+     * @param {ContextType} context Optional context type to specify the context from which the event is triggered.
+     * Use ContextType.Search for search answer context, ContextType.Answer for answer/explore context,
+     * ContextType.Liveboard for liveboard context, or ContextType.Spotter for spotter context.
+     * Available from SDK version 1.45.2 | ThoughtSpot: 26.3.0.cl
      * @returns A promise that resolves with the response from the embedded app
+     * @example
+     * ```js
+     * // Trigger Pin event with context (SDK: 1.45.2+)
+     * import { HostEvent, ContextType } from '@thoughtspot/visual-embed-sdk';
+     * embed.trigger(HostEvent.Pin, {
+     *   vizId: "123",
+     *   liveboardId: "456"
+     * }, ContextType.Search);
+     * ```
+     * @version SDK: 1.45.2 | ThoughtSpot: 26.3.0.cl (for context parameter)
      */
     public async trigger<HostEventT extends HostEvent, PayloadT, ContextT extends ContextType>(
         messageType: HostEventT,
@@ -1431,7 +1446,21 @@ export class TsEmbed {
         }
 
         // send an empty object, this is needed for liveboard default handlers
-        return this.hostEventClient.triggerHostEvent(messageType, data, context);
+        return this.hostEventClient.triggerHostEvent(messageType, data, context).catch((err: Error & {
+            isValidationError?: boolean;
+            embedErrorDetails?: { errorType: ErrorDetailsTypes; message: string; code: EmbedErrorCodes; error: string };
+        }): Promise<null> => {
+            if (err?.isValidationError) {
+                const errorDetails = err.embedErrorDetails ?? {
+                    errorType: ErrorDetailsTypes.VALIDATION_ERROR,
+                    message: err.message || ERROR_MESSAGE.UPDATEFILTERS_INVALID_PAYLOAD,
+                    code: EmbedErrorCodes.UPDATEFILTERS_INVALID_PAYLOAD,
+                    error: err.message,
+                };
+                this.handleError(errorDetails);
+            }
+            throw err;
+        });
     }
 
     /**
@@ -1474,8 +1503,33 @@ export class TsEmbed {
     }
 
     /**
-     * Get the current context of the embedded TS component.
-     * @returns The current context object containing the page type and object ids.
+    * Context object for the embedded component.
+    * @returns {ContextObject} The current context object containing the page type and object ids.
+    * @example
+    * ```js
+    * const context = await embed.getCurrentContext();
+    * console.log(context);
+    * 
+    * // Example output
+    * {
+    *   stack: [
+    *     {
+    *       name: 'Liveboard',
+    *       type: ContextType.Liveboard,
+    *       objectIds: {
+    *         liveboardId: '123',
+    *       },
+    *     },
+    *   ],
+    *   currentContext: {
+    *     name: 'Liveboard',
+    *     type: ContextType.Liveboard,
+    *     objectIds: {
+    *       liveboardId: '123',
+    *     },
+    *   },
+    * }
+    * ```
      * @version SDK: 1.45.2 | ThoughtSpot: 26.3.0.cl
      */
     public async getCurrentContext(): Promise<ContextObject> {

package/src/errors.ts

@@ -30,6 +30,8 @@ export const ERROR_MESSAGE = {
     SSR_ENVIRONMENT_ERROR: 'SSR environment detected. This function cannot be called in SSR environment.',
     UPDATE_PARAMS_FAILED: 'Failed to update embed parameters',
     INVALID_SPOTTER_DOCUMENTATION_URL: 'Invalid spotterDocumentationUrl. Please provide a valid http or https URL.',
+    UPDATEFILTERS_INVALID_PAYLOAD: 'UpdateFilters requires a valid filter or filters array. Expected: { filter: { column, oper, values } } or { filters: [{ column, oper, values }, ...] }',
+    DRILLDOWN_INVALID_PAYLOAD: 'DrillDown requires a valid points object. Expected: { points: { clickedPoint?, selectedPoints? }, autoDrillDown?, vizId? }',
 };
 
 export const CUSTOM_ACTIONS_ERROR_MESSAGE = {

package/src/react/index.tsx

@@ -25,84 +25,87 @@ const componentFactory = <T extends typeof TsEmbed, U extends EmbedProps, V exte
     // Embed.preRender() method instead of the usual render method, and it will
     // not be destroyed when the component is unmounted.
     isPreRenderedComponent = false,
- ) => React.forwardRef<InstanceType<T>, U>(
-    (props: U, forwardedRef: React.MutableRefObject<InstanceType<T>>) => {
-        const ref = React.useRef<HTMLDivElement>(null);
-        const { className, style, ...embedProps } = props;
-        const { viewConfig, listeners } = getViewPropsAndListeners<Omit<U, 'className' | 'style'>, V>(
-            embedProps,
-        );
-
-        const handleDestroy = (tsEmbed: InstanceType<T>) => {
-            // do not destroy if it is a preRender component
-            if (isPreRenderedComponent) return;
-
-            // if component is connected to a preRendered component
-            if (props.preRenderId) {
-                tsEmbed.hidePreRender();
-                return;
-            }
-
-            tsEmbed.destroy();
-        };
-
-        const handlePreRenderRendering = (tsEmbed: InstanceType<T>) => {
-            tsEmbed.preRender();
-        };
+ ) => {
+    const Component = React.forwardRef<InstanceType<T>, U>(
+        (props: U, forwardedRef: React.MutableRefObject<InstanceType<T>>) => {
+            const ref = React.useRef<HTMLDivElement>(null);
+            const { className, style, ...embedProps } = props;
+            const { viewConfig, listeners } = getViewPropsAndListeners<Omit<U, 'className' | 'style'>, V>(
+                embedProps,
+            );
+
+            const handleDestroy = (tsEmbed: InstanceType<T>) => {
+                // do not destroy if it is a preRender component
+                if (isPreRenderedComponent) return;
+
+                // if component is connected to a preRendered component
+                if (props.preRenderId) {
+                    tsEmbed.hidePreRender();
+                    return;
+                }
+
+                tsEmbed.destroy();
+            };
 
-        const handleDefaultRendering = (tsEmbed: InstanceType<T>) => {
-            // if component is connected to a preRendered component
-            if (props.preRenderId) {
-                tsEmbed.showPreRender();
-                return;
-            }
+            const handlePreRenderRendering = (tsEmbed: InstanceType<T>) => {
+                tsEmbed.preRender();
+            };
 
-            tsEmbed.render();
-        };
+            const handleDefaultRendering = (tsEmbed: InstanceType<T>) => {
+                // if component is connected to a preRendered component
+                if (props.preRenderId) {
+                    tsEmbed.showPreRender();
+                    return;
+                }
 
-        const handleRendering = (tsEmbed: InstanceType<T>) => {
-            if (isPreRenderedComponent) {
-                handlePreRenderRendering(tsEmbed);
-                return;
-            }
-            handleDefaultRendering(tsEmbed);
-        };
-
-        useDeepCompareEffect(() => {
-            const tsEmbed = new EmbedConstructor(
-                ref!.current,
-                deepMerge(
-                    {
-                        insertAsSibling: viewConfig.insertAsSibling,
-                        frameParams: {
-                            class: viewConfig.insertAsSibling ? className || '' : '',
-                        },
-                    },
-                    viewConfig,
-                ),
-            ) as InstanceType<T>;
-            Object.keys(listeners).forEach((eventName) => {
-                tsEmbed.on(eventName as EmbedEvent, listeners[eventName as EmbedEvent]);
-            });
-            handleRendering(tsEmbed);
-            if (forwardedRef) {
-                 
-                forwardedRef.current = tsEmbed;
-            }
-            return () => {
-                handleDestroy(tsEmbed);
+                tsEmbed.render();
             };
-        }, [viewConfig, listeners]);
 
-        const preRenderStyles = isPreRenderedComponent ? { display: 'none' } : {};
+            const handleRendering = (tsEmbed: InstanceType<T>) => {
+                if (isPreRenderedComponent) {
+                    handlePreRenderRendering(tsEmbed);
+                    return;
+                }
+                handleDefaultRendering(tsEmbed);
+            };
 
-        return viewConfig.insertAsSibling ? (
-            <span data-testid="tsEmbed" ref={ref} style={{ position: 'absolute', ...preRenderStyles }}></span>
-        ) : (
-            <div data-testid="tsEmbed" ref={ref} style={{ ...style, ...preRenderStyles }} className={`ts-embed-container ${className}`}></div>
-        );
-    },
-);
+            useDeepCompareEffect(() => {
+                const tsEmbed = new EmbedConstructor(
+                    ref!.current,
+                    deepMerge(
+                        {
+                            insertAsSibling: viewConfig.insertAsSibling,
+                            frameParams: {
+                                class: viewConfig.insertAsSibling ? className || '' : '',
+                            },
+                        },
+                        viewConfig,
+                    ),
+                ) as InstanceType<T>;
+                Object.keys(listeners).forEach((eventName) => {
+                    tsEmbed.on(eventName as EmbedEvent, listeners[eventName as EmbedEvent]);
+                });
+                handleRendering(tsEmbed);
+                if (forwardedRef) {
+                    forwardedRef.current = tsEmbed;
+                }
+                return () => {
+                    handleDestroy(tsEmbed);
+                };
+            }, [viewConfig, listeners]);
+
+            const preRenderStyles = isPreRenderedComponent ? { display: 'none' } : {};
+
+            return viewConfig.insertAsSibling ? (
+                <span data-testid="tsEmbed" ref={ref} style={{ position: 'absolute', ...preRenderStyles }}></span>
+            ) : (
+                <div data-testid="tsEmbed" ref={ref} style={{ ...style, ...preRenderStyles }} className={`ts-embed-container ${className}`}></div>
+            );
+        },
+    );
+    Component.displayName = EmbedConstructor.name || 'EmbedComponent';
+    return Component;
+};
 
 interface SearchProps extends EmbedProps, SearchViewConfig { }
 
@@ -442,6 +445,7 @@ export const SpotterMessage = React.forwardRef<
         />
     );
 });
+SpotterMessage.displayName = 'SpotterMessage';
 
 /**
  * React component for PreRendered Conversation embed.