@faststore/core 4.6.0-dev.1 → 4.6.0-dev.3

package/src/sdk/recommendations/useRecommendationShelf.ts

@@ -0,0 +1,141 @@
+import { usePDP } from '@faststore/core'
+import { useMemo } from 'react'
+
+import { useCart } from 'src/sdk/cart'
+
+import type { ItemContext } from './types'
+import {
+  type RecommendationInput,
+  type RecommendationResponse,
+  useRecommendations,
+} from './useRecommendations'
+import { useRecommendationUserId } from './useRecommendationUserId'
+import { getTypeFromVrn } from './vrn'
+
+export function getRecommendationArguments(
+  campaignVrn: string,
+  context: { userId?: string | null; contextProducts: string[] }
+): RecommendationInput | null {
+  const { userId, contextProducts } = context
+  const type = getTypeFromVrn(campaignVrn)
+
+  // `type` is null for malformed/unknown VRNs; bail out so we never fetch (and
+  // never throw) on an invalid campaign coming from the CMS.
+  if (!type || !userId) return null
+
+  switch (type) {
+    case 'NEXT_INTERACTION':
+    case 'VISUAL_SIMILARITY':
+    case 'CROSS_SELL':
+    case 'SIMILAR_ITEMS':
+      // These campaigns need product context. Without any (e.g. `CART` context
+      // on an empty cart, or `PDP` context outside a product page), skip the
+      // fetch instead of requesting recommendations we can't anchor.
+      if (contextProducts.length === 0) {
+        return null
+      }
+      return {
+        userId,
+        campaignVrn,
+        products: contextProducts,
+      }
+    default:
+      return {
+        userId,
+        campaignVrn,
+        products: [],
+      }
+  }
+}
+
+export type UseRecommendationShelfArgs = {
+  readonly campaignVrn: string
+  /**
+   * Opt-in for VTEX Recommendations. When `false` (default) the campaign is
+   * never requested. The anonymous user id is still resolved, but it goes
+   * unused and never leaves the browser.
+   */
+  readonly enableRecommendations?: boolean
+  /**
+   * Where to read the products used as context for the recommendation request.
+   * @default 'PDP'
+   */
+  readonly itemsContext?: ItemContext
+}
+
+export type UseRecommendationShelfResult = {
+  readonly items: RecommendationResponse['products']
+  readonly isLoading: boolean
+  readonly error: unknown
+  readonly campaign?: RecommendationResponse['campaign']
+  readonly correlationId?: string
+}
+
+const EMPTY_ITEMS: RecommendationResponse['products'] = []
+
+/**
+ * Headless data layer behind every recommendation shelf: resolves the campaign
+ * type, the anonymous user id and the product context, then fetches the
+ * campaign. It renders nothing — presentation lives in the shelf components
+ * that consume it, so a new surface can reuse the campaign rules instead of
+ * reimplementing them.
+ */
+export function useRecommendationShelf({
+  campaignVrn,
+  enableRecommendations = false,
+  itemsContext = 'PDP',
+}: UseRecommendationShelfArgs): UseRecommendationShelfResult {
+  const userId = useRecommendationUserId(campaignVrn)
+
+  const { data: productDetailPage } = usePDP()
+  const { items: cartItems } = useCart()
+
+  // Resolve the products used as context for the request from the configured
+  // source: the current PDP product, or the (deduplicated) cart items.
+  const contextProducts = useMemo(() => {
+    if (itemsContext === 'CART') {
+      return Array.from(
+        new Set(
+          cartItems
+            .map((item) => item.itemOffered.isVariantOf.productGroupID)
+            .filter(Boolean)
+        )
+      )
+    }
+
+    const pdpProduct = productDetailPage?.product?.isVariantOf?.productGroupID
+
+    return pdpProduct ? [pdpProduct] : []
+  }, [itemsContext, cartItems, productDetailPage])
+
+  // Gate the whole feature behind the CMS opt-in: when Recommendations is
+  // disabled the shelf never requests recommendations (nor renders).
+  const recommendationArgs = enableRecommendations
+    ? getRecommendationArguments(campaignVrn, {
+        userId,
+        contextProducts,
+      })
+    : null
+
+  const { data, isLoading, error } = useRecommendations(recommendationArgs)
+
+  if (error) {
+    // Don't log `recommendationArgs`: it carries the userId. Log only
+    // non-identifying context.
+    console.error(
+      'Error fetching recommendations',
+      (error as { cause?: unknown })?.cause,
+      (error as { message?: string })?.message,
+      'for campaign',
+      campaignVrn
+    )
+  }
+
+  return {
+    items: error ? EMPTY_ITEMS : (data?.products ?? EMPTY_ITEMS),
+    isLoading,
+    error,
+    campaign: data?.campaign,
+    correlationId: data?.correlationId,
+  }
+}

