@faststore/core 4.4.1-dev.0 → 4.5.0-dev.1

package/src/utils/quoteStatus.ts

@@ -0,0 +1,27 @@
+export type QuoteStatusKey =
+  | 'Draft'
+  | 'Requested'
+  | 'InReview'
+  | 'Reviewed'
+  | 'Approved'
+  | 'Declined'
+  | 'Expired'
+  | 'ConvertedToCart'
+  | 'ConvertedToOrder'
+
+export type QuoteStatusMapValue = {
+  variant: 'neutral' | 'warning' | 'info' | 'success' | 'danger'
+  label: string
+}
+
+export const quoteStatusMap: Record<QuoteStatusKey, QuoteStatusMapValue> = {
+  Draft: { variant: 'neutral', label: 'Draft' },
+  Requested: { variant: 'warning', label: 'Requested' },
+  InReview: { variant: 'warning', label: 'In Review' },
+  Reviewed: { variant: 'info', label: 'Revised' },
+  Approved: { variant: 'success', label: 'Approved' },
+  Declined: { variant: 'danger', label: 'Declined' },
+  Expired: { variant: 'neutral', label: 'Expired' },
+  ConvertedToCart: { variant: 'success', label: 'Converted' },
+  ConvertedToOrder: { variant: 'success', label: 'Converted to Order' },
+}

package/src/utils/retry.ts

@@ -0,0 +1,69 @@
+export interface RetryOptions<T> {
+  /**
+   * Maximum number of retries after the initial attempt.
+   * @default 5
+   */
+  attempts?: number
+  /**
+   * Delay between attempts, in milliseconds.
+   * @default 500
+   */
+  delayMs?: number
+  /**
+   * Doubles the delay after each attempt, capped at `maxDelayMs`.
+   * @default false
+   */
+  backoff?: boolean
+  /**
+   * Upper bound for the delay when `backoff` is enabled.
+   * @default 3000
+   */
+  maxDelayMs?: number
+  /**
+   * Stops retrying once this predicate returns `true`. Defaults to "the value
+   * is truthy".
+   */
+  until?: (value: T) => boolean
+  /**
+   * Aborts the retry loop early (e.g. on component unmount).
+   */
+  signal?: AbortSignal
+}
+
+// Repeatedly calls `fn` until `until` is satisfied or the retry budget is
+// exhausted. Useful when a value is produced asynchronously by an external
+// script (e.g. a cookie set by a pixel, or an endpoint that is not ready on
+// the first call). Returns the last value produced, even when the budget runs
+// out, so callers can decide how to handle the give-up case.
+export async function retry<T>(
+  fn: () => T | Promise<T>,
+  {
+    attempts = 5,
+    delayMs = 500,
+    backoff = false,
+    maxDelayMs = 3000,
+    until = Boolean,
+    signal,
+  }: RetryOptions<T> = {}
+): Promise<T> {
+  let value = await fn()
+  let delay = delayMs
+  let remaining = attempts
+
+  while (!until(value) && remaining > 0 && !signal?.aborted) {
+    await new Promise((resolve) => setTimeout(resolve, delay))
+
+    if (signal?.aborted) {
+      break
+    }
+
+    value = await fn()
+    remaining -= 1
+
+    if (backoff) {
+      delay = Math.min(delay * 2, maxDelayMs)
+    }
+  }
+
+  return value
+}

package/test/components/RecommendationShelf/RecommendationShelf.browser.test.tsx

