@envive-ai/react-hooks 0.3.63 → 0.3.64

package/src/services/amplitudeService/eventNames.ts

@@ -48,4 +48,8 @@ export enum EnviveMetricsEventName {
   WidgetTextRequest = 'Widget Text Request',
   WidgetTextResponse = 'Widget Text Response',
   WidgetTextClicked = 'Widget Text Clicked',
+  // Operational diagnostics for widget loading (see useWidgetLoadDiagnostics). A single event
+  // with a `type` discriminator (widget_mounted | widget_load_outcome | widget_load_stalled)
+  // so eng can measure the layered load net and, crucially, the negative space between layers.
+  Diagnostics = 'Diagnostics',
 }

package/src/services/ga4ProjectionService/ga4EventSchema.ts

@@ -156,4 +156,9 @@ export const GA4_EVENT_SCHEMA: Record<EnviveMetricsEventName, GA4EventSchemaEntr
   [EnviveMetricsEventName.WidgetTextClicked]: {
     gaEventName: null,
   },
+
+  // Internal eng operational monitoring — never projected to merchant GA4.
+  [EnviveMetricsEventName.Diagnostics]: {
+    gaEventName: null,
+  },
 };

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

@@ -92,6 +92,7 @@ describe('HardcopyService', () => {
           titleLabel: 'Hello World',
           promptButtonTexts: ['Prompt 1', 'Prompt 2'],
         },
+        servedFrom: 'api',
       });
     });
 
@@ -383,7 +384,11 @@ describe('HardcopyService', () => {
         userEvent: {} as any,
       });
 
-      expect(result).toBe(MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.PromptCarouselV3]);
+      expect(result).toEqual({
+        ...MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.PromptCarouselV3],
+        servedFrom: 'static',
+        fallbackReason: 'error',
+      });
     });
 
     it('returns the MOCK_HARDCOPY_RESPONSE entry when the API returns falsy', async () => {
@@ -394,7 +399,11 @@ describe('HardcopyService', () => {
         userEvent: {} as any,
       });
 
-      expect(result).toBe(MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.SocialProofV3]);
+      expect(result).toEqual({
+        ...MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.SocialProofV3],
+        servedFrom: 'static',
+        fallbackReason: 'error',
+      });
     });
 
     it('does not fire WidgetTextResponse when falling back to mock', async () => {
@@ -437,9 +446,11 @@ describe('HardcopyService', () => {
 
         await vi.advanceTimersByTimeAsync(HARDCOPY_TIMEOUT_MS);
 
-        await expect(resultPromise).resolves.toBe(
-          MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.PromptCarouselV3],
-        );
+        await expect(resultPromise).resolves.toEqual({
+          ...MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.PromptCarouselV3],
+          servedFrom: 'static',
+          fallbackReason: 'timeout',
+        });
       } finally {
         vi.useRealTimers();
       }

package/src/services/hardcopyService/hardcopyService.ts

@@ -49,6 +49,10 @@ export type HardcopyResponse = {
   language: string;
   rawValues?: Record<string, WidgetString | WidgetString[]>;
   values: Record<string, string | string[]>;
+  // How the copy was served, for widget-load diagnostics: 'api' = live backend response,
+  // 'static' = fell back to the bundled MOCK_HARDCOPY_RESPONSE after a backend error or timeout.
+  servedFrom?: 'api' | 'static';
+  fallbackReason?: 'timeout' | 'error';
 };
 
 export interface IHardcopyService {
@@ -265,6 +269,8 @@ export class HardcopyService implements IHardcopyService {
       },
     });
 
+    // Reason the API path failed, surfaced on the static fallback for widget-load diagnostics.
+    let fallbackReason: 'timeout' | 'error' | undefined;
     try {
       const response = await withTimeout(
         CommerceApiClient.getHardcopy(widgetTextRequest),
@@ -287,16 +293,18 @@ export class HardcopyService implements IHardcopyService {
               : {}),
           },
         });
-        return convertedResponse;
+        return { ...convertedResponse, servedFrom: 'api' };
       }
     } catch (error) {
       logger.logError('error getting hardcopy from backend', error);
+      fallbackReason =
+        error instanceof Error && error.message.includes('timed out') ? 'timeout' : 'error';
     }
 
     const mockResponse = MOCK_HARDCOPY_RESPONSE[request.widgetType];
     if (mockResponse) {
       logger.logDebug('no real response, using mock', mockResponse);
-      return mockResponse;
+      return { ...mockResponse, servedFrom: 'static', fallbackReason: fallbackReason ?? 'error' };
     }
     throw new Error(`No hardcopy response found for widget type: ${request.widgetType}`);
   }