@envive-ai/react-hooks 0.3.11 → 0.3.13

package/src/hooks/Search/useSearch.tsx

@@ -18,10 +18,8 @@ import {
 import { isFilterOpenAtom } from 'src/atoms/globalSearch/globalSearch';
 import { formatFilterDisplayName } from 'src/atoms/search/utils';
 import { ProductSorting } from 'src/atoms/search/types';
-import {
-  SpiffyMetricsEventName,
-  useAmplitude,
-} from 'src/contexts/amplitudeContext/amplitudeContext';
+import { useAmplitude } from 'src/contexts/amplitudeContext/amplitudeContext';
+import { SpiffyMetricsEventName } from 'src/services/amplitudeService/amplitudeService';
 import { SpiffyWidgets } from 'src/application/models/spiffyWidgets';
 import { ProductCardConfig } from 'src/contexts/types';
 import { SearchResult } from 'src/application/models/api/search';

package/src/hooks/Search/useSearchInput.ts

@@ -4,7 +4,7 @@ import Fuse from 'fuse.js';
 
 import { autocompleteStateAtom } from 'src/atoms/globalSearch';
 import { amplitudeTrackEventAtom } from 'src/atoms/amplitude/amplitudeTrackEventAtom';
-import { SpiffyMetricsEventName } from 'src/contexts/amplitudeContext';
+import { SpiffyMetricsEventName } from 'src/services/amplitudeService/amplitudeService';
 import { SpiffyWidgets } from 'src/application/models/spiffyWidgets';
 
 export interface UseSearchInputProps {

package/src/hooks/TrackComponentVisibleEvent/useTrackComponentVisibleEvent.ts

@@ -1,10 +1,8 @@
 import { RefObject, useEffect, useRef } from 'react';
 import { SpiffyWidgets } from 'src/application/models/spiffyWidgets';
 import { useIntersection } from 'src/hooks/Intersection/useIntersection';
-import {
-  SpiffyMetricsEventName,
-  useAmplitude,
-} from 'src/contexts/amplitudeContext/amplitudeContext';
+import { useAmplitude } from 'src/contexts/amplitudeContext/amplitudeContext';
+import { SpiffyMetricsEventName } from 'src/services/amplitudeService/amplitudeService';
 
 /**
  * Tracks a component and logs an event to Amplitude when the component is visible.

package/src/hooks/UpdateAnalyticsProps/useUpdateAnalyticsProps.ts

@@ -1,9 +1,7 @@
 import { useAtomValue } from 'jotai';
 import { useEffect, useRef } from 'react';
-import {
-  SpiffyMetricsEventName,
-  useAmplitude,
-} from 'src/contexts/amplitudeContext/amplitudeContext';
+import { useAmplitude } from 'src/contexts/amplitudeContext/amplitudeContext';
+import { SpiffyMetricsEventName } from 'src/services/amplitudeService/amplitudeService';
 import { hasParsedVariantInfoAtom, variantInfoAtom } from 'src/atoms/app/variant';
 
 /**

package/src/services/amplitudeService/amplitudeService.ts

@@ -11,52 +11,11 @@ import type {
 import { FeatureFlagService } from 'src/contexts/featureFlagServiceContext/featureFlagServiceContext';
 import { WidgetTypeV3 } from 'src/contexts/typesV3';
 import { ChatElementDisplayLocationV3 } from 'src/application/models/chatElementDisplayLocationV3';
+import { projectToGA4 } from '../ga4ProjectionService/ga4ProjectionService';
+import { EnviveMetricsEventName, SpiffyMetricsEventName } from './eventNames';
 
-export enum SpiffyMetricsEventName {
-  BundleLoaded = 'Bundle Loaded',
-  EnvironmentInitialized = 'Environment Initialized',
-  ChatLiveAgentBtnClick = 'Chat Live Agent Btn Click',
-  ChatFloatingButtonVisible = 'Chat Floating Button Visible',
-  ChatComponentVisible = 'Chat Component Visible',
-  ChatComponentExpanded = 'Chat Component Expanded',
-  ChatComponentCollapsed = 'Chat Component Collapsed',
-  ChatUserMessageInput = 'Chat User Message Input',
-  ChatSuggestionClicked = 'Chat Suggestion Clicked',
-  ChatAssistantResponse = 'Chat Assistant Response',
-  ProductCardClicked = 'Product Card Clicked',
-  ProductReviewCardClicked = 'Product Review Card Clicked',
-  AddToCartClicked = 'Add To Cart Clicked',
-  PromptCardClicked = 'Prompt Card Clicked',
-  SupportedEvent = 'Supported Event',
-  SearchBackToResponseClicked = 'Search Back to Response Clicked',
-  PerformanceMetrics = 'Performance Metrics',
-  SearchBarClicked = 'Search Bar Clicked',
-  OrderLookupStarted = 'Order Lookup Started',
-  OrderLookupFormSubmitted = 'Order Lookup Form Submitted',
-  SearchComponentVisible = 'Search Component Visible',
-  SearchZeroStateSuggestionClicked = 'Search Zero State Suggestion Clicked', // This is the scrolling list of suggestion buttons in global search
-  SearchInputStarted = 'Search Input Started',
-  SearchQuerySubmitted = 'Search Query Submitted',
-  // SearchAutocompleteViewed = 'Search Autocomplete Viewed', // TODO: add this when autocomplete is added
-  // SearchAutocompleteClicked = 'Search Autocomplete Clicked', // TODO: add this when autocomplete is added
-  SearchResultsViewed = 'Search Results Viewed',
-  SearchTimeToFirstClick = 'Search Time to First Click',
-  SearchZeroResultsRate = 'Search Zero Results Rate',
-  SearchFilterClicked = 'Search Filter Clicked',
-  SearchSortClicked = 'Search Sort Clicked',
-}
-
-export enum EnviveMetricsEventName {
-  WidgetRendered = 'Widget Rendered',
-  WidgetInteraction = 'Widget Interaction',
-  ChatRequest = 'Chat Request',
-  ChatResponse = 'Chat Response',
-  EnviveInitialized = 'Envive Initialized',
-  PageViewed = 'Page Viewed', // Will this be useful?
-  WidgetTextRequest = 'Widget Text Request',
-  WidgetTextResponse = 'Widget Text Response',
-  WidgetTextClicked = 'Widget Text Clicked',
-}
+// Re-export event names for convenience
+export { EnviveMetricsEventName, SpiffyMetricsEventName };
 
 export interface TrackEventParams {
   eventName: SpiffyMetricsEventName | EnviveMetricsEventName;
@@ -142,7 +101,7 @@ export class AmplitudeService {
       'environment.envive_enabled': this.config.enabledFeatures?.envive,
     };
 
-    const orgLevelAmplitudeTrackingProps = AmplitudeService.isEnviveEvent(eventName)
+    const orgLevelAmplitudeTrackingProps = AmplitudeService.isV3EnviveEvent(eventName)
       ? {
           ...this.config.featureFlagService.getFullFlagValues(),
           ...experimentProps,
@@ -375,12 +334,12 @@ export class AmplitudeService {
     return eventProps ?? {};
   }
 
-  static isEnviveEvent(eventName: SpiffyMetricsEventName | EnviveMetricsEventName): boolean {
+  static isV3EnviveEvent(eventName: SpiffyMetricsEventName | EnviveMetricsEventName): boolean {
     return Object.values(EnviveMetricsEventName).includes(eventName as EnviveMetricsEventName);
   }
 
   static decorateEventName(eventName: SpiffyMetricsEventName | EnviveMetricsEventName): string {
-    if (AmplitudeService.isEnviveEvent(eventName)) {
+    if (AmplitudeService.isV3EnviveEvent(eventName)) {
       return `[Envive] ${eventName}`;
     }
     return `[Spiffy] ${eventName}`;
@@ -438,8 +397,13 @@ export class AmplitudeService {
         },
       );
 
-      if (alsoSendToGoogleAnalytics && this.config.orgGaConfig) {
-        // TODO: Add in windowDataLayerService or context alternative and hook it up here
+      if (AmplitudeService.isV3EnviveEvent(eventName) && this.config.orgGaConfig) {
+        const mergedPropsForGA4 = {
+          ...this.getDefaultTrackingProps(eventName),
+          ...mappedEventProps,
+        };
+        projectToGA4(eventName as EnviveMetricsEventName, mergedPropsForGA4);
+      } else if (alsoSendToGoogleAnalytics && this.config.orgGaConfig) {
         Logger.logDebug('[spiffy-ai] GA tracking', decoratedEventName);
         if (typeof window !== 'undefined' && window.dataLayer) {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/services/amplitudeService/eventNames.ts

@@ -0,0 +1,52 @@
+/**
+ * Event name enums for Amplitude tracking.
+ *
+ * NOTE: This file exists separately to avoid circular dependency issues.
+ * The amplitudeService imports from ga4ProjectionService, which needs these enums.
+ * By keeping the enums in a separate file, ga4ProjectionService can import them
+ * without creating a circular dependency with amplitudeService.
+ */
+
+export enum SpiffyMetricsEventName {
+  BundleLoaded = 'Bundle Loaded',
+  EnvironmentInitialized = 'Environment Initialized',
+  ChatLiveAgentBtnClick = 'Chat Live Agent Btn Click',
+  ChatFloatingButtonVisible = 'Chat Floating Button Visible',
+  ChatComponentVisible = 'Chat Component Visible',
+  ChatComponentExpanded = 'Chat Component Expanded',
+  ChatComponentCollapsed = 'Chat Component Collapsed',
+  ChatUserMessageInput = 'Chat User Message Input',
+  ChatSuggestionClicked = 'Chat Suggestion Clicked',
+  ChatAssistantResponse = 'Chat Assistant Response',
+  ProductCardClicked = 'Product Card Clicked',
+  ProductReviewCardClicked = 'Product Review Card Clicked',
+  AddToCartClicked = 'Add To Cart Clicked',
+  PromptCardClicked = 'Prompt Card Clicked',
+  SupportedEvent = 'Supported Event',
+  SearchBackToResponseClicked = 'Search Back to Response Clicked',
+  PerformanceMetrics = 'Performance Metrics',
+  SearchBarClicked = 'Search Bar Clicked',
+  OrderLookupStarted = 'Order Lookup Started',
+  OrderLookupFormSubmitted = 'Order Lookup Form Submitted',
+  SearchComponentVisible = 'Search Component Visible',
+  SearchZeroStateSuggestionClicked = 'Search Zero State Suggestion Clicked',
+  SearchInputStarted = 'Search Input Started',
+  SearchQuerySubmitted = 'Search Query Submitted',
+  SearchResultsViewed = 'Search Results Viewed',
+  SearchTimeToFirstClick = 'Search Time to First Click',
+  SearchZeroResultsRate = 'Search Zero Results Rate',
+  SearchFilterClicked = 'Search Filter Clicked',
+  SearchSortClicked = 'Search Sort Clicked',
+}
+
+export enum EnviveMetricsEventName {
+  WidgetRendered = 'Widget Rendered',
+  WidgetInteraction = 'Widget Interaction',
+  ChatRequest = 'Chat Request',
+  ChatResponse = 'Chat Response',
+  EnviveInitialized = 'Envive Initialized',
+  PageViewed = 'Page Viewed',
+  WidgetTextRequest = 'Widget Text Request',
+  WidgetTextResponse = 'Widget Text Response',
+  WidgetTextClicked = 'Widget Text Clicked',
+}

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

@@ -0,0 +1,334 @@
+import { EnviveMetricsEventName } from '../../amplitudeService/eventNames';
+import { projectToGA4 } from '../ga4ProjectionService';
+
+describe('projectToGA4', () => {
+  beforeEach(() => {
+    window.dataLayer = [];
+  });
+
+  afterEach(() => {
+    delete (window as any).dataLayer;
+  });
+
+  describe('excluded events', () => {
+    it('should not push to dataLayer for WidgetTextRequest', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetTextRequest, { widget_type: 'test' });
+      expect(window.dataLayer).toHaveLength(0);
+    });
+
+    it('should not push to dataLayer for WidgetTextResponse', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetTextResponse, { widget_type: 'test' });
+      expect(window.dataLayer).toHaveLength(0);
+    });
+
+    it('should not push to dataLayer for WidgetTextClicked', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetTextClicked, { text: 'hello' });
+      expect(window.dataLayer).toHaveLength(0);
+    });
+  });
+
+  describe('Widget Rendered', () => {
+    it('should push filtered and flattened props', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetRendered, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'floating_button',
+        'trigger.interaction_id': 'abc-123',
+      });
+
+      expect(window.dataLayer).toHaveLength(1);
+      expect(window.dataLayer[0]).toEqual({
+        event: 'envive_widget_rendered',
+        context_page_type: 'pdp',
+        context_page_id: 'product-123',
+        trigger_widget: 'floating_button',
+      });
+    });
+
+    it('should exclude fields not in allowedFields', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetRendered, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'floating_button',
+        'trigger.interaction_id': 'should-be-dropped',
+        'some.random_field': 'also-dropped',
+      });
+
+      const pushed = window.dataLayer[0];
+      expect(pushed).not.toHaveProperty('trigger_interaction_id');
+      expect(pushed).not.toHaveProperty('some_random_field');
+    });
+  });
+
+  describe('page_id sanitization', () => {
+    it('should keep page_id for pdp page type', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetRendered, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'floating_button',
+      });
+
+      expect(window.dataLayer[0]).toHaveProperty('context_page_id', 'product-123');
+    });
+
+    it('should keep page_id for plp page type', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetRendered, {
+        'context.page_type': 'plp',
+        'context.page_id': 'category-456',
+        'trigger.widget': 'floating_button',
+      });
+
+      expect(window.dataLayer[0]).toHaveProperty('context_page_id', 'category-456');
+    });
+
+    it('should omit page_id for search page type', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetRendered, {
+        'context.page_type': 'search',
+        'context.page_id': 'some search query',
+        'trigger.widget': 'floating_button',
+      });
+
+      expect(window.dataLayer[0]).not.toHaveProperty('context_page_id');
+    });
+
+    it('should omit page_id for homepage page type', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetRendered, {
+        'context.page_type': 'homepage',
+        'context.page_id': 'https://example.com',
+        'trigger.widget': 'floating_button',
+      });
+
+      expect(window.dataLayer[0]).not.toHaveProperty('context_page_id');
+    });
+
+    it('should omit page_id for other page type', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetRendered, {
+        'context.page_type': 'other',
+        'context.page_id': 'https://example.com/about',
+        'trigger.widget': 'floating_button',
+      });
+
+      expect(window.dataLayer[0]).not.toHaveProperty('context_page_id');
+    });
+  });
+
+  describe('Widget Interaction', () => {
+    it('should push base fields and flatten dot keys', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetInteraction, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'chat_overlay',
+        'trigger.widget_interaction': 'link_clicked',
+      });
+
+      expect(window.dataLayer[0]).toEqual({
+        event: 'envive_widget_interaction',
+        context_page_type: 'pdp',
+        context_page_id: 'product-123',
+        trigger_widget: 'chat_overlay',
+        trigger_widget_interaction: 'link_clicked',
+      });
+    });
+
+    it('should extract collapse_source from widget_interaction_data for widget_collapsed', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetInteraction, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'chat_overlay',
+        'trigger.widget_interaction': 'widget_collapsed',
+        'trigger.widget_interaction_data': { collapse_source: 'close_button' },
+      });
+
+      expect(window.dataLayer[0]).toHaveProperty('trigger_collapse_source', 'close_button');
+    });
+
+    it('should extract product_id from widget_interaction_data for product_card_clicked', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetInteraction, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'chat_overlay',
+        'trigger.widget_interaction': 'product_card_clicked',
+        'trigger.widget_interaction_data': { product_id: 'sku-789', url: 'https://example.com' },
+      });
+
+      const pushed = window.dataLayer[0];
+      expect(pushed).toHaveProperty('trigger_product_id', 'sku-789');
+      expect(pushed).not.toHaveProperty('url');
+    });
+
+    it('should extract suggestion_id from widget_interaction_data for suggestion_scrolled', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetInteraction, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'chat_overlay',
+        'trigger.widget_interaction': 'suggestion_scrolled',
+        'trigger.widget_interaction_data': { suggestion_id: 'sug-456' },
+      });
+
+      expect(window.dataLayer[0]).toHaveProperty('trigger_suggestion_id', 'sug-456');
+    });
+
+    it('should drop widget_interaction_data for unwhitelisted interactions', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetInteraction, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'chat_overlay',
+        'trigger.widget_interaction': 'link_clicked',
+        'trigger.widget_interaction_data': { url: 'https://example.com' },
+      });
+
+      const pushed = window.dataLayer[0];
+      expect(pushed).not.toHaveProperty('url');
+      expect(pushed).not.toHaveProperty('trigger_widget_interaction_data');
+    });
+  });
+
+  describe('Chat Request', () => {
+    it('should include only allowed fields', () => {
+      projectToGA4(EnviveMetricsEventName.ChatRequest, {
+        page_type: 'pdp',
+        page_id: 'product-123',
+        'trigger.widget': 'chat_overlay',
+        'chat.request_id': 'req-001',
+        'chat.request_type': 'suggestion',
+        'chat.request_text': 'Tell me about this product',
+        'chat.user_typed': false,
+        'chat.suggestion_id': 'sug-123',
+        'chat.suggestion_category': 'product_info',
+      });
+
+      const pushed = window.dataLayer[0];
+      expect(pushed).toEqual({
+        event: 'envive_chat_request',
+        page_type: 'pdp',
+        page_id: 'product-123',
+        trigger_widget: 'chat_overlay',
+        chat_request_type: 'suggestion',
+        chat_user_typed: false,
+        chat_suggestion_id: 'sug-123',
+        chat_suggestion_category: 'product_info',
+      });
+    });
+  });
+
+  describe('Chat Response', () => {
+    it('should include only allowed fields', () => {
+      projectToGA4(EnviveMetricsEventName.ChatResponse, {
+        page_type: 'plp',
+        page_id: 'category-456',
+        'trigger.widget': 'chat_overlay',
+        'chat.response_time_ms': '1200',
+        'chat.request_type': 'text',
+        'chat.request_id': 'req-001',
+        'chat.request_text': 'Show me shoes',
+        'chat.user_typed': true,
+        'chat.product_cards_returned': 3,
+        'chat.review_cards_returned': 0,
+      });
+
+      const pushed = window.dataLayer[0];
+      expect(pushed).toEqual({
+        event: 'envive_chat_response',
+        page_type: 'plp',
+        page_id: 'category-456',
+        trigger_widget: 'chat_overlay',
+        chat_user_typed: true,
+        chat_response_time_ms: '1200',
+        chat_product_cards_returned: 3,
+        chat_review_cards_returned: 0,
+      });
+    });
+  });
+
+  describe('Envive Initialized', () => {
+    it('should include only allowed fields and drop environment details', () => {
+      projectToGA4(EnviveMetricsEventName.EnviveInitialized, {
+        'environment.execution_context': 'bundle',
+        'environment.page_url': 'https://example.com/products/shoe',
+        'environment.envive_user_id': 'user-abc',
+        'environment.execution_environment': 'prod',
+        'environment.context_source': 'app',
+        'environment.sales_agent_enabled': true,
+        'environment.search_enabled': false,
+        'environment.envive_on_query_param': false,
+        'environment.window_show': true,
+        'environment.client_session': true,
+        'environment.envive_enabled': true,
+        'performance.start_time_ms': 150,
+        'performance.initialize_time_ms': 320,
+      });
+
+      expect(window.dataLayer[0]).toEqual({
+        event: 'envive_initialized',
+        environment_sales_agent_enabled: true,
+        environment_envive_enabled: true,
+        performance_start_time_ms: 150,
+        performance_initialize_time_ms: 320,
+      });
+    });
+  });
+
+  describe('Page Viewed', () => {
+    it('should use envive_page_context_evaluated as event name', () => {
+      projectToGA4(EnviveMetricsEventName.PageViewed, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'context.supported': true,
+        'context.ready': true,
+        'context.page_variant_id': 'variant-A',
+        'environment.envive_enabled': true,
+      });
+
+      expect(window.dataLayer[0]).toEqual({
+        event: 'envive_page_context_evaluated',
+        context_page_type: 'pdp',
+        context_page_id: 'product-123',
+        context_supported: true,
+        context_ready: true,
+        context_page_variant_id: 'variant-A',
+        environment_envive_enabled: true,
+      });
+    });
+
+    it('should omit page_id for non-pdp/plp page types', () => {
+      projectToGA4(EnviveMetricsEventName.PageViewed, {
+        'context.page_type': 'search',
+        'context.page_id': 'shoes',
+        'context.supported': true,
+        'context.ready': true,
+        'environment.envive_enabled': true,
+      });
+
+      const pushed = window.dataLayer[0];
+      expect(pushed).not.toHaveProperty('context_page_id');
+      expect(pushed).toHaveProperty('context_page_type', 'search');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle undefined eventProps', () => {
+      projectToGA4(EnviveMetricsEventName.EnviveInitialized);
+
+      expect(window.dataLayer).toHaveLength(1);
+      expect(window.dataLayer[0]).toEqual({ event: 'envive_initialized' });
+    });
+
+    it('should handle empty eventProps', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetRendered, {});
+
+      expect(window.dataLayer).toHaveLength(1);
+      expect(window.dataLayer[0]).toEqual({ event: 'envive_widget_rendered' });
+    });
+
+    it('should not throw when window.dataLayer is undefined', () => {
+      delete (window as any).dataLayer;
+
+      expect(() => {
+        projectToGA4(EnviveMetricsEventName.WidgetRendered, {
+          'context.page_type': 'pdp',
+          'trigger.widget': 'floating_button',
+        });
+      }).not.toThrow();
+    });
+  });
+});

