@envive-ai/react-hooks 0.3.62 → 0.3.63

package/src/services/enviveConfigService/enviveConfigService.ts

@@ -2,7 +2,15 @@ import { OrgConfigExperimentAssignment, OrgConfigFeatureGate } from 'src/applica
 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
@@ -21,6 +29,12 @@ type EnviveConfigServiceProps = {
   userId: string;
   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.
+  env?: string;
+  contextSource?: string;
 };
 
 export type EnviveServiceConfig = {
@@ -36,9 +50,10 @@ 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.
+  // The user's Statsig experiment-layer assignments, from the widget config's
+  // resolved experiments — getWidgetConfig, or bootstrap's `widget_config`
+  // (both ungated by use_unified_config; empty only under a version pin).
+  // amplitudeService reads these to enrich events with `experiment.{ns}.*` props.
   experiment_assignments?: OrgConfigExperimentAssignment[];
   // orgConfig.resolution is populated only on the unified path (sourced from
   // getWidgetConfig.resolution, not /v1/org/config.resolution) so the version
@@ -51,8 +66,18 @@ export interface IEnviveConfigService {
   readonly baseUrl: string;
   readonly apiKey: string;
   getEnviveConfig(): Promise<EnviveServiceConfig>;
+  // NB: `takeBootstrapUrlResolving` is intentionally NOT on this interface. It's
+  // a bootstrap-only detail consumed solely by the injection bundle via the
+  // concrete EnviveConfigService; keeping it off the public DI contract avoids a
+  // breaking change for external consumers that supply their own config service
+  // (EnviveProvider only ever calls getEnviveConfig / baseUrl / apiKey).
 }
 
+// The bootstrap url_resolving payload plus the URL it was resolved for, so the
+// warm-up can verify the URL still matches before seeding (see F1: a SPA nav
+// during the bootstrap round trip must not cache URL A's result under URL B).
+type BootstrapUrlResolving = { url: string; response: UrlResolverResponse };
+
 export class EnviveConfigService implements IEnviveConfigService {
   public readonly baseUrl: string;
 
@@ -64,14 +89,40 @@ export class EnviveConfigService implements IEnviveConfigService {
 
   private readonly source: string;
 
+  private readonly env?: string;
+
+  private readonly contextSource?: string;
+
   private response: EnviveServiceConfig | null = null;
 
-  constructor({ baseUrl, apiKey, userId, namespace, source }: EnviveConfigServiceProps) {
+  private bootstrapUrlResolving: BootstrapUrlResolving | null = null;
+
+  constructor({
+    baseUrl,
+    apiKey,
+    userId,
+    namespace,
+    source,
+    env,
+    contextSource,
+  }: EnviveConfigServiceProps) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.userId = userId;
     this.namespace = namespace;
     this.source = source;
+    this.env = env;
+    this.contextSource = contextSource;
+  }
+
+  // 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.
+  takeBootstrapUrlResolving(): BootstrapUrlResolving | null {
+    const value = this.bootstrapUrlResolving;
+    this.bootstrapUrlResolving = null;
+    return value;
   }
 
   private getCacheKey(): string {
@@ -132,16 +183,84 @@ export class EnviveConfigService implements IEnviveConfigService {
     // list of gates the app checks, so the resolver evaluates and returns them.
     const gateNames = Object.values(FeatureGates).map(featureGate => featureGate.toString());
 
-    this.response = await fetchUnifiedGraphQLConfig(
+    const widgetConfig = await fetchUnifiedGraphQLConfig(
       this.baseUrl,
       this.apiKey,
       this.userId,
       gateNames,
       this.source,
     );
+
+    this.response = await this.maybeUpgradeToBootstrap(widgetConfig, gateNames);
     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

@@ -0,0 +1,276 @@
+import Logger from 'src/application/logging/logger';
+import type { UrlResolverResponse } from 'src/atoms/app/variant';
+import {
+  ExperimentConfigResolutionMetadata,
+  OrgConfigExperimentAssignment,
+  OrgConfigFeatureGate,
+} from 'src/application/models/api/orgConfigResults';
+import type { GraphQlConfigValues } from 'src/contexts/graphqlContext';
+import { configVersionOverride } from 'src/types/config-versions';
+import { transformV3ProductsConfig } from './fetchGraphQLConfig';
+// Type-only import — erased at compile time, so this does not create a runtime
+// import cycle with enviveConfigService (which imports fetchBootstrapConfig).
+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;
+  userId: string;
+  // Config `source` (Statsig user property), 'app' in the injection bundle.
+  source: string;
+  // Scopes org_config.configs to this namespace. REQUIRED: without it pymono
+  // returns EVERY namespace on the org — including internal-only configs (the AI
+  // system prompt, brand-voice instructions, etc.) — in the response the public
+  // 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;
+  // 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.
+  featureGates?: Record<string, boolean>;
+}
+
+export interface BootstrapResult {
+  config: EnviveServiceConfig;
+  // The initial page-variant result, ready to seed urlResolverAtom so the
+  // warm-up skips its own /v1/url_resolving call. null when bootstrap's
+  // (best-effort) url-resolving branch returned nothing.
+  urlResolving: UrlResolverResponse | null;
+}
+
+// --- raw wire shapes (POST /v1/session/bootstrap is REST snake_case) ---------
+
+interface RawFeatureGate {
+  name?: string;
+  value?: boolean;
+  group_name?: string | null;
+  rule_id?: string | null;
+}
+
+interface RawExperimentAssignment {
+  layer_name?: string;
+  namespace?: OrgConfigExperimentAssignment['namespace'];
+  allocated_experiment_name?: string | null;
+  group_name?: string | null;
+}
+
+interface RawResolution {
+  base_version?: string;
+  base_version_source?: string;
+}
+
+interface RawBootstrapResponse {
+  org_config?: {
+    org?: { org?: Record<string, string | undefined> };
+    gates?: RawFeatureGate[];
+  };
+  widget_config?: {
+    products_config?: Parameters<typeof transformV3ProductsConfig>[0];
+    // Read from widget_config (not org_config) to match getWidgetConfig — see the
+    // mapping below.
+    experiment_assignments?: RawExperimentAssignment[];
+    resolution?: RawResolution;
+  };
+  url_resolving?: UrlResolverResponse | null;
+}
+
+// gates arrive snake (`group_name`); getWidgetConfig's arrive camel. Only the
+// name/value are used for gate checks — groupName is carried for amplitude.
+const toBootstrapGates = (raw: RawFeatureGate[] | undefined): OrgConfigFeatureGate[] =>
+  (raw ?? []).map(g => ({
+    name: g.name,
+    value: g.value,
+    groupName: g.group_name ?? undefined,
+  }));
+
+// experiment_assignments already match the snake OrgConfigExperimentAssignment
+// wire shape (unlike getWidgetConfig's camel, which needs toExperimentAssignments).
+const toBootstrapAssignments = (
+  raw: RawExperimentAssignment[] | undefined,
+): OrgConfigExperimentAssignment[] =>
+  (raw ?? []).map(a => ({
+    layer_name: a.layer_name,
+    namespace: a.namespace,
+    allocated_experiment_name: a.allocated_experiment_name,
+    group_name: a.group_name,
+  }));
+
+// resolution is snake here (REST); getWidgetConfig's is camel (Ariadne).
+const toResolution = (
+  raw: RawResolution | undefined,
+): ExperimentConfigResolutionMetadata | undefined =>
+  raw ? { baseVersion: raw.base_version, baseVersionSource: raw.base_version_source } : undefined;
+
+// One round trip for the config the widget client needs at init: org identity +
+// gates + experiment assignments + productsConfig/resolution, PLUS the initial
+// url-resolving result — the consolidation of `GET /v1/org/config`, GraphQL
+// `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.
+//
+// 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).
+const BOOTSTRAP_TIMEOUT_MS = 1500;
+
+export const fetchBootstrapConfig = async ({
+  baseUrl,
+  apiKey,
+  userId,
+  source,
+  namespace,
+  gateNames,
+  url,
+  orgId,
+  orgShortName,
+  contextSource,
+  env,
+  chatId,
+  featureGates,
+}: FetchBootstrapConfigParams): Promise<BootstrapResult> => {
+  const version = configVersionOverride();
+
+  // 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.
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), BOOTSTRAP_TIMEOUT_MS);
+  let result: RawBootstrapResponse;
+  try {
+    const response = await fetch(`${baseUrl}/v1/session/bootstrap`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        user_id: userId,
+        source,
+        // Scope org_config.configs to the widget namespace — WITHOUT this, pymono
+        // returns every namespace's configs (internal ones included) to the browser.
+        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,
+        },
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Bootstrap config request failed: ${response.statusText}`);
+    }
+    result = (await response.json()) as RawBootstrapResponse;
+  } finally {
+    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) {
+    throw new Error(
+      'Bootstrap config response missing required sections (org_config.org.org / org_config.gates / widget_config)',
+    );
+  }
+  const orgConfig = result.org_config;
+  const widgetConfig = result.widget_config;
+  // The guard above guarantees org.org at runtime; the `?? {}` only satisfies the
+  // type-narrowing (TS doesn't carry the optional-chain narrowing through the alias).
+  const orgOrg = orgConfig.org?.org ?? {};
+  const resolution = toResolution(widgetConfig.resolution);
+
+  // A malformed products config degrades to mock defaults WITHOUT losing the
+  // org / gates / experiments that came back fine — mirrors fetchUnifiedGraphQLConfig.
+  let orgConfigValues: GraphQlConfigValues;
+  try {
+    orgConfigValues = { ...transformV3ProductsConfig(widgetConfig.products_config), resolution };
+  } catch (err) {
+    logger.logError('fetchBootstrapConfig | Error transforming products config', err);
+    orgConfigValues = { colorsConfig: undefined, frontendConfig: undefined, resolution };
+  }
+
+  const config: EnviveServiceConfig = {
+    // org_config is byte-identical to the legacy /v1/org/config (snake), the
+    // exact shape EnviveServiceConfig.org was built to hold. Constructed
+    // defensively (like fetchUnifiedGraphQLConfig) rather than passed through.
+    org: {
+      org: {
+        id: orgOrg.id ?? '',
+        short_name: orgOrg.short_name ?? '',
+        display_name: orgOrg.display_name ?? '',
+        domain: orgOrg.domain ?? '',
+        status: orgOrg.status ?? '',
+        created_at: orgOrg.created_at ?? '',
+        updated_at: orgOrg.updated_at ?? '',
+      },
+    },
+    gates: toBootstrapGates(orgConfig.gates),
+    // From widget_config, NOT org_config: getWidgetConfig sources assignments from
+    // its widget config (ungated), whereas bootstrap's `org_config.experiment_assignments`
+    // is populated ONLY when the `use_unified_config` gate evaluates true SERVER-SIDE
+    // (pymono `unified_config_active`). Reading org_config would drop assignments —
+    // and the amplitude `experiment.{ns}.*` enrichment — on the client-override test
+    // path (gate ON via `?use_unified_config=true` but 0% server-side). widget_config
+    // matches getWidgetConfig in every case (equal when the gate is on; version pin
+    // empties both).
+    experiment_assignments: toBootstrapAssignments(widgetConfig.experiment_assignments),
+    orgConfig: orgConfigValues,
+  };
+
+  return { config, urlResolving: result.url_resolving ?? null };
+};

package/src/services/enviveConfigService/fetchGraphQLConfig.ts

@@ -151,10 +151,13 @@ const v3FrontendConfigCleanup = (
   };
 };
 
-// Turns a raw productsConfig payload (from getProductsConfigByVersion or
-// getWidgetConfig) into the camelCase GraphQlConfigValues shape the rest of
-// the toolkit consumes. Returns mock config when colors are absent.
-const transformV3ProductsConfig = (
+// Turns a raw productsConfig payload (from getProductsConfigByVersion,
+// getWidgetConfig, or the /v1/session/bootstrap widget_config) into the
+// camelCase GraphQlConfigValues shape the rest of the toolkit consumes.
+// Returns mock config when colors are absent. Exported so fetchBootstrapConfig
+// reuses the exact same transform (bootstrap's products_config carries the same
+// `.{section}.values` shape as getWidgetConfig's productsConfig).
+export const transformV3ProductsConfig = (
   productsConfig:
     | {
         frontend?: { values?: { merchant_override_css?: string } };

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

@@ -4,7 +4,12 @@ import type { AppDetails } from 'src/atoms/app';
 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';
+import {
+  HARDCOPY_TIMEOUT_MS,
+  HardcopyService,
+  MOCK_HARDCOPY_RESPONSE,
+  MockHardcopyService,
+} from '../hardcopyService';
 
 const { MockLogger, mockGetHardcopy, mockGetQueryParam } = vi.hoisted(() => {
   const MockLogger = vi.fn(function () {
@@ -269,6 +274,38 @@ describe('HardcopyService', () => {
       );
     });
 
+    it.each([
+      [WidgetTypeV3.ProductCardV3, 'ImagePromptCardV3'],
+      [WidgetTypeV3.PromptButtonCarouselWithImageV3, 'SingleImagePromptV3'],
+    ])(
+      'stamps the API-facing (translated) widget type on both events: %s → %s',
+      async (internalType, wireType) => {
+        // The AI-suggestions accounting joins these events against the backend registry,
+        // which is keyed by the wire type. Stamping the internal name zeroed the stats
+        // for aliased widgets (Naturalizer PLP).
+        const trackEvent = vi.fn();
+        mockGetHardcopy.mockResolvedValueOnce(makeWidgetTextResponse());
+
+        await makeService(trackEvent).getHardcopy({
+          widgetType: internalType,
+          userEvent: {} as any,
+        });
+
+        expect(trackEvent).toHaveBeenCalledWith(
+          expect.objectContaining({
+            eventName: EnviveMetricsEventName.WidgetTextRequest,
+            eventProps: expect.objectContaining({ widget_type: wireType }),
+          }),
+        );
+        expect(trackEvent).toHaveBeenCalledWith(
+          expect.objectContaining({
+            eventName: EnviveMetricsEventName.WidgetTextResponse,
+            eventProps: expect.objectContaining({ widget_type: wireType }),
+          }),
+        );
+      },
+    );
+
     it('forwards ai_suggestions_attribution_by_slot on WidgetTextResponse when present', async () => {
       const trackEvent = vi.fn();
       const attribution = {
@@ -385,6 +422,28 @@ describe('HardcopyService', () => {
         }),
       ).rejects.toThrow('No hardcopy response found for widget type: UnknownWidget');
     });
+
+    it('falls back to the mock when the API request hangs past the timeout', async () => {
+      // A request that never settles — the timeout is the only thing that can release it.
+      // Without it the widget's loading latch never resolves ("PLP staying in loading state").
+      vi.useFakeTimers();
+      try {
+        mockGetHardcopy.mockReturnValueOnce(new Promise(() => {}));
+
+        const resultPromise = makeService().getHardcopy({
+          widgetType: WidgetTypeV3.PromptCarouselV3,
+          userEvent: {} as any,
+        });
+
+        await vi.advanceTimersByTimeAsync(HARDCOPY_TIMEOUT_MS);
+
+        await expect(resultPromise).resolves.toBe(
+          MOCK_HARDCOPY_RESPONSE[WidgetTypeV3.PromptCarouselV3],
+        );
+      } finally {
+        vi.useRealTimers();
+      }
+    });
   });
 });
 

package/src/services/hardcopyService/hardcopyService.ts

@@ -4,6 +4,7 @@ import { WidgetString, WidgetText } from 'src/application/models/api/widgetText'
 import { WidgetTextRequest } from 'src/application/models/api/widgetTextRequest';
 import { toCamelCase } from 'src/application/models/utils/snakeToCamelTransformer';
 import { getQueryParam } from 'src/application/utils';
+import { coreWidgetTypeToApiWidgetType } from 'src/application/utils/widgetTextRequestToApiRequest';
 import { UserEvent } from 'src/application/models';
 import Logger from 'src/application/logging/logger';
 import { AppDetails } from 'src/atoms/app';
@@ -14,6 +15,30 @@ import { EnviveMetricsEventName, TrackEventParams } from '../amplitudeService';
 
 const logger = new Logger('hardcopyService');
 
+// Longest a hardcopy request may hang before we stop waiting for it. The backend-error
+// path below already falls back to static copy, but a request that never settles at all
+// never reaches that catch — it left the widget's loading latch unresolved forever, which
+// is the "PLP staying in loading state" failure. Racing the request against this timeout
+// turns a hang into the same fallback path an error takes, so the widget always leaves its
+// loading state.
+//
+// Kept under the ~4-5s at which session replays show shoppers abandon a still-loading
+// widget: a rescue that fires after they've left helps no one. When it fires, the catch
+// below logs an error (message includes "timed out") — that log is the signal monitoring
+// can count to measure how often hardcopy stalls.
+export const HARDCOPY_TIMEOUT_MS = 4000;
+
+// Reject if `promise` has not settled within `ms`. The underlying request is not aborted
+// (a late response is simply discarded) — the only goal is to stop *waiting*, so the
+// caller's error handling can run.
+const withTimeout = <T>(promise: Promise<T>, ms: number): Promise<T> => {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`hardcopy request timed out after ${ms}ms`)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer)) as Promise<T>;
+};
+
 export interface HardcopyRequest {
   widgetType: WidgetTypeV3;
   userEvent: UserEvent;
@@ -218,23 +243,40 @@ export class HardcopyService implements IHardcopyService {
       url: window.location.href,
     };
 
+    // The Widget Text events must carry the API-facing (translated) widget type, not the
+    // internal one: the AI-suggestions accounting joins these events against the backend
+    // registry, which is keyed by the wire type (e.g. ProductCardV3 is sent — and stored —
+    // as ImagePromptCardV3). Stamping the internal name here zeroed those stats. An
+    // unmapped type keeps the internal name — analytics must never block serving.
+    let wireWidgetType: string = request.widgetType;
+    try {
+      wireWidgetType = coreWidgetTypeToApiWidgetType(request.widgetType);
+    } catch {
+      logger.logDebug('no wire mapping for widget type — keeping internal name', {
+        widgetType: request.widgetType,
+      });
+    }
+
     this.config.trackEvent?.({
       eventName: EnviveMetricsEventName.WidgetTextRequest,
       eventProps: {
-        widget_type: request.widgetType,
+        widget_type: wireWidgetType,
         request_id: widgetTextRequest.requestId,
       },
     });
 
     try {
-      const response = await CommerceApiClient.getHardcopy(widgetTextRequest);
+      const response = await withTimeout(
+        CommerceApiClient.getHardcopy(widgetTextRequest),
+        HARDCOPY_TIMEOUT_MS,
+      );
       if (response) {
         const convertedResponse = convertToHardcopyResponse(response);
         logger.logDebug('converted response', convertedResponse);
         this.config.trackEvent?.({
           eventName: EnviveMetricsEventName.WidgetTextResponse,
           eventProps: {
-            widget_type: request.widgetType,
+            widget_type: wireWidgetType,
             response_id: response.responseId,
             widget_text: response.values,
             request_id: widgetTextRequest.requestId,