@envive-ai/react-hooks 0.3.38 → 0.3.40

package/src/application/utils/index.ts

@@ -6,7 +6,6 @@ export * from './divideArray';
 export * from './domObserver';
 export * from './elementObserver';
 export * from './imageFilter';
-export * from './merchantUtils';
 export * from './messageFromFormSubmittedEvent';
 export * from './messageFromQueryEvent';
 export * from './messageFromResponse';

package/src/atoms/envive/resolvedBaseConfigVersion.ts

@@ -0,0 +1,11 @@
+import { atom } from 'jotai';
+
+// The `base_version` pymono resolved for the current user on the unified
+// path (sourced from getWidgetConfig.resolution, not REST). Read by
+// commerce-api, salesAgentService, and hardcopyService as a fallback after
+// the `spiffy_config_version` / `envive_config_version` URL params, so
+// inference requests are scoped to the same version that produced the
+// widgets the user is rendering. Undefined until the unified-path fetch
+// completes, on the legacy path, and when the resolution sentinel
+// `base_version_source === "deployed"` indicates no real pin to forward.
+export const resolvedBaseConfigVersionAtom = atom<string | undefined>(undefined);

package/src/contexts/enviveContext/enviveContext.tsx

@@ -1,7 +1,9 @@
 import { ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useSetAtom } from 'jotai';
 
 import { AmplitudeService } from 'src/services/amplitudeService/amplitudeService';
 import { EnviveServiceConfig, IEnviveConfigService } from 'src/services/enviveConfigService';
+import { resolvedBaseConfigVersionAtom } from 'src/atoms/envive/resolvedBaseConfigVersion';
 import { IHardcopyService } from 'src/services/hardcopyService';
 import { IUserIdentityService } from 'src/services/userIdentityService';
 import Logger from 'src/application/logging/logger';