package/src/services/ga4ProjectionService/ga4EventSchema.ts

@@ -0,0 +1,143 @@
+/**
+ * GA4 Event Schema — single source of truth for Envive → GA4 projection.
+ *
+ * Every EnviveMetricsEventName MUST have an entry here. The Record type enforces
+ * this at compile time — adding a new enum member without a schema entry will
+ * cause a TypeScript error.
+ *
+ * ## How to update this file
+ *
+ * When adding or modifying event properties, decide whether they belong in `allowedFields` using these criteria:
+ * - **Low cardinality** — avoid unbounded values (free text, IDs, URLs, timestamps).
+ * - **Non-sensitive** — no PII, user input text, or internal implementation details.
+ * - **Flat scalar** — GA4 custom dimensions are flat strings/numbers/booleans.
+ *   Nested objects should NOT be added; extract specific sub-fields instead.
+ * - **Snake_case key** — must already be dot-notation snake_case (e.g. `chat.user_typed`).
+ * - **Analytically useful** — the field should enable meaningful filtering/segmentation
+ *   for merchants in their GA4 dashboards.
+ *
+ * If excluded from `allowedFields`, the projection layer will automatically drop it.
+ *
+ * IF IN DOUBT, DON'T HESITATE TO REACH OUT TO THE ANALYTICS TEAM!!!
+ */
+import { EnviveMetricsEventName } from '../amplitudeService/eventNames';
+
+/**
+ * Defines which fields to extract from `trigger.widget_interaction_data`
+ * for a given `trigger.widget_interaction` value.
+ *
+ * Key: the value of `trigger.widget_interaction` (e.g. "widget_collapsed")
+ * Value: mapping of { ga4FlatKey: sourceFieldInWidgetInteractionData }
+ */
+export type WidgetInteractionDataProjection = Record<string, Record<string, string>>;
+
+export interface GA4ProjectedEventConfig {
+  gaEventName: string;
+  allowedFields: readonly string[];
+  widgetInteractionDataProjections?: WidgetInteractionDataProjection;
+}
+
+export interface GA4ExcludedEventConfig {
+  gaEventName: null;
+}
+
+export type GA4EventSchemaEntry = GA4ProjectedEventConfig | GA4ExcludedEventConfig;
+
+const WIDGET_INTERACTION_DATA_PROJECTIONS: WidgetInteractionDataProjection = {
+  widget_collapsed: { trigger_collapse_source: 'collapse_source' },
+  product_card_clicked: { trigger_product_id: 'product_id' },
+  suggestion_scrolled: { trigger_suggestion_id: 'suggestion_id' },
+};
+
+export const GA4_EVENT_SCHEMA: Record<EnviveMetricsEventName, GA4EventSchemaEntry> = {
+  [EnviveMetricsEventName.WidgetRendered]: {
+    gaEventName: 'envive_widget_rendered',
+    allowedFields: [
+      'context.page_type',
+      'context.page_id',
+      'trigger.widget',
+      'trigger.widget_role',
+      'context.surface',
+    ],
+  },
+
+  // This event is not currently implemented
+  [EnviveMetricsEventName.WidgetInteraction]: {
+    gaEventName: 'envive_widget_interaction',
+    allowedFields: [
+      'context.page_type',
+      'context.page_id',
+      'trigger.widget',
+      'trigger.widget_interaction',
+      'trigger.entity_role',
+      'context.surface',
+    ],
+    widgetInteractionDataProjections: WIDGET_INTERACTION_DATA_PROJECTIONS,
+  },
+
+  [EnviveMetricsEventName.ChatRequest]: {
+    gaEventName: 'envive_chat_request',
+    allowedFields: [
+      'page_type',
+      'page_id',
+      'trigger.widget',
+      'chat.request_type',
+      // 'chat.request_text', // This is high cardinality and potentially PII but we might want to include it later
+      'chat.user_typed',
+      'chat.suggestion_id', // not currently implemented
+      'chat.suggestion_category', // not currently implemented
+      'chat.suggestion_created_at', // not currently implemented
+      'chat.suggestion_is_answer', // not currently implemented
+      'chat.form_type', // not currently implemented
+    ],
+  },
+
+  [EnviveMetricsEventName.ChatResponse]: {
+    gaEventName: 'envive_chat_response',
+    allowedFields: [
+      'page_type',
+      'page_id',
+      'trigger.widget', // not currently implemented (maybe it should'nt be???)
+      'chat.user_typed',
+      'chat.response_time_ms',
+      'chat.product_cards_returned',
+      'chat.review_cards_returned',
+    ],
+  },
+
+  [EnviveMetricsEventName.EnviveInitialized]: {
+    gaEventName: 'envive_initialized',
+    allowedFields: [
+      'environment.sales_agent_enabled',
+      'environment.envive_enabled',
+      // 'environment.search_enabled', // For now, search is not implemented. We will add it later.
+      'performance.start_time_ms',
+      'performance.initialize_time_ms',
+    ],
+  },
+
+  // This event is not currently implemented
+  [EnviveMetricsEventName.PageViewed]: {
+    gaEventName: 'envive_page_context_evaluated',
+    allowedFields: [
+      'context.page_type',
+      'context.page_id',
+      'context.supported',
+      'context.ready',
+      'context.page_variant_id',
+      'environment.envive_enabled',
+    ],
+  },
+
+  [EnviveMetricsEventName.WidgetTextRequest]: {
+    gaEventName: null,
+  },
+
+  [EnviveMetricsEventName.WidgetTextResponse]: {
+    gaEventName: null,
+  },
+
+  [EnviveMetricsEventName.WidgetTextClicked]: {
+    gaEventName: null,
+  },
+};