@envive-ai/react-hooks 0.3.46 → 0.3.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envive-ai/react-hooks",
-  "version": "0.3.46",
+  "version": "0.3.48",
   "description": "React hooks for connecting to Envive AI services.",
   "keywords": [
     "react",
@@ -274,6 +274,10 @@
       "import": "./dist/events/index.js",
       "require": "./dist/events/index.cjs"
     },
+    "./hooks/AddToCart": {
+      "import": "./dist/hooks/AddToCart/index.js",
+      "require": "./dist/hooks/AddToCart/index.cjs"
+    },
     "./hooks/AmplitudeOperations": {
       "import": "./dist/hooks/AmplitudeOperations/index.js",
       "require": "./dist/hooks/AmplitudeOperations/index.cjs"
@@ -350,6 +354,10 @@
       "import": "./dist/hooks/PageViewedEvent/index.js",
       "require": "./dist/hooks/PageViewedEvent/index.cjs"
     },
+    "./hooks/ProductDetails": {
+      "import": "./dist/hooks/ProductDetails/index.js",
+      "require": "./dist/hooks/ProductDetails/index.cjs"
+    },
     "./hooks/ProductImageUrl": {
       "import": "./dist/hooks/ProductImageUrl/index.js",
       "require": "./dist/hooks/ProductImageUrl/index.cjs"
@@ -422,10 +430,18 @@
       "import": "./dist/services/enviveConfigService/index.js",
       "require": "./dist/services/enviveConfigService/index.cjs"
     },
+    "./services/featureFlagService": {
+      "import": "./dist/services/featureFlagService/index.js",
+      "require": "./dist/services/featureFlagService/index.cjs"
+    },
     "./services/hardcopyService": {
       "import": "./dist/services/hardcopyService/index.js",
       "require": "./dist/services/hardcopyService/index.cjs"
     },