@@ -102,6 +104,7 @@ export const EnviveProvider: React.FC<EnviveProviderProps> = ({
 }) => {
   const { extensionService } = services;
   const [enviveServiceConfig, setEnviveServiceConfig] = useState<EnviveServiceConfig | null>(null);
+  const setResolvedBaseConfigVersion = useSetAtom(resolvedBaseConfigVersionAtom);
   const didReportSuccessRef = useRef(false);
 
   const invokeExtensionCallback = useCallback((callback?: () => Promise<unknown> | void) => {
@@ -128,10 +131,26 @@ export const EnviveProvider: React.FC<EnviveProviderProps> = ({
   useEffect(() => {
     invokeExtensionCallback(extensionService?.onInjectionLoading);
 
+    // Clear any prior merchant's resolved version before the new fetch — the
+    // atom is module-level and survives EnviveProvider remounts (e.g. when
+    // Envive Hub switches merchants). Without the reset, the previous
+    // merchant's `baseVersion` would leak into the new merchant's inference
+    // requests when the new resolution falls back to the "deployed" sentinel
+    // and the conditional write below is skipped.
+    setResolvedBaseConfigVersion(undefined);
+
     const fetchEnviveConfig = async () => {
       try {
         const config = await services.enviveConfigService.getEnviveConfig();
         setEnviveServiceConfig(config);
+        // Forward only real pins to inference. baseVersionSource === "deployed"
+        // is the sentinel for "no merchant_layer, no override" — leaving the
+        // atom undefined lets inference fall through to backend's default
+        // version selection instead of pinning to the literal string "deployed".
+        const { baseVersion, baseVersionSource } = config.orgConfig?.resolution ?? {};
+        if (baseVersion && baseVersionSource && baseVersionSource !== 'deployed') {
+          setResolvedBaseConfigVersion(baseVersion);
+        }
       } catch (error) {
         const resolvedError =
           error instanceof Error ? error : new Error('Failed to load envive config');
@@ -146,6 +165,7 @@ export const EnviveProvider: React.FC<EnviveProviderProps> = ({
     extensionService,
     invokeExtensionCallback,
     invokeExtensionErrorCallback,
+    setResolvedBaseConfigVersion,
   ]);
 
   useEffect(() => {

package/src/contexts/graphqlContext/graphqlContext.tsx

@@ -4,6 +4,7 @@ import { baseUrlAtom, orgLevelApiKeyAtom } from 'src/atoms/envive/enviveConfig';
 import { ColorMapping } from 'src/application/models/colorsConfig';
 import { FrontendConfig } from 'src/application/models/frontendConfig';
 import { CamelCasedPropertiesDeep } from 'src/application/models';
+import { ExperimentConfigResolutionMetadata } from 'src/application/models/api/orgConfigResults';
 import { FrontendConfigV3 } from 'src/application/models/frontendConfigV3';
 import { ColorMappingV3 } from 'src/application/models/colorsConfigV3';
 import { OrgPageConfig } from '../types';
@@ -17,6 +18,10 @@ export type GraphQlConfigValues = {
   colorsConfig?: ColorsConfigResponse | ColorsConfigV3Response;
   frontendConfig?: CamelCasedPropertiesDeep<FrontendConfig | FrontendConfigV3>;
   orgPageConfig?: OrgPageConfig;
+  // Populated only by the unified-path fetcher (getWidgetConfig.resolution).
+  // Legacy getColorsAndFrontendQuery does not return it. Read by EnviveProvider
+  // to thread baseVersion into inference requests as override_config_version.
+  resolution?: ExperimentConfigResolutionMetadata;
 };
 
 interface GraphQLContextValue {

package/src/contexts/salesAgentContext/salesAgentService.ts

@@ -15,6 +15,7 @@ import {
 import { messageFromResponse } from 'src/application/utils';
 import { appDetailsAtom } from 'src/atoms/app';
 import { analyticsContextAtom } from 'src/atoms/app/variant';
+import { resolvedBaseConfigVersionAtom } from 'src/atoms/envive/resolvedBaseConfigVersion';
 import {
   messagesAtom,
   pendingResponseAtom,
@@ -247,6 +248,7 @@ export const useSalesAgentService: () => SalesAgentService = () => {
 
   const featureFlagService = useFeatureFlagService();
   const context = useAtomValue(appDetailsAtom);
+  const resolvedBaseConfigVersion = useAtomValue(resolvedBaseConfigVersionAtom);
 
   const createResponsePayload = useCallback(
     ({
@@ -261,6 +263,7 @@ export const useSalesAgentService: () => SalesAgentService = () => {
       const overrideConfigVersion =
         getQueryParam('spiffy_config_version') ||
         getQueryParam('envive_config_version') ||
+        resolvedBaseConfigVersion ||
         undefined;
       const overrideModelDatetime = getQueryParam('override_model_datetime') || undefined;
       return {
@@ -273,7 +276,7 @@ export const useSalesAgentService: () => SalesAgentService = () => {
         overrideModelDatetime,
       };
     },
-    [context, featureFlagService?.featureFlagService],
+    [context, featureFlagService?.featureFlagService, resolvedBaseConfigVersion],
   );
 
   const getStreamingResponses = useCallback(

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

@@ -698,4 +698,99 @@ describe('AmplitudeService', () => {
       });
     });
   });
+
+  describe('Experiment-assignment props', () => {
+    it('emits experiment.{ns}.* keys as null when no assignments are configured', async () => {
+      const service = createService();
+      await service.trackEvent({
+        eventName: SpiffyMetricsEventName.ChatUserMessageInput,
+        eventProps: {},
+      });
+      const props = mockTrack.mock.calls[0]?.[1] ?? {};
+      expect(props['experiment.ml.layer_name']).toBeNull();
+      expect(props['experiment.ml.experiment_name']).toBeNull();
+      expect(props['experiment.ml.group_name']).toBeNull();
+      expect(props['experiment.ml.rule_id']).toBeNull();
+      expect(props['experiment.merchant.layer_name']).toBeNull();
+      expect(props['experiment.merchant.experiment_name']).toBeNull();
+      expect(props['experiment.merchant.group_name']).toBeNull();
+      expect(props['experiment.merchant.rule_id']).toBeNull();
+    });
+
+    it('populates experiment.{ns}.* keys when assignments are passed at construction', async () => {
+      const service = createService({
+        experimentAssignments: [
+          {
+            layer_name: 'ml_test_store',
+            namespace: 'ml',
+            allocated_experiment_name: 'automated_testing_ml_experiment',
+            group_name: 'ML Config Variation',
+          },
+          {
+            layer_name: 'merchant_test_store',
+            namespace: 'merchant',
+            allocated_experiment_name: 'automated_testing_merchant_experiment',
+            group_name: 'Merchant Config Variation',
+          },
+        ],
+      });
+      await service.trackEvent({
+        eventName: SpiffyMetricsEventName.ChatUserMessageInput,
+        eventProps: {},
+      });
+      const props = mockTrack.mock.calls[0]?.[1] ?? {};
+      expect(props['experiment.ml.layer_name']).toBe('ml_test_store');
+      expect(props['experiment.ml.experiment_name']).toBe('automated_testing_ml_experiment');
+      expect(props['experiment.ml.group_name']).toBe('ML Config Variation');
+      expect(props['experiment.merchant.layer_name']).toBe('merchant_test_store');
+      expect(props['experiment.merchant.experiment_name']).toBe(
+        'automated_testing_merchant_experiment',
+      );
+      expect(props['experiment.merchant.group_name']).toBe('Merchant Config Variation');
+      // rule_id reserved — backend doesn't surface it.
+      expect(props['experiment.ml.rule_id']).toBeNull();
+      expect(props['experiment.merchant.rule_id']).toBeNull();
+    });
+
+    it('emits the unassigned namespace as null when only one is assigned', async () => {
+      const service = createService({
+        experimentAssignments: [
+          {
+            layer_name: 'ml_test_store',
+            namespace: 'ml',
+            allocated_experiment_name: 'ml_only',
+            group_name: 'ML Only',
+          },
+        ],
+      });
+      await service.trackEvent({
+        eventName: SpiffyMetricsEventName.ChatUserMessageInput,
+        eventProps: {},
+      });
+      const props = mockTrack.mock.calls[0]?.[1] ?? {};
+      expect(props['experiment.ml.layer_name']).toBe('ml_test_store');
+      expect(props['experiment.merchant.layer_name']).toBeNull();
+    });
+
+    it('drops malformed assignments missing layer_name or namespace', async () => {
+      const service = createService({
+        experimentAssignments: [
+          // Missing layer_name → dropped silently. (Belt-and-braces: pymono's
+          // tests enforce the wire shape, but if a field ever goes null we'd
+          // rather emit `null` props than crash.)
+          {
+            namespace: 'ml',
+            allocated_experiment_name: 'orphan',
+          },
+        ],
+      });
+      await service.trackEvent({
+        eventName: SpiffyMetricsEventName.ChatUserMessageInput,
+        eventProps: {},
+      });
+      const props = mockTrack.mock.calls[0]?.[1] ?? {};
+      expect(props['experiment.ml.layer_name']).toBeNull();
+      expect(props['experiment.ml.experiment_name']).toBeNull();
+    });
+  });
 });

package/src/services/amplitudeService/amplitudeService.ts

@@ -11,6 +11,7 @@ import type {
 import { FeatureFlagService } from 'src/contexts/featureFlagServiceContext/featureFlagServiceContext';
 import { WidgetTypeV3 } from 'src/contexts/typesV3';
 import { ChatElementDisplayLocationV3 } from 'src/application/models/chatElementDisplayLocationV3';
+import { ExperimentNamespace, OrgConfigExperimentAssignment } from 'src/application/models';
 import { projectToGA4 } from '../ga4ProjectionService/ga4ProjectionService';
 import { EnviveMetricsEventName, SpiffyMetricsEventName } from './eventNames';
 
@@ -39,8 +40,37 @@ export interface AmplitudeServiceConfig {
   enviveOn: boolean;
   enabledFeatures?: Record<string, boolean>;
   getLocalStorageItem: null | ((key: string) => string | null);
+  // Captured at construction. Drives `experiment.{ns}.*` event-property
+  // enrichment. Sourced from /v1/org/config when the `use_unified_config`
+  // gate is on; otherwise omitted (props emit as null).
+  experimentAssignments?: OrgConfigExperimentAssignment[];
 }
 
+// Namespaces emitted on every event with constant keys, so the BigQuery
+// schema is stable regardless of which (if any) experiment is running.
+// Currently `ml` + `merchant`; matches `ExperimentNamespace`.
+const EXPERIMENT_NAMESPACES: ExperimentNamespace[] = ['ml', 'merchant'];
+
+const buildExperimentProps = (
+  assignments: OrgConfigExperimentAssignment[] | undefined,
+): Record<string, unknown> => {
+  const byNamespace = new Map<ExperimentNamespace, OrgConfigExperimentAssignment>();
+  (assignments ?? []).forEach(a => {
+    if (a.layer_name != null && a.namespace != null) {
+      byNamespace.set(a.namespace, a);
+    }
+  });
+  return EXPERIMENT_NAMESPACES.reduce<Record<string, unknown>>((acc, ns) => {
+    const a = byNamespace.get(ns);
+    acc[`experiment.${ns}.layer_name`] = a?.layer_name ?? null;
+    acc[`experiment.${ns}.experiment_name`] = a?.allocated_experiment_name ?? null;
+    acc[`experiment.${ns}.group_name`] = a?.group_name ?? null;
+    // `rule_id` reserved — backend doesn't currently surface it.
+    acc[`experiment.${ns}.rule_id`] = null;
+    return acc;
+  }, {});
+};
+
 export class AmplitudeService {
   private amplitudeClient: BrowserClient | undefined;
 
@@ -91,7 +121,7 @@ export class AmplitudeService {
             return acc;
           }, {})
         : {};
-    const experimentProps = {}; // No direct equivalent for experiments in EnviveConfig yet
+    const experimentProps = buildExperimentProps(this.config.experimentAssignments);
 
     const environmentProps = {
       'environment.execution_context': 'bundle',

package/src/services/enviveConfigService/__tests__/fetchGraphQLConfig.test.ts

@@ -1,6 +1,10 @@
-import { fetchGraphQLConfig, DEFAULT_PAGE_VARIANTS } from '../fetchGraphQLConfig';
 import { mockV3ColorsConfig, mockV3FrontendConfig } from 'src/contexts/graphqlContext/mockV3Config';
 import { FloatingButtonLocation } from '@envive-ai/react-toolkit-v3/FloatingButton';
+import {
+  DEFAULT_PAGE_VARIANTS,
+  fetchGraphQLConfig,
+  fetchUnifiedGraphQLConfig,
+} from '../fetchGraphQLConfig';
 
 const { MockLogger } = vi.hoisted(() => {
   const MockLogger = vi.fn(function () {
@@ -423,3 +427,105 @@ describe('fetchGraphQLConfig', () => {
     });
   });
 });
+
+describe('fetchUnifiedGraphQLConfig', () => {
+  function makeUnifiedOkFetch(v3RootConfigValues: unknown, resolution?: unknown) {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          data: {
+            me: {
+              getWidgetConfig: {
+                productsConfig: {
+                  v_three_config: { values: v3RootConfigValues },
+                },
+                resolution,
+              },
+            },
+          },
+        }),
+    });
+  }
+
+  it('issues a getWidgetConfig query (not getProductsConfigByVersion) and forwards userId', async () => {
+    makeUnifiedOkFetch(null);
+
+    await fetchUnifiedGraphQLConfig('https://api.example.com', 'key', 'user_1');
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.query).toContain('getWidgetConfig');
+    expect(body.query).not.toContain('getProductsConfigByVersion');
+    // userId is required by the schema; omitting it 400s. Regression guard.
+    // version is absent without a URL-param override so the resolver uses
+    // Statsig bucketing (passing 'deployed' here would bypass Statsig).
+    expect(body.variables).toEqual({ userId: 'user_1' });
+  });
+
+  it('threads a spiffy_config_version URL param through as the version variable', async () => {
+    window.history.replaceState({}, '', '/?spiffy_config_version=1.2.3');
+    try {
+      makeUnifiedOkFetch(null);
+
+      await fetchUnifiedGraphQLConfig('https://api.example.com', 'key', 'user_1');
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.variables).toEqual({ userId: 'user_1', version: '1.2.3' });
+    } finally {
+      window.history.replaceState({}, '', '/');
+    }
+  });
+
+  it('parses productsConfig into the same shape as fetchGraphQLConfig', async () => {
+    makeUnifiedOkFetch(baseV3Config);
+
+    const result = await fetchUnifiedGraphQLConfig('https://api.example.com', 'key', 'user_1');
+
+    expect(result.colorsConfig).toBeDefined();
+    expect(result.frontendConfig).toBeDefined();
+    expect(result.orgPageConfig).toBeDefined();
+  });
+
+  it('returns resolution metadata alongside the config so callers can thread baseVersion into inference', async () => {
+    makeUnifiedOkFetch(baseV3Config, {
+      baseVersion: '1.0.670',
+      baseVersionSource: 'merchant_layer',
+    });
+
+    const result = await fetchUnifiedGraphQLConfig('https://api.example.com', 'key', 'user_1');
+
+    expect(result.resolution).toEqual({
+      baseVersion: '1.0.670',
+      baseVersionSource: 'merchant_layer',
+    });
+  });
+
+  it('selects resolution fields in the query so the server can fill them', async () => {
+    makeUnifiedOkFetch(null);
+
+    await fetchUnifiedGraphQLConfig('https://api.example.com', 'key', 'user_1');
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.query).toContain('resolution');
+    expect(body.query).toContain('baseVersion');
+    expect(body.query).toContain('baseVersionSource');
+  });
+
+  it('falls back to DEFAULT_PAGE_VARIANTS when productsConfig has no page_variants array', async () => {
+    // Reuses the no-colors fallback path: when productsConfig is missing
+    // colors, DEFAULT_PAGE_VARIANTS is returned as the orgPageConfig.
+    makeUnifiedOkFetch(null);
+
+    const result = await fetchUnifiedGraphQLConfig('https://api.example.com', 'key', 'user_1');
+
+    expect(result.orgPageConfig?.pageVariants).toEqual(DEFAULT_PAGE_VARIANTS);
+  });
+
+  it('returns empty config on network failure', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('boom'));
+
+    const result = await fetchUnifiedGraphQLConfig('https://api.example.com', 'key', 'user_1');
+
+    expect(result).toEqual({ colorsConfig: undefined, frontendConfig: undefined });
+  });
+});

package/src/services/enviveConfigService/enviveConfigService.ts

@@ -1,7 +1,8 @@
-import { OrgConfigFeatureGate } from 'src/application/models';
+import { OrgConfigExperimentAssignment, OrgConfigFeatureGate } from 'src/application/models';
 import { FeatureGates } from 'src/application/models/featureGates';
+import { FeatureFlagService } from 'src/contexts/featureFlagServiceContext';
 import { GraphQlConfigValues } from 'src/contexts/graphqlContext';
-import { fetchGraphQLConfig } from './fetchGraphQLConfig';
+import { fetchGraphQLConfig, fetchUnifiedGraphQLConfig } from './fetchGraphQLConfig';
 
 type EnviveConfigServiceProps = {
   baseUrl: string;
@@ -24,6 +25,14 @@ export type EnviveServiceConfig = {
     };
   };
   gates: OrgConfigFeatureGate[];
+  // Populated by the backend when the `use_unified_config` Statsig gate
+  // evaluates true. amplitudeService reads these to enrich events with
+  // `experiment.{ns}.*` properties.
+  experiment_assignments?: OrgConfigExperimentAssignment[];
+  // orgConfig.resolution is populated only on the unified path (sourced from
+  // getWidgetConfig.resolution, not /v1/org/config.resolution) so the version
+  // threaded into inference requests matches the version that produced the
+  // rendered widgets.
   orgConfig?: GraphQlConfigValues;
 };
 
@@ -67,16 +76,35 @@ export class EnviveConfigService implements IEnviveConfigService {
         .map(featureGate => featureGate.toString())
         .join(','),
     });
-    const [orgConfigResponse, orgConfig] = await Promise.all([
-      fetch(`${this.baseUrl}/v1/org/config?${queryParams.toString()}`, {
+    // Serialized so we can branch the GraphQL call on the `use_unified_config`
+    // gate returned by /v1/org/config. Once the migration to getWidgetConfig
+    // completes (one endpoint returning gates + experiments + productsConfig),
+    // this collapses back to a single call.
+    const orgConfigResponse = await fetch(
+      `${this.baseUrl}/v1/org/config?${queryParams.toString()}`,
+      {
         method: 'GET',
         headers: {
           'Content-Type': 'application/json',
           Authorization: `Bearer ${this.apiKey}`,
         },
-      }).then(r => r.json() as Promise<EnviveServiceConfig>),
-      fetchGraphQLConfig(this.baseUrl, this.apiKey),
-    ]);
+      },
+    ).then(async r => {
+      if (!r.ok) {
+        throw new Error(`Org config request failed with status ${r.status}`);
+      }
+      return r.json() as Promise<EnviveServiceConfig>;
+    });
+
+    // Honor URL / `window._spiffy` / localStorage overrides for
+    // `use_unified_config` the same way every other feature gate is read.
+    const useUnifiedConfig = new FeatureFlagService(
+      orgConfigResponse.gates ?? [],
+    ).isFeatureGateEnabled(FeatureGates.UseUnifiedConfig);
+    const orgConfig = useUnifiedConfig
+      ? await fetchUnifiedGraphQLConfig(this.baseUrl, this.apiKey, this.userId)
+      : await fetchGraphQLConfig(this.baseUrl, this.apiKey);
+
     this.response = { ...orgConfigResponse, orgConfig };
     return this.response;
   }