package/src/{components/sections/RecommendationShelf → sdk/recommendations}/vrn.ts

@@ -1,4 +1,4 @@
-import type { RecommendationType } from './RecommendationShelf.types'
+import type { RecommendationType } from './types'
 
 // Single source of truth for the campaign taxonomy: maps each Intelligent Search
 // campaign VRN type to its `RecommendationType`. The supported VRN types, the

package/src/sdk/session/index.ts

@@ -194,6 +194,9 @@ export const validateSession = async (session: Session) => {
 const [validationStore, onValidate, hasValidatedStore] =
   createValidationStore(validateSession)
 
+/** True after at least one validateSession cycle finished (success or failure). */
+export const hasValidatedSessionStore = hasValidatedStore
+
 const urlAwareInitialSession = getInitialSession()
 const defaultStore = createSessionStore(
   urlAwareInitialSession,
@@ -214,6 +217,17 @@ export const sessionStore = {
     // Trigger cart revalidation when session changes
     cartStore.set(cartStore.read())
   },
+  /**
+   * Updates session without revalidating the cart. Used when aligning
+   * `channel.salesChannel` to an orderForm SC adopted by `validateCart`.
+   * Still runs `validateSession` via the store's optimistic validator; that
+   * path keeps an explicit (non-default) client SC.
+   */
+  setSilent: (val: Session) => {
+    if (deepEqual(val, defaultStore.read()) === true) return
+
+    defaultStore.set(val)
+  },
 }
 
 export async function logoutAndClearSession(session: Session) {

package/src/sdk/session/syncSalesChannelFromOrderForm.ts

@@ -0,0 +1,68 @@
+import type { Session } from '@faststore/sdk'
+
+function parseChannelRecord(
+  raw: string | null | undefined
+): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(raw || '{}')
+
+    if (
+      parsed !== null &&
+      typeof parsed === 'object' &&
+      !Array.isArray(parsed)
+    ) {
+      return parsed as Record<string, unknown>
+    }
+  } catch {
+    // Malformed channel — reset below.
+  }
+
+  return {}
+}
+
+function readSalesChannel(channel: Record<string, unknown>): string {
+  const value = channel.salesChannel
+
+  if (typeof value === 'string' || typeof value === 'number') {
+    return String(value)
+  }
+
+  return ''
+}
+
+/**
+ * Aligns `fs::session.channel` with a sales channel adopted from the orderForm
+ * (e.g. after Quick Order) without revalidating the cart.
+ *
+ * Uses `sessionStore.setSilent` so we do not trigger `cartStore.set` mid-flight
+ * (that race previously wiped SC-exclusive items). Marks the channel as
+ * explicit (`hasOnlyDefaultSalesChannel: false`) so `validateSession` keeps it.
+ */
+export function syncSalesChannelFromOrderForm(
+  salesChannel: string | null | undefined,
+  readSession: () => Session,
+  setSilent: (session: Session) => void
+): boolean {
+  if (salesChannel == null || salesChannel === '') {
+    return false
+  }
+
+  const session = readSession()
+  const channel = parseChannelRecord(session.channel)
+  const nextSalesChannel = String(salesChannel)
+
+  if (readSalesChannel(channel) === nextSalesChannel) {
+    return false
+  }
+
+  setSilent({
+    ...session,
+    channel: JSON.stringify({
+      ...channel,
+      salesChannel: nextSalesChannel,
+      hasOnlyDefaultSalesChannel: false,
+    }),
+  })
+
+  return true
+}

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

