@envive-ai/react-hooks 0.3.19 → 0.3.21

package/src/contexts/enviveContext/enviveContext.tsx

@@ -1,4 +1,4 @@
-import { ReactNode, useEffect, useMemo, useState } from 'react';
+import { ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import { OrgConfigFeatureGate } from 'src/application/models/api/orgConfigResults';
 import { EnviveConfigService, EnviveServiceConfig } from 'src/services/enviveConfigService';
@@ -30,6 +30,12 @@ interface AgentWrapperProps {
   enabledAgents: EnviveAgent[];
 }
 
+export interface ExtensionStatusCallbacks {
+  onInjectionLoading?: () => Promise<unknown> | void;
+  onInjectionSuccess?: () => Promise<unknown> | void;
+  onInjectionError?: (error: Error) => Promise<unknown> | void;
+}
+
 interface EnviveProviderProps extends AgentWrapperProps {
   amplitudeApiKey?: string;
   dataResidency?: string;
@@ -58,6 +64,7 @@ interface EnviveProviderProps extends AgentWrapperProps {
   overrideConfig?: GraphQlConfigValues;
   mockSalesAgentData?: any;
   hardcopyOverride?: Partial<Record<WidgetTypeV3, HardcopyResponse>>;
+  extensionService?: ExtensionStatusCallbacks;
 }
 
 const SearchAgentWrapper: React.FC<AgentWrapperProps> = ({ children, enabledAgents }) => {
@@ -108,9 +115,34 @@ export const EnviveProvider: React.FC<EnviveProviderProps> = ({
   requestV3Config = false,
   mockSalesAgentData,
   hardcopyOverride,
+  extensionService,
   ...config
 }) => {
   const [userId, setUserId] = useState<string>('');
+  const didReportSuccessRef = useRef(false);
+
+  const invokeExtensionCallback = useCallback((callback?: () => Promise<unknown> | void) => {
+    if (!callback) {
+      return;
+    }
+
+    Promise.resolve(callback()).catch(error => {
+      logger.logDebug('Extension status callback failed', error);
+    });
+  }, []);
+
+  const invokeExtensionErrorCallback = useCallback(
+    (error: Error) => {
+      if (!extensionService?.onInjectionError) {
+        return;
+      }
+
+      Promise.resolve(extensionService.onInjectionError(error)).catch(callbackError => {
+        logger.logDebug('Extension error callback failed', callbackError);
+      });
+    },
+    [extensionService],
+  );
 
   const userIdService = useMemo(
     () =>
@@ -133,6 +165,8 @@ export const EnviveProvider: React.FC<EnviveProviderProps> = ({
   const [enviveServiceConfig, setEnviveServiceConfig] = useState<EnviveServiceConfig | null>(null);
 
   useEffect(() => {
+    invokeExtensionCallback(extensionService?.onInjectionLoading);
+
     // Really not happy with this approach, but I'm seeing 429 errors in the tests
     // because of the rate limiting on the API.
     const enviveConfigService =
@@ -144,11 +178,38 @@ export const EnviveProvider: React.FC<EnviveProviderProps> = ({
         namespace: namespace || '',
         source: source || '',
       });
-    enviveConfigService.getEnviveConfig().then(newConfig => {
-      setEnviveServiceConfig(newConfig);
-      return newConfig;
-    });
-  }, [config, userId, namespace, source, inputEnviveConfigService]);
+    const fetchEnviveConfig = async () => {
+      try {
+        const newConfig = await enviveConfigService.getEnviveConfig();
+        setEnviveServiceConfig(newConfig);
+      } catch (error) {
+        const resolvedError =
+          error instanceof Error ? error : new Error('Failed to load envive config');
+        logger.logError('Failed to initialize EnviveProvider', resolvedError);
+        invokeExtensionErrorCallback(resolvedError);
+      }
+    };
+
+    fetchEnviveConfig();
+  }, [
+    config,
+    userId,
+    namespace,
+    source,
+    inputEnviveConfigService,
+    extensionService,
+    invokeExtensionCallback,
+    invokeExtensionErrorCallback,
+  ]);
+
+  useEffect(() => {
+    if (!enviveServiceConfig || didReportSuccessRef.current) {
+      return;
+    }
+
+    didReportSuccessRef.current = true;
+    invokeExtensionCallback(extensionService?.onInjectionSuccess);
+  }, [enviveServiceConfig, extensionService, invokeExtensionCallback]);
 
   const enviveConfig = useMemo(
     () => ({
@@ -182,7 +243,10 @@ export const EnviveProvider: React.FC<EnviveProviderProps> = ({
             <FeatureFlagServiceProvider featureFlagService={featureFlagService}>
               <UserIdentityProvider userIdService={userIdService}>
                 <AmplitudeProvider externalAmplitudeService={inputAmplitudeService}>
-                  <PageProvider previewMode={previewMode}>
+                  <PageProvider
+                    previewMode={previewMode}
+                    onUrlResolverNotReady={extensionService?.onInjectionError}
+                  >
                     <WidgetConfigProvider>
                       <HardcopyProvider hardcopyOverride={hardcopyOverride}>
                         <EnviveCssProvider>

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

@@ -27,6 +27,12 @@ vi.mock('src/application/commerce-api', () => ({
   },
 }));
 
+// Mock useAmplitude (PageProvider dispatches page viewed event internally)
+vi.mock('src/contexts/amplitudeContext', () => ({
+  EnviveMetricsEventName: { PageViewed: 'Page Viewed' },
+  useAmplitude: () => ({ trackEvent: vi.fn() }),
+}));
+
 // Component that uses the usePage hook
 const MockComponent: React.FC = () => {
   const context = usePage();

package/src/contexts/pageContext/pageContext.tsx

@@ -5,19 +5,23 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
 } 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';
 
@@ -35,13 +39,17 @@ const PageContext = createContext<
 export const PageProvider: React.FC<{
   children: ReactNode;
   previewMode: boolean;
-}> = ({ children, previewMode = false }) => {
+  /** When URL resolver returns `ready: false`, invoked for extension/injection failure reporting. */
+  onUrlResolverNotReady?: (error: Error) => Promise<unknown> | void;
+}> = ({ children, previewMode = false, onUrlResolverNotReady }) => {
   const [pageUrl, setPageUrl] = useState<string | undefined>(undefined);
   const [urlResolverResponse, setUrlResolverResponse] = useAtom(urlResolverAtom);
   const [isLoading, setIsLoading] = useState(false);
   const [variantInfo, setVariantInfo] = useAtom(pageVariantInfoAtom);
   const [userEvent, setUserEvent] = useAtom(pageUserEventAtom);
   const [isSupported, setIsSupported] = useState(false);
+  const lastNotReadyUrlRef = useRef<string | null>(null);
+
   useEffect(() => {
     setPageUrl(window.location.href);
   }, []);
@@ -72,11 +80,13 @@ export const PageProvider: React.FC<{
       if (response.ready) {
         const newVariantInfo = mapUrlResolverResponseToVariantInfo(url, response);
         const newUserEvent = mapApiUserEventToUserEvent(response.user_event ?? undefined);
+        logger.logDebug('setting variant info and user event', { newVariantInfo, newUserEvent });
         setVariantInfo(newVariantInfo);
         setUserEvent(newUserEvent);
       } else {
         setUserEvent(undefined);
         setVariantInfo(undefined);
+        logger.logDebug('set variant info and user event to undefined', { variantInfo, userEvent });
       }
     },
     [setVariantInfo, setUserEvent],
@@ -104,6 +114,16 @@ export const PageProvider: React.FC<{
         setVariantFromUrlResolver(cleansedUrl, response);
         setIsLoading(false);
         setIsSupported(response.ready);
+
+        if (response.ready) {
+          lastNotReadyUrlRef.current = null;
+        } else if (onUrlResolverNotReady && lastNotReadyUrlRef.current !== cleansedUrl) {
+          lastNotReadyUrlRef.current = cleansedUrl;
+          const err = new Error(`URL resolver returned ready=false for ${cleansedUrl}`);
+          Promise.resolve(onUrlResolverNotReady(err)).catch(callbackError => {
+            logger.logDebug('onUrlResolverNotReady callback failed', callbackError);
+          });
+        }
       } catch (e) {
         setIsLoading(false);
         logger.logError('Failed to resolve page URL', e, { pageUrl });
@@ -118,8 +138,65 @@ export const PageProvider: React.FC<{
     userEvent,
     variantInfo,
     previewMode,
+    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]);
+};