@envive-ai/react-hooks 0.3.19-alpha-marlo-2 → 0.3.19-alpha-marlo-4

package/src/contexts/pageContext/pageContext.tsx

@@ -10,15 +10,18 @@ import {
 } from 'react';
 import {
   UrlResolverResponse,
+  hasParsedVariantInfoAtom,
   pageUserEventAtom,
   pageVariantInfoAtom,
   urlResolverAtom,
+  variantInfoAtom,
 } from 'src/atoms/app/variant';
-import { useAtom } from 'jotai';
+import { useAtom, useAtomValue } from 'jotai';
 import CommerceApiClient from 'src/application/commerce-api';
 import Logger from 'src/application/logging/logger';
 import { PageVisitCategory, UserEventCategory } from '@spiffy-ai/commerce-api-client';
 import { VariantTypeEnum } from 'src/application/models';
+import { EnviveMetricsEventName, useAmplitude } from 'src/contexts/amplitudeContext';
 import { mapApiUserEventToUserEvent, mapUrlResolverResponseToVariantInfo } from './mapping';
 import { PageDetails } from './types';
 
@@ -138,6 +141,62 @@ export const PageProvider: React.FC<{
     onUrlResolverNotReady,
   ]);
 
+  const { trackEvent } = useAmplitude();
+  const resolvedVariantInfo = useAtomValue(variantInfoAtom);
+  const hasParsedVariantInfo = useAtomValue(hasParsedVariantInfoAtom);
+  const pageViewedFired = useRef(false);
+
+  useEffect(() => {
+    if (pageViewedFired.current || isLoading || !hasParsedVariantInfo || !variantInfo) {
+      return;
+    }
+
+    let pageType: string;
+    let pageId: string;
+
+    switch (variantInfo.variantType) {
+      case VariantTypeEnum.Pdp:
+        pageType = 'pdp';
+        pageId = variantInfo.productId;
+        break;
+      case VariantTypeEnum.Plp:
+        pageType = 'plp';
+        pageId = variantInfo.plpId;
+        break;
+      case VariantTypeEnum.Home:
+        pageType = 'homepage';
+        pageId = variantInfo.url;
+        break;
+      case VariantTypeEnum.Other:
+        pageType = 'other';
+        pageId = variantInfo.url;
+        break;
+      case VariantTypeEnum.PageVisit:
+        pageType = 'other';
+        pageId = variantInfo.url;
+        break;
+      case VariantTypeEnum.FullPageSalesAgent:
+        pageType = 'full_page_sales_agent';
+        pageId = variantInfo.url;
+        break;
+      default:
+        return;
+    }
+
+    pageViewedFired.current = true;
+
+    trackEvent({
+      eventName: EnviveMetricsEventName.PageViewed,
+      eventProps: {
+        'context.page_type': pageType,
+        'context.page_id': pageId,
+        'context.supported': isSupported,
+        'context.ready': isSupported,
+        'context.page_variant_id': resolvedVariantInfo.variantId,
+      },
+    });
+  }, [isLoading, isSupported, hasParsedVariantInfo, variantInfo, resolvedVariantInfo, trackEvent]);
+
   const setPageUrlStable = useCallback((url: string) => {
     setPageUrl(url);
   }, []);

package/src/hooks/PageViewedEvent/__tests__/usePageViewedEvent.test.ts

