@envive-ai/react-hooks 0.3.46 → 0.3.48

package/src/hooks/AddToCart/__tests__/useAddToCart.test.tsx

@@ -0,0 +1,204 @@
+import { UserEventCategory } from '@spiffy-ai/commerce-api-client';
+import { renderHook } from '@testing-library/react';
+import { Provider, createStore } from 'jotai';
+import React from 'react';
+import { addToCartCallbackAtom, enviveConfigAtom } from 'src/atoms/envive/enviveConfig';
+import { newOrgConfigAtom } from 'src/atoms/org';
+import { GraphQlConfigValues } from 'src/contexts/graphqlContext';
+import { createAddToCartUserEvent } from '../createAddToCartUserEvent';
+import { useAddToCart } from '../useAddToCart';
+
+const enabledUiConfig = {
+  frontendConfig: {
+    uiConfigs: {
+      lookAndFeel: {
+        addToCart: {
+          enabled: true,
+          backgroundColor: 'var(--envive-colors-background-dark)',
+          textColor: 'var(--envive-colors-text-light)',
+          ctaText: 'Add to Cart',
+        },
+      },
+    },
+  },
+} as unknown as GraphQlConfigValues;
+
+const disabledUiConfig = {
+  frontendConfig: {
+    uiConfigs: {
+      lookAndFeel: {
+        addToCart: { enabled: false },
+      },
+    },
+  },
+} as unknown as GraphQlConfigValues;
+
+const configFunctionUiConfig = (addToCartFunction: string) =>
+  ({
+    frontendConfig: {
+      uiConfigs: {
+        lookAndFeel: {
+          addToCart: {
+            enabled: true,
+            addToCartFunction,
+          },
+        },
+      },
+    },
+  }) as unknown as GraphQlConfigValues;
+
+const renderUseAddToCart = (store: ReturnType<typeof createStore>) => {
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    // The jotai Provider is typed against the root @types/react (18) while this
+    // package resolves @types/react 19; the cast bridges the two ReactNode types.
+    <Provider store={store}>{children as React.ReactElement<unknown, string>}</Provider>
+  );
+  return renderHook(() => useAddToCart(), { wrapper });
+};
+
+describe('addToCartCallbackAtom', () => {
+  it('returns undefined when no config is set', () => {
+    const store = createStore();
+    expect(store.get(addToCartCallbackAtom)).toBeUndefined();
+  });
+
+  it('returns the callback from the envive config', () => {
+    const store = createStore();
+    const addToCart = vi.fn();
+    store.set(enviveConfigAtom, { identifyingPrefix: 'test', addToCart });
+    expect(store.get(addToCartCallbackAtom)).toBe(addToCart);
+  });
+});
+
+describe('useAddToCart', () => {
+  it('is enabled when both the callback and the enabled ui config are present', () => {
+    const store = createStore();
+    const addToCart = vi.fn();
+    store.set(enviveConfigAtom, { identifyingPrefix: 'test', addToCart });
+    store.set(newOrgConfigAtom, enabledUiConfig);
+
+    const { result } = renderUseAddToCart(store);
+
+    expect(result.current.isAddToCartEnabled).toBe(true);
+    expect(result.current.addToCart).toBe(addToCart);
+    expect(result.current.config).toEqual({
+      enabled: true,
+      backgroundColor: 'var(--envive-colors-background-dark)',
+      textColor: 'var(--envive-colors-text-light)',
+      ctaText: 'Add to Cart',
+    });
+  });
+
+  it('is disabled when only the callback is present', () => {
+    const store = createStore();
+    store.set(enviveConfigAtom, { identifyingPrefix: 'test', addToCart: vi.fn() });
+
+    const { result } = renderUseAddToCart(store);
+
+    expect(result.current.isAddToCartEnabled).toBe(false);
+  });
+
+  it('is disabled when only the ui config is present', () => {
+    const store = createStore();
+    store.set(newOrgConfigAtom, enabledUiConfig);
+
+    const { result } = renderUseAddToCart(store);
+
+    expect(result.current.isAddToCartEnabled).toBe(false);
+    expect(result.current.addToCart).toBeUndefined();
+  });
+
+  it('is disabled when the ui config section is disabled', () => {
+    const store = createStore();
+    store.set(enviveConfigAtom, { identifyingPrefix: 'test', addToCart: vi.fn() });
+    store.set(newOrgConfigAtom, disabledUiConfig);
+
+    const { result } = renderUseAddToCart(store);
+
+    expect(result.current.isAddToCartEnabled).toBe(false);
+  });
+
+  it('is disabled when neither gate is present', () => {
+    const store = createStore();
+
+    const { result } = renderUseAddToCart(store);
+
+    expect(result.current.isAddToCartEnabled).toBe(false);
+    expect(result.current.addToCart).toBeUndefined();
+    expect(result.current.config).toBeUndefined();
+  });
+
+  it('falls back to the parsed config function when no window callback is set', () => {
+    const store = createStore();
+    store.set(
+      newOrgConfigAtom,
+      configFunctionUiConfig('function(params) { globalThis.__uatCalls = [params]; }'),
+    );
+
+    const { result } = renderUseAddToCart(store);
+
+    expect(result.current.isAddToCartEnabled).toBe(true);
+    result.current.addToCart?.({ product_id: 'config-fn' });
+    expect((globalThis as Record<string, unknown>).__uatCalls).toEqual([
+      { product_id: 'config-fn' },
+    ]);
+  });
+
+  it('prefers the window callback over the config function when both are present', () => {
+    const store = createStore();
+    const windowAddToCart = vi.fn();
+    store.set(enviveConfigAtom, { identifyingPrefix: 'test', addToCart: windowAddToCart });
+    store.set(
+      newOrgConfigAtom,
+      configFunctionUiConfig('function(params) { globalThis.__uatCalls = [params]; }'),
+    );
+
+    const { result } = renderUseAddToCart(store);
+
+    expect(result.current.isAddToCartEnabled).toBe(true);
+    expect(result.current.addToCart).toBe(windowAddToCart);
+  });
+
+  it('is disabled when the config function string is invalid and no window callback is set', () => {
+    const store = createStore();
+    store.set(newOrgConfigAtom, configFunctionUiConfig('function( { broken'));
+
+    const { result } = renderUseAddToCart(store);
+
+    expect(result.current.isAddToCartEnabled).toBe(false);
+    expect(result.current.addToCart).toBeUndefined();
+  });
+});
+
+describe('createAddToCartUserEvent', () => {
+  it('creates an AddToCart user event with the product attributes', () => {
+    const event = createAddToCartUserEvent({
+      productId: 'product-1',
+      parentProductId: 'group-1',
+      url: 'https://example.com/product-1',
+    });
+
+    expect(event.category).toBe(UserEventCategory.AddToCart);
+    expect(event.eventId).toEqual(expect.any(String));
+    expect(event.createdAt).toEqual(expect.any(String));
+    expect(event).toMatchObject({
+      attributes: {
+        productId: 'product-1',
+        parentProductId: 'group-1',
+        url: 'https://example.com/product-1',
+      },
+    });
+  });
+
+  it('defaults optional attributes to empty strings', () => {
+    const event = createAddToCartUserEvent({ productId: 'product-1' });
+
+    expect(event).toMatchObject({
+      attributes: {
+        productId: 'product-1',
+        parentProductId: '',
+        url: '',
+      },
+    });
+  });
+});

