@envive-ai/react-hooks 0.3.45 → 0.3.47

package/src/services/enviveConfigService/enviveConfigService.ts

@@ -1,9 +1,21 @@
 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 { FeatureFlagService } from 'src/services/featureFlagService';
+import type { GraphQlConfigValues } from 'src/contexts/graphqlContext';
+import { configVersionOverride } from 'src/types/config-versions';
 import { fetchGraphQLConfig, fetchUnifiedGraphQLConfig } from './fetchGraphQLConfig';
 
+// Short-lived so config changes (gates, experiments) still propagate within
+// a session, while sparing every page navigation from re-fetching org
+// config + GraphQL config, both of which sit on the critical path before
+// first paint.
+const CONFIG_CACHE_TTL_MS = 5 * 60 * 1000;
+
+type CachedConfigEntry = {
+  value: EnviveServiceConfig;
+  expiresAt: number;
+};
+
 type EnviveConfigServiceProps = {
   baseUrl: string;
   apiKey: string;
@@ -63,10 +75,57 @@ export class EnviveConfigService implements IEnviveConfigService {
     this.source = source;
   }
 
+  private getCacheKey(): string {
+    return `envive-config-cache:${this.baseUrl}:${this.apiKey}:${this.userId}:${this.namespace}:${this.source}`;
+  }
+
+  // `envive_config_version` / `spiffy_config_version` pin a specific config
+  // version for debugging/rollback. Any use of that override must always
+  // bypass the cache below — both reading a stale entry and writing one
+  // under the shared key would defeat the override's purpose.
+  private readCachedConfig(): EnviveServiceConfig | null {
+    if (configVersionOverride()) {
+      return null;
+    }
+    try {
+      const raw = sessionStorage.getItem(this.getCacheKey());
+      if (!raw) {
+        return null;
+      }
+      const entry = JSON.parse(raw) as CachedConfigEntry;
+      if (Date.now() >= entry.expiresAt) {
+        return null;
+      }
+      return entry.value;
+    } catch {
+      return null;
+    }
+  }
+
+  private writeCachedConfig(value: EnviveServiceConfig): void {
+    if (configVersionOverride()) {
+      return;
+    }
+    try {
+      const entry: CachedConfigEntry = { value, expiresAt: Date.now() + CONFIG_CACHE_TTL_MS };
+      sessionStorage.setItem(this.getCacheKey(), JSON.stringify(entry));
+    } catch {
+      // Storage disabled, full, or unavailable (private browsing, etc.) -
+      // fail open and let the next call re-fetch instead of caching.
+    }
+  }
+
   async getEnviveConfig(): Promise<EnviveServiceConfig> {
     if (this.response !== null) {
       return this.response;
     }
+
+    const cached = this.readCachedConfig();
+    if (cached !== null) {
+      this.response = cached;
+      return this.response;
+    }
+
     const queryParams = new URLSearchParams({
       namespace: this.namespace,
       source: this.source,
@@ -106,6 +165,7 @@ export class EnviveConfigService implements IEnviveConfigService {
       : await fetchGraphQLConfig(this.baseUrl, this.apiKey);
 
     this.response = { ...orgConfigResponse, orgConfig };
+    this.writeCachedConfig(this.response);
     return this.response;
   }
 }

package/src/services/enviveConfigService/fetchGraphQLConfig.ts

@@ -7,13 +7,16 @@ import {
 } from 'src/application/models';
 import { FrontendConfigV3 } from 'src/application/models/frontendConfigV3';
 import { ColorMappingV3 } from 'src/application/models/colorsConfigV3';
-import { FloatingButtonLocation } from '@envive-ai/react-toolkit-v3/FloatingButton';
+// Type-only: a value import would pull the FloatingButton component (and
+// React) through the package's component index into the injection bundle's
+// pre-config chunk.
+import type { FloatingButtonLocation } from '@envive-ai/react-toolkit-v3/FloatingButton';
 import { getColorsAndFrontendQuery } from 'src/application/models/graphql/queries/getColorsAndFrontendQuery';
 import { getWidgetConfigQuery } from 'src/application/models/graphql/queries/getWidgetConfigQuery';
 import { mockV3ColorsConfig, mockV3FrontendConfig } from 'src/contexts/graphqlContext/mockV3Config';
 import { WidgetConfigV3 } from 'src/contexts/typesV3';
 import { PageVariantConfig, PageVariantTestType, WidgetMountingConfig } from 'src/contexts/types';
-import { GraphQlConfigValues } from 'src/contexts/graphqlContext';
+import type { GraphQlConfigValues } from 'src/contexts/graphqlContext';
 import { configVersionOverride } from 'src/types/config-versions';
 import { ExperimentConfigResolutionMetadata } from 'src/application/models/api/orgConfigResults';
 
@@ -39,11 +42,19 @@ export const DEFAULT_PAGE_VARIANTS: PageVariantConfig[] = [
   },
 ];
 
+// String-literal values of the FloatingButtonLocation enum; keep in sync
+// with @envive-ai/react-toolkit-v3/FloatingButton/types/types.ts.
+const FLOATING_BUTTON_POSITIONS = [
+  'bottom-left',
+  'middle-left',
+  'middle-right',
+  'bottom-right',
+] as const;
+
 const mapPositionToCamelCase = (position: string): FloatingButtonLocation => {
-  if (position === 'bottom-left') return FloatingButtonLocation.BOTTOM_LEFT;
-  if (position === 'middle-left') return FloatingButtonLocation.MIDDLE_LEFT;
-  if (position === 'middle-right') return FloatingButtonLocation.MIDDLE_RIGHT;
-  if (position === 'bottom-right') return FloatingButtonLocation.BOTTOM_RIGHT;
+  if ((FLOATING_BUTTON_POSITIONS as readonly string[]).includes(position)) {
+    return position as FloatingButtonLocation;
+  }
   throw new Error(`Invalid position: ${position}`);
 };
 

package/src/services/featureFlagService/index.ts

@@ -0,0 +1,176 @@
+import { OrgConfigFeatureGate } from 'src/application/models/api/orgConfigResults';
+import { FeatureGates } from 'src/application/models/featureGates';
+import Logger from 'src/application/logging/logger';
+
+const FEATURE_FLAGS_STORAGE_KEY = 'spiffy-feature-flags';
+
+const logger = new Logger('featureFlagService');
+
+export interface FullFlagValue {
+  resolved: boolean;
+  initial: boolean | undefined;
+  query_param_override: boolean | undefined;
+  window_param_override: boolean | undefined;
+  stored_override: boolean | undefined;
+}
+
+// Kept free of React imports: the injection bundle constructs this service
+// before deciding whether to load the React app, and pulling React into
+// that pre-config code path would put it on the eager critical chunk.
+export class FeatureFlagService {
+  private featureGates: OrgConfigFeatureGate[];
+
+  constructor(featureGates: OrgConfigFeatureGate[]) {
+    this.featureGates = featureGates;
+  }
+
+  static getQueryParamFeatureGateOverrides(featureGate: FeatureGates): boolean | undefined {
+    const url = window.location?.href ?? '';
+    if (url.includes('?')) {
+      const urlObj = new URL(url);
+      const params = new URLSearchParams(urlObj.search);
+      const paramsObj = Object.fromEntries(params.entries());
+      const value = paramsObj[featureGate];
+
+      if (value != null) {
+        return value === 'true';
+      }
+    }
+
+    return undefined;
+  }
+
+  static getWindowFeatureGateOverrides(featureGate: FeatureGates): boolean | undefined {
+    if (typeof window === 'undefined') {
+      return undefined;
+    }
+    const windowOverride = window as Window & {
+      _envive?: { featureOverrides?: Record<string, boolean> };
+      _spiffy?: { featureOverrides?: Record<string, boolean> };
+    };
+    const featureOverrides =
+      windowOverride?._envive?.featureOverrides ?? windowOverride?._spiffy?.featureOverrides;
+    const value = featureOverrides?.[String(featureGate)];
+    if (value != null) {
+      return value;
+    }
+    return undefined;
+  }
+
+  static getStoredFeatureGateOverrides(featureGate: FeatureGates): boolean | undefined {
+    if (typeof window === 'undefined' || typeof window.localStorage === 'undefined') {
+      return undefined;
+    }
+    try {
+      const featureFlags = window.localStorage.getItem(FEATURE_FLAGS_STORAGE_KEY);
+      if (!featureFlags) {
+        return undefined;
+      }
+      const featureFlagsObj = JSON.parse(featureFlags) as Record<string, boolean>;
+      return featureFlagsObj[featureGate];
+    } catch (err) {
+      logger.logError('getStoredFeatureGateOverrides: error parsing feature flags', err);
+      return undefined;
+    }
+  }
+
+  static getFeatureFlagOverride(featureGate: FeatureGates): boolean | undefined {
+    const queryOverride = FeatureFlagService.getQueryParamFeatureGateOverrides(featureGate);
+    if (queryOverride != null) {
+      logger.logDebug(
+        `isFeatureGateEnabled featureGate:${featureGate} overridden by URL param. New value: ${queryOverride}`,
+      );
+      return queryOverride;
+    }
+
+    const windowOverride = FeatureFlagService.getWindowFeatureGateOverrides(featureGate);
+    if (windowOverride != null) {
+      logger.logDebug(
+        `isFeatureGateEnabled featureGate:${featureGate} overridden by window param. New value: ${windowOverride}`,
+      );
+      return windowOverride;
+    }
+
+    const storedOverride = FeatureFlagService.getStoredFeatureGateOverrides(featureGate);
+    if (storedOverride != null) {
+      logger.logDebug(
+        `isFeatureGateEnabled featureGate:${featureGate} overridden by stored value. New value: ${storedOverride}`,
+      );
+      return storedOverride;
+    }
+
+    return undefined;
+  }
+
+  isFeatureGateEnabled = (featureGate: FeatureGates): boolean => {
+    const gateValue = this.featureGates.find(gate => gate.name === featureGate);
+
+    const featureFlagOverride = FeatureFlagService.getFeatureFlagOverride(featureGate);
+    if (featureFlagOverride !== undefined) {
+      return featureFlagOverride;
+    }
+
+    if (gateValue == null || gateValue.value == null) {
+      logger.logDebug(
+        `isFeatureGateEnabled featureGate:${featureGate} value is undefined - returning false`,
+      );
+      return false;
+    }
+    return gateValue.value;
+  };
+
+  // Ensure that standard overrides work as expected
+  isClientSessionEnabled = (): boolean =>
+    this.isFeatureGateEnabled(FeatureGates.IsClientSessionEnabled);
+
+  getFeatureFlags = (): Record<string, boolean> => {
+    return Object.fromEntries(
+      Object.values(FeatureGates).map((featureGate: FeatureGates) => [
+        featureGate,
+        this.isFeatureGateEnabled(featureGate),
+      ]),
+    );
+  };
+
+  getFullFlagValue = (featureGate: FeatureGates): FullFlagValue => {
+    const gateValue = this.featureGates.find(gate => gate.name === featureGate);
+    return {
+      resolved: this.isFeatureGateEnabled(featureGate),
+      initial: gateValue?.value,
+      query_param_override: FeatureFlagService.getQueryParamFeatureGateOverrides(featureGate),
+      window_param_override: FeatureFlagService.getWindowFeatureGateOverrides(featureGate),
+      stored_override: FeatureFlagService.getStoredFeatureGateOverrides(featureGate),
+    };
+  };
+
+  getFullFlagValues = (): Record<string, FullFlagValue> => {
+    const featureGates = Object.values(FeatureGates).map((featureGate: FeatureGates) => [
+      featureGate,
+      this.getFullFlagValue(featureGate),
+    ]);
+
+    return featureGates.length > 0
+      ? featureGates.reduce<Record<string, FullFlagValue>>((acc, entry) => {
+          const [name, value] = entry as [FeatureGates, FullFlagValue];
+          if (name && value != null) {
+            return { ...acc, [`feature_gate.${name}`]: value };
+          }
+          return acc;
+        }, {})
+      : {};
+  };
+
+  static persistFeatureGateOverrides(): void {
+    if (typeof window === 'undefined' || typeof window.localStorage === 'undefined') {
+      return;
+    }
+    const overrides = Object.values(FeatureGates)
+      .map(
+        featureGate =>
+          [featureGate, FeatureFlagService.getFeatureFlagOverride(featureGate)] as const,
+      )
+      .filter(([, value]) => value !== undefined)
+      .reduce<Record<string, boolean>>((acc, [key, value]) => ({ ...acc, [key]: value! }), {});
+    window.localStorage.setItem(FEATURE_FLAGS_STORAGE_KEY, JSON.stringify(overrides));
+  }
+}

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

@@ -229,6 +229,42 @@ describe('projectToGA4', () => {
       expect(window.dataLayer[0]).toHaveProperty('interaction_suggestion_id', 'sug-456');
     });
 
+    it('should extract product_id and option_name but not option_value for variant_option_selected', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetInteraction, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'floating_chat',
+        'trigger.widget_interaction': 'variant_option_selected',
+        'trigger.widget_interaction_data': {
+          variant_option_selected: {
+            product_id: 'sku-789',
+            option_name: 'Color',
+            option_value: 'Grey',
+          },
+        },
+      });
+
+      const pushed = window.dataLayer[0];
+      expect(pushed).toHaveProperty('interaction_product_id', 'sku-789');
+      expect(pushed).toHaveProperty('interaction_option_name', 'Color');
+      expect(pushed).not.toHaveProperty('interaction_option_value');
+      expect(pushed).not.toHaveProperty('option_value');
+    });
+
+    it('should extract interaction_product_id for variant selector open/dismiss', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetInteraction, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'floating_chat',
+        'trigger.widget_interaction': 'variant_selector_dismissed',
+        'trigger.widget_interaction_data': {
+          variant_selector_dismissed: { product_id: 'sku-789' },
+        },
+      });
+
+      expect(window.dataLayer[0]).toHaveProperty('interaction_product_id', 'sku-789');
+    });
+
     it('should drop widget_interaction_data for unwhitelisted interactions', () => {
       projectToGA4(EnviveMetricsEventName.WidgetInteraction, {
         'context.page_type': 'pdp',

package/src/services/ga4ProjectionService/ga4EventSchema.ts

@@ -52,6 +52,13 @@ const WIDGET_INTERACTION_DATA_PROJECTIONS: WidgetInteractionDataProjection = {
   widget_collapsed: { interaction_collapse_source: 'widget_collapsed.collapse_source' },
   product_card_clicked: { interaction_product_id: 'product_card_clicked.product_id' },
   suggestion_scrolled: { interaction_suggestion_id: 'suggestion_scrolled.suggestion_id' },
+  variant_selector_opened: { interaction_product_id: 'variant_selector_opened.product_id' },
+  // option_value is intentionally excluded — merchant-defined values are high cardinality
+  variant_option_selected: {
+    interaction_product_id: 'variant_option_selected.product_id',
+    interaction_option_name: 'variant_option_selected.option_name',
+  },
+  variant_selector_dismissed: { interaction_product_id: 'variant_selector_dismissed.product_id' },
 };
 
 export const GA4_EVENT_SCHEMA: Record<EnviveMetricsEventName, GA4EventSchemaEntry> = {

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

@@ -1,7 +1,7 @@
 import { WidgetTypeV3 } from 'src/contexts/typesV3';
 import type { WidgetText } from 'src/application/models/api/widgetText';
 import type { AppDetails } from 'src/atoms/app';
-import { EnviveMetricsEventName } from 'src/services/amplitudeService';
+import { EnviveMetricsEventName, TrackEventParams } from 'src/services/amplitudeService';
 import { getAtomStore } from 'src/atoms/atomStore/atomStore';
 import { resolvedBaseConfigVersionAtom } from 'src/atoms/envive/resolvedBaseConfigVersion';
 import { HardcopyService, MOCK_HARDCOPY_RESPONSE, MockHardcopyService } from '../hardcopyService';
@@ -269,6 +269,52 @@ describe('HardcopyService', () => {
       );
     });
 
+    it('forwards ai_suggestions_attribution_by_slot on WidgetTextResponse when present', async () => {
+      const trackEvent = vi.fn();
+      const attribution = {
+        prompt_button_texts: {
+          served_method_id: 'variant_b',
+          served_method_type: 'bandit_pbm',
+        },
+      };
+      mockGetHardcopy.mockResolvedValueOnce(
+        makeWidgetTextResponse({ aiSuggestionsAttributionBySlot: attribution }),
+      );
+
+      await makeService(trackEvent).getHardcopy({
+        widgetType: WidgetTypeV3.ChatPreviewV3,
+        userEvent: {} as any,
+      });
+
+      expect(trackEvent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          eventName: EnviveMetricsEventName.WidgetTextResponse,
+          eventProps: expect.objectContaining({
+            ai_suggestions_attribution_by_slot: attribution,
+          }),
+        }),
+      );
+    });
+
+    it('omits ai_suggestions_attribution_by_slot when the response carries none', async () => {
+      const trackEvent = vi.fn();
+      mockGetHardcopy.mockResolvedValueOnce(makeWidgetTextResponse());
+
+      await makeService(trackEvent).getHardcopy({
+        widgetType: WidgetTypeV3.ChatPreviewV3,
+        userEvent: {} as any,
+      });
+
+      const responseEvent = trackEvent.mock.calls
+        .map(([params]: [TrackEventParams]) => params)
+        .find(
+          (params: TrackEventParams) =>
+            params.eventName === EnviveMetricsEventName.WidgetTextResponse,
+        );
+      expect(responseEvent).toBeDefined();
+      expect(responseEvent!.eventProps).not.toHaveProperty('ai_suggestions_attribution_by_slot');
+    });
+
     it('does not crash when trackEvent is not provided', async () => {
       const service = new HardcopyService({
         getAppDetails: () => mockAppDetails,

package/src/services/hardcopyService/hardcopyService.ts

@@ -237,6 +237,11 @@ export class HardcopyService implements IHardcopyService {
             response_id: response.responseId,
             widget_text: response.values,
             request_id: widgetTextRequest.requestId,
+            // Which method served each overridden slot — training/attribution
+            // reads this from the analytics event; passed through verbatim.
+            ...(response.aiSuggestionsAttributionBySlot
+              ? { ai_suggestions_attribution_by_slot: response.aiSuggestionsAttributionBySlot }
+              : {}),
           },
         });
         return convertedResponse;

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

@@ -0,0 +1,85 @@
+import { createStore } from 'jotai';
+import { getAtomStore, setAtomStoreForTesting } from 'src/atoms/atomStore/atomStore';
+import { contextSourceAtom, envAtom, enviveConfigAtom } from 'src/atoms/envive/enviveConfig';
+import { featureFlagServiceAtom } from 'src/atoms/org/graphqlConfig';
+import { FeatureFlagService } from 'src/services/featureFlagService';
+import type { EnviveServiceConfig } from 'src/services/enviveConfigService';
+import { warmUrlResolver } from '../index';
+
+const { mockResolveUrl } = vi.hoisted(() => ({ mockResolveUrl: vi.fn() }));
+
+vi.mock('src/application/commerce-api', () => ({
+  default: { resolveUrl: mockResolveUrl },
+}));
+
+const enviveServiceConfig = {
+  org: { org: { short_name: 'test-org', id: 'org-1' } },
+} as EnviveServiceConfig;
+
+const baseParams = {
+  baseUrl: 'https://commerce-api.spiffy.ai',
+  apiKey: 'test-key',
+  enviveServiceConfig,
+  show: true,
+  enviveOn: false,
+};
+
+describe('warmUrlResolver', () => {
+  beforeEach(() => {
+    setAtomStoreForTesting(createStore());
+    window.sessionStorage.clear();
+    vi.clearAllMocks();
+    mockResolveUrl.mockResolvedValue({ ready: true });
+  });
+
+  it('seeds env, contextSource, and the feature flag service before resolving', async () => {
+    const featureFlagService = new FeatureFlagService([]);
+
+    let envAtCallTime: string | undefined;
+    let contextSourceAtCallTime: string | undefined;
+    let flagServiceAtCallTime: FeatureFlagService | undefined;
+    mockResolveUrl.mockImplementation(async () => {
+      const store = getAtomStore();
+      envAtCallTime = store.get(envAtom);
+      contextSourceAtCallTime = store.get(contextSourceAtom);
+      flagServiceAtCallTime = store.get(featureFlagServiceAtom)?.featureFlagService;
+      return { ready: true };
+    });
+
+    await warmUrlResolver({
+      ...baseParams,
+      env: 'prod',
+      contextSource: 'app',
+      featureFlagService,
+    });
+
+    expect(mockResolveUrl).toHaveBeenCalledTimes(1);
+    expect(envAtCallTime).toBe('prod');
+    expect(contextSourceAtCallTime).toBe('app');
+    expect(flagServiceAtCallTime).toBe(featureFlagService);
+  });
+
+  it('does not overwrite atoms a provider has already seeded', async () => {
+    const store = getAtomStore();
+    const existingFlagService = new FeatureFlagService([]);
+    store.set(enviveConfigAtom, { identifyingPrefix: 'test', env: 'dev' });
+    store.set(featureFlagServiceAtom, { featureFlagService: existingFlagService });
+
+    await warmUrlResolver({
+      ...baseParams,
+      env: 'prod',
+      contextSource: 'playground',
+      featureFlagService: new FeatureFlagService([]),
+    });
+
+    expect(store.get(envAtom)).toBe('dev');
+    expect(store.get(featureFlagServiceAtom)?.featureFlagService).toBe(existingFlagService);
+  });
+
+  it('leaves the feature flag service atom unset when none is provided', async () => {
+    await warmUrlResolver(baseParams);
+
+    expect(getAtomStore().get(featureFlagServiceAtom)).toBeUndefined();
+    expect(mockResolveUrl).toHaveBeenCalledTimes(1);
+  });
+});

package/src/services/urlResolverWarmupService/index.ts

@@ -0,0 +1,89 @@
+import CommerceApiClient from 'src/application/commerce-api';
+import Logger from 'src/application/logging/logger';
+import { UrlResolverResponse, urlResolverAtom } from 'src/atoms/app/variant';
+import { getAtomStore } from 'src/atoms/atomStore/atomStore';
+import { enviveConfigAtom } from 'src/atoms/envive/enviveConfig';
+import { resolvedBaseConfigVersionAtom } from 'src/atoms/envive/resolvedBaseConfigVersion';
+import { featureFlagServiceAtom } from 'src/atoms/org/graphqlConfig';
+import { EnviveServiceConfig } from 'src/services/enviveConfigService';
+import type { FeatureFlagService } from 'src/services/featureFlagService';
+
+const logger = new Logger('urlResolverWarmupService');
+
+export interface WarmUrlResolverParams {
+  baseUrl: string;
+  apiKey: string;
+  enviveServiceConfig: EnviveServiceConfig;
+  show?: boolean;
+  enviveOn?: boolean;
+  env?: string;
+  contextSource?: string;
+  featureFlagService?: FeatureFlagService;
+}
+
+/**
+ * Fires the /v1/url_resolving request as soon as the org config is available,
+ * instead of waiting for the React tree to mount and PageProvider's effect to
+ * run — that removes a full network round trip from the first-widget-paint
+ * critical path.
+ *
+ * Seeds the same atoms EnviveProvider/EnviveConfigProvider populate later
+ * (with identical values) so the request context matches the one
+ * PageProvider would send, then stores the response in the
+ * sessionStorage-backed urlResolverAtom that PageProvider consults before
+ * fetching. Concurrent calls for the same URL are deduped inside
+ * CommerceApiClient.resolveUrl.
+ */
+export const warmUrlResolver = async ({
+  baseUrl,
+  apiKey,
+  enviveServiceConfig,
+  show,
+  enviveOn,
+  env,
+  contextSource,
+  featureFlagService,
+}: WarmUrlResolverParams): Promise<void> => {
+  try {
+    const store = getAtomStore();
+    // Must match PageProvider's URL cleansing so the cache key lines up.
+    const cleansedUrl = window.location.href.toLowerCase().trim();
+    if (store.get(urlResolverAtom)[cleansedUrl]) {
+      return;
+    }
+
+    // The CommerceApiClient singleton captures baseUrl/apiKey at first
+    // instantiation, so these atoms must be seeded before any API call.
+    // Only seed when unset — providers own this atom once React mounts.
+    if (store.get(enviveConfigAtom) === undefined) {
+      store.set(enviveConfigAtom, {
+        baseUrl,
+        orgLevelApiKey: apiKey,
+        orgShortName: enviveServiceConfig.org.org.short_name,
+        orgId: enviveServiceConfig.org.org.id,
+        show,
+        enviveOn,
+        env,
+        contextSource,
+      });
+    }
+    // resolveUrl reads feature gates through featureFlagServiceAtom; without
+    // this seed the warm-up request is computed with feature_gates={} and
+    // that response is what gets cached for PageProvider.
+    if (featureFlagService && store.get(featureFlagServiceAtom) === undefined) {
+      store.set(featureFlagServiceAtom, { featureFlagService });
+    }
+    // Mirrors EnviveProvider: "deployed" is the no-pin sentinel.
+    const { baseVersion, baseVersionSource } = enviveServiceConfig.orgConfig?.resolution ?? {};
+    if (baseVersion && baseVersionSource && baseVersionSource !== 'deployed') {
+      store.set(resolvedBaseConfigVersionAtom, baseVersion);
+    }
+
+    const response = (await CommerceApiClient.resolveUrl(cleansedUrl)) as UrlResolverResponse;
+    store.set(urlResolverAtom, { url: cleansedUrl, response });
+  } catch (err) {
+    // Fail open: PageProvider issues its own resolveUrl call when the cache
+    // is empty, so a warm-up failure never blocks rendering.
+    logger.logDebug('URL resolver warm-up failed', err);
+  }
+};

package/src/types/enviveConfig.ts

@@ -2,8 +2,11 @@ import { FrontendConfigOverrides, VariantInfo } from 'src/application/models';
 import type { HardcopyResponse } from 'src/contexts/hardcopyContext/hardcopyContext';
 import type { WidgetTypeV3 } from 'src/contexts/typesV3';
 
+export type AddToCartCallback = (params: { product_id: string }) => void | Promise<void>;
+
 export interface EnviveConfig {
   publicKey?: string;
+  addToCart?: AddToCartCallback;
   userID?: string;
   env?: 'prod' | 'dev';
   clientID?: string;