@@ -0,0 +1,297 @@
+import { renderHook } from '@testing-library/react';
+import { VariantTypeEnum } from 'src/application/models';
+import { EnviveMetricsEventName } from 'src/contexts/amplitudeContext';
+import {
+  FullPageSalesAgentVariantInfo,
+  HomeVariantInfo,
+  OtherVariantInfo,
+  PDPPageVariantInfo,
+  PLPPageVariantInfo,
+  PageVariantInfo,
+  VisitPageVariantInfo,
+} from 'src/contexts/pageContext/types';
+import { extractPageViewedContext, usePageViewedEvent } from '../usePageViewedEvent';
+
+const mockTrackEvent = vi.fn();
+
+vi.mock('src/contexts/amplitudeContext', async () => {
+  const actual = await vi.importActual('src/contexts/amplitudeContext');
+  return {
+    ...actual,
+    useAmplitude: () => ({
+      trackEvent: mockTrackEvent,
+    }),
+  };
+});
+
+const mockUsePage = vi.fn();
+vi.mock('src/contexts/pageContext', () => ({
+  usePage: () => mockUsePage(),
+}));
+
+const mockUseAtomValue = vi.fn();
+vi.mock('jotai', async () => {
+  const actual = await vi.importActual('jotai');
+  return {
+    ...actual,
+    useAtomValue: () => mockUseAtomValue(),
+  };
+});
+
+describe('extractPageViewedContext', () => {
+  it('should return pdp context', () => {
+    const variant: PDPPageVariantInfo = {
+      variantType: VariantTypeEnum.Pdp,
+      productId: 'product-123',
+      collections: [],
+      numberOfReviews: 0,
+      merchantTags: [],
+      url: 'https://example.com/products/product-123',
+    };
+    expect(extractPageViewedContext(variant)).toEqual({
+      page_type: 'pdp',
+      page_id: 'product-123',
+    });
+  });
+
+  it('should return plp context', () => {
+    const variant: PLPPageVariantInfo = {
+      variantType: VariantTypeEnum.Plp,
+      plpId: 'collection-456',
+      topCategory: 'shoes',
+      url: 'https://example.com/collections/shoes',
+    };
+    expect(extractPageViewedContext(variant)).toEqual({
+      page_type: 'plp',
+      page_id: 'collection-456',
+    });
+  });
+
+  it('should return homepage context', () => {
+    const variant: HomeVariantInfo = {
+      variantType: VariantTypeEnum.Home,
+      url: 'https://example.com/',
+    };
+    expect(extractPageViewedContext(variant)).toEqual({
+      page_type: 'homepage',
+      page_id: 'https://example.com/',
+    });
+  });
+
+  it('should return other context for Other variant', () => {
+    const variant: OtherVariantInfo = {
+      variantType: VariantTypeEnum.Other,
+      url: 'https://example.com/about',
+    };
+    expect(extractPageViewedContext(variant)).toEqual({
+      page_type: 'other',
+      page_id: 'https://example.com/about',
+    });
+  });
+
+  it('should return other context for PageVisit variant', () => {
+    const variant: VisitPageVariantInfo = {
+      variantType: VariantTypeEnum.PageVisit,
+      url: 'https://example.com/contact',
+    };
+    expect(extractPageViewedContext(variant)).toEqual({
+      page_type: 'other',
+      page_id: 'https://example.com/contact',
+    });
+  });
+
+  it('should return full_page_sales_agent context', () => {
+    const variant: FullPageSalesAgentVariantInfo = {
+      variantType: VariantTypeEnum.FullPageSalesAgent,
+      url: 'https://example.com/agent',
+    };
+    expect(extractPageViewedContext(variant)).toEqual({
+      page_type: 'full_page_sales_agent',
+      page_id: 'https://example.com/agent',
+    });
+  });
+
+  it('should return null for unknown variant type', () => {
+    const variant = { variantType: 'unknown' } as unknown as PageVariantInfo;
+    expect(extractPageViewedContext(variant)).toBeNull();
+  });
+});
+
+describe('usePageViewedEvent', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should not fire when still loading', () => {
+    mockUsePage.mockReturnValue({
+      variantInfo: {
+        variantType: VariantTypeEnum.Pdp,
+        productId: 'p1',
+        collections: [],
+        numberOfReviews: 0,
+        merchantTags: [],
+        url: '',
+      },
+      isSupported: true,
+      isLoading: true,
+    });
+    mockUseAtomValue
+      .mockReturnValueOnce({ variantId: 'v1', variant: 'pdp' })
+      .mockReturnValueOnce(true);
+
+    renderHook(() => usePageViewedEvent());
+    expect(mockTrackEvent).not.toHaveBeenCalled();
+  });
+
+  it('should not fire when hasParsedVariantInfo is false', () => {
+    mockUsePage.mockReturnValue({
+      variantInfo: {
+        variantType: VariantTypeEnum.Pdp,
+        productId: 'p1',
+        collections: [],
+        numberOfReviews: 0,
+        merchantTags: [],
+        url: '',
+      },
+      isSupported: true,
+      isLoading: false,
+    });
+    mockUseAtomValue
+      .mockReturnValueOnce({ variantId: 'v1', variant: 'pdp' })
+      .mockReturnValueOnce(false);
+
+    renderHook(() => usePageViewedEvent());
+    expect(mockTrackEvent).not.toHaveBeenCalled();
+  });
+
+  it('should not fire when pageVariantInfo is undefined', () => {
+    mockUsePage.mockReturnValue({
+      variantInfo: undefined,
+      isSupported: false,
+      isLoading: false,
+    });
+    mockUseAtomValue
+      .mockReturnValueOnce({ variantId: 'v1', variant: 'pdp' })
+      .mockReturnValueOnce(true);
+
+    renderHook(() => usePageViewedEvent());
+    expect(mockTrackEvent).not.toHaveBeenCalled();
+  });
+
+  it('should fire with correct props for pdp page', () => {
+    mockUsePage.mockReturnValue({
+      variantInfo: {
+        variantType: VariantTypeEnum.Pdp,
+        productId: 'product-123',
+        collections: [],
+        numberOfReviews: 5,
+        merchantTags: [],
+        url: 'https://example.com/products/product-123',
+      },
+      isSupported: true,
+      isLoading: false,
+    });
+    mockUseAtomValue
+      .mockReturnValueOnce({ variantId: 'variant-A', variant: 'pdp' })
+      .mockReturnValueOnce(true);
+
+    renderHook(() => usePageViewedEvent());
+
+    expect(mockTrackEvent).toHaveBeenCalledTimes(1);
+    expect(mockTrackEvent).toHaveBeenCalledWith({
+      eventName: EnviveMetricsEventName.PageViewed,
+      eventProps: {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'context.supported': true,
+        'context.ready': true,
+        'context.page_variant_id': 'variant-A',
+      },
+    });
+  });
+
+  it('should fire only once even if dependencies change', () => {
+    mockUsePage.mockReturnValue({
+      variantInfo: {
+        variantType: VariantTypeEnum.Pdp,
+        productId: 'product-123',
+        collections: [],
+        numberOfReviews: 0,
+        merchantTags: [],
+        url: '',
+      },
+      isSupported: true,
+      isLoading: false,
+    });
+    mockUseAtomValue
+      .mockReturnValueOnce({ variantId: 'v1', variant: 'pdp' })
+      .mockReturnValueOnce(true);
+
+    const { rerender } = renderHook(() => usePageViewedEvent());
+
+    mockUseAtomValue
+      .mockReturnValueOnce({ variantId: 'v1', variant: 'pdp' })
+      .mockReturnValueOnce(true);
+
+    rerender();
+
+    expect(mockTrackEvent).toHaveBeenCalledTimes(1);
+  });
+
+  it('should fire with full_page_sales_agent page type', () => {
+    mockUsePage.mockReturnValue({
+      variantInfo: {
+        variantType: VariantTypeEnum.FullPageSalesAgent,
+        url: 'https://example.com/agent',
+      },
+      isSupported: true,
+      isLoading: false,
+    });
+    mockUseAtomValue
+      .mockReturnValueOnce({ variantId: 'fpsa-variant', variant: 'full_page' })
+      .mockReturnValueOnce(true);
+
+    renderHook(() => usePageViewedEvent());
+
+    expect(mockTrackEvent).toHaveBeenCalledTimes(1);
+    expect(mockTrackEvent).toHaveBeenCalledWith({
+      eventName: EnviveMetricsEventName.PageViewed,
+      eventProps: {
+        'context.page_type': 'full_page_sales_agent',
+        'context.page_id': 'https://example.com/agent',
+        'context.supported': true,
+        'context.ready': true,
+        'context.page_variant_id': 'fpsa-variant',
+      },
+    });
+  });
+
+  it('should set supported and ready to false when isSupported is false', () => {
+    mockUsePage.mockReturnValue({
+      variantInfo: {
+        variantType: VariantTypeEnum.Pdp,
+        productId: 'product-456',
+        collections: [],
+        numberOfReviews: 0,
+        merchantTags: [],
+        url: '',
+      },
+      isSupported: false,
+      isLoading: false,
+    });
+    mockUseAtomValue
+      .mockReturnValueOnce({ variantId: 'v2', variant: 'pdp' })
+      .mockReturnValueOnce(true);
+
+    renderHook(() => usePageViewedEvent());
+
+    expect(mockTrackEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        eventProps: expect.objectContaining({
+          'context.supported': false,
+          'context.ready': false,
+        }),
+      }),
+    );
+  });
+});

