@faststore/core 3.98.3 → 3.98.4

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @faststore/core@3.98.2 prebuild /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.98.3 prebuild /home/runner/work/faststore/faststore/packages/core
 > na run partytown && na run generate
 
 
-> @faststore/core@3.98.2 partytown /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.98.3 partytown /home/runner/work/faststore/faststore/packages/core
 > partytown copylib ./public/~partytown
 
 Partytown lib copied to: /home/runner/work/faststore/faststore/packages/core/public/~partytown
 
-> @faststore/core@3.98.2 generate /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.98.3 generate /home/runner/work/faststore/faststore/packages/core
 > na run generate:schema && na run generate:codegen && na run format:generated
 
 
-> @faststore/core@3.98.2 generate:schema /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.98.3 generate:schema /home/runner/work/faststore/faststore/packages/core
 > tsx src/server/generator/generateGraphQLSchemaFile.ts
 
 Schema GraphQL file generated successfully
 
-> @faststore/core@3.98.2 generate:codegen /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.98.3 generate:codegen /home/runner/work/faststore/faststore/packages/core
 > graphql-codegen
 
 [STARTED] Parse Configuration
@@ -37,11 +37,11 @@ Running lifecycle hook "afterStart" scripts...
 [CLI] Loading Documents
 [CLI] Generating output
 
-> @faststore/core@3.98.2 format:generated /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.98.3 format:generated /home/runner/work/faststore/faststore/packages/core
 > prettier --write "@generated/**/*.{ts,js,tsx,jsx,json}" --loglevel error
 
 
-> @faststore/core@3.98.2 build /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.98.3 build /home/runner/work/faststore/faststore/packages/core
 > next build
 
 ⚠ No build cache found. Please configure build caching for faster rebuilds. Read more: https://nextjs.org/docs/messages/no-cache
@@ -59,8 +59,8 @@ https://nextjs.org/telemetry
    Collecting page data ...
    Generating static pages (0/6) ...
 
   Generating static pages (1/6) 
-
   Generating static pages (2/6) 
 Warning: Dynamic Content not found for the page: home. Refer to the Dynamic Content documentation at https://developers.vtex.com/docs/guides/faststore/dynamic-content-overview for mapping the page and the corresponding data-fetching function.
+
   Generating static pages (2/6) 
 
   Generating static pages (4/6) 
 
 ✓ Generating static pages (6/6) 
    Finalizing page optimization ...
@@ -81,7 +81,7 @@ Route (pages)                              Size     First Load JS
 ├ λ /api/health/live                       0 B             109 kB
 ├ λ /api/health/ready                      0 B             109 kB
 ├ λ /api/preview                           0 B             109 kB
-├ ● /checkout                              745 B           158 kB
+├ ● /checkout                              745 B           159 kB
 ├ ● /login                                 1.7 kB          159 kB
 ├ λ /pvt/account                           245 B           109 kB
 ├ ● /pvt/account/[...unknown]              286 B           109 kB
@@ -103,8 +103,8 @@ Route (pages)                              Size     First Load JS
 + First Load JS shared by all              118 kB
   ├ chunks/framework-d514426edf885c68.js   45.4 kB
   ├ chunks/main-edeb2c6a5c48bb3f.js        33.2 kB
-  ├ chunks/pages/_app-735c745509e1e8d6.js  26.1 kB
-  ├ chunks/webpack-fc37ce1526507eaf.js     3.88 kB
+  ├ chunks/pages/_app-8be996b3105d8c26.js  26.3 kB
+  ├ chunks/webpack-fd706604cbbdc60f.js     3.88 kB
   └ css/8a513f4b536b0ab0.css               9.18 kB
 
 λ  (Server)  server-side renders at runtime (uses getInitialProps or getServerSideProps)

package/.turbo/turbo-test.log

@@ -1,16 +1,16 @@
 
-> @faststore/core@3.98.2 test /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@3.98.3 test /home/runner/work/faststore/faststore/packages/core
 > jest
 
-PASS test/utils/multipleTemplates.test.ts (12.426 s)
-PASS test/utils/clearCookies.test.ts (11.827 s)
+PASS test/utils/clearCookies.test.ts (12.005 s)
+PASS test/utils/multipleTemplates.test.ts (13.659 s)
 PASS test/server/cms/global.test.ts