@@ -29,23 +29,17 @@ vi.mock('src/components/skeletons/ProductShelfSkeleton', () => ({
 }))
 
 const useRecommendations = vi.hoisted(() => vi.fn())
-vi.mock(
-  'src/components/sections/RecommendationShelf/useRecommendations',
-  () => ({
-    useRecommendations,
-  })
-)
+vi.mock('src/sdk/recommendations/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,
-  })
-)
+vi.mock('src/sdk/recommendations/useRecommendationUserId', () => ({
+  useRecommendationUserId,
+}))
 
 import { RecommendationShelf } from 'src/components/sections/RecommendationShelf/RecommendationShelf'
 

package/test/sdk/cart/waitForSessionValidated.test.ts

@@ -0,0 +1,96 @@
+import { createBaseStore } from '@faststore/sdk'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  SESSION_VALIDATION_WAIT_MS,
+  waitForSessionValidated,
+} from '../../../src/sdk/cart/waitForSessionValidated'
+
+describe('waitForSessionValidated', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('resolves immediately when session was already validated', async () => {
+    const store = createBaseStore(true)
+
+    await expect(waitForSessionValidated(store)).resolves.toBeUndefined()
+  })
+
+  it('resolves when session becomes validated after subscribe', async () => {
+    const store = createBaseStore(false)
+
+    const pending = waitForSessionValidated(store, 5_000)
+    store.set(true)
+
+    await expect(pending).resolves.toBeUndefined()
+  })
+
+  it('ignores subscribe callbacks while validated is still false', async () => {
+    vi.useFakeTimers()
+    const listeners: Array<(value: boolean) => void> = []
+    const store = {
+      read: vi.fn(() => false),
+      readInitial: vi.fn(() => false),
+      subscribe: vi.fn((listener: (value: boolean) => void) => {
+        listeners.push(listener)
+        return () => {
+          const index = listeners.indexOf(listener)
+          if (index >= 0) {
+            listeners.splice(index, 1)
+          }
+        }
+      }),
+      set: vi.fn(),
+    }
+
+    const pending = waitForSessionValidated(store, SESSION_VALIDATION_WAIT_MS)
+
+    // Emit false — should not resolve yet
+    for (const listener of listeners) {
+      listener(false)
+    }
+
+    await vi.advanceTimersByTimeAsync(SESSION_VALIDATION_WAIT_MS)
+    await expect(pending).resolves.toBeUndefined()
+  })
+
+  it('resolves on timeout when session never validates', async () => {
+    vi.useFakeTimers()
+    const store = createBaseStore(false)
+
+    const pending = waitForSessionValidated(store, SESSION_VALIDATION_WAIT_MS)
+
+    await vi.advanceTimersByTimeAsync(SESSION_VALIDATION_WAIT_MS)
+
+    await expect(pending).resolves.toBeUndefined()
+  })
+
+  it('resolves the race when validation finishes between read and subscribe', async () => {
+    let current = false
+    const listeners: Array<(value: boolean) => void> = []
+
+    const store = {
+      read: vi.fn(() => {
+        // First read: not validated. Second read (post-subscribe): validated.
+        const value = current
+        current = true
+        return value
+      }),
+      readInitial: vi.fn(() => false),
+      subscribe: vi.fn((listener: (value: boolean) => void) => {
+        listeners.push(listener)
+        return () => {
+          const index = listeners.indexOf(listener)
+          if (index >= 0) {
+            listeners.splice(index, 1)
+          }
+        }
+      }),
+      set: vi.fn(),
+    }
+
+    await expect(waitForSessionValidated(store, 5_000)).resolves.toBeUndefined()
+    expect(store.subscribe).toHaveBeenCalledTimes(1)
+    expect(store.read).toHaveBeenCalledTimes(2)
+  })
+})