+    "./services/urlResolverWarmupService": {
+      "import": "./dist/services/urlResolverWarmupService/index.js",
+      "require": "./dist/services/urlResolverWarmupService/index.cjs"
+    },
     "./services/userIdentityService": {
       "import": "./dist/services/userIdentityService/index.js",
       "require": "./dist/services/userIdentityService/index.cjs"

package/src/application/__tests__/commerceApiAddToCartRehydration.test.ts

@@ -0,0 +1,126 @@
+import { ResponseCategory, UserEventCategory } from '@spiffy-ai/commerce-api-client';
+import { getAtomStore } from 'src/atoms/atomStore/atomStore';
+import { enviveConfigAtom } from 'src/atoms/envive/enviveConfig';
+import { MessageType } from 'src/application/models';
+import CommerceApiClient from '../commerce-api';
+
+const { mockV1GetSessionMessages } = vi.hoisted(() => ({
+  mockV1GetSessionMessages: vi.fn(),
+}));
+
+vi.mock('@spiffy-ai/commerce-api-client', async (importOriginal: () => Promise<unknown>) => {
+  const actual = (await importOriginal()) as typeof import('@spiffy-ai/commerce-api-client');
+  return {
+    ...actual,
+    DefaultApi: vi.fn().mockImplementation(function DefaultApi() {
+      return { v1GetSessionMessages: mockV1GetSessionMessages };
+    }),
+  };
+});
+
+const makeSessionResponse = (overrides: Record<string, unknown> = {}) => ({
+  responses: [],
+  suggestions: [],
+  user_events: [],
+  ...overrides,
+});
+
+const productResponse = (id: string, title: string) => ({
+  id: `resp-${id}`,
+  created_at: '2026-07-20T00:00:00.000Z',
+  category: ResponseCategory.Product,
+  attributes: {
+    id,
+    title,
+    url: `https://example.com/${id}`,
+  },
+});
+
+const addToCartEvent = (eventId: string, productId: string) => ({
+  event_id: eventId,
+  created_at: '2026-07-20T00:00:01.000Z',
+  category: UserEventCategory.AddToCart,
+  attributes: {
+    product_id: productId,
+    parent_product_id: '',
+    url: '',
+  },
+});
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  getAtomStore().set(enviveConfigAtom, {
+    baseUrl: 'https://commerce-api.test',
+    orgLevelApiKey: 'test-key',
+    orgId: 'org-1',
+    orgShortName: 'test-org',
+    env: 'dev',
+    contextSource: 'app',
+  });
+});
+
+describe('CommerceApiClient.getResponses — AddToCart title resolution on rehydration', () => {
+  it('resolves the title for free from a matching Product response, without a fallback fetch', async () => {
+    mockV1GetSessionMessages.mockResolvedValueOnce(
+      makeSessionResponse({
+        responses: [[productResponse('sku-tier1', 'Tier One Sweater')]],
+        user_events: [addToCartEvent('evt-tier1', 'sku-tier1')],
+      }),
+    );
+    const fetchSpy = vi.spyOn(global, 'fetch');
+
+    const { messages } = await CommerceApiClient.getResponses('org-1', 'chat-1', 'user-1');
+
+    const addToCartMessage = messages.flat().find(m => m.id === 'evt-tier1');
+    expect(addToCartMessage?.type).toBe(MessageType.QueryTyped);
+    if (addToCartMessage?.type === MessageType.QueryTyped) {
+      expect(addToCartMessage.metadata.content).toBe('Add Tier One Sweater to my cart');
+    }
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it('falls back to a cached product-details fetch when no matching response exists', async () => {
+    mockV1GetSessionMessages.mockResolvedValueOnce(
+      makeSessionResponse({
+        user_events: [addToCartEvent('evt-tier2', 'sku-tier2')],
+      }),
+    );
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ data: { me: { productOptions: { title: 'Tier Two Boots' } } } }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const { messages } = await CommerceApiClient.getResponses('org-1', 'chat-1', 'user-1');
+
+    const addToCartMessage = messages.flat().find(m => m.id === 'evt-tier2');
+    expect(addToCartMessage?.type).toBe(MessageType.QueryTyped);
+    if (addToCartMessage?.type === MessageType.QueryTyped) {
+      expect(addToCartMessage.metadata.content).toBe('Add Tier Two Boots to my cart');
+    }
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('degrades to the raw productId when neither tier resolves a title', async () => {
+    mockV1GetSessionMessages.mockResolvedValueOnce(
+      makeSessionResponse({
+        user_events: [addToCartEvent('evt-tier3', 'sku-tier3-unresolvable')],
+      }),
+    );
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ data: { me: { productOptions: null } } }),
+      }),
+    );
+
+    const { messages } = await CommerceApiClient.getResponses('org-1', 'chat-1', 'user-1');
+
+    const addToCartMessage = messages.flat().find(m => m.id === 'evt-tier3');
+    expect(addToCartMessage?.type).toBe(MessageType.QueryTyped);
+    if (addToCartMessage?.type === MessageType.QueryTyped) {
+      expect(addToCartMessage.metadata.content).toBe('Add sku-tier3-unresolvable to my cart');
+    }
+  });
+});

package/src/application/commerce-api.ts

@@ -28,6 +28,10 @@ import {
   UserEvent,
 } from 'src/application/models';
 import { OrgConfig } from 'src/application/models/api/orgConfigResults';
+import {
+  ProductDetails,
+  getProductOptionsQuery,
+} from 'src/application/models/graphql/queries/getProductOptionsQuery';
 import { ProductExperiment } from 'src/application/models/productExperiment';
 import { validateOrgConfigResults } from 'src/application/models/validators/validateOrgConfigResults';
 import { validateResponse } from 'src/application/models/validators/validateResponse';