-PASS test/utils/cookieCacheBusting.test.ts
-PASS test/server/cms/index.test.ts (6.051 s)
-PASS test/server/index.test.ts (24.09 s)
+PASS test/utils/cookieCacheBusting.test.ts (15.415 s)
+PASS test/server/cms/index.test.ts (6.077 s)
+PASS test/server/index.test.ts (12.996 s)
 
 Test Suites: 6 passed, 6 total
-Tests:       47 passed, 47 total
+Tests:       52 passed, 52 total
 Snapshots:   0 total
-Time:        25.195 s
+Time:        27.695 s
 Ran all test suites.

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.98.4](https://github.com/vtex/faststore/compare/v3.98.3...v3.98.4) (2026-04-15)
+
+**Note:** Version bump only for package @faststore/core
+
 ## [3.98.3](https://github.com/vtex/faststore/compare/v3.98.2...v3.98.3) (2026-04-09)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/core",
-  "version": "3.98.3",
+  "version": "3.98.4",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -124,5 +124,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.3.2"
   },
-  "gitHead": "de14e7d1dded5c80a2580cfd9df597420956369b"
+  "gitHead": "ee710a0c31c409363948a3c3b7c7c1f26acb25cb"
 }

package/src/sdk/graphql/request.ts

@@ -29,7 +29,7 @@ export const request = async <Query = unknown, Variables = unknown>(
   variables: Variables,
   options?: RequestOptions
 ) => {
-  // Get cache busting value based person?.id from session
+  // Get cache busting value based on auth state and postal code
   const value = getClientCacheBustingValue()
 
   const { data, errors } = await baseRequest<Variables, Query>('/api/graphql', {

package/src/sdk/product/usePageProductsQuery.ts

@@ -1,3 +1,4 @@
+import storeConfig from 'discovery.config'
 import { useSearch } from '@faststore/sdk'
 import { gql } from '@generated'
 import type {
@@ -15,6 +16,7 @@ import {
   useState,
 } from 'react'
 import { useQuery } from 'src/sdk/graphql/useQuery'
+import { useSession } from 'src/sdk/session'
 import { generatedBuildTime } from '../../../next-seo.config'
 import { useLocalizedVariables } from './useLocalizedVariables'
 import { useShouldFetchFirstPage } from './useShouldFetchFirstPage'
@@ -80,8 +82,23 @@ export const useCreateUseGalleryPage = (
   params?: UseCreateUseGalleryPageProps
 ) => {
   const initialPages = params?.initialPages?.search ? [params.initialPages] : []
+
+  // Seed the cache with the same region-aware key shape that useGalleryPage uses,
+  // so hasSameVariables correctly matches on first mount and avoids an unnecessary
+  // re-fetch of the SSR-loaded page.
+  const isDeliveryPromiseEnabled = storeConfig.deliveryPromise?.enabled ?? false
+  const { postalCode } = useSession()
   const initialVariables = params?.serverManyProductsVariables
-    ? [getKey(params.serverManyProductsVariables)]
+    ? [
+        getKey(
+          isDeliveryPromiseEnabled
+            ? {
+                ...params.serverManyProductsVariables,
+                _postalCode: postalCode ?? '',
+              }
+            : params.serverManyProductsVariables
+        ),
+      ]
     : []
 
   const [pages, setPages] =
@@ -97,6 +114,8 @@ export const useCreateUseGalleryPage = (
       itemsPerPage,
     } = useSearch()
 
+    const { postalCode, isValidating: isSessionValidating } = useSession()
+
     const localizedVariables = useLocalizedVariables({
       first: itemsPerPage,
       after: (itemsPerPage * page).toString(),
@@ -105,9 +124,20 @@ export const useCreateUseGalleryPage = (
       selectedFacets,
     })
 
+    // Include postalCode in the cache key so pages are invalidated on region change.
+    // _postalCode is not sent to the API — it only affects the local cache comparison.
+    // Only applied when deliveryPromise is enabled to avoid unnecessary cache fragmentation.
+    const localizedVariablesWithRegion = useMemo(
+      () =>
+        isDeliveryPromiseEnabled
+          ? { ...localizedVariables, _postalCode: postalCode ?? '' }
+          : localizedVariables,
+      [localizedVariables, postalCode]
+    )
+
     const hasSameVariables = deepEquals(
       pagesCache.current[page],
-      getKey(localizedVariables)
+      getKey(localizedVariablesWithRegion)
     )
 
     const shouldFetchFirstPage = useShouldFetchFirstPage({
@@ -123,13 +153,14 @@ export const useCreateUseGalleryPage = (
     >(query, localizedVariables, {
       fallbackData: null,
       suspense: true,
-      doNotRun: !shouldFetch,
+      doNotRun:
+        !shouldFetch || (isDeliveryPromiseEnabled && isSessionValidating),
     })
 
     const shouldUpdatePages = data !== null
 
     if (shouldUpdatePages) {
-      pagesCache.current[page] = getKey(localizedVariables)
+      pagesCache.current[page] = getKey(localizedVariablesWithRegion)
 
       // Update refs
       const newPages = [...pagesRef.current]

package/src/sdk/product/useProductGalleryQuery.ts

@@ -1,3 +1,4 @@
+import storeConfig from 'discovery.config'
 import { gql } from '@generated'
 import { useQuery } from 'src/sdk/graphql/useQuery'
 import { useSession } from 'src/sdk/session'
@@ -138,7 +139,7 @@ export const useProductGalleryQuery = ({
   selectedFacets,
   itemsPerPage,
 }: ProductGalleryQueryOptions) => {
-  const { locale } = useSession()
+  const { locale, isValidating: isSessionValidating } = useSession()
   const { state, setState } = useSearch()
   const localizedVariables = useLocalizedVariables({
     first: itemsPerPage,
@@ -148,7 +149,10 @@ export const useProductGalleryQuery = ({
     selectedFacets,
   })
 
+  const isDeliveryPromiseEnabled = storeConfig.deliveryPromise?.enabled ?? false
+
   const queryResult = useQuery<Query, Variables>(query, localizedVariables, {
+    doNotRun: isDeliveryPromiseEnabled && isSessionValidating,
     onSuccess: (data: Query) => {
       const updatedFuzzyFacetValue = data.search.metadata?.fuzzy
       const updatedOperatorFacetValue = data.search.metadata?.logicalOperator
@@ -196,6 +200,7 @@ export const useProductGalleryQuery = ({
   const operatorFacetValue = findFacetValue(selectedFacets, 'operator')
   const shouldRefetchQuery =
     !queryResult.error && (!fuzzyFacetValue || !operatorFacetValue)
+
   if (shouldRefetchQuery) {
     // The first result is not relevant, return null data to avoid rendering the page while the query is being re-fetched
     return { ...queryResult, isValidating: true, data: null }

package/src/utils/cookieCacheBusting.ts

@@ -1,6 +1,8 @@
+import storeConfig from 'discovery.config'
 import { sessionStore } from 'src/sdk/session'
 
 export const STORAGE_KEY_PERSON_ID = 'faststore_person_id'
+export const STORAGE_KEY_POSTAL_CODE = 'faststore_postal_code'
 export const STORAGE_KEY_CACHE_BUST_LAST_VALUE =
   'faststore_cache_bust_last_value'
 
@@ -17,8 +19,19 @@ const getPersonId = (): string | null => {
 }
 
 /**
- * Gets the stored person id from sessionStorage (client-side only)
+ * Gets postalCode from session when deliveryPromise is enabled.
+ * Reads session store directly since vtex_segment is httpOnly and inaccessible via JavaScript.
+ * Returns null for stores that don't use delivery promise — postal code has no effect
+ * on their facets, so there is no need to fragment the CDN cache by region.
  */
+const getPostalCode = (): string | null => {
+  if (typeof window === 'undefined' || !storeConfig.deliveryPromise?.enabled) {
+    return null
+  }
+  const session = sessionStore.read() ?? sessionStore.readInitial()
+  return session?.postalCode ?? null
+}
+
 const getStoredPersonId = (): string | null => {
   if (typeof sessionStorage === 'undefined') {
     return null
@@ -31,6 +44,21 @@ const getStoredPersonId = (): string | null => {
   }
 }
 
+/**
+ * Gets the postal code from sessionStorage (client-side only)
+ */
+const getStoredPostalCode = (): string | null => {
+  if (typeof sessionStorage === 'undefined') {
+    return null
+  }
+
+  try {
+    return sessionStorage.getItem(STORAGE_KEY_POSTAL_CODE)
+  } catch {
+    return null
+  }
+}
+
 /**
  * Stores the person id in sessionStorage (client-side only)
  */
@@ -50,9 +78,22 @@ const storePersonId = (value: string | null): void => {
   }
 }
 
-/**
- * Gets the last cache busting value from sessionStorage (client-side only)
- */
+const storePostalCode = (value: string | null): void => {
+  if (typeof sessionStorage === 'undefined') {
+    return
+  }
+
+  try {
+    if (value === null) {
+      sessionStorage.removeItem(STORAGE_KEY_POSTAL_CODE)
+    } else {
+      sessionStorage.setItem(STORAGE_KEY_POSTAL_CODE, value)
+    }
+  } catch {
+    // Ignore storage errors
+  }
+}
+
 const getLastValue = (): string | null => {
   if (typeof sessionStorage === 'undefined') {
     return null
@@ -66,7 +107,7 @@ const getLastValue = (): string | null => {
 }
 
 /**
- * Stores the last cache busting value in sessionStorage (client-side only)
+ * Stores the last value in sessionStorage (client-side only)
  */
 const storeLastValue = (value: string): void => {
   if (typeof sessionStorage === 'undefined') {
@@ -81,7 +122,7 @@ const storeLastValue = (value: string): void => {
 }
 
 /**
- * Clears all cache busting related data from sessionStorage (client-side only)
+ * Clears the cache busting related data from sessionStorage (client-side only)
  */
 const clearCacheBustingStorage = (): void => {
   if (typeof sessionStorage === 'undefined') {
@@ -90,46 +131,65 @@ const clearCacheBustingStorage = (): void => {
 
   try {
     sessionStorage.removeItem(STORAGE_KEY_PERSON_ID)
+    sessionStorage.removeItem(STORAGE_KEY_POSTAL_CODE)
     sessionStorage.removeItem(STORAGE_KEY_CACHE_BUST_LAST_VALUE)
   } catch {
     // Ignore storage errors
   }
 }
 
+const buildValue = (
+  personId: string | null,
+  postalCode: string | null
+): string => {
+  const timestamp = Date.now().toString()
+  return [timestamp, personId, postalCode].filter(Boolean).join('::')
+}
+
 /**
- * Gets cache busting value for client-side based on auth state changes.
- * Uses person?.id from session (via useSession/ValidateSession) since auth cookies
- * are now httpOnly and cannot be accessed via JavaScript.
+ * Gets cache busting value for client-side GET requests based on session state.
+ *
+ * Covers two axes that make GraphQL responses user/region-specific:
+ * - Auth state (person.id): logged-in users see personalised prices and availability.
+ * - Postal code: delivery-promise facets (shipping, delivery-options) differ per region.
+ *
+ * The value is appended as the `v` query param so the CDN treats each
+ * combination as a distinct cache entry. Returns null when neither axis is set,
+ * meaning the public CDN cache is shared across all anonymous visitors with no
+ * location — which is the correct behaviour for stores without delivery promise.
  */
 export const getClientCacheBustingValue = (): string | null => {
   const currentPersonId = getPersonId()
+  const currentPostalCode = getPostalCode()
 
-  // Guard clause: if user is not logged in (no person?.id), clear storage and don't proceed with cache busting logic
-  if (currentPersonId === null) {
+  // No session-specific data: clear storage and allow shared public CDN caching (don't proceed with cache busting logic)
+  if (!currentPersonId && !currentPostalCode) {
     clearCacheBustingStorage()
     return null
   }
 
   const storedPersonId = getStoredPersonId()
+  const storedPostalCode = getStoredPostalCode()
 
-  // If person changed (login/logout or different user), update stored value and return new value
-  if (currentPersonId !== storedPersonId) {
+  // Either axis changed: persist new state and generate a fresh cache-busting value
+  if (
+    currentPersonId !== storedPersonId ||
+    currentPostalCode !== storedPostalCode
+  ) {
     storePersonId(currentPersonId)
-    const timestamp = Date.now().toString()
-    const value = `${timestamp}::${currentPersonId}`
+    storePostalCode(currentPostalCode)
+    const value = buildValue(currentPersonId, currentPostalCode)
     storeLastValue(value)
     return value
   }
 
-  // Person hasn't changed, return last value or create one if it doesn't exist
+  // Nothing changed: reuse existing value (or create one if storage was cleared)
   const lastValue = getLastValue()
   if (lastValue) {
     return lastValue
   }
 
-  // Fallback: if no last value, create one
-  const timestamp = Date.now().toString()
-  const value = `${timestamp}::${currentPersonId}`
+  const value = buildValue(currentPersonId, currentPostalCode)
   storeLastValue(value)
   return value
 }