package/test/sdk/recommendations/useRecommendationShelf.browser.test.tsx

@@ -0,0 +1,199 @@
+import { renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const usePDP = vi.hoisted(() => vi.fn())
+vi.mock('@faststore/core', () => ({ usePDP }))
+
+const useCart = vi.hoisted(() => vi.fn())
+vi.mock('src/sdk/cart', () => ({ useCart }))
+
+const useRecommendations = vi.hoisted(() => vi.fn())
+vi.mock('src/sdk/recommendations/useRecommendations', () => ({
+  useRecommendations,
+}))
+
+const useRecommendationUserId = vi.hoisted(() => vi.fn())
+vi.mock('src/sdk/recommendations/useRecommendationUserId', () => ({
+  useRecommendationUserId,
+}))
+
+import { useRecommendationShelf } from 'src/sdk/recommendations/useRecommendationShelf'
+
+const TOP_ITEMS_VRN = 'vrn:recommendations:acc:rec-top-items-v2:campaign-1'
+const CROSS_SELL_VRN = 'vrn:recommendations:acc:rec-cross-v2:campaign-1'
+
+const cartItem = (productGroupID: string) => ({
+  itemOffered: { isVariantOf: { productGroupID } },
+})
+
+const campaignData = {
+  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' },
+}
+
+const lastArgs = () => useRecommendations.mock.calls.at(-1)?.[0]
+
+beforeEach(() => {
+  usePDP.mockReturnValue({ data: undefined })
+  useCart.mockReturnValue({ items: [] })
+  useRecommendationUserId.mockReturnValue('user-1')
+  useRecommendations.mockReturnValue({
+    data: campaignData,
+    isLoading: false,
+    error: null,
+  })
+})
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('useRecommendationShelf', () => {
+  it('exposes the campaign payload when enabled', () => {
+    const { result } = renderHook(() =>
+      useRecommendationShelf({
+        campaignVrn: TOP_ITEMS_VRN,
+        enableRecommendations: true,
+      })
+    )
+
+    expect(result.current.items).toHaveLength(2)
+    expect(result.current.campaign?.title).toBe('Recommended for you')
+    expect(result.current.correlationId).toBe('corr-1')
+  })
+
+  it('never fetches while recommendations are disabled', () => {
+    renderHook(() => useRecommendationShelf({ campaignVrn: TOP_ITEMS_VRN }))
+
+    expect(lastArgs()).toBeNull()
+  })
+
+  it('never fetches before a userId resolves', () => {
+    useRecommendationUserId.mockReturnValue(null)
+
+    renderHook(() =>
+      useRecommendationShelf({
+        campaignVrn: TOP_ITEMS_VRN,
+        enableRecommendations: true,
+      })
+    )
+
+    expect(lastArgs()).toBeNull()
+  })
+
+  it('never fetches on a malformed campaign vrn', () => {
+    renderHook(() =>
+      useRecommendationShelf({
+        campaignVrn: 'not-a-vrn',
+        enableRecommendations: true,
+      })
+    )
+
+    expect(lastArgs()).toBeNull()
+  })
+
+  it('anchors cart-context campaigns on the deduplicated cart products', () => {
+    useCart.mockReturnValue({
+      items: [cartItem('pg-1'), cartItem('pg-2'), cartItem('pg-1')],
+    })
+
+    renderHook(() =>
+      useRecommendationShelf({
+        campaignVrn: CROSS_SELL_VRN,
+        enableRecommendations: true,
+        itemsContext: 'CART',
+      })
+    )
+
+    expect(lastArgs()).toEqual({
+      userId: 'user-1',
+      campaignVrn: CROSS_SELL_VRN,
+      products: ['pg-1', 'pg-2'],
+    })
+  })
+
+  it('skips cart-context campaigns while the cart is empty', () => {
+    renderHook(() =>
+      useRecommendationShelf({
+        campaignVrn: CROSS_SELL_VRN,
+        enableRecommendations: true,
+        itemsContext: 'CART',
+      })
+    )
+
+    expect(lastArgs()).toBeNull()
+  })
+
+  it('still fetches context-agnostic campaigns on an empty cart', () => {
+    renderHook(() =>
+      useRecommendationShelf({
+        campaignVrn: TOP_ITEMS_VRN,
+        enableRecommendations: true,
+        itemsContext: 'CART',
+      })
+    )
+
+    expect(lastArgs()).toEqual({
+      userId: 'user-1',
+      campaignVrn: TOP_ITEMS_VRN,
+      products: [],
+    })
+  })
+
+  it('follows the live cart context when not frozen', () => {
+    useCart.mockReturnValue({ items: [cartItem('pg-1')] })
+
+    const { rerender } = renderHook(() =>
+      useRecommendationShelf({
+        campaignVrn: CROSS_SELL_VRN,
+        enableRecommendations: true,
+        itemsContext: 'CART',
+      })
+    )
+
+    useCart.mockReturnValue({ items: [cartItem('pg-1'), cartItem('pg-2')] })
+    rerender()
+
+    expect(lastArgs()?.products).toEqual(['pg-1', 'pg-2'])
+  })
+
+  it('anchors PDP-context campaigns on the current product', () => {
+    usePDP.mockReturnValue({
+      data: { product: { isVariantOf: { productGroupID: 'pg-pdp' } } },
+    })
+
+    renderHook(() =>
+      useRecommendationShelf({
+        campaignVrn: CROSS_SELL_VRN,
+        enableRecommendations: true,
+      })
+    )
+
+    expect(lastArgs()?.products).toEqual(['pg-pdp'])
+  })
+
+  it('returns no items and logs without the userId on error', () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+    useRecommendations.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      error: new Error('boom'),
+    })
+
+    const { result } = renderHook(() =>
+      useRecommendationShelf({
+        campaignVrn: TOP_ITEMS_VRN,
+        enableRecommendations: true,
+      })
+    )
+
+    expect(result.current.items).toEqual([])
+    expect(result.current.error).toBeInstanceOf(Error)
+    expect(consoleError).toHaveBeenCalled()
+    expect(JSON.stringify(consoleError.mock.calls)).not.toContain('user-1')
+  })
+})

