@faststore/core 4.5.0-dev.2 → 4.5.0-dev.4

package/src/sdk/analytics/hooks/useStartRecommendationSession.ts

@@ -1,8 +1,8 @@
-import { useEffect } from 'react'
+import { useEffect, useRef } from 'react'
 
 import { gql } from '@faststore/core/api'
 
-import storeConfig from 'discovery.config'
+import { hasEnabledRecommendationShelf } from 'src/sdk/analytics/utils/hasEnabledRecommendationShelf'
 import { useLazyQuery } from 'src/sdk/graphql/useLazyQuery'
 import { getCookie } from 'src/utils/getCookie'
 import { retry } from 'src/utils/retry'
@@ -20,12 +20,28 @@ const startRecommendationSessionMutation = gql(`
 type StartRecommendationSessionData = { startRecommendationSession: boolean }
 type StartRecommendationSessionVariables = Record<string, never>
 
+// In-memory lock so Layout re-renders (e.g. multiple RecommendationShelves
+// fetching) cannot start more than one session before the cookie lands.
+// Survives effect cleanup / Strict Mode remounts for this JS realm.
+let hasRequestedStartRecommendationSession = false
+
+/** @internal Test-only: clears the in-memory session-start lock. */
+export function resetStartRecommendationSessionLock() {
+  hasRequestedStartRecommendationSession = false
+}
+
 /**
  * Starts the anonymous recommendation/personalization session once per browser
  * session.
  *
- * Mounted globally from `Layout` so it runs on every page, regardless of
- * whether a recommendation section is present.
+ * Mounted from `Layout` with the current page props. Opt-in is controlled by
+ * the CMS boolean prop `enableRecommendations` on `RecommendationShelf`
+ * (default `false`): if no shelf on the page has it enabled, this hook is a
+ * no-op and the store never hits the Recommendations API.
+ *
+ * Multiple enabled shelves on the same page still produce a single call: the
+ * hook runs once from Layout and is gated by an in-memory lock plus the
+ * session cookie.
  *
  * The product view is no longer reported through a mutation here: the PDP now
  * exposes the product data as `<meta property="product:*">` tags, which the
@@ -33,11 +49,10 @@ type StartRecommendationSessionVariables = Record<string, never>
  *
  * All work runs client-side in effects (after hydration), so it doesn't affect
  * SSR/TTFB or Lighthouse render metrics.
- *
- * Gated behind the `experimental.enableRecommendations` flag: stores that don't
- * opt into Recommendations never start a session nor hit the Recommendations API.
  */
-export function useStartRecommendationSession() {
+export function useStartRecommendationSession(pageProps?: unknown) {
+  const enableRecommendations = hasEnabledRecommendationShelf(pageProps)
+
   const [runStartRecommendationSession] = useLazyQuery<
     StartRecommendationSessionData,
     StartRecommendationSessionVariables
@@ -49,30 +64,40 @@ export function useStartRecommendationSession() {
     }
   )
 
+  // useLazyQuery returns a new `execute` identity every render; keep a stable
+  // ref so the effect does not re-subscribe (and re-fire) on unrelated updates.
+  const runStartRecommendationSessionRef = useRef(runStartRecommendationSession)
+  runStartRecommendationSessionRef.current = runStartRecommendationSession
+
   useEffect(() => {
-    if (!storeConfig.experimental.enableRecommendations) {
+    if (!enableRecommendations) {
       return
     }
 
     const startRecommendationSessionCookie = getCookie(
       VTEX_REC_USER_START_SESSION
     )
-
     if (startRecommendationSessionCookie) {
       return
     }
 
-    const controller = new AbortController()
+    if (hasRequestedStartRecommendationSession) {
+      return
+    }
+    hasRequestedStartRecommendationSession = true
 
     // The session endpoint may not be ready on the first try, so we retry with
     // exponential backoff until it returns a defined result (or we give up).
     // Transient request/GraphQL rejections are treated as retryable: swallow
     // the error and return `undefined` so the backoff loop keeps going instead
     // of aborting on the first failure.
+    //
+    // Intentionally no AbortController: cleanup would cancel the only attempt
+    // (Strict Mode remount / Layout re-render) while the lock stays set.
     void retry(
       async () => {
         try {
-          return await runStartRecommendationSession({})
+          return await runStartRecommendationSessionRef.current({})
         } catch {
           return undefined
         }
@@ -83,14 +108,9 @@ export function useStartRecommendationSession() {
         backoff: true,
         maxDelayMs: 3000,
         until: (result) => result !== undefined,
-        signal: controller.signal,
       }
       // Guard the discarded promise so a give-up (or any unexpected rejection)
       // never surfaces as an unhandled promise rejection.
     ).catch(() => {})
-
-    return () => {
-      controller.abort()
-    }
-  }, [runStartRecommendationSession])
+  }, [enableRecommendations])
 }

package/src/sdk/analytics/utils/hasEnabledRecommendationShelf.ts

@@ -0,0 +1,49 @@
+type CmsSection = {
+  name?: string
+  $componentKey?: string
+  data?: {
+    enableRecommendations?: boolean
+  }
+}
+
+function pushSections(target: CmsSection[], value: unknown) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (item && typeof item === 'object') {
+        target.push(item as CmsSection)
+      }
+    }
+    return
+  }
+
+  if (value && typeof value === 'object') {
+    const sections = (value as { sections?: unknown }).sections
+    if (Array.isArray(sections)) {
+      pushSections(target, sections)
+    }
+  }
+}
+
+/**
+ * Returns true when the current page CMS data includes at least one
+ * `RecommendationShelf` with `enableRecommendations: true`.
+ */
+export function hasEnabledRecommendationShelf(pageProps: unknown): boolean {
+  if (!pageProps || typeof pageProps !== 'object') {
+    return false
+  }
+
+  const props = pageProps as Record<string, unknown>
+  const sections: CmsSection[] = []
+
+  pushSections(sections, props.sections)
+  pushSections(sections, props.globalSections)
+  pushSections(sections, props.page)
+
+  return sections.some(
+    (section) =>
+      (section.name === 'RecommendationShelf' ||
+        section.$componentKey === 'RecommendationShelf') &&
+      section.data?.enableRecommendations === true
+  )
+}

package/src/sdk/localization/LocalizedProductContext.tsx

@@ -0,0 +1,65 @@
+import { createContext, useContext, useMemo } from 'react'
+import type { PropsWithChildren } from 'react'
+
+export interface LocalizedProductLocale {
+  locale: string
+  slug: string
+}
+
+interface LocalizedProductData {
+  /**
+   * Localized slug entries for all available locales of the current page.
+   * Null when localization is disabled or the page type does not support it.
+   */
+  otherLocales: LocalizedProductLocale[] | null
+  /**
+   * Suffix appended after the localized slug when building the redirect URL.
+   * Use '/p' for product pages (PDP), '' for collection/PLP pages.
+   */
+  urlSuffix: string
+}
+
+const LocalizedProductContext = createContext<LocalizedProductData | null>(null)
+
+type LocalizedProductProviderProps = Readonly<
+  PropsWithChildren<{
+    otherLocales: LocalizedProductLocale[] | null | undefined
+    /**
+     * Suffix to append to the localized slug when building the redirect URL.
+     * Defaults to '/p' (product pages). Pass '' for collection/PLP pages.
+     */
+    urlSuffix?: string
+  }>
+>
+
+/**
+ * Provides localized page data (otherLocales, urlSuffix) to any component in
+ * the tree — including global components like LocalizationButton that are
+ * not co-located with page sections.
+ *
+ * Set in p.tsx (PDP) and [...slug].tsx (PLP); returns null outside those pages.
+ */
+export function LocalizedProductProvider({
+  otherLocales,
+  urlSuffix = '/p',
+  children,
+}: LocalizedProductProviderProps) {
+  const value = useMemo(
+    () => ({ otherLocales: otherLocales ?? null, urlSuffix }),
+    [otherLocales, urlSuffix]
+  )
+
+  return (
+    <LocalizedProductContext.Provider value={value}>
+      {children}
+    </LocalizedProductContext.Provider>
+  )
+}
+
+/**
+ * Returns localized product data for the current page.
+ * Safe to call from any component — returns null outside a product page.
+ */
+export function useLocalizedProduct(): LocalizedProductData | null {
+  return useContext(LocalizedProductContext)
+}

package/src/sdk/localization/useBindingSelector.ts

@@ -9,8 +9,86 @@ import {
   isValidUrl,
   resolveBinding,
 } from './bindingSelector'
+import type { LocalizedProductLocale } from './LocalizedProductContext'
 import type { BindingSelectorError, Locale } from './types'
 
+const OTHER_LOCALES_STORAGE_PREFIX = 'fs:otherLocales:'
+
+/**
+ * Extracts the SKU id from a PDP-shaped pathname ("/.../{slug}-{skuId}/p").
+ * Slugs always end with "-{skuId}" (see `getSlug` in the API), so the id is the
+ * last "-"-separated segment of the path segment that precedes "/p".
+ * Returns null when the path is not a product page or has no numeric id.
+ */
+export function getSkuIdFromPdpPath(pathname: string): string | null {
+  const match = pathname.match(/\/([^/]+)\/p\/?$/) // NOSONAR
+  const skuId = match?.[1]?.split('-').pop()
+
+  return skuId && /^\d+$/.test(skuId) ? skuId : null
+}
+
+/**
+ * Persists the localized slug map for a product keyed by its SKU id. This lets
+ * the locale selector rebuild canonical localized product URLs even after the
+ * user lands on a context-less page (e.g. a 404 for a locale where the product
+ * is unavailable), where `otherLocales` is no longer provided by the page.
+ */
+export function persistOtherLocales(
+  otherLocales: LocalizedProductLocale[]
+): void {
+  if (typeof window === 'undefined' || !otherLocales.length) return
+
+  const skuId = otherLocales[0]?.slug.split('-').pop()
+  if (!skuId) return
+
+  try {
+    globalThis.sessionStorage.setItem(
+      `${OTHER_LOCALES_STORAGE_PREFIX}${skuId}`,
+      JSON.stringify(otherLocales)
+    )
+  } catch {
+    // sessionStorage may be unavailable (private mode/quota); non-critical.
+  }
+}
+
+function isLocalizedProductLocaleArray(
+  value: unknown
+): value is LocalizedProductLocale[] {
+  return (
+    Array.isArray(value) &&
+    value.every(
+      (item) =>
+        typeof item === 'object' &&
+        item !== null &&
+        typeof (item as Record<string, unknown>).locale === 'string' &&
+        typeof (item as Record<string, unknown>).slug === 'string'
+    )
+  )
+}
+
+/**
+ * Recovers a previously persisted localized slug map for the product referenced
+ * by the current PDP URL. Returns null when not on a PDP or nothing is stored.
+ */
+export function recoverOtherLocales(): LocalizedProductLocale[] | null {
+  if (typeof window === 'undefined') return null
+
+  const skuId = getSkuIdFromPdpPath(globalThis.location.pathname)
+  if (!skuId) return null
+
+  try {
+    const raw = globalThis.sessionStorage.getItem(
+      `${OTHER_LOCALES_STORAGE_PREFIX}${skuId}`
+    )
+
+    if (!raw) return null
+    const parsed: unknown = JSON.parse(raw)
+    return isLocalizedProductLocaleArray(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
 interface Currency {
   code: string
   name: string
@@ -64,9 +142,17 @@ export interface UseBindingSelectorReturn {
  * Hook that provides state and actions for the localization selector.
  * Manages locale selection, currency filtering, and binding resolution.
  *
+ * @param otherLocales - Optional list of localized slugs for the current page.
+ *   When provided (e.g. on PDP or PLP), the save action navigates to the
+ *   localized page URL instead of preserving the current page path verbatim.
+ * @param urlSuffix - Suffix appended after the slug when building the redirect URL.
+ *   Use '/p' for product pages (default) and '' for collection/PLP pages.
  * @returns Object with languages, currencies, selections, and actions
  */
-export function useBindingSelector(): UseBindingSelectorReturn {
+export function useBindingSelector(
+  otherLocales?: Array<{ locale: string; slug: string }> | null,
+  urlSuffix = '/p'
+): UseBindingSelectorReturn {
   const { locale: currentLocale, currency: currentCurrency } = useSession()
   const localizationConfig = storeConfig.localization as LocalizationConfig
 
@@ -96,6 +182,15 @@ export function useBindingSelector(): UseBindingSelectorReturn {
     }
   }, [currentCurrency?.code])
 
+  // Persist the product's localized slugs so a later locale switch can rebuild
+  // the canonical localized URL even from a context-less page (e.g. a 404).
+  // Only relevant on PDPs — PLP otherLocales are collection slugs, not products.
+  useEffect(() => {
+    if (urlSuffix === '/p' && otherLocales?.length) {
+      persistOtherLocales(otherLocales)
+    }
+  }, [otherLocales, urlSuffix])
+
   // Build language options with disambiguation - returns Record<localeCode, languageName>
   const languages = useMemo(
     () => buildLanguageOptions(localizationConfig.locales),
@@ -181,12 +276,60 @@ export function useBindingSelector(): UseBindingSelectorReturn {
       return
     }
 
-    // Redirect to binding URL, preserving the current page path and query string
-    window.location.href = buildRedirectUrl(
+    // Prefer the current page's localized slugs. When missing (e.g. we're on a
+    // 404 for a locale where the product is unavailable) recover the map that was
+    // persisted while on a working PDP, so we can still build the canonical
+    // localized product URL instead of dropping the user on the locale home.
+    const effectiveOtherLocales = otherLocales?.length
+      ? otherLocales
+      : recoverOtherLocales()
+
+    if (effectiveOtherLocales?.length) {
+      // 1. Target locale has a specific translation → use it
+      const localizedEntry = effectiveOtherLocales.find(
+        (e) => e.locale === localeCode
+      )
+
+      // 2. No translation for target locale → fall back to the default locale slug
+      //    (IS linkText, always in the default locale) to avoid carrying over a
+      //    translated slug from a different locale (e.g. Italian slug on es-ES).
+      //    For an unavailable target this yields a 404 at the product URL (expected).
+      const fallbackEntry = effectiveOtherLocales.find(
+        (e) => e.locale === localizationConfig.defaultLocale
+      )
+
+      const entry = localizedEntry ?? fallbackEntry
+
+      if (entry) {
+        const baseUrl = binding.url.replace(/\/$/, '')
+        globalThis.location.href = `${baseUrl}/${entry.slug}${urlSuffix}${globalThis.location.search}${globalThis.location.hash}`
+        return
+      }
+    }
+
+    // otherLocales is empty/null but we're still on a PDP: strip the stale slug.
+    if (globalThis.location.pathname.endsWith('/p')) {
+      globalThis.location.href = binding.url
+      return
+    }
+
+    // No localized slugs available (not even persisted): preserve the current
+    // page path under the target binding instead of dropping the user on the
+    // locale home. For a default-locale slug this resolves the product; for an
+    // unavailable/untranslated slug it yields a 404 at the product URL, never the
+    // locale root.
+    globalThis.location.href = buildRedirectUrl(
       binding.url,
-      `${window.location.pathname}${window.location.search}${window.location.hash}`
+      `${globalThis.location.pathname}${globalThis.location.search}${globalThis.location.hash}`
     )
-  }, [localeCode, currencyCode, localizationConfig.locales])
+  }, [
+    localeCode,
+    currencyCode,
+    localizationConfig.locales,
+    localizationConfig.defaultLocale,
+    otherLocales,
+    urlSuffix,
+  ])
 
   const isSaveEnabled = Boolean(localeCode && currencyCode && !error)
 

package/src/server/index.ts

@@ -34,6 +34,7 @@ interface ExecuteOptions<V = Record<string, unknown>> {
   operation: Operation
   variables: V
   query?: string | null
+  locale?: string
 }
 
 const persistedQueries = new Map()
@@ -98,7 +99,7 @@ export const execute = async <V extends Maybe<{ [key: string]: unknown }>, D>(
     cookies: Map<string, Record<string, string>> | null
   }
 }> => {
-  const { operation, variables, query: maybeQuery } = options
+  const { operation, variables, query: maybeQuery, locale } = options
   const { operationHash, operationName } = operation['__meta__']
 
   if (!persistedQueries.size) {
@@ -127,6 +128,14 @@ export const execute = async <V extends Maybe<{ [key: string]: unknown }>, D>(
 
   const contextValue = await contextFactory(envelopContext)
 
+  // Override the store-default locale with the per-request locale (if any) so
+  // localization-aware resolvers read it from ctx.storage.locale. Resolvers that
+  // carry their own locale (e.g. product/search via locator facets) still
+  // override this default inside their own resolution.
+  if (locale) {
+    contextValue.storage.locale = locale
+  }
+
   const { data, errors } = (await run({
     schema,
     document: parse(query),

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

@@ -47,27 +47,6 @@ vi.mock(
   })
 )
 
-// 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'
@@ -91,7 +70,6 @@ beforeEach(() => {
     loading: false,
   })
   useRecommendationUserId.mockReturnValue('user-1')
-  recommendationsFlag.enabled = true
 })
 
 afterEach(() => {
@@ -99,7 +77,7 @@ afterEach(() => {
 })
 
 describe('RecommendationShelf', () => {
-  it('renders a product card per recommended product', async () => {
+  it('renders a product card per recommended product when enabled', async () => {
     useRecommendations.mockReturnValue({
       data: recommendationData,
       isLoading: false,
@@ -107,7 +85,7 @@ describe('RecommendationShelf', () => {
     })
 
     const { getAllByTestId, getByText } = render(
-      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} enableRecommendations />
     )
 
     await waitFor(() => {
@@ -126,7 +104,9 @@ describe('RecommendationShelf', () => {
       error: null,
     })
 
-    render(<RecommendationShelf campaignVrn={CROSS_SELL_VRN} />)
+    render(
+      <RecommendationShelf campaignVrn={CROSS_SELL_VRN} enableRecommendations />
+    )
 
     await waitFor(() => {
       const lastArgs = useRecommendations.mock.calls.at(-1)?.[0]
@@ -146,7 +126,11 @@ describe('RecommendationShelf', () => {
     })
 
     const { getByText } = render(
-      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} title="Custom title" />
+      <RecommendationShelf
+        campaignVrn={CAMPAIGN_VRN}
+        enableRecommendations
+        title="Custom title"
+      />
     )
 
     await waitFor(() => {
@@ -162,6 +146,25 @@ describe('RecommendationShelf', () => {
       error: null,
     })
 
+    const { container, queryByTestId } = render(
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} enableRecommendations />
+    )
+
+    await waitFor(() => {
+      const lastArgs = useRecommendations.mock.calls.at(-1)?.[0]
+      expect(lastArgs).toBeNull()
+    })
+    expect(queryByTestId('product-card')).toBeNull()
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('skips the fetch when recommendations are disabled (default)', async () => {
+    useRecommendations.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      error: null,
+    })
+
     const { container, queryByTestId } = render(
       <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
     )
@@ -182,7 +185,7 @@ describe('RecommendationShelf', () => {
     })
 
     const { container } = render(
-      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} enableRecommendations />
     )
 
     expect(container).toBeEmptyDOMElement()
@@ -196,7 +199,7 @@ describe('RecommendationShelf', () => {
     })
 
     const { container, queryByTestId } = render(
-      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} enableRecommendations />
     )
 
     expect(queryByTestId('product-card')).toBeNull()
@@ -211,25 +214,9 @@ describe('RecommendationShelf', () => {
     })
 
     const { getByTestId } = render(
-      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} enableRecommendations />
     )
 
     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/sdk/analytics/hasEnabledRecommendationShelf.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+
+import { hasEnabledRecommendationShelf } from 'src/sdk/analytics/utils/hasEnabledRecommendationShelf'
+
+describe('hasEnabledRecommendationShelf', () => {
+  it('returns false for empty or unrelated page props', () => {
+    expect(hasEnabledRecommendationShelf(undefined)).toBe(false)
+    expect(hasEnabledRecommendationShelf({})).toBe(false)
+    expect(
+      hasEnabledRecommendationShelf({
+        sections: [{ name: 'ProductShelf', data: {} }],
+      })
+    ).toBe(false)
+  })
+
+  it('returns true when a page section enables recommendations', () => {
+    expect(
+      hasEnabledRecommendationShelf({
+        sections: [
+          {
+            name: 'RecommendationShelf',
+            data: { enableRecommendations: true, campaignVrn: 'vrn:x' },
+          },
+        ],
+      })
+    ).toBe(true)
+  })
+
+  it('returns true when a global section enables recommendations', () => {
+    expect(
+      hasEnabledRecommendationShelf({
+        globalSections: {
+          sections: [
+            {
+              $componentKey: 'RecommendationShelf',
+              data: { enableRecommendations: true },
+            },
+          ],
+        },
+      })
+    ).toBe(true)
+  })
+
+  it('returns true when page.sections enables recommendations', () => {
+    expect(
+      hasEnabledRecommendationShelf({
+        page: {
+          sections: [
+            {
+              name: 'RecommendationShelf',
+              data: { enableRecommendations: true },
+            },
+          ],
+        },
+      })
+    ).toBe(true)
+  })
+
+  it('returns false when the shelf is present but enableRecommendations is false', () => {
+    expect(
+      hasEnabledRecommendationShelf({
+        sections: [
+          {
+            name: 'RecommendationShelf',
+            data: { enableRecommendations: false },
+          },
+        ],
+      })
+    ).toBe(false)
+  })
+
+  it('returns true when at least one of multiple shelves enables recommendations', () => {
+    expect(
+      hasEnabledRecommendationShelf({
+        sections: [
+          {
+            name: 'RecommendationShelf',
+            data: { enableRecommendations: false },
+          },
+          {
+            name: 'RecommendationShelf',
+            data: { enableRecommendations: true },
+          },
+        ],
+      })
+    ).toBe(true)
+  })
+})