@faststore/core 4.4.0-dev.3 → 4.4.0-dev.4

package/src/proxy.ts

@@ -48,6 +48,29 @@ const validLocales = new Set(
   Object.keys(storeConfig.localization?.locales || {})
 )
 
+/**
+ * Resolves the locale Next.js already assigned to this request (path prefix or
+ * domain routing). For _next/data routes the locale is embedded in the path.
+ */
+function getActiveLocaleFromRequest(request: NextRequest): string | undefined {
+  const { pathname } = request.nextUrl
+  const dataMatch = pathname.match(DATA_ROUTE_RE)
+
+  if (dataMatch) {
+    const localeFromData = dataMatch[1]
+    if (validLocales.has(localeFromData)) {
+      return localeFromData
+    }
+  }
+
+  const { locale } = request.nextUrl
+  if (locale && validLocales.has(locale)) {
+    return locale
+  }
+
+  return undefined
+}
+
 /**
  * Rewrites the request to the subdomain locale.
  * Without this, getStaticProps receives the wrong locale on subdomain domains
@@ -61,6 +84,19 @@ function rewriteSubdomainRequest(
   request: NextRequest,
   locale: string
 ): NextResponse | null {
+  const activeLocale = getActiveLocaleFromRequest(request)
+
+  // Root bindings share a hostname with path-prefixed locales (e.g. /pt-BR).
+  // When Next already resolved a different locale, skip injecting the subdomain
+  // locale to avoid double-prefix rewrites like /pt-BR/en-US/...
+  if (
+    activeLocale &&
+    validLocales.has(activeLocale) &&
+    activeLocale !== locale
+  ) {
+    return null
+  }
+
   const { pathname, search } = request.nextUrl
 
   const dataMatch = pathname.match(DATA_ROUTE_RE)

package/src/sdk/session/index.ts

@@ -19,7 +19,7 @@ import { cartStore } from '../cart'
 import { request } from '../graphql/request'
 import { createValidationStore, useStore } from '../useStore'
 import { getPostalCode } from '../userLocation/index'
-import { getInitialSession, installLocaleCorrector } from './initialSession'
+import { getInitialSession, reconcileSessionLocale } from './initialSession'
 import { RELOAD_AFTER_LOGOUT_KEY, SESSION_READY_KEY } from './storageKeys'
 
 const isReloadAfterLogoutPending = (): boolean => {
@@ -195,11 +195,14 @@ const [validationStore, onValidate, hasValidatedStore] =
   createValidationStore(validateSession)
 
 const urlAwareInitialSession = getInitialSession()
-const defaultStore = createSessionStore(urlAwareInitialSession, onValidate)
-
-if (storeConfig.localization?.enabled && typeof window !== 'undefined') {
-  installLocaleCorrector(defaultStore, urlAwareInitialSession)
-}
+const defaultStore = createSessionStore(
+  urlAwareInitialSession,
+  onValidate,
+  'fs::session',
+  storeConfig.localization?.enabled
+    ? { reconcile: reconcileSessionLocale }
+    : undefined
+)
 
 export const sessionStore = {
   ...defaultStore,

package/src/sdk/session/initialSession.ts

@@ -1,5 +1,4 @@
-import type { Session, Store } from '@faststore/sdk'
-import deepEqual from 'fast-deep-equal'
+import type { Session } from '@faststore/sdk'
 
 import storeConfig from '../../../discovery.config'
 import { getSettings } from '../localization/settings'
@@ -31,10 +30,10 @@ function safeParseChannel(
  * useLocalizationConfig detect the URL locale and correct the session —
  * causing a second, redundant pair of validateSession + validateCart calls.
  *
- * By seeding the initial value with the URL locale we ensure:
- * 1. readInitial() already contains the correct locale (fixes first-visit).
- * 2. The correction subscriber below can fix IDB payloads that carry an
- *    outdated locale without an extra round-trip.
+ * By seeding the initial value with the URL locale we ensure readInitial()
+ * already contains the correct locale (fixes first-visit). IDB payloads that
+ * carry an outdated locale are corrected by `reconcileSessionLocale` (wired as
+ * the `persisted` reconcile seam in `createSessionStore`).
  */
 export function getInitialSession(
   defaults: Session = storeConfig.session
@@ -60,50 +59,36 @@ export function getInitialSession(
 }
 
 /**
- * Installs a one-shot subscriber that corrects the locale/currency/channel
- * when the persisted middleware hydrates a session from IDB whose values
- * differ from the URL-derived initial session.
+ * Reconciles a session payload read from IDB (on hydration and on the
+ * `focus`/`visibilitychange` cross-tab sync) with the URL-derived localization
+ * settings, forcing `locale`/`currency`/`salesChannel` to follow the URL while
+ * preserving every other field from the persisted payload.
  *
- * Why this works:
- * - It must be subscribed AFTER `optimistic`, so it fires within the same
- *   synchronous `store.set()` call that enqueues `validateSession(stale)`.
- * - It then calls `store.set(corrected)`, re-entering the base store's set().
- *   The base store invokes `cancelations.forEach(cancel)` which flips the
- *   `cancel` flag of the just-enqueued optimistic handler — preventing the
- *   stale `validateSession` from ever hitting the network — and broadcasts
- *   again, enqueueing a new optimistic handler with the corrected value.
+ * This is the SDK `persisted` reconcile seam (see `CreateStoreOptions`): the
+ * URL is the single source of truth for localization, so neither a stale IDB
+ * value nor a `validateSession` round-trip (which receives no locale hint in
+ * `search` on path-based bindings) can flip the locale back to the default.
  *
- * The `corrected` flag guarantees the subscriber runs at most once: subsequent
- * locale changes (e.g. from `LocalizationSelector`) must not be intercepted.
- *
- * @returns Unsubscribe function (mainly useful in tests).
+ * When localization is disabled or there is no `window` (SSR), the payload is
+ * returned untouched.
  */
-export function installLocaleCorrector(
-  store: Store<Session>,
-  initialSession: Session
-): () => void {
-  let corrected = false
-
-  return store.subscribe((session: Session) => {
-    if (corrected) return
-    corrected = true
-
-    if (
-      session.locale === initialSession.locale &&
-      deepEqual(session.currency, initialSession.currency) &&
-      session.channel === initialSession.channel
-    ) {
-      return
-    }
+export function reconcileSessionLocale(fromIDB: Session): Session {
+  if (!storeConfig.localization?.enabled || typeof window === 'undefined') {
+    return fromIDB
+  }
 
-    const channel = safeParseChannel(session.channel)
-    channel.salesChannel = safeParseChannel(initialSession.channel).salesChannel
+  try {
+    const settings = getSettings()
+    const channel = safeParseChannel(fromIDB.channel)
+    channel.salesChannel = settings.salesChannel
 
-    store.set({
-      ...session,
-      locale: initialSession.locale,
-      currency: initialSession.currency,
+    return {
+      ...fromIDB,
+      locale: settings.locale,
+      currency: settings.currency,
       channel: JSON.stringify(channel),
-    })
-  })
+    }
+  } catch {
+    return fromIDB
+  }
 }

package/src/utils/localization/localizeRedirectDestination.ts

@@ -0,0 +1,66 @@
+import storeConfig from 'discovery.config'
+import { addCustomPathPrefix, extractCustomPathPrefix } from './bindingPaths'
+
+type RedirectLocaleContext = {
+  locale?: string
+  defaultLocale?: string
+  /**
+   * Present in `getServerSideProps` (absent in `getStaticProps`). Its `url`
+   * keeps the original, pre-proxy-rewrite path — including custom binding
+   * prefixes like `/europe/it` — which `resolvedUrl` does not.
+   */
+  req?: { url?: string }
+}
+
+/**
+ * Localizes an internal redirect `destination` for `getServerSideProps` /
+ * `getStaticProps`, mirroring the client-side `useLink.resolveLink` logic.
+ *
+ * Next.js (Pages Router) does NOT add the active locale to a
+ * `redirect.destination`, so without this the redirect drops to the default
+ * binding. Resolution order (same as `resolveLink`):
+ *
+ * 1. If the request is on a custom binding path (e.g. `/europe/it`, `/emea-eur`),
+ *    preserve that prefix via `addCustomPathPrefix` — the `proxy.ts` rewrite maps
+ *    the prefixed URL back to the right locale, keeping the user on the vanity path.
+ * 2. Otherwise, if on a non-default Next locale, prepend `/${locale}`.
+ * 3. Otherwise (default locale / subdomain binding), return as-is.
+ *
+ * The custom-path branch requires `context.req.url`; in `getStaticProps` (no
+ * request) only the locale branch applies.
+ */
+export function localizeRedirectDestination(
+  destination: string,
+  context: RedirectLocaleContext
+): string {
+  if (!storeConfig.localization?.enabled) {
+    return destination
+  }
+
+  // Only internal, absolute paths are localized (skip external URLs and
+  // protocol-relative `//host` destinations).
+  if (!destination.startsWith('/') || destination.startsWith('//')) {
+    return destination
+  }
+
+  const requestUrl = context.req?.url ?? ''
+
+  // 1. Custom binding path (e.g. `/europe/it`) — preserve it, matching resolveLink.
+  if (extractCustomPathPrefix(requestUrl) !== null) {
+    return addCustomPathPrefix(destination, requestUrl)
+  }
+
+  // 2. Non-default Next locale (e.g. `/it-IT`) — Next won't add it on redirects.
+  const { locale, defaultLocale } = context
+
+  if (!locale || !defaultLocale || locale === defaultLocale) {
+    return destination
+  }
+
+  // Already prefixed (defensive — avoids `/it-IT/it-IT/...`).
+  if (destination === `/${locale}` || destination.startsWith(`/${locale}/`)) {
+    return destination
+  }
+
+  return `/${locale}${destination}`
+}

package/src/utils/localization/withLocaleValidation.ts

@@ -23,12 +23,6 @@ export function withLocaleValidationSSR<P extends Record<string, any>>(
       return getServerSidePropsFn(context)
     }
 
-    // Skip locale validation for private/authenticated routes
-    const pathname = req.url?.split('?')[0] ?? ''
-    if (pathname.startsWith('/pvt/')) {
-      return getServerSidePropsFn(context)
-    }
-
     const isValid = validateLocaleForHostname(hostname, locale)
 
     if (!isValid) {

package/test/proxy.localization.test.ts

@@ -0,0 +1,122 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const checkStoreProtectionMock = vi.hoisted(() => vi.fn())
+const getSubdomainBindingsMock = vi.hoisted(() => vi.fn())
+const getCustomPathsFromBindingsMock = vi.hoisted(() => vi.fn())
+const isValidLocaleMock = vi.hoisted(() => vi.fn())
+
+vi.mock('discovery.config', () => ({
+  __esModule: true,
+  default: {
+    localization: {
+      enabled: true,
+      locales: {
+        'en-US': { bindings: [] },
+        'pt-BR': { bindings: [] },
+      },
+    },
+  },
+}))
+
+vi.mock('../src/server/password-protection-service', () => ({
+  PasswordProtectionService: class {
+    checkStoreProtection = checkStoreProtectionMock
+  },
+}))
+
+vi.mock('src/utils/localization/bindingPaths', () => ({
+  getCustomPathsFromBindings: getCustomPathsFromBindingsMock,
+  getSubdomainBindings: getSubdomainBindingsMock,
+  isValidLocale: isValidLocaleMock,
+}))
+
+function localizedRequest(
+  pathname: string,
+  options?: { locale?: string; host?: string }
+): NextRequest {
+  const host = options?.host ?? 'localhost:3000'
+  const req = new NextRequest(`http://${host}${pathname}`, {
+    headers: { host },
+  })
+
+  if (options?.locale) {
+    Object.defineProperty(req.nextUrl, 'locale', {
+      value: options.locale,
+      writable: true,
+      configurable: true,
+    })
+  }
+
+  return req
+}
+
+describe('proxy localization rewrite', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.resetModules()
+    checkStoreProtectionMock.mockResolvedValue({
+      response: NextResponse.next(),
+    })
+    getSubdomainBindingsMock.mockReturnValue([
+      { hostname: 'localhost', locale: 'en-US' },
+    ])
+    getCustomPathsFromBindingsMock.mockReturnValue([])
+    isValidLocaleMock.mockImplementation((locale: string) =>
+      ['en-US', 'pt-BR'].includes(locale)
+    )
+  })
+
+  it('skips subdomain rewrite when request locale differs from root binding locale', async () => {
+    const { proxy } = await import('../src/proxy')
+    const response = (await proxy(
+      localizedRequest('/pvt/account/profile', { locale: 'pt-BR' })
+    )) as NextResponse
+
+    expect(response.headers.get('x-middleware-rewrite')).toBeNull()
+  })
+
+  it('rewrites when request locale matches subdomain binding locale', async () => {
+    const { proxy } = await import('../src/proxy')
+    const response = (await proxy(
+      localizedRequest('/pvt/account/profile', { locale: 'en-US' })
+    )) as NextResponse
+
+    const rewrite = response.headers.get('x-middleware-rewrite')
+    expect(rewrite).toContain('/en-US/pvt/account/profile')
+  })
+
+  it('rewrites paths without a locale segment when no active locale is set', async () => {
+    const { proxy } = await import('../src/proxy')
+    const response = (await proxy(
+      localizedRequest('/pvt/account/profile')
+    )) as NextResponse
+
+    const rewrite = response.headers.get('x-middleware-rewrite')
+    expect(rewrite).toContain('/en-US/pvt/account/profile')
+  })
+
+  it('skips _next/data rewrite when data locale differs from subdomain locale', async () => {
+    const { proxy } = await import('../src/proxy')
+    const response = (await proxy(
+      localizedRequest(
+        '/_next/data/development/pt-BR/pvt/account/profile.json',
+        { locale: 'pt-BR' }
+      )
+    )) as NextResponse
+
+    expect(response.headers.get('x-middleware-rewrite')).toBeNull()
+  })
+
+  it('does not rewrite _next/data when data locale matches subdomain locale', async () => {
+    const { proxy } = await import('../src/proxy')
+    const response = (await proxy(
+      localizedRequest(
+        '/_next/data/development/en-US/pvt/account/profile.json',
+        { locale: 'en-US' }
+      )
+    )) as NextResponse
+
+    expect(response.headers.get('x-middleware-rewrite')).toBeNull()
+  })
+})