@@ -35,6 +39,7 @@ import { validateSuggestion } from 'src/application/models/validators/validateSu
 import { validateUserEvent } from 'src/application/models/validators/validateUserEvent';
 import {
   getQueryParam,
+  messageFromAddToCartEvent,
   messageFromQueryEvent,
   messageFromResponse,
   messageFromSuggestionEvent,
@@ -146,7 +151,26 @@ class CommerceApiClient {
     this.productsApi = new ProductsApi(config);
   }
 
+  // Dedupes concurrent resolutions of the same URL: the injection bundle
+  // warms this call before React mounts, and PageProvider may request the
+  // same URL while the warm-up is still in flight.
+  private static inFlightUrlResolutions = new Map<string, Promise<unknown>>();
+
   static resolveUrl = async (url: string) => {
+    const inFlight = CommerceApiClient.inFlightUrlResolutions.get(url);
+    if (inFlight) {
+      return inFlight;
+    }
+    const request = CommerceApiClient.resolveUrlUncached(url);
+    CommerceApiClient.inFlightUrlResolutions.set(url, request);
+    try {
+      return await request;
+    } finally {
+      CommerceApiClient.inFlightUrlResolutions.delete(url);
+    }
+  };
+
+  private static resolveUrlUncached = async (url: string) => {
     const atomStore = getAtomStore();
     const orgShortName = atomStore.get(orgShortNameAtom);
     const orgId = atomStore.get(orgIdAtom);
@@ -405,33 +429,64 @@ class CommerceApiClient {
       )
       .filter(turn => turn.length > 0);
 
-    const userMessages: Message[][] = userEvents
-      .map(event => {
-        if ([UserEventCategory.QueryTyped, UserEventCategory.Search].includes(event.category)) {
-          return [messageFromQueryEvent(event)];
-        }
+    const userMessages: Message[][] = (
+      await Promise.all(
+        userEvents.map(async event => {
+          if ([UserEventCategory.QueryTyped, UserEventCategory.Search].includes(event.category)) {
+            return [messageFromQueryEvent(event)];
+          }
 
-        if (event.category === UserEventCategory.SuggestionClicked) {
-          return [messageFromSuggestionEvent(event, suggestions)];
-        }
+          if (event.category === UserEventCategory.SuggestionClicked) {
+            return [messageFromSuggestionEvent(event, suggestions)];
+          }
 
-        if (event.category === UserEventCategory.FormSubmitted) {
-          const formResponse = responses
-            .flat()
-            .find(
-              response =>
-                response.id === event.attributes.formResponseId &&
-                event.attributes.formType !== FormType.Escalation,
-            );
-
-          if (formResponse && formResponse.category === ResponseCategory.Form) {
-            return [messageFromFormSubmittedEvent(event, formResponse.attributes)];
+          if (event.category === UserEventCategory.AddToCart) {
+            // Historical events never carried a client-local productTitle (it's
+            // dropped before hitting the backend), so resolve it here: first for
+            // free from a matching Product response already fetched above, then
+            // as a fallback via the cached product-details call.
+            const matchedProduct = responses
+              .flat()
+              .find(
+                response =>
+                  response.category === ResponseCategory.Product &&
+                  response.attributes.id === event.attributes.productId,
+              );
+            let productTitle =
+              matchedProduct?.category === ResponseCategory.Product
+                ? matchedProduct.attributes.title
+                : undefined;
+            if (!productTitle) {
+              try {
+                const details = await CommerceApiClient.retrieveProductDetails(
+                  event.attributes.productId,
+                );
+                productTitle = details?.title;
+              } catch {
+                productTitle = undefined;
+              }
+            }
+            return [messageFromAddToCartEvent(event, productTitle)];
+          }
+
+          if (event.category === UserEventCategory.FormSubmitted) {
+            const formResponse = responses
+              .flat()
+              .find(
+                response =>
+                  response.id === event.attributes.formResponseId &&
+                  event.attributes.formType !== FormType.Escalation,
+              );
+
+            if (formResponse && formResponse.category === ResponseCategory.Form) {
+              return [messageFromFormSubmittedEvent(event, formResponse.attributes)];
+            }
           }
-        }
 
-        return [];
-      })
-      .filter((message): message is Message[] => message.length > 0);
+          return [];
+        }),
+      )
+    ).filter((message): message is Message[] => message.length > 0);
 
     // Sort the messages chronologically to reconstruct the chat history
     const sortedMessages = [...assistantMessages, ...userMessages].sort(
@@ -494,6 +549,70 @@ class CommerceApiClient {
     }
   };
 
+  // Caches resolved product details by productId for the lifetime of the
+  // session: variant selection, the display of the add-to-cart chat message,
+  // and useProductDetails all resolve the same product repeatedly. Failed
+  // requests are evicted so a later call can retry.
+  private static productDetailsCache = new Map<string, Promise<ProductDetails | undefined>>();
+
+  static retrieveProductDetails = (productId: string): Promise<ProductDetails | undefined> => {
+    const cached = CommerceApiClient.productDetailsCache.get(productId);
+    if (cached) {
+      return cached;
+    }
+    const request = CommerceApiClient.retrieveProductDetailsUncached(productId).catch(err => {
+      CommerceApiClient.productDetailsCache.delete(productId);
+      throw err;
+    });
+    CommerceApiClient.productDetailsCache.set(productId, request);
+    return request;
+  };
+
+  /**
+   * Retrieves variant-level product details for a single product via the GraphQL
+   * `me.productOptions` query on POST /v1/graphql. Only meaningful for products
+   * that offer variations.
+   *
+   * @param productId - The product ID to retrieve details for
+   * @returns ProductDetails, or undefined when the product has no options data
+   * @throws on network/HTTP failure or GraphQL errors
+   */
+  private static retrieveProductDetailsUncached = async (
+    productId: string,
+  ): Promise<ProductDetails | undefined> => {
+    const atomStore = getAtomStore();
+    const baseUrl = atomStore.get(baseUrlAtom);
+    const apiKey = atomStore.get(orgLevelApiKeyAtom);
+
+    try {
+      const response = await fetch(`${baseUrl}/v1/graphql`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          query: getProductOptionsQuery(),
+          variables: { productId },
+        }),
+      });
+
+      if (!response.ok) {
+        throw new ResponseError(response, `GraphQL request failed: ${response.statusText}`);
+      }
+
+      const result = await response.json();
+      if (result.errors) {
+        throw new Error(`GraphQL errors: ${JSON.stringify(result.errors)}`);
+      }
+
+      return result.data?.me?.productOptions ?? undefined;
+    } catch (err) {
+      await throwSessionRestartRequiredIf('Failed to retrieve product details', err);
+      return undefined;
+    }
+  };
+
   /**
    *
    * @param payload

package/src/application/models/api/userEvent.ts

@@ -12,7 +12,14 @@ import {
 import { CamelCasedPropertiesDeep } from 'src/application/models/utilityTypes';
 
 // TODO flatten these out or explore new typescript openapi generator fork
-export interface PDPAttributes extends CamelCasedPropertiesDeep<ApiPDPAttributes> {}
+export interface PDPAttributes extends CamelCasedPropertiesDeep<ApiPDPAttributes> {
+  /**
+   * Client-local only: never serialized to the backend (coreUserEventToApiUserEvent
+   * hand-picks fields and ignores this one). Lets the live add-to-cart chat message
+   * show a resolved product title instead of the raw productId.
+   */
+  productTitle?: string;
+}
 
 export interface PLPAttributes extends CamelCasedPropertiesDeep<ApiPLPAttributes> {}
 

