@envive-ai/react-hooks 0.3.20 → 0.3.22

package/src/contexts/amplitudeContext/amplitudeContext.tsx

@@ -23,6 +23,7 @@ export { EnviveMetricsEventName, SpiffyMetricsEventName };
 interface AmplitudeContextType {
   trackEvent: (params: TrackEventParams) => Promise<void>;
   isReady: boolean;
+  isMockMode: boolean;
   setSupplementalDefaultProps: (props: Record<string, unknown>) => void;
 }
 
@@ -55,6 +56,7 @@ export const AmplitudeProvider: React.FC<{
   const [service, setService] = useState<AmplitudeService | null>(null);
 
   const isReady = Boolean(userId && service && service.isReady);
+  const isMockMode = Boolean(service?.isMockApiKey);
 
   // Create service instance when dependencies are ready
   useEffect(() => {
@@ -109,16 +111,17 @@ export const AmplitudeProvider: React.FC<{
         }
       },
       isReady,
+      isMockMode,
       setSupplementalDefaultProps: (props: Record<string, unknown>) => {
         if (service) {
           service.setSupplementalDefaultProps(props);
         }
       },
     }),
-    [service, isReady],
+    [service, isReady, isMockMode],
   );
 
-  if (!isReady) {
+  if (!isReady && !isMockMode) {
     return null;
   }
 

package/src/contexts/pageContext/__tests__/pageContext.test.tsx

@@ -19,6 +19,16 @@ vi.spyOn(Logger.prototype, 'logInfo').mockImplementation(() => {});
 vi.spyOn(Logger.prototype, 'logWarn').mockImplementation(() => {});
 vi.spyOn(Logger.prototype, 'logError').mockImplementation(() => {});
 
+vi.mock('src/contexts/amplitudeContext', () => ({
+  useAmplitude: () => ({
+    trackEvent: vi.fn(),
+    isReady: true,
+  }),
+  EnviveMetricsEventName: {
+    PageViewed: 'Page Viewed',
+  },
+}));
+
 // Mock CommerceApiClient
 const mockResolveUrl = vi.fn();
 vi.mock('src/application/commerce-api', () => ({

package/src/hooks/Search/__tests__/useSearch.test.tsx

@@ -29,10 +29,6 @@ import { UserIdentityService } from 'src/services/userIdentityService';
 import { useSearch } from '../useSearch';
 
 // Mock dependencies
-vi.mock('src/hooks/TrackComponentVisibleEvent/useTrackComponentVisibleEvent', () => ({
-  useTrackComponentVisibleEvent: vi.fn(),
-}));
-
 vi.mock('src/hooks/Intersection/useIntersection', () => ({
   useIntersection: vi.fn(() => false),
 }));

package/src/hooks/Search/useSearch.tsx

@@ -27,8 +27,8 @@ import { SearchResponseProduct } from '@spiffy-ai/commerce-api-client';
 import { SearchFilterDatum, SelectFilterItem } from 'src/types/search-filter-types';
 import { orgShortNameAtom } from 'src/atoms/envive/enviveConfig';
 import { FrontendConfig, SearchResponseProductAttributes } from 'src/application/models';
+import { useIntersection } from 'src/hooks/Intersection/useIntersection';
 import { SearchResultsState, getSearchResultsState } from '../utils';
-import { useTrackComponentVisibleEvent } from '../TrackComponentVisibleEvent';
 import { useSearchInput } from './useSearchInput';
 import { useNewOrgConfig } from '../NewOrgConfig';
 import { useRecommendedProducts } from './useRecommendedProducts';
@@ -292,13 +292,19 @@ export const useSearch = ({
     scrollToTop();
   }, [setProductSorting, clearFilters, scrollToTop]);
 
-  // Side Effects
-  useTrackComponentVisibleEvent(
-    SpiffyWidgets.SearchResults,
-    searchResultsRef as RefObject<HTMLElement>,
-    {},
-    SpiffyMetricsEventName.SearchComponentVisible,
-  );
+  const searchResultsVisible = useIntersection(searchResultsRef as RefObject<HTMLElement>, '0px');
+  const hasTrackedSearchComponentVisible = useRef(false);
+
+  useEffect(() => {
+    if (!searchResultsVisible || hasTrackedSearchComponentVisible.current) {
+      return;
+    }
+    hasTrackedSearchComponentVisible.current = true;
+    trackEvent({
+      eventName: SpiffyMetricsEventName.SearchComponentVisible,
+      eventProps: {},
+    });
+  }, [searchResultsVisible, trackEvent]);
 
   useEffect(() => {
     if (

package/src/hooks/TrackComponentVisibleEvent/useTrackComponentVisibleEvent.ts

@@ -1,54 +1,47 @@
 import { RefObject, useEffect, useRef } from 'react';
-import { SpiffyWidgets } from 'src/application/models/spiffyWidgets';
 import { useIntersection } from 'src/hooks/Intersection/useIntersection';
 import { useAmplitude } from 'src/contexts/amplitudeContext/amplitudeContext';
-import { SpiffyMetricsEventName } from 'src/services/amplitudeService/amplitudeService';
+import {
+  EnviveMetricsEventName,
+  SpiffyMetricsEventName,
+} from 'src/services/amplitudeService/amplitudeService';
 
 /**
- * Tracks a component and logs an event to Amplitude when the component is visible.
+ * Tracks a component and logs `SpiffyMetricsEventName.ChatComponentVisible` when visible.
  *
- * @param component - The component to track.
  * @param element - The element to track visibility of.
- * @param eventProps - Additional properties to include with the event.
- * @param eventName - The Amplitude event name to track (defaults to ChatComponentVisible).
+ * @param eventProps - Properties to include with the event.
+ * @param rootMargin - Root margin for the intersection observer (defaults to 0px).
+ * @param enabled - Whether tracking is enabled (defaults to true).
  */
 export const useTrackComponentVisibleEvent = (
-  component: SpiffyWidgets,
   element: RefObject<HTMLElement>,
   eventProps?: Record<string, unknown>,
-  eventName: SpiffyMetricsEventName = SpiffyMetricsEventName.ChatComponentVisible,
-) => {
-  const isVisible = useIntersection(element, '0px');
+  rootMargin: string = '0px',
+  enabled: boolean = true,
+): { isVisible: boolean } => {
+  const isVisible = useIntersection(element, rootMargin);
   const hasTrackedEvent = useRef(false);
   const { trackEvent } = useAmplitude();
 
-  const componentProps = (() => {
-    if (eventName === SpiffyMetricsEventName.ChatComponentVisible) {
-      return {
-        chat_component: component,
-        ...eventProps,
-      };
-    }
-    if (eventName === SpiffyMetricsEventName.SearchComponentVisible) {
-      return {
-        search_component: component,
-        ...eventProps,
-      };
-    }
-    // Default case for other event types
-    return {
-      component,
-      ...eventProps,
-    };
-  })();
-
   useEffect(() => {
-    if (isVisible && !hasTrackedEvent.current) {
+    if (!enabled || hasTrackedEvent.current) {
+      return;
+    }
+    if (isVisible) {
+      trackEvent({
+        eventName: SpiffyMetricsEventName.ChatComponentVisible,
+        eventProps,
+      });
       trackEvent({
-        eventName,
-        eventProps: componentProps,
+        eventName: EnviveMetricsEventName.WidgetRendered,
+        eventProps: {
+          ...eventProps,
+          'trigger.widget': eventProps?.widget_type,
+        },
       });
       hasTrackedEvent.current = true;
     }
-  }, [isVisible, component, eventProps, eventName, componentProps, trackEvent]);
+  }, [enabled, isVisible, eventProps, trackEvent]);
+  return { isVisible };
 };

package/src/hooks/WidgetInteraction/types.ts

@@ -5,11 +5,12 @@ export interface WidgetInteractionContext {
   page_id: string;
 }
 
-interface WidgetInteractionTrigger {
+export interface WidgetInteractionTrigger {
   interaction_id?: string;
   widget: WidgetInteractionComponent;
   widget_interaction: WidgetInteractionType;
   widget_interaction_data?: WidgetInteractionData | null;
+  interaction_class?: InteractionClass;
 }
 
 export interface InternalWidgetInteraction {
@@ -63,6 +64,29 @@ export enum WidgetInteractionType {
   MANUAL_SCROLL_TO_BOTTOM = 'manual_scroll_to_bottom',
 }
 
+export enum InteractionClass {
+  PASSIVE = 'passive', // No user commitment — hover, scroll, visibility triggers
+  NAVIGATIONAL = 'navigational', // Opens/closes something — often a side effect of intent
+  INTENTIONAL = 'intentional', // Deliberate user action — clicks, submits, typed queries
+}
+
+export const INTERACTION_TYPE_CLASS: Record<WidgetInteractionType, InteractionClass> = {
+  [WidgetInteractionType.QUERY_INPUT_CLICKED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.SUGGESTION_CLICKED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.WIDGET_CLICKED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.WIDGET_HOVERED]: InteractionClass.PASSIVE,
+  [WidgetInteractionType.WIDGET_EXPANDED]: InteractionClass.NAVIGATIONAL,
+  [WidgetInteractionType.WIDGET_COLLAPSED]: InteractionClass.NAVIGATIONAL,
+  [WidgetInteractionType.SUGGESTION_SCROLLED]: InteractionClass.PASSIVE,
+  [WidgetInteractionType.LINK_CLICKED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.PRODUCT_CARD_CLICKED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.TEXT_LINK_CLICKED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.ARTICLE_LINK_CLICKED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.REVIEW_CARD_CLICKED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.MESSAGE_SUBMITTED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.MANUAL_SCROLL_TO_BOTTOM]: InteractionClass.PASSIVE,
+};
+
 export type URL = {
   url: string;
 };

package/src/hooks/WidgetInteraction/useWidgetInteraction.ts

@@ -3,7 +3,7 @@ import { pageVariantInfoAtom } from 'src/atoms/app';
 import { useAmplitude } from 'src/contexts/amplitudeContext';
 import { PageVariantInfo } from 'src/contexts/pageContext/types';
 import { v4 as uuid } from 'uuid';
-import { InternalWidgetInteraction, WidgetInteraction } from './types';
+import { INTERACTION_TYPE_CLASS, InternalWidgetInteraction, WidgetInteraction } from './types';
 import { extractPageContext } from './utils';
 
 const getInteractionId = () => uuid();
@@ -16,6 +16,8 @@ export const useWidgetInteraction = () => {
     if (props.trigger) {
       // eslint-disable-next-line no-param-reassign
       props.trigger.interaction_id = props.trigger.interaction_id || getInteractionId();
+      props.trigger.interaction_class =
+        props.trigger.interaction_class || INTERACTION_TYPE_CLASS[props.trigger.widget_interaction];
     }
 
     const eventProps = {

package/src/services/amplitudeService/__tests__/amplitudeService.test.ts

@@ -85,10 +85,12 @@ describe('AmplitudeService', () => {
     });
   });
 
+  const validApiKey = 'abcdef1234567890abcdef1234567890';
+
   const createService = (overrides?: Partial<AmplitudeServiceConfig>) => {
     return new AmplitudeService({
       userId: 'test-user-id',
-      amplitudeApiKey: 'test-api-key',
+      amplitudeApiKey: validApiKey,
       dataResidency: 'US',
       env: 'test',
       orgId: 'test-org-id',
@@ -107,7 +109,7 @@ describe('AmplitudeService', () => {
       createService();
 
       expect(mockInit).toHaveBeenCalledWith(
-        'test-api-key',
+        validApiKey,
         'test-user-id',
         expect.objectContaining({
           serverZone: 'US',
@@ -121,7 +123,7 @@ describe('AmplitudeService', () => {
     it('should not be ready if userId is missing', () => {
       const service = new AmplitudeService({
         userId: '',
-        amplitudeApiKey: 'test-api-key',
+        amplitudeApiKey: validApiKey,
         dataResidency: 'US',
         env: 'test',
         orgId: 'test-org-id',
@@ -157,7 +159,7 @@ describe('AmplitudeService', () => {
     it('should not be ready if featureFlagService is missing', () => {
       const service = new AmplitudeService({
         userId: 'test-user-id',
-        amplitudeApiKey: 'test-api-key',
+        amplitudeApiKey: validApiKey,
         dataResidency: 'US',
         env: 'test',
         orgId: 'test-org-id',
@@ -269,7 +271,7 @@ describe('AmplitudeService', () => {
     it('should not track if client is not initialized', async () => {
       const service = new AmplitudeService({
         userId: '',
-        amplitudeApiKey: 'test-api-key',
+        amplitudeApiKey: validApiKey,
         dataResidency: 'US',
         env: 'test',
         orgId: 'test-org-id',
@@ -419,7 +421,7 @@ describe('AmplitudeService', () => {
     it('should fall back to window.localStorage when getLocalStorageItem is not provided', async () => {
       const service = new AmplitudeService({
         userId: 'test-user-id',
-        amplitudeApiKey: 'test-api-key',
+        amplitudeApiKey: validApiKey,
         dataResidency: 'US',
         env: 'test',
         orgId: 'test-org-id',
@@ -597,6 +599,67 @@ describe('AmplitudeService', () => {
     });
   });
 
+  describe('isMockApiKey', () => {
+    it('should return true when amplitudeApiKey is "mock-amplitude-key"', () => {
+      const service = createService({ amplitudeApiKey: 'mock-amplitude-key' });
+
+      expect(service.isMockApiKey).toBe(true);
+    });
+
+    it('should return false for a real API key', () => {
+      const service = createService();
+
+      expect(service.isMockApiKey).toBe(false);
+    });
+  });
+
+  describe('Mock API key behavior', () => {
+    it('should not initialize the Amplitude client when using mock API key', () => {
+      createService({ amplitudeApiKey: 'mock-amplitude-key' });
+
+      expect(mockInit).not.toHaveBeenCalled();
+      expect(mockAdd).not.toHaveBeenCalled();
+    });
+
+    it('should log a warning when mock API key is detected during initialization', () => {
+      const logWarnSpy = vi.spyOn(Logger.prototype, 'logWarn');
+
+      createService({ amplitudeApiKey: 'mock-amplitude-key' });
+
+      expect(logWarnSpy).toHaveBeenCalledWith(
+        'Mock API key detected — running in mock mode, no events will be sent to Amplitude.',
+        'mock-amplitude-key',
+      );
+    });
+
+    it('should report isReady as false when using mock API key', () => {
+      const service = createService({ amplitudeApiKey: 'mock-amplitude-key' });
+
+      expect(service.isReady).toBe(false);
+    });
+
+    it('should not track events when using mock API key', async () => {
+      const service = createService({ amplitudeApiKey: 'mock-amplitude-key' });
+
+      await service.trackEvent({
+        eventName: SpiffyMetricsEventName.ChatUserMessageInput,
+        eventProps: { message: 'test' },
+      });
+
+      expect(mockTrack).not.toHaveBeenCalled();
+    });
+
+    it('should not call crypto.subtle.digest when using mock API key', async () => {
+      const service = createService({ amplitudeApiKey: 'mock-amplitude-key' });
+
+      await service.trackEvent({
+        eventName: SpiffyMetricsEventName.ChatUserMessageInput,
+      });
+
+      expect(mockDigest).not.toHaveBeenCalled();
+    });
+  });
+
   describe('Session replay initialization', () => {
     it('should disable session replay by default', () => {
       createService();

package/src/services/amplitudeService/amplitudeService.ts

@@ -56,6 +56,10 @@ export class AmplitudeService {
     this.initialize();
   }
 
+  get isMockApiKey(): boolean {
+    return this.config.amplitudeApiKey === 'mock-amplitude-key';
+  }
+
   get isReady(): boolean {
     return Boolean(
       this.config.userId &&
@@ -228,6 +232,14 @@ export class AmplitudeService {
       return;
     }
 
+    if (this.isMockApiKey) {
+      logger.logWarn(
+        'Mock API key detected — running in mock mode, no events will be sent to Amplitude.',
+        this.config.amplitudeApiKey,
+      );
+      return;
+    }
+
     if (!this.amplitudeClient) {
       const currentAmplitudeInstance: BrowserClient = createInstance();
 
@@ -353,6 +365,7 @@ export class AmplitudeService {
     eventGroups,
     alsoSendToGoogleAnalytics = false,
   }: TrackEventParams): Promise<void> {
+    if (this.isMockApiKey) return;
     logger.logDebug('Submitting event', eventName);
     try {
       const decoratedEventName = AmplitudeService.decorateEventName(eventName);