@@ -0,0 +1,235 @@
+import '@testing-library/jest-dom/vitest'
+import React from 'react'
+import { render, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const usePDP = vi.hoisted(() => vi.fn())
+vi.mock('@faststore/core', () => ({ usePDP }))
+
+vi.mock('@faststore/ui', () => {
+  const passthrough = ({ children }: React.PropsWithChildren) =>
+    React.createElement(React.Fragment, null, children)
+  return { ProductShelf: passthrough, Carousel: passthrough }
+})
+
+vi.mock('src/components/product/ProductCard', () => ({
+  default: () => React.createElement('div', { 'data-testid': 'product-card' }),
+}))
+
+vi.mock('src/components/skeletons/ProductShelfSkeleton', () => ({
+  default: ({
+    children,
+    loading,
+  }: React.PropsWithChildren<{ loading?: boolean }>) =>
+    React.createElement(
+      'div',
+      { 'data-testid': 'skeleton', 'data-loading': String(!!loading) },
+      children
+    ),
+}))
+
+const useRecommendations = vi.hoisted(() => vi.fn())
+vi.mock(
+  'src/components/sections/RecommendationShelf/useRecommendations',
+  () => ({
+    useRecommendations,
+  })
+)
+
+const useScreenResize = vi.hoisted(() => vi.fn())
+vi.mock('src/sdk/ui/useScreenResize', () => ({ default: useScreenResize }))
+
+const useRecommendationUserId = vi.hoisted(() => vi.fn())
+vi.mock(
+  'src/components/sections/RecommendationShelf/useRecommendationUserId',
+  () => ({
+    useRecommendationUserId,
+  })
+)
+
+// Keep the real store config (the cart SDK reads `storeConfig.cart` at module
+// init) and only override the opt-in flag, which we toggle per test.
+const recommendationsFlag = vi.hoisted(() => ({ enabled: true }))
+vi.mock('discovery.config', async (original) => {
+  const actual = (await original()) as { default?: Record<string, unknown> }
+  const base = (actual.default ?? actual) as Record<string, unknown>
+  const experimental = (base.experimental ?? {}) as Record<string, unknown>
+
+  return {
+    default: {
+      ...base,
+      experimental: {
+        ...experimental,
+        get enableRecommendations() {
+          return recommendationsFlag.enabled
+        },
+      },
+    },
+  }
+})
+
+import { RecommendationShelf } from 'src/components/sections/RecommendationShelf/RecommendationShelf'
+
+const CAMPAIGN_VRN = 'vrn:recommendations:acc:rec-top-items-v2:campaign-1'
+const CROSS_SELL_VRN = 'vrn:recommendations:acc:rec-cross-v2:campaign-1'
+
+const recommendationData = {
+  products: [
+    { id: 'p-1', isVariantOf: { productGroupID: 'p-1' } },
+    { id: 'p-2', isVariantOf: { productGroupID: 'p-2' } },
+  ],
+  correlationId: 'corr-1',
+  campaign: { id: 'camp-1', title: 'Recommended for you', type: 'TOP_ITEMS' },
+}
+
+beforeEach(() => {
+  usePDP.mockReturnValue({ data: undefined })
+  useScreenResize.mockReturnValue({
+    isMobile: false,
+    isTablet: false,
+    isDesktop: true,
+    loading: false,
+  })
+  useRecommendationUserId.mockReturnValue('user-1')
+  recommendationsFlag.enabled = true
+})
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('RecommendationShelf', () => {
+  it('renders a product card per recommended product', async () => {
+    useRecommendations.mockReturnValue({
+      data: recommendationData,
+      isLoading: false,
+      error: null,
+    })
+
+    const { getAllByTestId, getByText } = render(
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+    )
+
+    await waitFor(() => {
+      expect(getAllByTestId('product-card')).toHaveLength(2)
+    })
+    expect(getByText('Recommended for you')).toBeTruthy()
+  })
+
+  it('requests cross-sell recommendations using the current PDP product', async () => {
+    usePDP.mockReturnValue({
+      data: { product: { isVariantOf: { productGroupID: 'pg-1' } } },
+    })
+    useRecommendations.mockReturnValue({
+      data: recommendationData,
+      isLoading: false,
+      error: null,
+    })
+
+    render(<RecommendationShelf campaignVrn={CROSS_SELL_VRN} />)
+
+    await waitFor(() => {
+      const lastArgs = useRecommendations.mock.calls.at(-1)?.[0]
+      expect(lastArgs).toEqual({
+        userId: 'user-1',
+        campaignVrn: CROSS_SELL_VRN,
+        products: ['pg-1'],
+      })
+    })
+  })
+
+  it('prefers the provided title over the campaign title', async () => {
+    useRecommendations.mockReturnValue({
+      data: recommendationData,
+      isLoading: false,
+      error: null,
+    })
+
+    const { getByText } = render(
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} title="Custom title" />
+    )
+
+    await waitFor(() => {
+      expect(getByText('Custom title')).toBeTruthy()
+    })
+  })
+
+  it('skips the fetch and renders empty when there is no resolved userId', async () => {
+    useRecommendationUserId.mockReturnValue(null)
+    useRecommendations.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      error: null,
+    })
+
+    const { container, queryByTestId } = render(
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+    )
+
+    await waitFor(() => {
+      const lastArgs = useRecommendations.mock.calls.at(-1)?.[0]
+      expect(lastArgs).toBeNull()
+    })
+    expect(queryByTestId('product-card')).toBeNull()
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('renders nothing when there is an error', () => {
+    useRecommendations.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      error: new Error('boom'),
+    })
+
+    const { container } = render(
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+    )
+
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('renders nothing when there are no items and loading has finished', () => {
+    useRecommendations.mockReturnValue({
+      data: { ...recommendationData, products: [] },
+      isLoading: false,
+      error: null,
+    })
+
+    const { container, queryByTestId } = render(
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+    )
+
+    expect(queryByTestId('product-card')).toBeNull()
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('shows the skeleton while loading', () => {
+    useRecommendations.mockReturnValue({
+      data: undefined,
+      isLoading: true,
+      error: null,
+    })
+
+    const { getByTestId } = render(
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+    )
+
+    expect(getByTestId('skeleton').getAttribute('data-loading')).toBe('true')
+  })
+
+  it('skips the fetch when recommendations are disabled', async () => {
+    recommendationsFlag.enabled = false
+    useRecommendations.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      error: null,
+    })
+
+    render(<RecommendationShelf campaignVrn={CROSS_SELL_VRN} />)
+
+    await waitFor(() => {
+      const lastArgs = useRecommendations.mock.calls.at(-1)?.[0]
+      expect(lastArgs).toBeNull()
+    })
+  })
+})