package/src/hooks/AddToCart/addToCartErrorMessage.ts

@@ -0,0 +1,2 @@
+export const ADD_TO_CART_ERROR_MESSAGE =
+  "I'm sorry, I couldn't add that to your cart. Please try again, or add it directly from your cart.";

package/src/hooks/AddToCart/createAddToCartUserEvent.ts

@@ -0,0 +1,25 @@
+import { UserEventCategory } from '@spiffy-ai/commerce-api-client';
+import { UserEvent } from 'src/application/models';
+import { v4 as uuid } from 'uuid';
+
+export const createAddToCartUserEvent = ({
+  productId,
+  parentProductId,
+  url,
+  productTitle,
+}: {
+  productId: string;
+  parentProductId?: string;
+  url?: string;
+  productTitle?: string;
+}): UserEvent => ({
+  eventId: uuid(),
+  createdAt: new Date().toISOString(),
+  category: UserEventCategory.AddToCart,
+  attributes: {
+    productId,
+    parentProductId: parentProductId ?? '',
+    url: url ?? '',
+    productTitle,
+  },
+});

package/src/hooks/AddToCart/index.ts

@@ -0,0 +1,4 @@
+export * from './addToCartErrorMessage';
+export * from './createAddToCartUserEvent';
+export * from './parseAddToCartFunction';
+export * from './useAddToCart';