package/src/application/models/featureGates.ts

@@ -27,6 +27,11 @@ export enum FeatureGates {
   IsAiSuggestionsVariantEnabled = 'is_ai_suggestions_variant_enabled',
   IsAiSuggestionsVariantAEnabled = 'is_ai_suggestions_variant_a_enabled',
   IsAiSuggestionsVariantBEnabled = 'is_ai_suggestions_variant_b_enabled',
+  // Serves the agentic storefront (FullPageSalesAgentV3 welcome overlay)
+  // independently of the pdp/plp variant_b experiment. The backend serves the
+  // storefront under this gate and falls back to variant_b only until this
+  // ships, so an org can run the storefront without opting pdp/plp into variant_b.
+  IsAiSuggestionsStorefrontEnabled = 'is_ai_suggestions_storefront_enabled',
   IsVoiceInputEnabled = 'is_voice_input_enabled',
   // Statsig experiments / unified getWidgetConfig endpoint migration. When
   // true, EnviveConfigService calls getWidgetConfig (experiment-aware)

package/src/application/models/graphql/queries/getProductOptionsQuery.ts

@@ -0,0 +1,59 @@
+// Fetches variant-level product details (options, availability, pricing,
+// images) for a single product. Only meaningful for products that offer
+// variations — non-variant PDP surfaces should keep using the REST
+// /v1/products/retrieve path (CommerceApiClient.retrieveProducts).
+export const getProductOptionsQuery = () => `
+  query($productId: String!) {
+    me {
+      productOptions(productId: $productId) {
+        productId
+        virtualParentId
+        title
+        options {
+          name
+          values
+        }
+        variants {
+          variantId
+          available
+          originalPrice
+          salePrice
+          imageUrl
+          url
+          options {
+            name
+            value
+          }
+        }
+      }
+    }
+  }
+`;
+
+export interface ProductVariantOption {
+  name: string;
+  value: string;
+}
+
+export interface ProductVariant {
+  variantId: string;
+  available: boolean;
+  originalPrice?: number;
+  salePrice?: number;
+  imageUrl?: string;
+  url?: string;
+  options: ProductVariantOption[];
+}
+
+export interface ProductOption {
+  name: string;
+  values: string[];
+}
+
+export interface ProductDetails {
+  productId: string;
+  virtualParentId?: string;
+  title: string;
+  options: ProductOption[];
+  variants: ProductVariant[];
+}

package/src/application/models/validators/__tests__/validateUserEvent.test.ts

@@ -0,0 +1,41 @@
+import { UserEventCategory } from '@spiffy-ai/commerce-api-client';
+import { validateUserEvent } from 'src/application/models/validators/validateUserEvent';
+
+describe('validateUserEvent', () => {
+  it('preserves productId, parentProductId, and url for an AddToCart event', () => {
+    const result = validateUserEvent({
+      event_id: 'event-1',
+      created_at: '2026-07-20T00:00:00.000Z',
+      category: UserEventCategory.AddToCart,
+      attributes: {
+        product_id: 'product-1',
+        parent_product_id: 'parent-1',
+        url: 'https://example.com/product-1',
+      },
+    });
+
+    expect(result).toEqual({
+      eventId: 'event-1',
+      createdAt: '2026-07-20T00:00:00.000Z',
+      category: UserEventCategory.AddToCart,
+      attributes: {
+        productId: 'product-1',
+        parentProductId: 'parent-1',
+        url: 'https://example.com/product-1',
+      },
+    });
+  });
+
+  it('does not fall through to AppLoaded for an AddToCart event', () => {
+    const result = validateUserEvent({
+      event_id: 'event-1',
+      created_at: '2026-07-20T00:00:00.000Z',
+      category: UserEventCategory.AddToCart,
+      attributes: {
+        product_id: 'product-1',
+      },
+    });
+
+    expect(result?.category).toBe(UserEventCategory.AddToCart);
+  });
+});

package/src/application/models/validators/validateResponse.ts

@@ -48,6 +48,7 @@ export const validateResponse = (data: unknown): Response | undefined => {
       category: ResponseCategory.Product,
       attributes: {
         id: data.attributes.id,
+        itemGroupId: data.attributes.item_group_id,
         description: data.attributes.description,
         imageUrl: data.attributes.image_url,
         imageUrls: data.attributes.image_urls,

package/src/application/models/validators/validateUserEvent.ts

@@ -16,11 +16,16 @@ export const validateUserEvent = (data: unknown): UserEvent | undefined => {
     return undefined;
   }
 
-  if (data.category === UserEventCategory.PdpVisit && isApiPDPAttributes(data.attributes)) {
+  // PdpVisit and AddToCart share the same attributes structure
+  if (
+    (data.category === UserEventCategory.PdpVisit ||
+      data.category === UserEventCategory.AddToCart) &&
+    isApiPDPAttributes(data.attributes)
+  ) {
     return {
       eventId: data.event_id,
       createdAt: data.created_at,
-      category: UserEventCategory.PdpVisit,
+      category: data.category,
       attributes: {
         productId: data.attributes.product_id,
         parentProductId: data.attributes.parent_product_id,

package/src/application/utils/__tests__/messageFromAddToCartEvent.test.ts

@@ -0,0 +1,109 @@
+import { UserEventCategory } from '@spiffy-ai/commerce-api-client';
+import { MessageRole, MessageType, UserEvent } from 'src/application/models';
+import { messageFromAddToCartEvent } from '../messageFromAddToCartEvent';
+
+describe('messageFromAddToCartEvent', () => {
+  it('builds a user message from an AddToCart event', () => {
+    const event: UserEvent = {
+      eventId: 'event-1',
+      createdAt: '2026-07-20T00:00:00.000Z',
+      category: UserEventCategory.AddToCart,
+      attributes: {
+        productId: 'product-1',
+        parentProductId: '',
+        url: '',
+      },
+    };
+
+    expect(messageFromAddToCartEvent(event)).toEqual({
+      id: 'event-1',
+      role: MessageRole.User,
+      type: MessageType.QueryTyped,
+      createdAt: '2026-07-20T00:00:00.000Z',
+      metadata: {
+        content: 'Add product-1 to my cart',
+      },
+    });
+  });
+
+  it('returns undefined for a non-AddToCart event', () => {
+    const event: UserEvent = {
+      eventId: 'event-1',
+      createdAt: '2026-07-20T00:00:00.000Z',
+      category: UserEventCategory.AppLoaded,
+    };
+
+    expect(messageFromAddToCartEvent(event)).toBeUndefined();
+  });
+
+  it('prefers the explicit productTitle override parameter', () => {
+    const event: UserEvent = {
+      eventId: 'event-1',
+      createdAt: '2026-07-20T00:00:00.000Z',
+      category: UserEventCategory.AddToCart,
+      attributes: {
+        productId: 'product-1',
+        parentProductId: '',
+        url: '',
+        productTitle: 'Attribute Title',
+      },
+    };
+
+    expect(messageFromAddToCartEvent(event, 'Override Title')).toEqual({
+      id: 'event-1',
+      role: MessageRole.User,
+      type: MessageType.QueryTyped,
+      createdAt: '2026-07-20T00:00:00.000Z',
+      metadata: {
+        content: 'Add Override Title to my cart',
+      },
+    });
+  });
+
+  it('falls back to event.attributes.productTitle when no override is passed', () => {
+    const event: UserEvent = {
+      eventId: 'event-1',
+      createdAt: '2026-07-20T00:00:00.000Z',
+      category: UserEventCategory.AddToCart,
+      attributes: {
+        productId: 'product-1',
+        parentProductId: '',
+        url: '',
+        productTitle: 'Attribute Title',
+      },
+    };
+
+    expect(messageFromAddToCartEvent(event)).toEqual({
+      id: 'event-1',
+      role: MessageRole.User,
+      type: MessageType.QueryTyped,
+      createdAt: '2026-07-20T00:00:00.000Z',
+      metadata: {
+        content: 'Add Attribute Title to my cart',
+      },
+    });
+  });
+
+  it('falls back to the raw productId when neither a title override nor an attribute title is present', () => {
+    const event: UserEvent = {
+      eventId: 'event-1',
+      createdAt: '2026-07-20T00:00:00.000Z',
+      category: UserEventCategory.AddToCart,
+      attributes: {
+        productId: 'product-1',
+        parentProductId: '',
+        url: '',
+      },
+    };
+
+    expect(messageFromAddToCartEvent(event)).toEqual({
+      id: 'event-1',
+      role: MessageRole.User,
+      type: MessageType.QueryTyped,
+      createdAt: '2026-07-20T00:00:00.000Z',
+      metadata: {
+        content: 'Add product-1 to my cart',
+      },
+    });
+  });
+});

package/src/application/utils/index.ts

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