package/test/components/RecommendationShelf/useRecommendationUserId.test.ts

@@ -0,0 +1,69 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { renderHook, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const getUserIdFromCookie = vi.hoisted(() => vi.fn())
+vi.mock('src/sdk/analytics/utils', () => ({ getUserIdFromCookie }))
+
+// Run the retried function once and resolve/reject with its result so the tests
+// don't wait on the real backoff schedule.
+vi.mock('src/utils/retry', () => ({
+  retry: (fn: () => unknown) => Promise.resolve().then(fn),
+}))
+
+import { useRecommendationUserId } from 'src/components/sections/RecommendationShelf/useRecommendationUserId'
+
+const CAMPAIGN_VRN = 'vrn:recommendations:acc:rec-top-items-v2:campaign-1'
+
+beforeEach(() => {
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('useRecommendationUserId', () => {
+  it('starts as undefined while resolving', () => {
+    getUserIdFromCookie.mockReturnValue('user-1')
+
+    const { result } = renderHook(() => useRecommendationUserId(CAMPAIGN_VRN))
+
+    expect(result.current).toBeUndefined()
+  })
+
+  it('resolves the user id from the cookie', async () => {
+    getUserIdFromCookie.mockReturnValue('user-1')
+
+    const { result } = renderHook(() => useRecommendationUserId(CAMPAIGN_VRN))
+
+    await waitFor(() => {
+      expect(result.current).toBe('user-1')
+    })
+  })
+
+  it('resolves to null when the cookie has no usable id', async () => {
+    getUserIdFromCookie.mockReturnValue('')
+
+    const { result } = renderHook(() => useRecommendationUserId(CAMPAIGN_VRN))
+
+    await waitFor(() => {
+      expect(result.current).toBeNull()
+    })
+  })
+
+  it('resolves to null when the lookup throws', async () => {
+    getUserIdFromCookie.mockImplementation(() => {
+      throw new Error('boom')
+    })
+
+    const { result } = renderHook(() => useRecommendationUserId(CAMPAIGN_VRN))
+
+    await waitFor(() => {
+      expect(result.current).toBeNull()
+    })
+  })
+})

package/test/components/RecommendationShelf/useRecommendations.test.ts

@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@faststore/core/api', () => ({ gql: () => ({ __meta__: {} }) }))
+
+const useQueryMock = vi.hoisted(() => vi.fn())
+vi.mock('src/sdk/graphql/useQuery', () => ({
+  useQuery: useQueryMock,
+}))
+
+import { useRecommendations } from 'src/components/sections/RecommendationShelf/useRecommendations'
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('useRecommendations', () => {
+  it('does not run the query when args are null', () => {
+    useQueryMock.mockReturnValue({
+      data: undefined,
+      error: null,
+      isLoading: false,
+    })
+
+    const { data } = useRecommendations(null)
+
+    expect(data).toBeUndefined()
+    const options = useQueryMock.mock.calls[0][2]
+    expect(options.doNotRun).toBe(true)
+  })
+
+  it('unwraps the recommendations payload when args are provided', () => {
+    const recommendations = {
+      products: [{ productId: 'p-1' }],
+      correlationId: 'c-1',
+      campaign: { id: 'camp-1', title: 'Top', type: 'TOP_ITEMS' },
+    }
+
+    useQueryMock.mockReturnValue({
+      data: { recommendations },
+      error: null,
+      isLoading: false,
+    })
+
+    const args = { userId: 'u-1', campaignVrn: 'vrn:x', products: [] }
+    const { data, isLoading, error } = useRecommendations(args)
+
+    expect(data).toEqual(recommendations)
+    expect(isLoading).toBe(false)
+    expect(error).toBeNull()
+    expect(useQueryMock.mock.calls[0][2].doNotRun).toBe(false)
+  })
+})

package/test/components/RecommendationShelf/vrn.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  getTypeFromVrn,
+  isValidVrn,
+} from 'src/components/sections/RecommendationShelf/vrn'
+
+const vrn = (type: string) => `vrn:recommendations:account:${type}:campaign-1`
+
+describe('isValidVrn', () => {
+  it('accepts every supported campaign type', () => {
+    const types = [
+      'rec-cross-v2',
+      'rec-similar-v2',
+      'rec-persona-v2',
+      'rec-last-v2',
+      'rec-top-items-v2',
+      'rec-search-v2',
+      'rec-next-v2',
+      'rec-visual-v2',
+    ]
+
+    for (const type of types) {
+      expect(isValidVrn(vrn(type))).toBe(true)
+    }
+  })
+
+  it('rejects malformed or unknown vrns', () => {
+    expect(isValidVrn('not-a-vrn')).toBe(false)
+    expect(isValidVrn('vrn:recommendations:account:rec-unknown:campaign')).toBe(
+      false
+    )
+    expect(isValidVrn('vrn:recommendations:account:rec-cross-v2')).toBe(false)
+  })
+})
+
+describe('getTypeFromVrn', () => {
+  it('maps each vrn type to its recommendation type', () => {
+    expect(getTypeFromVrn(vrn('rec-cross-v2'))).toBe('CROSS_SELL')
+    expect(getTypeFromVrn(vrn('rec-similar-v2'))).toBe('SIMILAR_ITEMS')
+    expect(getTypeFromVrn(vrn('rec-persona-v2'))).toBe('PERSONALIZED')
+    expect(getTypeFromVrn(vrn('rec-last-v2'))).toBe('LAST_SEEN')
+    expect(getTypeFromVrn(vrn('rec-top-items-v2'))).toBe('TOP_ITEMS')
+    expect(getTypeFromVrn(vrn('rec-search-v2'))).toBe('SEARCH_BASED')
+    expect(getTypeFromVrn(vrn('rec-next-v2'))).toBe('NEXT_INTERACTION')
+    expect(getTypeFromVrn(vrn('rec-visual-v2'))).toBe('VISUAL_SIMILARITY')
+  })
+
+  it('returns null on an unknown campaign type', () => {
+    expect(getTypeFromVrn(vrn('rec-bogus'))).toBeNull()
+  })
+
+  it('returns null on a malformed vrn', () => {
+    expect(getTypeFromVrn('not-a-vrn')).toBeNull()
+  })
+})