package/test/sdk/session/reconcileSessionLocale.browser.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Tests for the localization reconcile seam.
+ *
+ * `reconcileSessionLocale` is wired into the SDK `persisted` middleware (via
+ * `createSessionStore({ reconcile })`) and runs every time a payload flows from
+ * IDB into memory — both on hydration and on the `focus`/`visibilitychange`
+ * cross-tab sync. It forces `locale`/`currency`/`salesChannel` to follow the
+ * URL (the single source of truth) while preserving every other field from the
+ * persisted payload. This replaces the previous one-shot `installLocaleCorrector`
+ * subscriber, which only fixed memory on the first hydration and never covered
+ * the focus sync.
+ */
+import type { Session } from '@faststore/sdk'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock(import('../../../discovery.config.js'), async (original) => ({
+  default: {
+    ...((await original()).default ?? (await original())),
+    localization: {
+      enabled: true,
+      defaultLocale: 'pt-BR',
+      regions: {
+        BR: {
+          code: 'BR',
+          name: 'Brazil',
+          dateFormat: 'DD/MM/YYYY',
+          timeFormat: '24h',
+          timeFormatMask: 'HH:mm',
+          unitSystem: 'metric',
+          defaultTimezone: 'GMT-3',
+        },
+        US: {
+          code: 'US',
+          name: 'United States',
+          dateFormat: 'MM/DD/YYYY',
+          timeFormat: '12h',
+          timeFormatMask: 'hh:mm a',
+          unitSystem: 'imperial',
+          defaultTimezone: 'GMT-5',
+        },
+      },
+      locales: {
+        'pt-BR': {
+          code: 'pt-BR',
+          name: 'Português',
+          languageCode: 'pt',
+          languageName: 'Portuguese',
+          script: 'Latn',
+          textDirection: 'ltr',
+          regionCode: 'BR',
+          bindings: [
+            {
+              currencyCode: 'BRL',
+              url: 'https://store.example.com/pt-BR',
+              salesChannel: '1',
+              isDefault: true,
+            },
+          ],
+        },
+        'en-US': {
+          code: 'en-US',
+          name: 'English',
+          languageCode: 'en',
+          languageName: 'English',
+          script: 'Latn',
+          textDirection: 'ltr',
+          regionCode: 'US',
+          bindings: [
+            {
+              currencyCode: 'USD',
+              url: 'https://store.example.com/en-US',
+              salesChannel: '2',
+              isDefault: false,
+            },
+          ],
+        },
+      },
+      currencies: {
+        BRL: { code: 'BRL', name: 'Brazilian Real', symbol: 'R$' },
+        USD: { code: 'USD', name: 'US Dollar', symbol: '$' },
+      },
+    },
+  },
+}))
+
+import { reconcileSessionLocale } from '../../../src/sdk/session/initialSession'
+
+const originalLocation = window.location
+
+function stubHref(href: string) {
+  Object.defineProperty(window, 'location', {
+    configurable: true,
+    value: { ...originalLocation, href },
+  })
+}
+
+const STALE: Session = {
+  locale: 'en-US',
+  currency: { code: 'USD', symbol: '$' },
+  channel: '{"salesChannel":"2","regionId":"region-xyz"}',
+  country: 'USA',
+  deliveryMode: null,
+  addressType: null,
+  city: null,
+  postalCode: null,
+  geoCoordinates: null,
+  b2b: null,
+  person: null,
+  marketingData: null,
+  refreshAfter: null,
+}
+
+describe('reconcileSessionLocale (browser, localization enabled)', () => {
+  afterEach(() => {
+    Object.defineProperty(window, 'location', {
+      configurable: true,
+      value: originalLocation,
+    })
+  })
+
+  it('forces locale/currency from the URL when the IDB payload is stale', () => {
+    stubHref('https://store.example.com/pt-BR/pvt/some/path')
+
+    const result = reconcileSessionLocale(STALE)
+
+    expect(result.locale).toBe('pt-BR')
+    expect(result.currency).toEqual({ code: 'BRL', symbol: 'R$' })
+  })
+
+  it('preserves unrelated session fields from the payload (e.g. person)', () => {
+    stubHref('https://store.example.com/pt-BR/some/path')
+
+    const payload: Session = {
+      ...STALE,
+      person: { id: 'p1', email: 'a@b.com', givenName: 'A', familyName: 'B' },
+      postalCode: '12345',
+    }
+
+    const result = reconcileSessionLocale(payload)
+
+    expect(result.locale).toBe('pt-BR')
+    expect(result.postalCode).toBe('12345')
+    expect(result.person).toEqual({
+      id: 'p1',
+      email: 'a@b.com',
+      givenName: 'A',
+      familyName: 'B',
+    })
+  })
+
+  it('replaces salesChannel inside channel JSON while preserving non-locale channel fields', () => {
+    stubHref('https://store.example.com/pt-BR/some/path')
+
+    const payload: Session = {
+      ...STALE,
+      channel:
+        '{"salesChannel":"2","regionId":"region-xyz","customKey":"keep-me"}',
+    }
+
+    const result = reconcileSessionLocale(payload)
+    const channel = JSON.parse(result.channel ?? '{}')
+
+    expect(channel.salesChannel).toBe('1')
+    expect(channel.regionId).toBe('region-xyz')
+    expect(channel.customKey).toBe('keep-me')
+  })
+
+  it('survives a malformed channel JSON in the payload (does not throw, still reconciles)', () => {
+    stubHref('https://store.example.com/pt-BR/some/path')
+
+    const payload: Session = { ...STALE, channel: '{not valid json' }
+
+    let result: Session | undefined
+    expect(() => {
+      result = reconcileSessionLocale(payload)
+    }).not.toThrow()
+
+    expect(result?.locale).toBe('pt-BR')
+    const channel = JSON.parse(result?.channel ?? '{}')
+    expect(channel.salesChannel).toBe('1')
+  })
+
+  it('is idempotent when the payload already matches the URL locale', () => {
+    stubHref('https://store.example.com/pt-BR/some/path')
+
+    const aligned: Session = {
+      ...STALE,
+      locale: 'pt-BR',
+      currency: { code: 'BRL', symbol: 'R$' },
+      channel: '{"salesChannel":"1","regionId":"region-xyz"}',
+    }
+
+    const result = reconcileSessionLocale(aligned)
+
+    expect(result.locale).toBe('pt-BR')
+    expect(result.currency).toEqual({ code: 'BRL', symbol: 'R$' })
+    expect(JSON.parse(result.channel ?? '{}').salesChannel).toBe('1')
+  })
+})

