@envive-ai/react-hooks 0.3.63 → 0.3.65

package/src/services/enviveConfigService/enviveConfigService.ts

@@ -3,15 +3,11 @@ import { FeatureGates } from 'src/application/models/featureGates';
 import type { GraphQlConfigValues } from 'src/contexts/graphqlContext';
 import { configVersionOverride } from 'src/types/config-versions';
 import { FeatureFlagService } from 'src/services/featureFlagService';
-import Logger from 'src/application/logging/logger';
 import type { UrlResolverResponse } from 'src/atoms/app/variant';
 import { getAtomStore } from 'src/atoms/atomStore/atomStore';
 import { chatIdAtom } from 'src/atoms/app';
-import { fetchUnifiedGraphQLConfig } from './fetchGraphQLConfig';
 import { fetchBootstrapConfig } from './fetchBootstrapConfig';
 
-const logger = new Logger('enviveConfigService');
-
 // 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
@@ -30,9 +26,9 @@ type EnviveConfigServiceProps = {
   namespace: string;
   source: string;
   // The url_resolving context bits the hooks layer can't derive itself, supplied
-  // by the injection bundle so getEnviveConfig can call /v1/session/bootstrap on
-  // the use_unified_config gate-ON path. Optional: when absent (mocks, non-bundle
-  // callers) the bootstrap branch is skipped and getWidgetConfig stands.
+  // by the injection bundle so getEnviveConfig can request bootstrap's
+  // url_resolving branch. Optional: when absent (mocks, or a disabled session)
+  // bootstrap is still called for config, just without the url_resolving branch.
   env?: string;
   contextSource?: string;
 };
