@faststore/core 3.99.1 → 4.0.0-dev.1

package/src/sdk/graphql/request.ts

@@ -1,13 +1,14 @@
 import { getClientCacheBustingValue } from 'src/utils/cookieCacheBusting'
 
 export type RequestOptions = Omit<BaseRequestOptions, 'operation' | 'variables'>
+
 export type Operation = {
   __meta__?: Record<string, any>
 }
 
-export interface GraphQLResponse<D = any> {
-  data: D
-  errors: any[]
+export interface GraphQLResponse<Data = any> {
+  data?: Data
+  errors?: any[]
 }
 
 export interface BaseRequestOptions<V = any> {
@@ -18,33 +19,12 @@ export interface BaseRequestOptions<V = any> {
   value?: string | null
 }
 
-const DEFAULT_HEADERS_BY_VERB: Record<string, Record<string, string>> = {
-  POST: {
-    'Content-Type': 'application/json',
-  },
-}
-
-export const request = async <Query = unknown, Variables = unknown>(
-  operation: Operation,
-  variables: Variables,
-  options?: RequestOptions
-) => {
-  // Get cache busting value based on auth state and postal code
-  const value = getClientCacheBustingValue()
-
-  const { data, errors } = await baseRequest<Variables, Query>('/api/graphql', {
-    ...options,
-    variables,
-    operation,
-    value,
-  })
-
-  if (errors?.length) {
-    throw errors[0]
-  }
+const cachedOperations = import('../../../@generated/cached-operations.json')
+  .then((mod) => mod.default as string[])
+  .catch(() => [] as string[])
 
-  return data
-}
+const MethodByOperation = async (operationName: string) =>
+  (await cachedOperations).includes(operationName) ? 'GET' : 'POST'
 
 /* This piece of code was taken out of @faststore/graphql-utils */
 const baseRequest = async <V = any, D = any>(
@@ -56,40 +36,76 @@ const baseRequest = async <V = any, D = any>(
   // Uses method from fetchOptions.
   // If no one is passed, figure out with via heuristic
   const method =
-    fetchOptions?.method !== undefined
-      ? fetchOptions.method.toUpperCase()
-      : operationName.endsWith('Query')
-        ? 'GET'
-        : 'POST'
+    fetchOptions?.method?.toUpperCase() ??
+    (await MethodByOperation(operationName))
 
+  const response = await (method === 'POST' ? POSTRequest : GETRequest)({
+    endpoint,
+    operation,
+    variables,
+    fetchOptions,
+    value,
+  })
+
+  return ParseInvalidRequest(response) ?? response.json()
+}
+
+const GETRequest = <Variables>({
+  operation,
+  variables,
+  fetchOptions,
+  endpoint,
+  value,
+}: BaseRequestOptions<Variables> & { endpoint: string }) => {
+  const { operationName, operationHash } = operation['__meta__']
   const params = new URLSearchParams({
     operationName,
     operationHash,
-    ...(method === 'GET' && { variables: JSON.stringify(variables) }),
-    ...(method === 'GET' && value && { v: value }),
+    variables: JSON.stringify(variables),
+    ...(value && { v: value }),
   })
 
-  const body =
-    method === 'POST'
-      ? JSON.stringify({
-          operationName,
-          operationHash,
-          variables,
-        })
-      : undefined
+  const url = `${endpoint}?${params.toString()}`
 
+  return fetch(url, {
+    method: 'GET',
+    body: undefined,
+    ...fetchOptions,
+  })
+}
+
+const POSTRequest = <Variables>({
+  operation,
+  variables,
+  fetchOptions,
+  endpoint,
+  value,
+}: BaseRequestOptions<Variables> & { endpoint: string }) => {
+  const { operationName, operationHash } = operation['__meta__']
+  const params = new URLSearchParams({
+    operationName,
+    operationHash,
+  })
   const url = `${endpoint}?${params.toString()}`
 
-  const response = await fetch(url, {
-    method,
-    body,
+  return fetch(url, {
+    method: 'POST',
+    body: JSON.stringify({
+      operationName,
+      operationHash,
+      variables,
+    }),
     ...fetchOptions,
     headers: {
-      ...DEFAULT_HEADERS_BY_VERB[method],
+      'Content-Type': 'application/json',
       ...fetchOptions?.headers,
     },
   })
+}
 
+const ParseInvalidRequest = <T>(
+  response: Awaited<ReturnType<typeof fetch>>
+) => {
   if (!response.ok) {
     const statusText = response.statusText
     return {
@@ -100,8 +116,44 @@ const baseRequest = async <V = any, D = any>(
         },
       ],
       data: undefined,
-    } as GraphQLResponse<D>
+    } as GraphQLResponse<T>
   }
+}
+
+export async function GraphqlRequest<Query = unknown, Variables = unknown>(
+  { operation, variables }: { operation: Operation; variables: Variables },
+  options?: RequestInit
+): Promise<GraphQLResponse<Query>> {
+  // Get cache busting value based on cookie changes
+  const value = getClientCacheBustingValue()
 
-  return response.json()
+  const response = await baseRequest<Variables, Query>('/api/graphql', {
+    variables,
+    operation,
+    fetchOptions: options,
+    value,
+  })
+
+  // in Order to keep the same behaviour of previous version (request) throwing error
+  if (response.errors?.length) {
+    throw response.errors[0]
+  }
+
+  return response
+}
+
+/**
+ * @description It only exists to backward compatibilities
+ */
+export async function request<Query = unknown, Variables = unknown>(
+  operation: Operation,
+  variables: Variables,
+  options?: RequestOptions
+) {
+  return (
+    await GraphqlRequest<Query, Variables>(
+      { operation, variables },
+      options?.fetchOptions
+    )
+  ).data
 }

package/src/sdk/localization/bindingSelector.ts

@@ -0,0 +1,91 @@
+import type { Binding, Locale } from './types'
+
+/**
+ * Capitalizes the first character of a string (e.g. "italiano" → "Italiano").
+ */
+function capitalizeFirst(str: string): string {
+  if (!str) return str
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+/**
+ * Builds language options as Record<string, string> for direct use with UISelectField.
+ * Uses native locale name with first letter capitalized; adds " (regionCode)" when multiple locales share the same name.
+ *
+ * @param locales - Record of locale objects from discovery.config
+ * @returns Record where key is locale code (e.g., "pt-BR") and value is display label (e.g., "Português (BR)")
+ */
+export function buildLanguageOptions(
+  locales: Record<string, Locale>
+): Record<string, string> {
+  // Count occurrences of each name to determine disambiguation needs
+  const languageCount: Record<string, number> = {}
+  Object.values(locales).forEach((locale) => {
+    languageCount[locale.name] = (languageCount[locale.name] || 0) + 1
+  })
+
+  // Build options with conditional disambiguation; format native name with first letter capitalized
+  const options: Record<string, string> = {}
+  Object.entries(locales).forEach(([code, locale]) => {
+    const label = capitalizeFirst(locale.name)
+    const needsDisambiguation = languageCount[locale.name] > 1
+    options[code] = needsDisambiguation
+      ? `${label} (${locale.regionCode})`
+      : label
+  })
+
+  return options
+}
+
+/**
+ * Extracts unique currency codes from a locale's bindings.
+ *
+ * @param locale - The locale object containing bindings
+ * @returns Array of unique currency codes (e.g., ["BRL", "USD"])
+ */
+export function getCurrenciesForLocale(locale: Locale): string[] {
+  const currencies = new Set<string>()
+
+  locale.bindings.forEach((binding) => {
+    currencies.add(binding.currencyCode)
+  })
+
+  return Array.from(currencies)
+}
+
+/**
+ * Resolves the correct binding for a locale+currency combination.
+ * Applies isDefault tie-breaker when multiple bindings match.
+ *
+ * @param bindings - Array of bindings from a locale
+ * @param currencyCode - The selected currency code to match
+ * @returns The resolved binding, or null if no match found
+ */
+export function resolveBinding(
+  bindings: Binding[],
+  currencyCode: string
+): Binding | null {
+  const matches = bindings.filter((b) => b.currencyCode === currencyCode)
+
+  if (matches.length === 0) return null
+  if (matches.length === 1) return matches[0]
+
+  // Multiple matches - apply isDefault tie-breaker
+  return matches.find((b) => b.isDefault) ?? matches[0]
+}
+
+/**
+ * Validates that a URL is non-empty and appears to be valid.
+ *
+ * @param url - The URL string to validate
+ * @returns True if the URL is valid, false otherwise
+ */
+export function isValidUrl(url: string): boolean {
+  if (!url || url.trim() === '') return false
+  try {
+    new URL(url)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/sdk/localization/index.ts

@@ -0,0 +1,4 @@
+export type { Binding, BindingSelectorError, Locale } from './types'
+export { useBindingSelector } from './useBindingSelector'
+export type { UseBindingSelectorReturn } from './useBindingSelector'
+export { useLocaleValidation } from './useLocaleValidation'

package/src/sdk/localization/match-url.ts

@@ -0,0 +1,64 @@
+import config from 'discovery.config'
+import { matchesBindingPath } from 'src/utils/localization/bindingPaths'
+
+function shouldSkipHostnameCheck(hostname: string): boolean {
+  const isDevelopment = process.env.NODE_ENV === 'development'
+  const isLocalhost = hostname === 'localhost' || hostname === '127.0.0.1'
+  const isPreviewUrl = hostname.endsWith('.vtex.app')
+
+  return isLocalhost || isPreviewUrl || isDevelopment
+}
+
+export function matchURLBinding(href: string) {
+  let binding
+  const matchedConfig = Object.entries(config.localization.locales).find(
+    ([_, langConfig]: [string, any]) => {
+      const hostURLObject = new URL(href)
+      const skipHostname = shouldSkipHostnameCheck(hostURLObject.hostname)
+
+      binding = langConfig.bindings.find(({ url }: { url: string }) => {
+        const configURLObject = new URL(url)
+
+        const hostnameMatch =
+          skipHostname || hostURLObject.hostname === configURLObject.hostname
+
+        if (!hostnameMatch) {
+          return false
+        }
+
+        // Verify protocol matches for security, but skip on environments
+        // where the hostname is already relaxed (localhost, preview deploys).
+        if (!skipHostname) {
+          const protocolMatch =
+            hostURLObject.protocol === configURLObject.protocol
+
+          if (!protocolMatch) {
+            return false
+          }
+        }
+
+        // If the config pathname is the root, it is a subdomain binding
+        // and we don't need to check if pathname matches.
+        const configPathname =
+          configURLObject.pathname.replace(/\/$/, '') || '/'
+        const isSubdomainBinding = configPathname === '/'
+
+        // Subdomain bindings rely on hostname, so when the hostname check
+        // is skipped we can only match path-based bindings.
+        if (isSubdomainBinding) {
+          return !skipHostname
+        }
+
+        // Check if pathname matches (exact or prefix match)
+        return matchesBindingPath(
+          hostURLObject.pathname,
+          configURLObject.pathname
+        )
+      })
+
+      return !!binding
+    }
+  )?.[1]
+
+  return { config: matchedConfig, binding }
+}

package/src/sdk/localization/types.ts

@@ -0,0 +1,31 @@
+export interface Binding {
+  currencyCode: string
+  url: string
+  salesChannel: string
+  /**
+   * When true, this binding is preferred for its locale in two cases:
+   * (1) When the URL does not match any binding, the default locale's binding
+   *     with isDefault is used for session/settings.
+   * (2) When resolving locale+currency and multiple bindings match (e.g. same
+   *     currency, different URLs), the one with isDefault is chosen.
+   * Each locale should have exactly one binding with isDefault: true to avoid
+   * ambiguous resolution.
+   */
+  isDefault: boolean
+}
+
+export interface Locale {
+  code: string
+  name: string
+  languageCode: string
+  languageName: string
+  script: string
+  textDirection: 'ltr' | 'rtl'
+  regionCode: string
+  bindings: Binding[]
+}
+
+export type BindingSelectorError =
+  | { type: 'no-binding-found'; locale: string; currency: string }
+  | { type: 'invalid-url'; url: string }
+  | { type: 'no-currencies'; locale: string }

package/src/sdk/localization/useBindingSelector.ts

@@ -0,0 +1,183 @@
+import { useCallback, useMemo, useState } from 'react'
+
+import storeConfig from '../../../discovery.config'
+import { buildRedirectUrl } from '../../utils/localization/bindingPaths'
+import { useSession } from '../session'
+import {
+  buildLanguageOptions,
+  getCurrenciesForLocale,
+  isValidUrl,
+  resolveBinding,
+} from './bindingSelector'
+import type { BindingSelectorError, Locale } from './types'
+
+interface Currency {
+  code: string
+  name: string
+  symbol: string
+}
+
+interface Region {
+  code: string
+  name: string
+  dateFormat: string
+  timeFormat: string
+  timeFormatMask: string
+  unitSystem: string
+  defaultTimezone: string
+}
+
+interface LocalizationConfig {
+  defaultLocale: string
+  regions: Record<string, Region>
+  locales: Record<string, Locale>
+  currencies: Record<string, Currency>
+}
+
+/**
+ * Hook return type for useBindingSelector.
+ */
+export interface UseBindingSelectorReturn {
+  /** Language options as { localeCode: languageName } for UISelectField */
+  languages: Record<string, string>
+  /** Currency options as { currencyCode: currencyCode } for UISelectField */
+  currencies: Record<string, string>
+  /** Selected locale code (e.g., "pt-BR") */
+  localeCode: string | null
+  /** Selected currency code (e.g., "BRL") */
+  currencyCode: string | null
+  /** True when both locale and currency are selected and no error */
+  isSaveEnabled: boolean
+  /** Current error state, if any */
+  error: BindingSelectorError | null
+  /** Action to set the locale code (e.g., "pt-BR") */
+  setLocaleCode: (code: string) => void
+  /** Action to set the currency code */
+  setCurrencyCode: (code: string) => void
+  /** Action to save selections and redirect */
+  save: () => void
+}
+
+/**
+ * Hook that provides state and actions for the localization selector.
+ * Manages locale selection, currency filtering, and binding resolution.
+ *
+ * @returns Object with languages, currencies, selections, and actions
+ */
+export function useBindingSelector(): UseBindingSelectorReturn {
+  const { locale: currentLocale, currency: currentCurrency } = useSession()
+  const localizationConfig = storeConfig.localization as LocalizationConfig
+
+  // Pre-select current locale code and currency code from session
+  const [localeCode, setLocaleCode] = useState<string | null>(
+    () => currentLocale ?? null
+  )
+  const [currencyCode, setCurrencyCode] = useState<string | null>(
+    () => currentCurrency?.code ?? null
+  )
+  const [error, setError] = useState<BindingSelectorError | null>(null)
+
+  // Build language options with disambiguation - returns Record<localeCode, languageName>
+  const languages = useMemo(
+    () => buildLanguageOptions(localizationConfig.locales),
+    [localizationConfig.locales]
+  )
+
+  // Filter currencies based on selected locale
+  const currencies = useMemo(() => {
+    if (!localeCode || !localizationConfig.locales[localeCode]) {
+      return {}
+    }
+    const currencyList = getCurrenciesForLocale(
+      localizationConfig.locales[localeCode]
+    )
+    // Convert array to Record<string, string> for UISelectField
+    return Object.fromEntries(currencyList.map((code) => [code, code]))
+  }, [localeCode, localizationConfig.locales])
+
+  // Handle locale code change
+  const handleSetLocaleCode = useCallback(
+    (code: string) => {
+      setLocaleCode(code)
+      setError(null)
+
+      // Check if current currency is available in new locale
+      const locale = localizationConfig.locales[code]
+      if (locale) {
+        const availableCurrencies = getCurrenciesForLocale(locale)
+
+        if (availableCurrencies.length === 0) {
+          setError({ type: 'no-currencies', locale: code })
+          setCurrencyCode(null)
+        } else {
+          const currencyStillValid =
+            currencyCode && availableCurrencies.includes(currencyCode)
+          if (!currencyStillValid) {
+            // Auto-select first currency if only one available, otherwise clear
+            setCurrencyCode(
+              availableCurrencies.length === 1 ? availableCurrencies[0] : null
+            )
+          }
+        }
+      }
+    },
+    [localizationConfig.locales, currencyCode]
+  )
+
+  // Handle currency code change
+  const handleSetCurrencyCode = useCallback((code: string) => {
+    setCurrencyCode(code)
+    setError(null)
+  }, [])
+
+  // Save and redirect
+  const save = useCallback(() => {
+    if (!localeCode || !currencyCode) return
+
+    const locale = localizationConfig.locales[localeCode]
+    if (!locale) {
+      setError({
+        type: 'no-binding-found',
+        locale: localeCode,
+        currency: currencyCode,
+      })
+      return
+    }
+
+    const binding = resolveBinding(locale.bindings, currencyCode)
+
+    if (!binding) {
+      setError({
+        type: 'no-binding-found',
+        locale: localeCode,
+        currency: currencyCode,
+      })
+      return
+    }
+
+    if (!isValidUrl(binding.url)) {
+      setError({ type: 'invalid-url', url: binding.url })
+      return
+    }
+
+    // Redirect to binding URL, preserving the current page path and query string
+    window.location.href = buildRedirectUrl(
+      binding.url,
+      `${window.location.pathname}${window.location.search}${window.location.hash}`
+    )
+  }, [localeCode, currencyCode, localizationConfig.locales])
+
+  const isSaveEnabled = Boolean(localeCode && currencyCode && !error)
+
+  return {
+    languages,
+    currencies,
+    localeCode,
+    currencyCode,
+    isSaveEnabled,
+    error,
+    setLocaleCode: handleSetLocaleCode,
+    setCurrencyCode: handleSetCurrencyCode,
+    save,
+  }
+}

package/src/sdk/localization/useLocaleValidation.ts

@@ -0,0 +1,49 @@
+import { useRouter } from 'next/router'
+import { useEffect } from 'react'
+
+import storeConfig from 'discovery.config'
+import { validateLocaleForHostname } from 'src/utils/localization/validateLocaleForHostname'
+
+/**
+ * Client-side validation hook for locale binding.
+ *
+ * This hook validates that the current locale matches the hostname binding
+ * configuration. It acts as a fallback for static pages that cannot perform
+ * server-side validation.
+ *
+ * If the locale is invalid for the current hostname, the user is redirected to the 404 page.
+ *
+ * Only runs if localization feature is enabled (localization.enabled === true).
+ */
+export function useLocaleValidation() {
+  const router = useRouter()
+
+  useEffect(() => {
+    // Skip validation if localization feature is not enabled
+    if (!storeConfig.localization?.enabled) {
+      return
+    }
+
+    // Skip validation if we're already on the 404 page (from SSR notFound)
+    if (router.pathname === '/404') {
+      return
+    }
+
+    const hostname = window.location.hostname
+    const locale = router.locale
+
+    if (!locale) {
+      return
+    }
+
+    try {
+      const isValid = validateLocaleForHostname(hostname, locale)
+
+      if (!isValid) {
+        window.location.href = `/404?from=${encodeURIComponent(`/${locale}${router.asPath}`)}`
+      }
+    } catch (error) {
+      console.warn('Client-side locale validation failed:', error)
+    }
+  }, [router.locale, router.asPath, router.defaultLocale, router.pathname])
+}