package/src/hooks/AddToCart/parseAddToCartFunction.ts

@@ -0,0 +1,31 @@
+import Logger from 'src/application/logging/logger';
+import { AddToCartCallback } from 'src/types/enviveConfig';
+
+const logger = new Logger('parseAddToCartFunction');
+
+/**
+ * Parses a merchant-supplied `add_to_cart_function` config string into a
+ * callable. The string is expected to evaluate to a function matching
+ * AddToCartCallback, e.g. "function(params) { window.myCart.add(params.product_id); }".
+ */
+export const parseAddToCartFunction = (
+  fnString: string | undefined,
+): AddToCartCallback | undefined => {
+  if (!fnString) {
+    return undefined;
+  }
+
+  try {
+    const parsed = new Function(`return (${fnString});`)();
+    if (typeof parsed !== 'function') {
+      logger.logError('add_to_cart_function did not evaluate to a function', undefined, {
+        fnString,
+      });
+      return undefined;
+    }
+    return parsed as AddToCartCallback;
+  } catch (error) {
+    logger.logError('Failed to parse add_to_cart_function', error, { fnString });
+    return undefined;
+  }
+};

package/src/hooks/AddToCart/useAddToCart.ts

@@ -0,0 +1,35 @@
+import { useAtomValue } from 'jotai';
+import { useMemo } from 'react';
+import { addToCartCallbackAtom } from 'src/atoms/envive/enviveConfig';
+import { newOrgConfigAtom } from 'src/atoms/org';
+import { AddToCartConfig, OrgUIConfigV3 } from 'src/contexts/typesV3';
+import { AddToCartCallback } from 'src/types/enviveConfig';
+import { parseAddToCartFunction } from './parseAddToCartFunction';
+
+export interface AddToCartHookResult {
+  /** True only when the org UI config enables add-to-cart AND a callback is available. */
+  isAddToCartEnabled: boolean;
+  addToCart?: AddToCartCallback;
+  config?: AddToCartConfig;
+}
+
+export const useAddToCart = (): AddToCartHookResult => {
+  const windowAddToCart = useAtomValue(addToCartCallbackAtom);
+  const newOrgConfig = useAtomValue(newOrgConfigAtom);
+  const uiConfigs = newOrgConfig?.frontendConfig?.uiConfigs as OrgUIConfigV3 | undefined;
+  const config = uiConfigs?.lookAndFeel?.addToCart;
+
+  const configAddToCart = useMemo(
+    () => parseAddToCartFunction(config?.addToCartFunction),
+    [config?.addToCartFunction],
+  );
+
+  // window._spiffy/_envive.addToCart always overrides the config-provided function.
+  const addToCart = windowAddToCart ?? configAddToCart;
+
+  return {
+    isAddToCartEnabled: Boolean(config?.enabled && addToCart),
+    addToCart,
+    config,
+  };
+};

package/src/hooks/PageViewedEvent/usePageViewedEvent.ts

@@ -1,6 +1,7 @@
 import { useAtomValue } from 'jotai';
 import { useEffect, useRef } from 'react';
 import { VariantTypeEnum } from 'src/application/models';
+import { getQueryParam } from 'src/application/utils/urlsParser';
 import { hasParsedVariantInfoAtom, variantInfoAtom } from 'src/atoms/app/variant';
 import { EnviveMetricsEventName, useAmplitude } from 'src/contexts/amplitudeContext';
 import { usePage } from 'src/contexts/pageContext';