package/src/hooks/PageViewedEvent/index.ts

@@ -0,0 +1 @@
+export * from './usePageViewedEvent';

package/src/hooks/PageViewedEvent/usePageViewedEvent.ts

@@ -0,0 +1,103 @@
+import { useAtomValue } from 'jotai';
+import { useEffect, useRef } from 'react';
+import { VariantTypeEnum } from 'src/application/models';
+import { hasParsedVariantInfoAtom, variantInfoAtom } from 'src/atoms/app/variant';
+import { EnviveMetricsEventName, useAmplitude } from 'src/contexts/amplitudeContext';
+import { usePage } from 'src/contexts/pageContext';
+import {
+  FullPageSalesAgentVariantInfo,
+  HomeVariantInfo,
+  OtherVariantInfo,
+  PDPPageVariantInfo,
+  PLPPageVariantInfo,
+  PageVariantInfo,
+  VisitPageVariantInfo,
+} from 'src/contexts/pageContext/types';
+
+interface PageViewedContext {
+  page_type: string;
+  page_id: string;
+}
+
+export const extractPageViewedContext = (
+  pageVariant: PageVariantInfo,
+): PageViewedContext | null => {
+  switch (pageVariant.variantType) {
+    case VariantTypeEnum.Pdp:
+      return {
+        page_type: 'pdp',
+        page_id: (pageVariant as PDPPageVariantInfo).productId,
+      };
+    case VariantTypeEnum.Plp:
+      return {
+        page_type: 'plp',
+        page_id: (pageVariant as PLPPageVariantInfo).plpId,
+      };
+    case VariantTypeEnum.Home:
+      return {
+        page_type: 'homepage',
+        page_id: (pageVariant as HomeVariantInfo).url,
+      };
+    case VariantTypeEnum.Other:
+      return {
+        page_type: 'other',
+        page_id: (pageVariant as OtherVariantInfo).url,
+      };
+    case VariantTypeEnum.PageVisit:
+      return {
+        page_type: 'other',
+        page_id: (pageVariant as VisitPageVariantInfo).url,
+      };
+    case VariantTypeEnum.FullPageSalesAgent:
+      return {
+        page_type: 'full_page_sales_agent',
+        page_id: (pageVariant as FullPageSalesAgentVariantInfo).url,
+      };
+    default:
+      return null;
+  }
+};
+
+/**
+ * Fires the [Envive] Page Viewed event once per page load when page context data is ready.
+ *
+ * This event captures page context information and is intended to eventually replace
+ * the [Amplitude] Page Viewed event.
+ */
+export const usePageViewedEvent = () => {
+  const hasFired = useRef(false);
+  const { trackEvent } = useAmplitude();
+  const { variantInfo: pageVariantInfo, isSupported, isLoading } = usePage();
+  const variantInfo = useAtomValue(variantInfoAtom);
+  const hasParsedVariantInfo = useAtomValue(hasParsedVariantInfoAtom);
+
+  useEffect(() => {
+    if (hasFired.current) {
+      return;
+    }
+
+    if (isLoading || !hasParsedVariantInfo || !pageVariantInfo) {
+      return;
+    }
+
+    const pageContext = extractPageViewedContext(pageVariantInfo);
+    if (!pageContext) {
+      return;
+    }
+
+    hasFired.current = true;
+
+    trackEvent({
+      eventName: EnviveMetricsEventName.PageViewed,
+      eventProps: {
+        'context.page_type': pageContext.page_type,
+        'context.page_id': pageContext.page_id,
+        // context.supported and context.ready both derive from isSupported (response.ready)
+        // because the supportedEventAtom is not currently populated.
+        'context.supported': isSupported,
+        'context.ready': isSupported,
+        'context.page_variant_id': variantInfo.variantId,
+      },
+    });
+  }, [isLoading, isSupported, hasParsedVariantInfo, pageVariantInfo, variantInfo, trackEvent]);
+};

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