package/test/{components/RecommendationShelf → sdk/recommendations}/useRecommendationUserId.test.ts

@@ -14,7 +14,7 @@ vi.mock('src/utils/retry', () => ({
   retry: (fn: () => unknown) => Promise.resolve().then(fn),
 }))
 
-import { useRecommendationUserId } from 'src/components/sections/RecommendationShelf/useRecommendationUserId'
+import { useRecommendationUserId } from 'src/sdk/recommendations/useRecommendationUserId'
 
 const CAMPAIGN_VRN = 'vrn:recommendations:acc:rec-top-items-v2:campaign-1'
 

package/test/{components/RecommendationShelf → sdk/recommendations}/useRecommendations.test.ts

@@ -7,7 +7,7 @@ vi.mock('src/sdk/graphql/useQuery', () => ({
   useQuery: useQueryMock,
 }))
 
-import { useRecommendations } from 'src/components/sections/RecommendationShelf/useRecommendations'
+import { useRecommendations } from 'src/sdk/recommendations/useRecommendations'
 
 afterEach(() => {
   vi.clearAllMocks()

package/test/{components/RecommendationShelf → sdk/recommendations}/vrn.test.ts

@@ -1,9 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import {
-  getTypeFromVrn,
-  isValidVrn,
-} from 'src/components/sections/RecommendationShelf/vrn'
+import { getTypeFromVrn, isValidVrn } from 'src/sdk/recommendations/vrn'
 
 const vrn = (type: string) => `vrn:recommendations:account:${type}:campaign-1`