@@ -87,6 +88,8 @@ export const usePageViewedEvent = () => {
 
     hasFired.current = true;
 
+    const envivePlacement = getQueryParam('envive_placement');
+
     trackEvent({
       eventName: EnviveMetricsEventName.PageViewed,
       eventProps: {
@@ -97,6 +100,7 @@ export const usePageViewedEvent = () => {
         'context.supported': isSupported,
         'context.ready': isSupported,
         'context.page_variant_id': variantInfo.variantId,
+        ...(envivePlacement ? { 'context.envive_placement': envivePlacement } : {}),
       },
     });
   }, [isLoading, isSupported, hasParsedVariantInfo, pageVariantInfo, variantInfo, trackEvent]);

package/src/hooks/ProductDetails/__tests__/useProductDetails.test.tsx

@@ -0,0 +1,129 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import CommerceApiClient from 'src/application/commerce-api';
+import { ProductDetails } from 'src/application/models/graphql/queries/getProductOptionsQuery';
+import { useProductDetails } from '../useProductDetails';
+
+const productDetails: ProductDetails = {
+  productId: 'small-time-teller-gold-black-gold',
+  virtualParentId: 'small-time-teller',
+  title: 'Small Time Teller',
+  options: [{ name: 'Color', values: ['Gold/Black/Gold', 'Silver'] }],
+  variants: [
+    {
+      variantId: 'variant-1',
+      available: true,
+      originalPrice: 125,
+      salePrice: 100,
+      imageUrl: 'https://example.com/variant-1.jpg',
+      url: 'https://example.com/products/small-time-teller?variant=1',
+      options: [{ name: 'Color', value: 'Gold/Black/Gold' }],
+    },
+  ],
+};
+
+describe('useProductDetails', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('stays idle and does not fetch when productId is undefined', () => {
+    const retrieveSpy = vi.spyOn(CommerceApiClient, 'retrieveProductDetails');
+
+    const { result } = renderHook(() => useProductDetails(undefined));
+
+    expect(result.current).toEqual({ data: undefined, isLoading: false, error: undefined });
+    expect(retrieveSpy).not.toHaveBeenCalled();
+  });
+
+  it('returns the product details after a successful fetch', async () => {
+    const retrieveSpy = vi
+      .spyOn(CommerceApiClient, 'retrieveProductDetails')
+      .mockResolvedValue(productDetails);
+
+    const { result } = renderHook(() => useProductDetails('small-time-teller-gold-black-gold'));
+
+    expect(result.current.isLoading).toBe(true);
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(retrieveSpy).toHaveBeenCalledWith('small-time-teller-gold-black-gold');
+    expect(result.current.data).toEqual(productDetails);
+    expect(result.current.error).toBeUndefined();
+  });
+
+  it('surfaces an error when the fetch fails', async () => {
+    vi.spyOn(CommerceApiClient, 'retrieveProductDetails').mockRejectedValue(
+      new Error('GraphQL request failed: Internal Server Error'),
+    );
+
+    const { result } = renderHook(() => useProductDetails('missing-product'));
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.data).toBeUndefined();
+    expect(result.current.error).toEqual(
+      new Error('GraphQL request failed: Internal Server Error'),
+    );
+  });
+
+  it('wraps non-Error rejections in an Error', async () => {
+    vi.spyOn(CommerceApiClient, 'retrieveProductDetails').mockRejectedValue('boom');
+
+    const { result } = renderHook(() => useProductDetails('missing-product'));
+
+    await waitFor(() => expect(result.current.error).toEqual(new Error('boom')));
+  });
+
+  it('resets to idle when productId becomes undefined', async () => {
+    vi.spyOn(CommerceApiClient, 'retrieveProductDetails').mockResolvedValue(productDetails);
+
+    const { result, rerender } = renderHook(({ productId }) => useProductDetails(productId), {
+      initialProps: { productId: 'small-time-teller-gold-black-gold' as string | undefined },
+    });
+    await waitFor(() => expect(result.current.data).toEqual(productDetails));
+
+    rerender({ productId: undefined });
+
+    expect(result.current).toEqual({ data: undefined, isLoading: false, error: undefined });
+  });
+
+  it('ignores a stale response when productId changes mid-flight', async () => {
+    let resolveFirst: (details: ProductDetails) => void = () => {};
+    const staleDetails = { ...productDetails, productId: 'stale-product' };
+    vi.spyOn(CommerceApiClient, 'retrieveProductDetails')
+      .mockImplementationOnce(
+        () =>
+          new Promise(resolve => {
+            resolveFirst = resolve;
+          }),
+      )
+      .mockResolvedValueOnce(productDetails);
+
+    const { result, rerender } = renderHook(({ productId }) => useProductDetails(productId), {
+      initialProps: { productId: 'stale-product' },
+    });
+
+    rerender({ productId: 'small-time-teller-gold-black-gold' });
+    resolveFirst(staleDetails);
+
+    await waitFor(() => expect(result.current.data).toEqual(productDetails));
+    expect(result.current.data?.productId).toBe('small-time-teller-gold-black-gold');
+  });
+
+  it('does not update state after unmount', async () => {
+    let resolveFetch: (details: ProductDetails) => void = () => {};
+    vi.spyOn(CommerceApiClient, 'retrieveProductDetails').mockImplementation(
+      () =>
+        new Promise(resolve => {
+          resolveFetch = resolve;
+        }),
+    );
+    const consoleErrorSpy = vi.spyOn(console, 'error');
+
+    const { unmount } = renderHook(() => useProductDetails('small-time-teller-gold-black-gold'));
+    unmount();
+    resolveFetch(productDetails);
+    await Promise.resolve();
+
+    expect(consoleErrorSpy).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/ProductDetails/__tests__/variantSelection.test.ts

@@ -0,0 +1,145 @@
+import {
+  ProductDetails,
+  ProductVariant,
+} from 'src/application/models/graphql/queries/getProductOptionsQuery';
+import {
+  findVariantForSelection,
+  getDefaultVariantSelection,
+  getSingleVariantId,
+  needsVariantSelection,
+} from '../variantSelection';
+
+const makeVariant = (overrides: Partial<ProductVariant>): ProductVariant => ({
+  variantId: 'variant-1',
+  available: true,
+  options: [],
+  ...overrides,
+});
+
+const multiVariantDetails: ProductDetails = {
+  productId: 'frypan-set',
+  title: 'Ceramic Nonstick Frypan',
+  options: [
+    { name: 'Size', values: ['8"', '10"'] },
+    { name: 'Color', values: ['Grey', 'Black'] },
+  ],
+  variants: [
+    makeVariant({
+      variantId: 'v-8-grey',
+      available: false,
+      options: [
+        { name: 'Size', value: '8"' },
+        { name: 'Color', value: 'Grey' },
+      ],
+    }),
+    makeVariant({
+      variantId: 'v-8-black',
+      available: true,
+      options: [
+        { name: 'Size', value: '8"' },
+        { name: 'Color', value: 'Black' },
+      ],
+    }),
+    makeVariant({
+      variantId: 'v-10-grey',
+      available: true,
+      options: [
+        { name: 'Size', value: '10"' },
+        { name: 'Color', value: 'Grey' },
+      ],
+    }),
+  ],
+};
+
+describe('needsVariantSelection', () => {
+  it('is true for multiple variants with a real choice', () => {
+    expect(needsVariantSelection(multiVariantDetails)).toBe(true);
+  });
+
+  it('is false for undefined details', () => {
+    expect(needsVariantSelection(undefined)).toBe(false);
+  });
+
+  it('is false for a single variant', () => {
+    expect(
+      needsVariantSelection({
+        ...multiVariantDetails,
+        variants: [multiVariantDetails.variants[0]],
+      }),
+    ).toBe(false);
+  });
+
+  it('is false when no option offers more than one value', () => {
+    expect(
+      needsVariantSelection({
+        ...multiVariantDetails,
+        options: [
+          { name: 'Size', values: ['8"'] },
+          { name: 'Color', values: ['Grey'] },
+        ],
+      }),
+    ).toBe(false);
+  });
+
+  it('is false when there are no options at all', () => {
+    expect(needsVariantSelection({ ...multiVariantDetails, options: [] })).toBe(false);
+  });
+});
+
+describe('getSingleVariantId', () => {
+  it('returns the variantId when exactly one variant exists', () => {
+    expect(
+      getSingleVariantId({ ...multiVariantDetails, variants: [multiVariantDetails.variants[1]] }),
+    ).toBe('v-8-black');
+  });
+
+  it('returns undefined for multiple variants', () => {
+    expect(getSingleVariantId(multiVariantDetails)).toBeUndefined();
+  });
+
+  it('returns undefined for undefined details', () => {
+    expect(getSingleVariantId(undefined)).toBeUndefined();
+  });
+});
+
+describe('getDefaultVariantSelection', () => {
+  it('uses the first available variant', () => {
+    expect(getDefaultVariantSelection(multiVariantDetails)).toEqual({
+      Size: '8"',
+      Color: 'Black',
+    });
+  });
+
+  it('falls back to the first variant when none are available', () => {
+    const details = {
+      ...multiVariantDetails,
+      variants: multiVariantDetails.variants.map(v => ({ ...v, available: false })),
+    };
+    expect(getDefaultVariantSelection(details)).toEqual({ Size: '8"', Color: 'Grey' });
+  });
+
+  it('falls back to first option values when there are no variants', () => {
+    expect(getDefaultVariantSelection({ ...multiVariantDetails, variants: [] })).toEqual({
+      Size: '8"',
+      Color: 'Grey',
+    });
+  });
+});
+
+describe('findVariantForSelection', () => {
+  it('finds the variant matching the selection exactly', () => {
+    expect(
+      findVariantForSelection(multiVariantDetails, { Size: '10"', Color: 'Grey' })?.variantId,
+    ).toBe('v-10-grey');
+  });
+
+  it('returns undefined for a combination that does not exist', () => {
+    expect(
+      findVariantForSelection(multiVariantDetails, { Size: '10"', Color: 'Black' }),
+    ).toBeUndefined();
+  });
+
+  it('returns undefined for a partial selection', () => {
+    expect(findVariantForSelection(multiVariantDetails, { Size: '8"' })).toBeUndefined();
+  });
+});

package/src/hooks/ProductDetails/index.ts

@@ -0,0 +1,2 @@
+export * from './useProductDetails';
+export * from './variantSelection';

package/src/hooks/ProductDetails/useProductDetails.ts

@@ -0,0 +1,62 @@
+import { useEffect, useState } from 'react';
+import CommerceApiClient from 'src/application/commerce-api';
+import { ProductDetails } from 'src/application/models/graphql/queries/getProductOptionsQuery';
+
+export type {
+  ProductDetails,
+  ProductOption,
+  ProductVariant,
+  ProductVariantOption,
+} from 'src/application/models/graphql/queries/getProductOptionsQuery';
+
+export interface UseProductDetailsResult {
+  data: ProductDetails | undefined;
+  isLoading: boolean;
+  error: Error | undefined;
+}
+
+/**
+ * Fetches variant-level product details (options, availability, pricing, images)
+ * for the given product ID via CommerceApiClient.retrieveProductDetails (GraphQL
+ * `me.productOptions`). Only meaningful for products that offer variations.
+ *
+ * Returns an idle result ({ data: undefined, isLoading: false, error: undefined })
+ * when productId is not provided.
+ */
+export const useProductDetails = (productId: string | undefined): UseProductDetailsResult => {
+  const [data, setData] = useState<ProductDetails | undefined>(undefined);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | undefined>(undefined);
+
+  useEffect(() => {
+    if (!productId) {
+      setData(undefined);
+      setIsLoading(false);
+      setError(undefined);
+      return undefined;
+    }
+    let cancelled = false;
+    setData(undefined);
+    setError(undefined);
+    setIsLoading(true);
+    CommerceApiClient.retrieveProductDetails(productId).then(
+      result => {
+        if (!cancelled) {
+          setData(result);
+          setIsLoading(false);
+        }
+      },
+      err => {
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+          setIsLoading(false);
+        }
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [productId]);
+
+  return { data, isLoading, error };
+};