@@ -118,7 +114,8 @@ export class EnviveConfigService implements IEnviveConfigService {
   // Hands off (once) the url_resolving payload that /v1/session/bootstrap
   // returned alongside the config — paired with the URL it was resolved for — so
   // the warm-up seeds urlResolverAtom with it instead of firing a separate
-  // /v1/url_resolving. null on the getWidgetConfig / cached path.
+  // /v1/url_resolving. null on the cached path or a config-only bootstrap (a
+  // disabled session, which requests no url_resolving branch).
   takeBootstrapUrlResolving(): BootstrapUrlResolving | null {
     const value = this.bootstrapUrlResolving;
     this.bootstrapUrlResolving = null;
@@ -176,91 +173,58 @@ export class EnviveConfigService implements IEnviveConfigService {
       return this.response;
     }
 
-    // getWidgetConfig is the single source of session config: it returns org
-    // identity + feature gates + experiment assignments (which used to be a
-    // separate GET /v1/org/config call) alongside productsConfig + the
-    // resolution metadata threaded into downstream inference. `gateNames` is the
-    // list of gates the app checks, so the resolver evaluates and returns them.
+    // /v1/session/bootstrap is the single session-config call: org identity +
+    // feature gates + experiment assignments + productsConfig/resolution, PLUS
+    // the initial url_resolving — the consolidation of GET /v1/org/config,
+    // GraphQL me.getWidgetConfig, and POST /v1/url_resolving into one round trip.
+    // `gateNames` is the full list of gates the app checks, so the server
+    // evaluates and returns them. A failure throws (see fetchBootstrapConfig) and
+    // propagates to inject.ts, which aborts injection — there is no getWidgetConfig
+    // left to fall back to, the same blast radius the single /v1/org/config had.
     const gateNames = Object.values(FeatureGates).map(featureGate => featureGate.toString());
 
-    const widgetConfig = await fetchUnifiedGraphQLConfig(
-      this.baseUrl,
-      this.apiKey,
-      this.userId,
-      gateNames,
-      this.source,
-    );
+    // env + contextSource are supplied only by the injection bundle (the hooks
+    // layer can't derive them). Present → request bootstrap's url_resolving branch
+    // and stash it for the warm-up to seed. Absent (mocks, or a disabled session
+    // that still needs org config + gates for the "Envive Initialized" event) →
+    // bootstrap returns config only, no page-variant round trip.
+    const wantsUrlResolving = this.env !== undefined && this.contextSource !== undefined;
+    // Captured once and reused for the stash so the URL carried to the warm-up is
+    // provably the one bootstrap resolved. The warm-up only seeds it if this still
+    // matches the current URL (a SPA nav during the round trip would otherwise
+    // cache this result under a later URL). Same cleansing as warmUrlResolver so
+    // the urlResolverAtom key lines up.
+    const cleansedUrl = window.location.href.toLowerCase().trim();
 
-    this.response = await this.maybeUpgradeToBootstrap(widgetConfig, gateNames);
+    const { config, urlResolving } = await fetchBootstrapConfig({
+      baseUrl: this.baseUrl,
+      apiKey: this.apiKey,
+      userId: this.userId,
+      source: this.source,
+      // Scope org_config.configs to this namespace so bootstrap doesn't return
+      // internal-only org configs to the browser (matches the legacy /v1/org/config).
+      namespace: this.namespace,
+      gateNames,
+      // The persistent chat session id (same source resolveUrl reads) so
+      // bootstrap's url_resolving carries it instead of an empty string.
+      chatId: getAtomStore().get(chatIdAtom),
+      ...(wantsUrlResolving
+        ? {
+            url: cleansedUrl,
+            contextSource: this.contextSource,
+            env: this.env,
+            // Client-side gate overrides only (query/window/localStorage); the
+            // server resolves the real gate values and merges these over them.
+            featureGates: FeatureFlagService.getFeatureFlagOverrides(),
+          }
+        : {}),
+    });
+
+    this.bootstrapUrlResolving = urlResolving ? { url: cleansedUrl, response: urlResolving } : null;
+    this.response = config;
     this.writeCachedConfig(this.response);
     return this.response;
   }
-
-  // The unified-config ramp (`use_unified_config` Statsig gate). When the gate
-  // is ON for this user, swap the getWidgetConfig result for Matt's
-  // /v1/session/bootstrap — the same config PLUS the initial url_resolving in
-  // ONE round trip (the consolidation this migration is about). The gate is read
-  // off the getWidgetConfig response just fetched, because the FE has no Statsig
-  // SDK: pymono evaluates the gate server-side and returns it. `FeatureFlagService`
-  // also honors a `?use_unified_config=true` override, so the bootstrap path is
-  // testable before the gate ramps.
-  //
-  // Only runs on the cache-miss path (bootstrap's config is then cached like any
-  // other), so a cached load never re-fetches. Needs env + contextSource for the
-  // url_resolving context — absent for mocks / non-bundle callers, where the
-  // branch is skipped. A bootstrap failure falls back to the getWidgetConfig
-  // config already in hand: a bootstrap problem degrades to the proven path
-  // instead of aborting injection. At 100% the getWidgetConfig call above is
-  // dropped and bootstrap becomes the sole config call (step 8).
-  private async maybeUpgradeToBootstrap(
-    widgetConfig: EnviveServiceConfig,
-    gateNames: string[],
-  ): Promise<EnviveServiceConfig> {
-    if (this.env === undefined || this.contextSource === undefined) {
-      return widgetConfig;
-    }
-    // Built once: reads the gate (override-aware) AND supplies the override-aware
-    // gate map bootstrap's url_resolving needs (matches the legacy resolveUrl path).
-    const featureFlagService = new FeatureFlagService(widgetConfig.gates);
-    if (!featureFlagService.isFeatureGateEnabled(FeatureGates.UseUnifiedConfig)) {
-      return widgetConfig;
-    }
-
-    // Captured once and reused for both the bootstrap request and the stash, so
-    // the URL carried to the warm-up is provably the one bootstrap resolved. The
-    // warm-up only seeds it if this still matches the current URL (a SPA nav
-    // during the round trip would otherwise cache this result under a later URL).
-    // Same cleansing as warmUrlResolver so the urlResolverAtom key lines up.
-    const cleansedUrl = window.location.href.toLowerCase().trim();
-    try {
-      const { config, urlResolving } = await fetchBootstrapConfig({
-        baseUrl: this.baseUrl,
-        apiKey: this.apiKey,
-        userId: this.userId,
-        source: this.source,
-        // Scope org_config.configs to this namespace so bootstrap doesn't return
-        // internal-only org configs to the browser (matches the legacy /v1/org/config).
-        namespace: this.namespace,
-        gateNames,
-        url: cleansedUrl,
-        orgId: widgetConfig.org.org.id,
-        orgShortName: widgetConfig.org.org.short_name,
-        contextSource: this.contextSource,
-        env: this.env,
-        featureGates: featureFlagService.getFeatureFlags(),
-        // The persistent chat session id (same source resolveUrl reads) so
-        // bootstrap's url_resolving carries it instead of an empty string.
-        chatId: getAtomStore().get(chatIdAtom),
-      });
-      this.bootstrapUrlResolving = urlResolving
-        ? { url: cleansedUrl, response: urlResolving }
-        : null;
-      return config;
-    } catch (err) {
-      logger.logError('getEnviveConfig | bootstrap upgrade failed, using getWidgetConfig', err);
-      return widgetConfig;
-    }
-  }
 }
 
 /**

package/src/services/enviveConfigService/fetchBootstrapConfig.ts

@@ -14,11 +14,6 @@ import type { EnviveServiceConfig } from './enviveConfigService';
 
 const logger = new Logger('fetchBootstrapConfig');
 
-// The url-resolving context bits the hooks layer can't derive on its own — the
-// injection bundle supplies env (a build-time var) and contextSource. org
-// identity is threaded from the getWidgetConfig response fetched moments earlier
-// (see enviveConfigService: bootstrap only runs on the gate-ON path, which reads
-// the gate off getWidgetConfig first, so org id/short_name are already in hand).
 export interface FetchBootstrapConfigParams {
   baseUrl: string;
   apiKey: string;
@@ -31,22 +26,27 @@ export interface FetchBootstrapConfigParams {
   // bundle receives. The legacy /v1/org/config call scoped it the same way.
   namespace: string;
   gateNames: string[];
-  // url_resolving inputs:
-  url: string;
-  orgId: string;
-  orgShortName: string;
+  chatId?: string;
+  // url_resolving inputs, all supplied together by the injection bundle when
+  // Envive is enabled. When `url` is present, bootstrap runs its page-variant
+  // branch and returns the initial url_resolving; when absent (envive_on=false —
+  // there is no page to resolve) the branch is omitted and bootstrap returns
+  // config only. org identity is NO LONGER sent: /v1/session/bootstrap fills
+  // org_id/org_short_name from the authenticated org (the API key), so the
+  // bootstrap-only client — which no longer calls getWidgetConfig — needs no way
+  // to learn its own org before the request.
+  url?: string;
   // Context `source` for url_resolving ('app' | 'playground'); may differ from
   // the config `source` above (playground = Envive Hub).
-  contextSource: string;
-  env: string;
-  chatId?: string;
-  // The override-aware feature gates (FeatureFlagService.getFeatureFlags()), so
-  // client-side gate overrides (query/window/localStorage) reach page-variant
-  // resolution — same as the legacy /v1/url_resolving request. Bootstrap merges
-  // these OVER its own server-resolved gates. Harmlessly ignored by pymono until
-  // SessionBootstrapUrlResolvingRequest gains the `feature_gates` field (the
-  // schema allows unknown fields; the model is `extra='ignore'`), so the FE can
-  // ship ahead of the backend.
+  contextSource?: string;
+  env?: string;
+  // Override-ONLY feature gates (FeatureFlagService.getFeatureFlagOverrides()):
+  // just the client-side overrides (query/window/localStorage), which bootstrap
+  // merges OVER its own server-resolved gates for page-variant selection — the
+  // legacy /v1/url_resolving behaviour. NOT a full resolved map: on the
+  // bootstrap-only path the client has no server gate values to resolve from, so
+  // a full map would clobber the server's gates. Empty (the common case, no
+  // overrides) leaves the server gates untouched.
   featureGates?: Record<string, boolean>;
 }
 
@@ -127,18 +127,17 @@ const toResolution = (
 // `me.getWidgetConfig`, and `POST /v1/url_resolving` behind Matt's endpoint.
 //
 // Raw fetch (the npm client `@spiffy-ai/commerce-api-client` has no bootstrap
-// method, same as getWidgetConfig). Throws on network/HTTP failure/timeout — the
-// caller (enviveConfigService) falls back to the getWidgetConfig config it already
-// holds, so a bootstrap problem degrades to the proven path rather than aborting
-// injection.
+// method). Throws on network/HTTP failure/timeout, which propagates through
+// getEnviveConfig to inject.ts and aborts injection — bootstrap is now the SOLE
+// config call, so there is no getWidgetConfig left to fall back to (the same
+// blast radius the single GET /v1/org/config call always had).
 //
-// Bootstrap is an OPTIONAL upgrade that BLOCKS the pre-first-paint critical path
-// (a second call after getWidgetConfig already succeeded), and we already hold a
-// usable getWidgetConfig config to fall back to — so it is tightly bounded. Kept
-// low so a slow/hung endpoint adds at most this much to first paint; on timeout
-// the fetch aborts and we fall back to getWidgetConfig. CALIBRATE against the
-// endpoint's real p99 before ramping the gate (a value below p99 will make normal
-// bootstraps false-abort into the fallback, defeating the consolidation).
+// Bootstrap BLOCKS the pre-first-paint critical path, so it is bounded by a
+// timeout: a hung /v1/session/bootstrap (server black-hole, half-open socket,
+// slow-loris body) would otherwise block injection until the browser's
+// multi-minute default. CALIBRATE against the endpoint's real p99 — with no
+// fallback, a value below p99 turns normal-but-slow bootstraps into FAILED
+// injections, so err on the generous side rather than the aggressive one.
 const BOOTSTRAP_TIMEOUT_MS = 1500;
 
 export const fetchBootstrapConfig = async ({
@@ -148,19 +147,43 @@ export const fetchBootstrapConfig = async ({
   source,
   namespace,
   gateNames,
+  chatId,
   url,
-  orgId,
-  orgShortName,
   contextSource,
   env,
-  chatId,
   featureGates,
 }: FetchBootstrapConfigParams): Promise<BootstrapResult> => {
   const version = configVersionOverride();
+  // The url_resolving branch is requested only when the bundle supplied a URL
+  // (Envive enabled). Absent → bootstrap returns config only (envive_on=false).
+  const urlResolvingBody =
+    url !== undefined
+      ? {
+          url_resolving: {
+            url,
+            context: {
+              user_id: userId,
+              // org_id / org_short_name intentionally omitted — the server fills
+              // them from the authenticated org (see SessionBootstrapService).
+              chat_id: chatId ?? '',
+              source: contextSource,
+              env,
+            },
+            // Override-only gates (empty unless the client set an override); the
+            // server merges these OVER its own resolved gates (pymono
+            // SessionBootstrapUrlResolvingRequest.feature_gates), so client-side
+            // overrides still reach page-variant selection.
+            feature_gates: featureGates,
+            // The config-version override comes ONLY from the URL query param
+            // (configVersionOverride) — the same source the config version uses.
+            override_config_version: version,
+          },
+        }
+      : {};
 
   // Armed before fetch and kept live across response.json() (a stalled body read
   // must also be interruptible), cleared in finally. On timeout the fetch rejects
-  // with an AbortError → maybeUpgradeToBootstrap's catch falls back to getWidgetConfig.
+  // with an AbortError → propagates through getEnviveConfig and aborts injection.
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), BOOTSTRAP_TIMEOUT_MS);
   let result: RawBootstrapResponse;
@@ -179,28 +202,7 @@ export const fetchBootstrapConfig = async ({
         namespace,
         include_feature_gates: gateNames,
         version,
-        url_resolving: {
-          url,
-          context: {
-            user_id: userId,
-            org_id: orgId,
-            org_short_name: orgShortName,
-            chat_id: chatId ?? '',
-            source: contextSource,
-            env,
-          },
-          // Override-aware gates so client gate overrides reach page-variant
-          // resolution (bootstrap merges these over its server-resolved gates).
-          // Ignored by pymono until the endpoint gains the field — safe to ship early.
-          feature_gates: featureGates,
-          // The config-version override comes ONLY from the URL query param
-          // (configVersionOverride) — the same source getWidgetConfig uses. It must
-          // NOT come from getWidgetConfig's resolved version: on the gate-ON path
-          // that response is discarded, and bootstrap resolves the config version
-          // server-side (scoping url_resolving to that resolved version, if desired,
-          // belongs on the server — not a getWidgetConfig dependency here).
-          override_config_version: version,
-        },
+        ...urlResolvingBody,
       }),
       signal: controller.signal,
     });
@@ -213,16 +215,22 @@ export const fetchBootstrapConfig = async ({
     clearTimeout(timeoutId);
   }
 
-  // A 2xx with a missing/partial payload must NOT silently replace the known-good
-  // getWidgetConfig config with empty gates / mock products — that would disable the
-  // client session or drop experiments. Throw instead, so maybeUpgradeToBootstrap's
-  // catch falls back to the getWidgetConfig result it already holds. `gates` is
-  // required as a NON-EMPTY array: we always request the full gateNames list and
-  // only reach bootstrap because getWidgetConfig returned real gates, so an
-  // empty/absent gates response is degraded → fall back. (A products config that is
-  // present-but-malformed still degrades to mock below — only the top-level
-  // sections are required here.)
-  if (!result.org_config?.org?.org || !result.org_config?.gates?.length || !result.widget_config) {
+  // A 2xx with a missing/partial payload must NOT silently become a broken config
+  // — a missing org identity or widget_config would drop products/experiments.
+  // Throw instead: with bootstrap the sole config call, the throw propagates to
+  // inject.ts and aborts injection rather than rendering a broken session. `gates`
+  // is required to be an ARRAY (present) but MAY be empty: an empty gates response
+  // is a valid "everything off" signal — FeatureFlagService then resolves every
+  // gate to false, so isClientSessionEnabled is false and the session disables
+  // gracefully (with the "Envive Initialized" event still firing). Rejecting empty
+  // gates would instead abort injection and lose that event. (A products config
+  // that is present-but-malformed still degrades to mock below — only the
+  // top-level sections are required here.)
+  if (
+    !result.org_config?.org?.org ||
+    !Array.isArray(result.org_config?.gates) ||
+    !result.widget_config
+  ) {
     throw new Error(
       'Bootstrap config response missing required sections (org_config.org.org / org_config.gates / widget_config)',
     );

package/src/services/enviveConfigService/fetchGraphQLConfig.ts

@@ -11,20 +11,10 @@ import { ColorMappingV3 } from 'src/application/models/colorsConfigV3';
 // 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 { 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 type { GraphQlConfigValues } from 'src/contexts/graphqlContext';
-import { configVersionOverride } from 'src/types/config-versions';
-import {
-  ExperimentConfigResolutionMetadata,
-  OrgConfigExperimentAssignment,
-  OrgConfigFeatureGate,
-} from 'src/application/models/api/orgConfigResults';
-// Type-only import — erased at compile time, so this does not create a runtime
-// import cycle with enviveConfigService (which imports fetchUnifiedGraphQLConfig).
-import type { EnviveServiceConfig } from './enviveConfigService';
 
 const logger = new Logger('fetchGraphQLConfig');
 
@@ -238,113 +228,3 @@ export const transformV3ProductsConfig = (
     },
   };
 };
-
-// The camelCase `experimentAssignments` GraphQL shape → the snake_case wire
-// shape amplitudeService reads (it previously arrived from REST /v1/org/config).
-const toExperimentAssignments = (
-  raw:
-    | ReadonlyArray<{
-        layerName?: string;
-        namespace?: OrgConfigExperimentAssignment['namespace'];
-        allocatedExperimentName?: string | null;
-        groupName?: string | null;
-      }>
-    | undefined,
-): OrgConfigExperimentAssignment[] =>
-  (raw ?? []).map(a => ({
-    layer_name: a.layerName,
-    namespace: a.namespace,
-    allocated_experiment_name: a.allocatedExperimentName,
-    group_name: a.groupName,
-  }));
-
-// The unified `getWidgetConfig` config path — now the single source of session
-// config. Returns everything the client needs in one call: org identity,
-// feature gates, and experiment assignments (which used to come from REST
-// `/v1/org/config`), plus the productsConfig and the resolution metadata pymono
-// used to pick the version (callers thread `resolution.baseVersion` into
-// downstream inference so it's scoped to the version that produced the rendered
-// widgets). `gateNames` selects which gates to evaluate; `source` feeds Statsig
-// user properties. A `spiffy_config_version` / `envive_config_version` URL
-// param, when present, is threaded through as the `version` variable to pin a
-// specific version (bypasses the merchant experiment — QA / rollback).
-//
-// Throws on network/GraphQL failure: with org + gates sourced here, there is no
-// partial-render fallback (inject.ts aborts injection on the throw), matching
-// how the old /v1/org/config call behaved.
-export const fetchUnifiedGraphQLConfig = async (
-  baseUrl: string,
-  apiKey: string,
-  userId: string,
-  gateNames: string[],
-  source: string,
-): Promise<EnviveServiceConfig> => {
-  const query = getWidgetConfigQuery();
-  const version = configVersionOverride();
-  const response = await fetch(`${baseUrl}/v1/graphql`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${apiKey}`,
-    },
-    body: JSON.stringify({ query, variables: { userId, version, gateNames, source } }),
-  });
-
-  if (!response.ok) {
-    throw new Error(`Unified config request failed: ${response.statusText}`);
-  }
-
-  const result = await response.json();
-  if (result.errors) {
-    throw new Error(`Unified config GraphQL errors: ${JSON.stringify(result.errors)}`);
-  }
-
-  const me = result.data?.me;
-  const widgetConfig = me?.getWidgetConfig;
-  const org = me?.org;
-
-  // A malformed products config (e.g. an invalid floating-button position)
-  // degrades to no config — widgets fall back to their mock defaults — WITHOUT
-  // losing the org / gates / experiments that came back fine. The fetch itself
-  // still throws above; only the products-config transform is guarded here.
-  const resolution = widgetConfig?.resolution as ExperimentConfigResolutionMetadata | undefined;
-  let orgConfig: GraphQlConfigValues;
-  try {
-    orgConfig = { ...transformV3ProductsConfig(widgetConfig?.productsConfig), resolution };
-  } catch (err) {
-    logger.logError('fetchUnifiedGraphQLConfig | Error transforming products config', err);
-    orgConfig = { colorsConfig: undefined, frontendConfig: undefined, resolution };
-  }
-
-  return {
-    // GraphQL Organization is camelCase; the rest of the app reads the
-    // snake_case shape /v1/org/config used to return. `status` isn't exposed by
-    // the GraphQL type (and isn't consumed downstream) — default it.
-    org: {
-      org: {
-        id: org?.id ?? '',
-        short_name: org?.shortName ?? '',
-        display_name: org?.displayName ?? '',
-        domain: org?.domain ?? '',
-        status: '',
-        created_at: org?.createdAt ?? '',
-        updated_at: org?.updatedAt ?? '',
-      },
-    },
-    gates: (
-      (widgetConfig?.gates ?? []) as Array<{
-        name?: string;
-        value?: boolean;
-        groupName?: string;
-      }>
-    ).map(
-      (g): OrgConfigFeatureGate => ({
-        name: g.name,
-        value: g.value,
-        groupName: g.groupName,
-      }),
-    ),
-    experiment_assignments: toExperimentAssignments(widgetConfig?.experimentAssignments),
-    orgConfig,
-  };
-};

package/src/services/featureFlagService/__tests__/getFeatureFlagOverrides.test.ts

@@ -0,0 +1,54 @@
+import { FeatureFlagService } from '../index';
+
+// getFeatureFlagOverrides feeds /v1/session/bootstrap's url_resolving.feature_gates.
+// It must return ONLY the gates the client actually overrides — never a full
+// resolved map — so the server's own resolved gates survive the merge (the client
+// on the bootstrap-only path has no server values to resolve from).
+describe('FeatureFlagService.getFeatureFlagOverrides', () => {
+  const _envive = window as Window & { _envive?: { featureOverrides?: Record<string, boolean> } };
+
+  beforeEach(() => {
+    window.history.replaceState({}, '', '/');
+    window.localStorage.clear();
+    delete _envive._envive;
+  });
+
+  afterEach(() => {
+    window.history.replaceState({}, '', '/');
+    window.localStorage.clear();
+    delete _envive._envive;
+  });
+
+  it('returns an empty map when nothing is overridden', () => {
+    expect(FeatureFlagService.getFeatureFlagOverrides()).toEqual({});
+  });
+
+  it('includes only the gates overridden via query param', () => {
+    window.history.replaceState({}, '', '/?use_unified_config=true&is_empty_div_plp_enabled=false');
+
+    const overrides = FeatureFlagService.getFeatureFlagOverrides();
+
+    // Only the two overridden gates appear — un-overridden gates are absent
+    // entirely (NOT resolved to false), so the server's gates survive the merge.
+    expect(overrides).toEqual({ use_unified_config: true, is_empty_div_plp_enabled: false });
+  });
+
+  it('includes a gate overridden via localStorage', () => {
+    window.localStorage.setItem(
+      'spiffy-feature-flags',
+      JSON.stringify({ use_unified_config: true }),
+    );
+
+    expect(FeatureFlagService.getFeatureFlagOverrides()).toEqual({ use_unified_config: true });
+  });
+
+  it('lets a query param override win over localStorage for the same gate', () => {
+    window.localStorage.setItem(
+      'spiffy-feature-flags',
+      JSON.stringify({ use_unified_config: false }),
+    );
+    window.history.replaceState({}, '', '/?use_unified_config=true');
+
+    expect(FeatureFlagService.getFeatureFlagOverrides().use_unified_config).toBe(true);
+  });
+});

package/src/services/featureFlagService/index.ts

@@ -160,17 +160,30 @@ export class FeatureFlagService {
       : {};
   };
 
-  static persistFeatureGateOverrides(): void {
-    if (typeof window === 'undefined' || typeof window.localStorage === 'undefined') {
-      return;
-    }
-    const overrides = Object.values(FeatureGates)
+  // Only the gates the client actually overrides (query param / window / stored),
+  // with the un-overridden ones left out entirely — NOT resolved to false. This
+  // is what /v1/session/bootstrap's url_resolving wants: the server resolves the
+  // real gate values itself and merges this map OVER them, so a full map of
+  // resolved values would clobber the server's gates with the client's (which,
+  // on the bootstrap-only path, has no server values to resolve from). An empty
+  // map (the common case — no overrides) leaves the server's gates untouched.
+  static getFeatureFlagOverrides(): Record<string, boolean> {
+    return 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));
+  }
+
+  static persistFeatureGateOverrides(): void {
+    if (typeof window === 'undefined' || typeof window.localStorage === 'undefined') {
+      return;
+    }
+    window.localStorage.setItem(
+      FEATURE_FLAGS_STORAGE_KEY,
+      JSON.stringify(FeatureFlagService.getFeatureFlagOverrides()),
+    );
   }
 }

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,
+  },
 };