package/test/sdk/session/reconcileSessionLocale.disabled.browser.test.ts

@@ -0,0 +1,38 @@
+/**
+ * When localization is disabled, `reconcileSessionLocale` must be a no-op so
+ * the persisted middleware behaves exactly as before (raw IDB payload flows
+ * into memory untouched).
+ */
+import type { Session } from '@faststore/sdk'
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock(import('../../../discovery.config.js'), async (original) => ({
+  default: {
+    ...((await original()).default ?? (await original())),
+    localization: undefined,
+  },
+}))
+
+import { reconcileSessionLocale } from '../../../src/sdk/session/initialSession'
+
+const PAYLOAD: Session = {
+  locale: 'en-US',
+  currency: { code: 'USD', symbol: '$' },
+  channel: '{"salesChannel":"2","regionId":"region-xyz"}',
+  country: 'USA',
+  deliveryMode: null,
+  addressType: null,
+  city: null,
+  postalCode: null,
+  geoCoordinates: null,
+  b2b: null,
+  person: null,
+  marketingData: null,
+  refreshAfter: null,
+}
+
+describe('reconcileSessionLocale (localization disabled)', () => {
+  it('returns the payload unchanged', () => {
+    expect(reconcileSessionLocale(PAYLOAD)).toBe(PAYLOAD)
+  })
+})