@@ -85,12 +85,10 @@ describe('AmplitudeService', () => {
     });
   });
 
-  const validApiKey = 'abcdef1234567890abcdef1234567890';
-
   const createService = (overrides?: Partial<AmplitudeServiceConfig>) => {
     return new AmplitudeService({
       userId: 'test-user-id',
-      amplitudeApiKey: validApiKey,
+      amplitudeApiKey: 'test-api-key',
       dataResidency: 'US',
       env: 'test',
       orgId: 'test-org-id',
@@ -109,7 +107,7 @@ describe('AmplitudeService', () => {
       createService();
 
       expect(mockInit).toHaveBeenCalledWith(
-        validApiKey,
+        'test-api-key',
         'test-user-id',
         expect.objectContaining({
           serverZone: 'US',
@@ -123,7 +121,7 @@ describe('AmplitudeService', () => {
     it('should not be ready if userId is missing', () => {
       const service = new AmplitudeService({
         userId: '',
-        amplitudeApiKey: validApiKey,
+        amplitudeApiKey: 'test-api-key',
         dataResidency: 'US',
         env: 'test',
         orgId: 'test-org-id',
@@ -159,7 +157,7 @@ describe('AmplitudeService', () => {
     it('should not be ready if featureFlagService is missing', () => {
       const service = new AmplitudeService({
         userId: 'test-user-id',
-        amplitudeApiKey: validApiKey,
+        amplitudeApiKey: 'test-api-key',
         dataResidency: 'US',
         env: 'test',
         orgId: 'test-org-id',
@@ -179,54 +177,6 @@ describe('AmplitudeService', () => {
 
       expect(service.isReady).toBe(true);
     });
-
-    it('should not set isMockMode when all required config is provided', () => {
-      const service = createService();
-
-      expect(service.isMockMode).toBe(false);
-    });
-  });
-
-  describe('Mock mode', () => {
-    it('should set isMockMode and not initialize the client when API key is not a valid hex string', () => {
-      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-
-      const service = createService({ amplitudeApiKey: 'not-a-valid-key' });
-
-      expect(service.isReady).toBe(false);
-      expect(service.isMockMode).toBe(true);
-      expect(mockInit).not.toHaveBeenCalled();
-
-      consoleSpy.mockRestore();
-    });
-
-    it('should print a console.log message when a mock API key is detected', () => {
-      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-
-      createService({ amplitudeApiKey: 'not-a-valid-key' });
-
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Mock API key detected'));
-
-      consoleSpy.mockRestore();
-    });
-
-    it('should not set isMockMode when API key is empty — service is simply not ready', () => {
-      const service = createService({ amplitudeApiKey: '' });
-
-      expect(service.isReady).toBe(false);
-      expect(service.isMockMode).toBe(false);
-    });
-
-    it('should not call the Amplitude client when trackEvent is called in mock mode', async () => {
-      const service = createService({ amplitudeApiKey: 'not-a-valid-key' });
-
-      await service.trackEvent({
-        eventName: SpiffyMetricsEventName.ChatUserMessageInput,
-        eventProps: { message: 'test' },
-      });
-
-      expect(mockTrack).not.toHaveBeenCalled();
-    });
   });
 
   describe('trackEvent', () => {
@@ -319,7 +269,7 @@ describe('AmplitudeService', () => {
     it('should not track if client is not initialized', async () => {
       const service = new AmplitudeService({
         userId: '',
-        amplitudeApiKey: validApiKey,
+        amplitudeApiKey: 'test-api-key',
         dataResidency: 'US',
         env: 'test',
         orgId: 'test-org-id',
@@ -469,7 +419,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: validApiKey,
+        amplitudeApiKey: 'test-api-key',
         dataResidency: 'US',
         env: 'test',
         orgId: 'test-org-id',

package/src/services/amplitudeService/amplitudeService.ts

@@ -51,8 +51,6 @@ export class AmplitudeService {
 
   private config: AmplitudeServiceConfig;
 
-  private _isMockMode: boolean = false;
-
   constructor(config: AmplitudeServiceConfig) {
     this.config = config;
     this.initialize();
@@ -67,10 +65,6 @@ export class AmplitudeService {
     );
   }
 
-  get isMockMode(): boolean {
-    return this._isMockMode;
-  }
-
   private getLocalStorageItem(key: string): string | null {
     if (this.config.getLocalStorageItem) {
       return this.config.getLocalStorageItem(key);
@@ -219,8 +213,8 @@ export class AmplitudeService {
     return enrichment;
   }
 
-  private static isValidAmplitudeApiKey(apiKey: string): boolean {
-    return /^[0-9a-f]{32}$/i.test(apiKey);
+  static isDummyApiKey(apiKey: string): boolean {
+    return !/^[0-9a-f]{32}$/i.test(apiKey);
   }
 
   private initialize(): void {
@@ -238,12 +232,8 @@ export class AmplitudeService {
       return;
     }
 
-    if (!AmplitudeService.isValidAmplitudeApiKey(this.config.amplitudeApiKey)) {
-      this._isMockMode = true;
-      // eslint-disable-next-line no-console
-      console.log(
-        '[AmplitudeService] Mock API key detected — running in mock mode, no events will be sent to Amplitude.',
-      );
+    if (AmplitudeService.isDummyApiKey(this.config.amplitudeApiKey)) {
+      logger.logDebug('AmplitudeService is using a dummy API key — analytics will not be tracked');
       return;
     }