@envive-ai/react-hooks 0.3.45 → 0.3.47

package/src/contexts/featureFlagServiceContext/featureFlagServiceContext.tsx

@@ -1,178 +1,11 @@
 import React, { ReactNode, createContext, useContext, useMemo } from 'react';
-import { OrgConfigFeatureGate } from 'src/application/models/api/orgConfigResults';
-import { FeatureGates } from 'src/application/models/featureGates';
-import Logger from 'src/application/logging/logger';
+import { FeatureFlagService, FullFlagValue } from 'src/services/featureFlagService';
 
-const FEATURE_FLAGS_STORAGE_KEY = 'spiffy-feature-flags';
-
-const logger = new Logger('featureFlagServiceContext');
-
-export interface FullFlagValue {
-  resolved: boolean;
-  initial: boolean | undefined;
-  query_param_override: boolean | undefined;
-  window_param_override: boolean | undefined;
-  stored_override: boolean | undefined;
-}
-
-// This is the class that was previously implicitly used or defined elsewhere
-export class FeatureFlagService {
-  private featureGates: OrgConfigFeatureGate[];
-
-  constructor(featureGates: OrgConfigFeatureGate[]) {
-    this.featureGates = featureGates;
-  }
-
-  static getQueryParamFeatureGateOverrides(featureGate: FeatureGates): boolean | undefined {
-    const url = window.location?.href ?? '';
-    if (url.includes('?')) {
-      const urlObj = new URL(url);
-      const params = new URLSearchParams(urlObj.search);
-      const paramsObj = Object.fromEntries(params.entries());
-      const value = paramsObj[featureGate];
-
-      if (value != null) {
-        return value === 'true';
-      }
-    }
-
-    return undefined;
-  }
-
-  static getWindowFeatureGateOverrides(featureGate: FeatureGates): boolean | undefined {
-    if (typeof window === 'undefined') {
-      return undefined;
-    }
-    const windowOverride = window as Window & {
-      _envive?: { featureOverrides?: Record<string, boolean> };
-      _spiffy?: { featureOverrides?: Record<string, boolean> };
-    };
-    const featureOverrides =
-      windowOverride?._envive?.featureOverrides ?? windowOverride?._spiffy?.featureOverrides;
-    const value = featureOverrides?.[String(featureGate)];
-    if (value != null) {
-      return value;
-    }
-    return undefined;
-  }
-
-  static getStoredFeatureGateOverrides(featureGate: FeatureGates): boolean | undefined {
-    if (typeof window === 'undefined' || typeof window.localStorage === 'undefined') {
-      return undefined;
-    }
-    try {
-      const featureFlags = window.localStorage.getItem(FEATURE_FLAGS_STORAGE_KEY);
-      if (!featureFlags) {
-        return undefined;
-      }
-      const featureFlagsObj = JSON.parse(featureFlags) as Record<string, boolean>;
-      return featureFlagsObj[featureGate];
-    } catch (err) {
-      logger.logError('getStoredFeatureGateOverrides: error parsing feature flags', err);
-      return undefined;
-    }
-  }
-
-  static getFeatureFlagOverride(featureGate: FeatureGates): boolean | undefined {
-    const queryOverride = FeatureFlagService.getQueryParamFeatureGateOverrides(featureGate);
-    if (queryOverride != null) {
-      logger.logDebug(
-        `isFeatureGateEnabled featureGate:${featureGate} overridden by URL param. New value: ${queryOverride}`,
-      );
-      return queryOverride;
-    }
-
-    const windowOverride = FeatureFlagService.getWindowFeatureGateOverrides(featureGate);
-    if (windowOverride != null) {
-      logger.logDebug(
-        `isFeatureGateEnabled featureGate:${featureGate} overridden by window param. New value: ${windowOverride}`,
-      );
-      return windowOverride;
-    }
-
-    const storedOverride = FeatureFlagService.getStoredFeatureGateOverrides(featureGate);
-    if (storedOverride != null) {
-      logger.logDebug(
-        `isFeatureGateEnabled featureGate:${featureGate} overridden by stored value. New value: ${storedOverride}`,
-      );
-      return storedOverride;
-    }
-
-    return undefined;
-  }
-
-  isFeatureGateEnabled = (featureGate: FeatureGates): boolean => {
-    const gateValue = this.featureGates.find(gate => gate.name === featureGate);
-
-    const featureFlagOverride = FeatureFlagService.getFeatureFlagOverride(featureGate);
-    if (featureFlagOverride !== undefined) {
-      return featureFlagOverride;
-    }
-
-    if (gateValue == null || gateValue.value == null) {
-      logger.logDebug(
-        `isFeatureGateEnabled featureGate:${featureGate} value is undefined - returning false`,
-      );
-      return false;
-    }
-    return gateValue.value;
-  };
-
-  // Ensure that standard overrides work as expected
-  isClientSessionEnabled = (): boolean =>
-    this.isFeatureGateEnabled(FeatureGates.IsClientSessionEnabled);
-
-  getFeatureFlags = (): Record<string, boolean> => {
-    return Object.fromEntries(
-      Object.values(FeatureGates).map((featureGate: FeatureGates) => [
-        featureGate,
-        this.isFeatureGateEnabled(featureGate),
-      ]),
-    );
-  };
-
-  getFullFlagValue = (featureGate: FeatureGates): FullFlagValue => {
-    const gateValue = this.featureGates.find(gate => gate.name === featureGate);
-    return {
-      resolved: this.isFeatureGateEnabled(featureGate),
-      initial: gateValue?.value,
-      query_param_override: FeatureFlagService.getQueryParamFeatureGateOverrides(featureGate),
-      window_param_override: FeatureFlagService.getWindowFeatureGateOverrides(featureGate),
-      stored_override: FeatureFlagService.getStoredFeatureGateOverrides(featureGate),
-    };
-  };
-
-  getFullFlagValues = (): Record<string, FullFlagValue> => {
-    const featureGates = Object.values(FeatureGates).map((featureGate: FeatureGates) => [
-      featureGate,
-      this.getFullFlagValue(featureGate),
-    ]);
-
-    return featureGates.length > 0
-      ? featureGates.reduce<Record<string, FullFlagValue>>((acc, entry) => {
-          const [name, value] = entry as [FeatureGates, FullFlagValue];
-          if (name && value != null) {
-            return { ...acc, [`feature_gate.${name}`]: value };
-          }
-          return acc;
-        }, {})
-      : {};
-  };
-
-  static persistFeatureGateOverrides(): void {
-    if (typeof window === 'undefined' || typeof window.localStorage === 'undefined') {
-      return;
-    }
-    const overrides = Object.values(FeatureGates)
-      .map(
-        featureGate =>
-          [featureGate, FeatureFlagService.getFeatureFlagOverride(featureGate)] as const,
-      )
-      .filter(([, value]) => value !== undefined)
-      .reduce<Record<string, boolean>>((acc, [key, value]) => ({ ...acc, [key]: value! }), {});
-    window.localStorage.setItem(FEATURE_FLAGS_STORAGE_KEY, JSON.stringify(overrides));
-  }
-}
+// The service class lives in src/services/featureFlagService (a React-free
+// module the injection bundle can import pre-config); re-export it here so
+// existing imports keep working.
+export { FeatureFlagService };
+export type { FullFlagValue };
 
 export interface FeatureFlagContextType {
   featureFlagService: FeatureFlagService | undefined;

package/src/contexts/localStorageContext/localStorageContext.tsx

@@ -1,12 +1,9 @@
 import React, { createContext, useCallback, useContext, useEffect, useMemo } from 'react';
 import Logger from 'src/application/logging/logger';
 import { LocalStorageEventListener } from 'src/application/models/localStorageEventListener';
+import { LocalStorageKeys } from './localStorageKeys';
 
-export enum LocalStorageKeys {
-  ChatId = 'v1-spiffy-chat-session-id',
-  SpiffyOnOverride = 'spiffy_on',
-  EnviveOnOverride = 'envive_on',
-}
+export { LocalStorageKeys };
 
 interface LocalStorageContextType {
   setItem: (key: string, value: string) => void;

package/src/contexts/localStorageContext/localStorageKeys.ts

@@ -0,0 +1,8 @@
+// Kept React-free: pre-config injection-bundle code (atoms/envive) needs
+// these keys, and importing them through localStorageContext.tsx would pull
+// React into the eager critical chunk.
+export enum LocalStorageKeys {
+  ChatId = 'v1-spiffy-chat-session-id',
+  SpiffyOnOverride = 'spiffy_on',
+  EnviveOnOverride = 'envive_on',
+}

package/src/contexts/pageContext/pageContext.tsx

@@ -176,7 +176,7 @@ export const PageProvider: React.FC<{
         pageId = variantInfo.url;
         break;
       case VariantTypeEnum.FullPageSalesAgent:
-        pageType = 'full_page_sales_agent';
+        pageType = 'adaptive_storefront';
         pageId = variantInfo.url;
         break;
       default:

package/src/contexts/salesAgentContext/__tests__/chatAPI.test.tsx

@@ -0,0 +1,63 @@
+import { renderHook } from '@testing-library/react';
+import { Provider, createStore } from 'jotai';
+import React from 'react';
+import { Message, MessageRole, MessageType } from 'src/application/models/message';
+import { messagesAtom } from 'src/atoms/chat/chatState';
+import { useSalesAgentChatAPI } from '../chatAPI';
+
+const mockTrackEvent = vi.fn();
+vi.mock('../../amplitudeContext', async () => {
+  const actual = await vi.importActual('../../amplitudeContext');
+  return {
+    ...actual,
+    useAmplitude: () => ({ trackEvent: mockTrackEvent }),
+  };
+});
+
+vi.mock('src/hooks/WidgetInteraction', () => ({
+  useWidgetInteraction: () => ({ trackWidgetInteraction: vi.fn() }),
+}));
+
+const asTextMessage = (message: Message) => message as Extract<Message, { type: MessageType.Text }>;
+
+const renderChatAPI = (store: ReturnType<typeof createStore>) => {
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    // The jotai Provider is typed against the root @types/react (18) while this
+    // package resolves @types/react 19; the cast bridges the two ReactNode types.
+    <Provider store={store}>{children as React.ReactElement<unknown, string>}</Provider>
+  );
+  return renderHook(() => useSalesAgentChatAPI(), { wrapper });
+};
+
+describe('useSalesAgentChatAPI.injectAssistantMessage', () => {
+  it('appends an assistant text message turn onto messagesAtom', () => {
+    const store = createStore();
+    const { result } = renderChatAPI(store);
+
+    result.current.injectAssistantMessage("I'm sorry, something went wrong.");
+
+    const messages = store.get(messagesAtom);
+    expect(messages).toHaveLength(1);
+    expect(messages[0]).toHaveLength(1);
+    expect(messages[0][0]).toMatchObject({
+      role: MessageRole.Assistant,
+      type: MessageType.Text,
+      metadata: { content: "I'm sorry, something went wrong." },
+    });
+    expect(messages[0][0].id).toEqual(expect.any(String));
+    expect(messages[0][0].createdAt).toEqual(expect.any(String));
+  });
+
+  it('appends subsequent messages as additional turns without clobbering prior ones', () => {
+    const store = createStore();
+    const { result } = renderChatAPI(store);
+
+    result.current.injectAssistantMessage('first');
+    result.current.injectAssistantMessage('second');
+
+    const messages = store.get(messagesAtom);
+    expect(messages).toHaveLength(2);
+    expect(asTextMessage(messages[0][0]).metadata).toMatchObject({ content: 'first' });
+    expect(asTextMessage(messages[1][0]).metadata).toMatchObject({ content: 'second' });
+  });
+});

package/src/contexts/salesAgentContext/chatAPI.ts

@@ -6,6 +6,7 @@ import Logger from 'src/application/logging/logger';
 import {
   ChatElementDisplayLocationV3,
   FormSubmittedAttributes,
+  Message,
   MessageRole,
   MessageType,
   Suggestion,
@@ -14,7 +15,7 @@ import {
 import { hasParsedVariantInfoAtom } from 'src/atoms/app';
 import { analyticsContextAtom } from 'src/atoms/app/variant';
 import { formSubmitAtom, replyEventCategoryAtom } from 'src/atoms/chat';
-import { suggestionsAtom } from 'src/atoms/chat/chatState';
+import { messagesAtom, suggestionsAtom } from 'src/atoms/chat/chatState';
 import { queueUserEventAtom } from 'src/atoms/chat/messageQueue';
 import { useWidgetInteraction } from 'src/hooks/WidgetInteraction';
 import {
@@ -49,6 +50,8 @@ export interface SalesAgentChatAPI {
     displayLocation: ChatElementDisplayLocationV3;
   }) => void;
   onFormResponseSubmitted: (form: FormSubmittedAttributes) => void;
+  /** Injects a synthetic assistant text message into the chat transcript, e.g. to surface a failure. */
+  injectAssistantMessage: (content: string) => void;
 }
 
 export const useSalesAgentChatAPI = (widget?: WidgetInteractionComponent) => {
@@ -60,6 +63,7 @@ export const useSalesAgentChatAPI = (widget?: WidgetInteractionComponent) => {
   const setSuggestions = useSetAtom(suggestionsAtom);
   const setReplyEventCategory = useSetAtom(replyEventCategoryAtom);
   const setFormSubmit = useSetAtom(formSubmitAtom);
+  const setMessages = useSetAtom(messagesAtom);
   const { trackEvent } = useAmplitude();
   const { trackWidgetInteraction } = useWidgetInteraction();
   const contextWidget = widget || WidgetInteractionComponent.FLOATING_CHAT;
@@ -260,11 +264,26 @@ export const useSalesAgentChatAPI = (widget?: WidgetInteractionComponent) => {
     [setReplyEventCategory, setFormSubmit, trackEvent, context, queueUserEvent],
   );
 
+  const injectAssistantMessage = useCallback(
+    (content: string) => {
+      const message: Message = {
+        id: uuid(),
+        role: MessageRole.Assistant,
+        type: MessageType.Text,
+        createdAt: new Date().toISOString(),
+        metadata: { content },
+      };
+      setMessages(current => [...current, [message]]);
+    },
+    [setMessages],
+  );
+
   return {
     logPageVisit,
     logUserEvent,
     onSuggestionClicked,
     onTypedMessageSubmitted,
     onFormResponseSubmitted,
+    injectAssistantMessage,
   };
 };

package/src/contexts/salesAgentContext/salesAgentContext.tsx

@@ -4,12 +4,14 @@ import { ReactNode, createContext, useCallback, useEffect, useMemo, useRef, useS
 import Logger from 'src/application/logging/logger';
 import { NextMessageRequest, Suggestion, UserEvent } from 'src/application/models';
 import { Message, MessageRole, MessageType } from 'src/application/models/message';
+import { messageFromAddToCartEvent } from 'src/application/utils';
 import {
   initializedAtom,
   messagesAtom,
   pendingResponseAtom,
   responseStreamingAtom,
   suggestionsAtom,
+  suggestionsLoadingAtom,
 } from 'src/atoms/chat/chatState';
 import {
   processUserEventAtom,
@@ -36,6 +38,9 @@ export interface SalesAgent extends SalesAgentChatAPI {
   isResponseStreaming: boolean;
   // True while the response is pending from the backend
   isPendingResponse: boolean;
+  // True while suggestions for the most recent message are being fetched (separate from the
+  // message response itself — suggestions are requested as a follow-up call once it completes)
+  isLoadingSuggestions: boolean;
   // True when the sales agent is initialized
   isInitialized: boolean;
 }
@@ -149,6 +154,12 @@ export const SalesAgentProvider: React.FC<SalesAgentProviderProps> = ({
           };
           setMessages(current => [...current, [newMessage]]);
         }
+        if (userEvent && userEvent.category === UserEventCategory.AddToCart) {
+          const newMessage = messageFromAddToCartEvent(userEvent);
+          if (newMessage) {
+            setMessages(current => [...current, [newMessage]]);
+          }
+        }
         if (userEvent && userEvent.category === UserEventCategory.FormSubmitted) {
           const { formResponseId, filledSchema } = userEvent.attributes;
           setMessages(prevMessagesState => {
@@ -227,6 +238,7 @@ export const useSalesAgent = (contextWidget?: WidgetInteractionComponent): Sales
   const pendingMessages = useAtomValue(userEventQueueAtom);
   const isResponseStreaming = useAtomValue(responseStreamingAtom);
   const isPendingResponse = useAtomValue(pendingResponseAtom);
+  const isLoadingSuggestions = useAtomValue(suggestionsLoadingAtom);
   const isInitialized = useAtomValue(initializedAtom);
   const {
     logPageVisit,
@@ -234,6 +246,7 @@ export const useSalesAgent = (contextWidget?: WidgetInteractionComponent): Sales
     onSuggestionClicked,
     onTypedMessageSubmitted,
     onFormResponseSubmitted,
+    injectAssistantMessage,
   } = useSalesAgentChatAPI(contextWidget);
 
   const salesAgent: SalesAgent = useMemo(() => {
@@ -244,11 +257,13 @@ export const useSalesAgent = (contextWidget?: WidgetInteractionComponent): Sales
       isInitialized,
       isResponseStreaming,
       isPendingResponse,
+      isLoadingSuggestions,
       logPageVisit,
       logUserEvent,
       onSuggestionClicked,
       onTypedMessageSubmitted,
       onFormResponseSubmitted,
+      injectAssistantMessage,
     };
   }, [
     messages,
@@ -257,11 +272,13 @@ export const useSalesAgent = (contextWidget?: WidgetInteractionComponent): Sales
     isInitialized,
     isResponseStreaming,
     isPendingResponse,
+    isLoadingSuggestions,
     logPageVisit,
     logUserEvent,
     onSuggestionClicked,
     onTypedMessageSubmitted,
     onFormResponseSubmitted,
+    injectAssistantMessage,
   ]);
   return salesAgent;
 };

package/src/contexts/salesAgentContext/salesAgentService.ts

@@ -22,6 +22,7 @@ import {
   requestFailureAtom,
   responseStreamingAtom,
   suggestionsAtom,
+  suggestionsLoadingAtom,
 } from 'src/atoms/chat/chatState';
 import { useAmplitude } from 'src/contexts/amplitudeContext';
 import { useFeatureFlagService } from 'src/contexts/featureFlagServiceContext';
@@ -242,6 +243,7 @@ export const useSalesAgentService: () => SalesAgentService = () => {
   const setSuggestions = useSetAtom(suggestionsAtom);
   const setPendingResponse = useSetAtom(pendingResponseAtom);
   const setResponseStreaming = useSetAtom(responseStreamingAtom);
+  const setSuggestionsLoading = useSetAtom(suggestionsLoadingAtom);
   const analyticsContext = useAtomValue(analyticsContextAtom);
   const messageInterceptor = useMessageInterceptor();
   const { trackEvent } = useAmplitude();
@@ -285,6 +287,7 @@ export const useSalesAgentService: () => SalesAgentService = () => {
       let successfulResponse: boolean | undefined;
       setPendingResponse(true);
       setSuggestions([]);
+      setSuggestionsLoading(true);
       const stream = CommerceApiClient.getNextResponseStreaming(payload);
       let responseAnalytics: Record<string, unknown> | undefined;
       try {
@@ -360,6 +363,7 @@ export const useSalesAgentService: () => SalesAgentService = () => {
       // logPerfMetric,
       setRequestFailure,
       setSuggestions,
+      setSuggestionsLoading,
       messageInterceptor,
       setMessages,
       setPendingResponse,
@@ -368,10 +372,15 @@ export const useSalesAgentService: () => SalesAgentService = () => {
 
   const getSuggestions = useCallback(
     async (payload: NextMessageRequest): Promise<void> => {
-      const newSuggestions = await CommerceApiClient.getNextSuggestions(payload);
-      setSuggestions(newSuggestions);
+      setSuggestionsLoading(true);
+      try {
+        const newSuggestions = await CommerceApiClient.getNextSuggestions(payload);
+        setSuggestions(newSuggestions);
+      } finally {
+        setSuggestionsLoading(false);
+      }
     },
-    [setSuggestions],
+    [setSuggestions, setSuggestionsLoading],
   );
 
   const hydrateMessages = useCallback(async () => {

package/src/contexts/types.ts

@@ -13,6 +13,7 @@ import { ChatState } from 'src/types/custservice-types';
 import { SuggestionBarLocationForMetrics } from 'src/types/suggestionBarV2-types';
 import { TestProps } from 'src/types/test-types';
 import { OrgConfigFeatureGate } from 'src/application/models/api/orgConfigResults';
+import type { AddToCartCallback } from 'src/types/enviveConfig';
 import { WidgetConfigV3, WidgetTypeV3 } from './typesV3';
 import type { HardcopyResponse } from './hardcopyContext/hardcopyContext';
 
@@ -939,6 +940,7 @@ export interface EnviveConfig {
   publicKey?: string;
   featureGates?: OrgConfigFeatureGate[];
   hardcopyOverride?: Partial<Record<WidgetTypeV3, HardcopyResponse>>;
+  addToCart?: AddToCartCallback;
 }
 
 export type {

package/src/contexts/typesV3.ts

@@ -111,6 +111,17 @@ export const enum ButtonColorsVars {
 
 type ImageAspectRatio = '1/1' | '3/4';
 
+type AddToCartConfig = {
+  enabled: boolean;
+  // Colors are CSS variable strings, e.g. 'var(--envive-colors-background-dark)'
+  backgroundColor?: string;
+  textColor?: string;
+  ctaText?: string;
+  // Merchant-supplied JS function, as a string, used to invoke their cart.
+  // Ignored when window._spiffy/_envive.addToCart is set - the window variable always takes precedence.
+  addToCartFunction?: string;
+};
+
 type ButtonColors = {
   lightButtonBackgroundColor: string;
   lightButtonBorderColor?: string;
@@ -193,6 +204,7 @@ type LookAndFeelConfig = {
   imageAspectRatio: ImageAspectRatio;
   buttonColors: ButtonColors;
   typography: Typography;
+  addToCart?: AddToCartConfig;
 };
 
 export enum ConfigVersionEnum {
@@ -385,6 +397,7 @@ interface FullPageSalesAgentWidgetV3Config extends BaseWidgetConfig<WidgetTypeV3
   mobileBackgroundImage?: string;
   desktopBackgroundImage?: string;
   backgroundColor?: string;
+  chatBackgroundColor?: string;
   suggestionButtonType?: PromptButtonVariant;
 }
 
@@ -402,6 +415,7 @@ type WidgetConfigV3 =
   | FullPageSalesAgentWidgetV3Config;
 
 export type {
+  AddToCartConfig,
   ChatPreviewComparisonWidgetV3Config,
   ChatPreviewLoadingWidgetV3Config,
   ChatPreviewWidgetV3Config,

package/src/hooks/AddToCart/__tests__/parseAddToCartFunction.test.ts

@@ -0,0 +1,31 @@
+import { parseAddToCartFunction } from '../parseAddToCartFunction';
+
+describe('parseAddToCartFunction', () => {
+  it('returns undefined when no string is provided', () => {
+    expect(parseAddToCartFunction(undefined)).toBeUndefined();
+  });
+
+  it('parses a function-expression string into a callable', async () => {
+    const fn = parseAddToCartFunction('function(params) { globalThis.__testCalls = [params]; }');
+
+    expect(fn).toBeInstanceOf(Function);
+    fn?.({ product_id: 'abc' });
+    expect((globalThis as Record<string, unknown>).__testCalls).toEqual([{ product_id: 'abc' }]);
+  });
+
+  it('parses an arrow-function string into a callable', () => {
+    const fn = parseAddToCartFunction('(params) => { globalThis.__testCalls = [params]; }');
+
+    expect(fn).toBeInstanceOf(Function);
+    fn?.({ product_id: 'xyz' });
+    expect((globalThis as Record<string, unknown>).__testCalls).toEqual([{ product_id: 'xyz' }]);
+  });
+
+  it('returns undefined when the string has a syntax error', () => {
+    expect(parseAddToCartFunction('function( { broken')).toBeUndefined();
+  });
+
+  it('returns undefined when the string evaluates to a non-function value', () => {
+    expect(parseAddToCartFunction('42')).toBeUndefined();
+  });
+});