create-brainerce-store 1.88.0 → 1.89.0

package/templates/nextjs/base/src/core/hooks/use-product-listing.ts

@@ -1,25 +1,27 @@
 'use client';
 
-import { useEffect, useMemo, useState, useCallback } from 'react';
+import { useEffect, useMemo, useRef, useState, useCallback } from 'react';
 import { useSearchParams } from 'next/navigation';
 import { useRouter } from '@/core/lib/navigation';
 import type { Product, ProductQueryParams, PublicMetafieldDefinition } from 'brainerce';
 import { getClient } from '@/core/lib/brainerce';
+import {
+  buildProductQuery,
+  isFilterableMetafield,
+  listingSignature,
+  LISTING_SORTS,
+  METAFIELD_URL_PREFIX,
+  readListingUrlState,
+  selectedMetafieldsKey,
+} from '@/core/lib/listing-query';
+import { useListingSeed } from '@/core/providers/listing-seed';
 import { useRegion } from '@/core/providers/store-provider';
 
-const PAGE_SIZE = 20;
-
 /**
- * Metafield (custom-field) values are passed in the URL as `mf_<key>=v1,v2`
- * for readability (no JSON encoding). The SDK assembles them back into
- * `{ [key]: string[] }` before calling `client.getProducts`.
- *
- * Only definitions with `filterable: true` of type SELECT / MULTI_SELECT /
- * BOOLEAN are honored server-side — the storefront renders facets only for
- * those.
+ * How the URL becomes a query (page size, sort table, `mf_<key>` facets, which
+ * custom fields count as filterable) lives in `@/core/lib/listing-query`, shared
+ * with the server page that renders the first page of `/products`.
  */
-const METAFIELD_URL_PREFIX = 'mf_';
-const FILTERABLE_TYPES = new Set(['SELECT', 'MULTI_SELECT', 'BOOLEAN']);
 
 export type SortOption = {
   labelKey: 'sortNewest' | 'sortNameAZ' | 'sortNameZA' | 'sortPriceLow' | 'sortPriceHigh';
@@ -28,11 +30,11 @@ export type SortOption = {
 };
 
 export const sortOptions: SortOption[] = [
-  { labelKey: 'sortNewest', sortBy: 'createdAt', sortOrder: 'desc' },
-  { labelKey: 'sortNameAZ', sortBy: 'name', sortOrder: 'asc' },
-  { labelKey: 'sortNameZA', sortBy: 'name', sortOrder: 'desc' },
-  { labelKey: 'sortPriceLow', sortBy: 'price', sortOrder: 'asc' },
-  { labelKey: 'sortPriceHigh', sortBy: 'price', sortOrder: 'desc' },
+  { labelKey: 'sortNewest', ...LISTING_SORTS[0] },
+  { labelKey: 'sortNameAZ', ...LISTING_SORTS[1] },
+  { labelKey: 'sortNameZA', ...LISTING_SORTS[2] },
+  { labelKey: 'sortPriceLow', ...LISTING_SORTS[3] },
+  { labelKey: 'sortPriceHigh', ...LISTING_SORTS[4] },
 ];
 
 export interface CategoryNode {
@@ -115,35 +117,64 @@ export function useProductListing(): UseProductListingResult {
   const router = useRouter();
   const { regionId } = useRegion();
 
-  const searchQuery = searchParams.get('search') || '';
-  const categoryId = searchParams.get('category') || '';
-  const brandId = searchParams.get('brand') || '';
-  const tagId = searchParams.get('tag') || '';
-  // `minPrice` / `maxPrice` are discrete top-level query keys on getProducts —
-  // there is no `filters` object. The SDK builds its query string from a fixed
-  // whitelist, so a misspelt key is dropped silently and the caller gets a 200
-  // of unfiltered results rather than an error.
-  const minPrice = searchParams.get('minPrice') || '';
-  const maxPrice = searchParams.get('maxPrice') || '';
-  const sortParam = searchParams.get('sort') || '0';
+  // Everything the URL says about the query, read by the same function the
+  // server page uses.
+  const urlState = useMemo(() => readListingUrlState(searchParams), [searchParams]);
+  const { search: searchQuery, categoryId, brandId, tagId, minPrice, maxPrice } = urlState;
+  const sortIndex = urlState.sortIndex;
+
+  // The server renders the first page of THIS url (`app/products/page.tsx`), so
+  // the initial HTML carries real products. The seed answers the query only
+  // while its signature equals the one this hook computes: same filters, sort,
+  // page, facets and region. Anything else is fetched exactly as before.
+  const listingSeed = useListingSeed();
+
+  // Filterable custom-field definitions. Seeded when the URL selects a facet, so
+  // the signature below can be computed before the browser has loaded them.
+  const [metafieldDefs, setMetafieldDefs] = useState<PublicMetafieldDefinition[]>(
+    listingSeed?.metafieldDefs ?? []
+  );
+
+  // Stable serialized signature of the selected metafield facets: the
+  // `loadProducts` dependency, and the source of the SDK `metafields` shape.
+  // `''` when nothing is selected, so the SDK call omits `metafields` entirely
+  // and the backend short-circuits that filter branch.
+  const metafieldsKey = useMemo(
+    () =>
+      selectedMetafieldsKey(
+        urlState.metafields,
+        metafieldDefs.map((d) => d.key)
+      ),
+    [urlState.metafields, metafieldDefs]
+  );
+
+  const querySignature = listingSignature(urlState, {
+    regionId,
+    metafieldsKey,
+    page: urlState.page,
+  });
+  const seedApplies = !!listingSeed && listingSeed.signature === querySignature;
 
-  const [products, setProducts] = useState<Product[]>([]);
-  const [loading, setLoading] = useState(true);
+  const [products, setProducts] = useState<Product[]>(
+    seedApplies && listingSeed ? listingSeed.products : []
+  );
+  // ⛔ A seeded listing starts with `loading` false. The spinner branch renders
+  // instead of the grid while it is true, so a `true` here puts the spinner, not
+  // the products, into the server HTML and the seed buys nothing.
+  const [loading, setLoading] = useState(!seedApplies);
   const [loadingMore, setLoadingMore] = useState(false);
-  const [page, setPage] = useState(1);
-  const [totalPages, setTotalPages] = useState(1);
-  const [total, setTotal] = useState(0);
+  const [page, setPage] = useState(seedApplies && listingSeed ? listingSeed.page : urlState.page);
+  const [totalPages, setTotalPages] = useState(
+    seedApplies && listingSeed ? listingSeed.totalPages : 1
+  );
+  const [total, setTotal] = useState(seedApplies && listingSeed ? listingSeed.total : 0);
   const [categories, setCategories] = useState<CategoryNode[]>([]);
   const [brands, setBrands] = useState<Array<{ id: string; name: string }>>([]);
   const [tags, setTags] = useState<Array<{ id: string; name: string }>>([]);
-  const [metafieldDefs, setMetafieldDefs] = useState<PublicMetafieldDefinition[]>([]);
   const [metafieldCounts, setMetafieldCounts] = useState<Record<string, Record<string, number>>>(
     {}
   );
 
-  const sortIndex = parseInt(sortParam, 10) || 0;
-  const currentSort = sortOptions[sortIndex] || sortOptions[0];
-
   // Load categories, brands, tags, and metafield definitions (for custom-field facets).
   // The metafield-definitions endpoint already returns only definitions
   // published to this sales channel; we filter client-side to the ones flagged
@@ -167,11 +198,7 @@ export function useProductListing(): UseProductListingResult {
       if (brandRes.status === 'fulfilled') setBrands(brandRes.value.brands);
       if (tagRes.status === 'fulfilled') setTags(tagRes.value.tags);
       if (mfRes.status === 'fulfilled') {
-        setMetafieldDefs(
-          mfRes.value.definitions.filter(
-            (d) => d.filterable === true && FILTERABLE_TYPES.has(d.type)
-          )
-        );
+        setMetafieldDefs(mfRes.value.definitions.filter(isFilterableMetafield));
       }
       if (mfCountRes.status === 'fulfilled') {
         const counts: Record<string, Record<string, number>> = {};
@@ -186,20 +213,6 @@ export function useProductListing(): UseProductListingResult {
     loadFilters();
   }, []);
 
-  // Stable serialized signature of the selected metafield facets — used as
-  // the `loadProducts` dependency (and to derive the SDK shape). When no
-  // facets are selected, this is `''` so the SDK call omits `metafields`
-  // entirely and the backend short-circuits the filter branch.
-  const metafieldsKey = useMemo(() => {
-    if (metafieldDefs.length === 0) return '';
-    const parts: string[] = [];
-    for (const def of metafieldDefs) {
-      const raw = searchParams.get(`${METAFIELD_URL_PREFIX}${def.key}`);
-      if (raw) parts.push(`${def.key}=${raw}`);
-    }
-    return parts.sort().join('&');
-  }, [metafieldDefs, searchParams]);
-
   // Load products when filters change
   const loadProducts = useCallback(
     async (pageNum: number, append: boolean) => {
@@ -211,50 +224,9 @@ export function useProductListing(): UseProductListingResult {
         }
 
         const client = getClient();
-        const params: ProductQueryParams = {
-          page: pageNum,
-          limit: PAGE_SIZE,
-          sortBy: currentSort.sortBy,
-          sortOrder: currentSort.sortOrder,
-        };
-
-        // ⛔ Region belongs on every product read. Omit it and this grid
-        // quotes the DEFAULT region's prices to every shopper on earth, on a
-        // page that looks perfectly correct. `undefined` on a store with no
-        // regions, and the SDK then omits the param.
-        if (regionId) params.regionId = regionId;
-
-        if (searchQuery) params.search = searchQuery;
-        if (categoryId) params.categories = categoryId;
-        if (brandId) params.brands = brandId;
-        if (tagId) params.tags = tagId;
-        // Sent only when the shopper set a bound, and only when it parses as a
-        // number: `minPrice`/`maxPrice` are typed `number` on ProductQueryParams,
-        // and a NaN would serialize into the query string and filter everything
-        // out. An unset bound is simply omitted.
-        const minPriceNum = minPrice === '' ? NaN : Number(minPrice);
-        const maxPriceNum = maxPrice === '' ? NaN : Number(maxPrice);
-        if (Number.isFinite(minPriceNum)) params.minPrice = minPriceNum;
-        if (Number.isFinite(maxPriceNum)) params.maxPrice = maxPriceNum;
-        // Build the `metafields` shape from `metafieldsKey` (each segment is
-        // `key=v1,v2`). Equivalent to reading the URL params directly but
-        // tied to the stable signature already in this callback's deps.
-        if (metafieldsKey) {
-          const mf: Record<string, string[]> = {};
-          for (const segment of metafieldsKey.split('&')) {
-            const eq = segment.indexOf('=');
-            if (eq < 0) continue;
-            const k = segment.slice(0, eq);
-            const v = segment
-              .slice(eq + 1)
-              .split(',')
-              .map((s) => s.trim())
-              .filter(Boolean);
-            if (v.length > 0) mf[k] = v;
-          }
-          if (Object.keys(mf).length > 0) params.metafields = mf;
-        }
-
+        // Region switching re-runs the query so the grid re-prices, exactly like
+        // changing a filter (`regionId` is part of the signature).
+        const params = buildProductQuery(urlState, { regionId, metafieldsKey, page: pageNum });
         const result = await client.getProducts(params);
 
         if (append) {
@@ -272,25 +244,32 @@ export function useProductListing(): UseProductListingResult {
         setLoadingMore(false);
       }
     },
-    [
-      searchQuery,
-      categoryId,
-      brandId,
-      tagId,
-      minPrice,
-      maxPrice,
-      currentSort.sortBy,
-      currentSort.sortOrder,
-      metafieldsKey,
-      // Switching region re-runs the query so the grid re-prices, exactly
-      // like changing a filter.
-      regionId,
-    ]
+    [urlState, regionId, metafieldsKey]
   );
 
+  // The signature of the query the products on screen answer. Starts as the
+  // seed's when it applies, so the first effect run is a no-op. A ref holding the
+  // signature rather than a flag spent on first use: React's dev-only double
+  // effect run then cannot consume the seed and fetch anyway. The first run that
+  // sees a different signature (a filter, a sort, a page, a region switch) loads.
+  const loadedSignature = useRef<string | null>(seedApplies ? querySignature : null);
+
   useEffect(() => {
-    loadProducts(1, false);
-  }, [loadProducts]);
+    if (loadedSignature.current === querySignature) return;
+    loadedSignature.current = querySignature;
+    // Client-side navigation to a URL the server has already rendered (the
+    // crawlable prev/next links under the grid): the new seed arrives with the
+    // new URL, so adopt it instead of fetching the same page a second time.
+    if (listingSeed && listingSeed.signature === querySignature) {
+      setProducts(listingSeed.products);
+      setPage(listingSeed.page);
+      setTotalPages(listingSeed.totalPages);
+      setTotal(listingSeed.total);
+      setLoading(false);
+      return;
+    }
+    loadProducts(urlState.page, false);
+  }, [loadProducts, querySignature, urlState.page, listingSeed]);
 
   function handleLoadMore() {
     if (page < totalPages && !loadingMore) {
@@ -305,6 +284,9 @@ export function useProductListing(): UseProductListingResult {
     } else {
       params.delete(key);
     }
+    // A different filter or sort is a different result set; keeping `?page=3`
+    // would land the shopper on the third page of something they just changed.
+    if (key !== 'page') params.delete('page');
     router.push(`/products?${params.toString()}`);
   }
 
@@ -329,6 +311,7 @@ export function useProductListing(): UseProductListingResult {
     } else {
       params.delete('maxPrice');
     }
+    params.delete('page');
     router.push(`/products?${params.toString()}`);
   }
 

package/templates/nextjs/base/src/core/hooks/use-reviews-enabled.ts

@@ -0,0 +1,17 @@
+'use client';
+
+import { useStoreInfo } from '@/core/providers/store-provider';
+import { reviewsAreOn } from '@/core/lib/store-info';
+
+/**
+ * Whether to render reviews UI: the section, the star rating on a product card,
+ * a rating band. `false` only when the merchant switched reviews off.
+ *
+ * Absent counts as ON, including while the store info is still loading, so a
+ * store with reviews on never flashes its stars away. `Product.avgRating` and
+ * `reviewCount` keep their stored values while reviews are off, so gate on this,
+ * never on `reviewCount > 0`.
+ */
+export function useReviewsEnabled(): boolean {
+  return reviewsAreOn(useStoreInfo().storeInfo);
+}

package/templates/nextjs/base/src/core/lib/listing-query.ts

@@ -0,0 +1,199 @@
+import type { ProductQueryParams, PublicMetafieldDefinition } from 'brainerce';
+
+/**
+ * The product-listing query, in one plain module shared by the server page and
+ * the client hook.
+ *
+ * `/products` renders its first page on the SERVER from the URL
+ * (`app/products/page.tsx`), and `use-product-listing.ts` decides in the browser
+ * whether that seed still answers the query it would have run. Both must derive
+ * the SAME query and the SAME signature from the same URL, or the seed is either
+ * thrown away (a wasted round trip and a spinner flash) or shown for a query it
+ * does not match (the wrong products). Two copies of this logic would drift, so
+ * there is one.
+ *
+ * No `'use client'` directive on purpose: a non-component export crossing that
+ * boundary into a server component becomes a client reference, not a value.
+ */
+export const LISTING_PAGE_SIZE = 20;
+
+/** Number of products the homepage's featured grid shows. */
+export const HOME_FEATURED_LIMIT = 8;
+
+/** Metafield facets travel in the URL as `mf_<key>=v1,v2`. */
+export const METAFIELD_URL_PREFIX = 'mf_';
+
+/** Sort choices by `?sort=` index. Index 0 (newest first) is the default. */
+export const LISTING_SORTS = [
+  { sortBy: 'createdAt', sortOrder: 'desc' },
+  { sortBy: 'name', sortOrder: 'asc' },
+  { sortBy: 'name', sortOrder: 'desc' },
+  { sortBy: 'price', sortOrder: 'asc' },
+  { sortBy: 'price', sortOrder: 'desc' },
+] as const satisfies ReadonlyArray<{
+  sortBy: NonNullable<ProductQueryParams['sortBy']>;
+  sortOrder: NonNullable<ProductQueryParams['sortOrder']>;
+}>;
+
+/** Only these custom-field types render as a facet, and so only these filter. */
+const FILTERABLE_METAFIELD_TYPES = new Set(['SELECT', 'MULTI_SELECT', 'BOOLEAN']);
+
+export function isFilterableMetafield(def: PublicMetafieldDefinition): boolean {
+  return def.filterable === true && FILTERABLE_METAFIELD_TYPES.has(def.type);
+}
+
+/** What both `URLSearchParams` and a server `searchParams` object can answer. */
+export interface ListingParamSource {
+  get(name: string): string | null;
+  keys(): Iterable<string>;
+}
+
+/** Wrap a Next.js server `searchParams` object so it reads like `URLSearchParams`. */
+export function paramSourceFromObject(
+  query: Record<string, string | string[] | undefined>
+): ListingParamSource {
+  const first = (value: string | string[] | undefined): string | null =>
+    Array.isArray(value) ? (value[0] ?? null) : (value ?? null);
+  return {
+    get: (name) => first(query[name]),
+    keys: () => Object.keys(query),
+  };
+}
+
+export interface ListingUrlState {
+  search: string;
+  categoryId: string;
+  brandId: string;
+  tagId: string;
+  minPrice: string;
+  maxPrice: string;
+  sortIndex: number;
+  /** 1-based page named by `?page=`; 1 when absent or not a positive integer. */
+  page: number;
+  /** Raw `mf_<key>` values by metafield key. */
+  metafields: Record<string, string>;
+}
+
+const MAX_PAGE = 1000;
+
+export function readListingUrlState(source: ListingParamSource): ListingUrlState {
+  const metafields: Record<string, string> = {};
+  for (const key of source.keys()) {
+    if (!key.startsWith(METAFIELD_URL_PREFIX)) continue;
+    const raw = source.get(key);
+    if (raw) metafields[key.slice(METAFIELD_URL_PREFIX.length)] = raw;
+  }
+  const pageNum = parseInt(source.get('page') ?? '', 10);
+  return {
+    search: source.get('search') || '',
+    categoryId: source.get('category') || '',
+    brandId: source.get('brand') || '',
+    tagId: source.get('tag') || '',
+    // `minPrice` / `maxPrice` are discrete top-level query keys on getProducts;
+    // there is no `filters` object, and the SDK builds its query string from a
+    // fixed whitelist, so a misspelt key is dropped silently and the caller gets
+    // a 200 of unfiltered results rather than an error.
+    minPrice: source.get('minPrice') || '',
+    maxPrice: source.get('maxPrice') || '',
+    sortIndex: parseInt(source.get('sort') ?? '', 10) || 0,
+    page: Number.isFinite(pageNum) && pageNum >= 1 ? Math.min(pageNum, MAX_PAGE) : 1,
+    metafields,
+  };
+}
+
+/** The sort the URL selects, falling back to newest-first for an unknown index. */
+export function listingSort(state: Pick<ListingUrlState, 'sortIndex'>) {
+  return LISTING_SORTS[state.sortIndex] ?? LISTING_SORTS[0];
+}
+
+/**
+ * Stable signature of the selected metafield facets, in `key=v1,v2` segments
+ * joined by `&` and sorted. Only keys named in `filterableKeys` count: a facet
+ * the store does not expose as filterable is ignored, exactly as the listing UI
+ * ignores it. `''` when nothing is selected, so the SDK call omits `metafields`
+ * entirely and the backend short-circuits that filter branch.
+ */
+export function selectedMetafieldsKey(
+  metafields: Record<string, string>,
+  filterableKeys: readonly string[]
+): string {
+  const parts: string[] = [];
+  for (const key of filterableKeys) {
+    const raw = metafields[key];
+    if (raw) parts.push(`${key}=${raw}`);
+  }
+  return parts.sort().join('&');
+}
+
+interface QueryOptions {
+  regionId: string | undefined;
+  metafieldsKey: string;
+  page: number;
+}
+
+/**
+ * The `getProducts` params for a URL state. The one place that knows how a URL
+ * becomes a query; the server page and the client hook both call it.
+ *
+ * ⛔ Region belongs on every product read. Omit it and the grid quotes the
+ * DEFAULT region's prices to every shopper on earth, on a page that looks
+ * perfectly correct. `undefined` on a store with no regions, and the SDK then
+ * omits the param.
+ */
+export function buildProductQuery(state: ListingUrlState, opts: QueryOptions): ProductQueryParams {
+  const sort = listingSort(state);
+  const params: ProductQueryParams = {
+    page: opts.page,
+    limit: LISTING_PAGE_SIZE,
+    sortBy: sort.sortBy,
+    sortOrder: sort.sortOrder,
+  };
+  if (opts.regionId) params.regionId = opts.regionId;
+  if (state.search) params.search = state.search;
+  if (state.categoryId) params.categories = state.categoryId;
+  if (state.brandId) params.brands = state.brandId;
+  if (state.tagId) params.tags = state.tagId;
+  // Sent only when the shopper set a bound, and only when it parses as a number:
+  // `minPrice`/`maxPrice` are typed `number`, and a NaN would serialize into the
+  // query string and filter everything out. An unset bound is simply omitted.
+  const minPriceNum = state.minPrice === '' ? NaN : Number(state.minPrice);
+  const maxPriceNum = state.maxPrice === '' ? NaN : Number(state.maxPrice);
+  if (Number.isFinite(minPriceNum)) params.minPrice = minPriceNum;
+  if (Number.isFinite(maxPriceNum)) params.maxPrice = maxPriceNum;
+  if (opts.metafieldsKey) {
+    const mf: Record<string, string[]> = {};
+    for (const segment of opts.metafieldsKey.split('&')) {
+      const eq = segment.indexOf('=');
+      if (eq < 0) continue;
+      const values = segment
+        .slice(eq + 1)
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (values.length > 0) mf[segment.slice(0, eq)] = values;
+    }
+    if (Object.keys(mf).length > 0) params.metafields = mf;
+  }
+  return params;
+}
+
+/**
+ * Everything that decides WHICH products a query returns, as one string. A seed
+ * is valid for exactly the signature it was fetched at.
+ */
+export function listingSignature(state: ListingUrlState, opts: QueryOptions): string {
+  const sort = listingSort(state);
+  return [
+    opts.regionId ?? '',
+    state.search,
+    state.categoryId,
+    state.brandId,
+    state.tagId,
+    state.minPrice,
+    state.maxPrice,
+    sort.sortBy,
+    sort.sortOrder,
+    opts.metafieldsKey,
+    opts.page,
+  ].join('|');
+}

package/templates/nextjs/base/src/core/lib/locale-path.ts

@@ -0,0 +1,29 @@
+import { defaultLocale } from '@/i18n';
+
+/**
+ * URL prefix for a locale under the "as-needed" strategy: none for the default
+ * locale (clean URLs), `/{locale}` for every other one.
+ *
+ * ⛔ The default locale arrives as a real `params.locale` too. The middleware
+ * rewrites `/foo` to `/{defaultLocale}/foo` internally and 308-redirects
+ * `/{defaultLocale}/foo` back to `/foo`, so a canonical tag, breadcrumb link or
+ * JSON-LD url built as `/${locale}/foo` for the default locale points at a URL
+ * that redirects. Build every public path through this helper.
+ *
+ * Reads the same scaffold-time `defaultLocale` the middleware uses, so the two
+ * can never disagree about which locale is the unprefixed one.
+ */
+export function localePrefix(locale: string | undefined | null): string {
+  return locale && locale !== defaultLocale ? `/${locale}` : '';
+}
+
+/**
+ * Site-relative public path for `path` in `locale`:
+ * `localePath('he', '/blog')` → `/he/blog`, default locale → `/blog`,
+ * `localePath('he', '/')` → `/he`, `localePath(undefined, '/')` → `/`.
+ */
+export function localePath(locale: string | undefined | null, path: string): string {
+  const prefix = localePrefix(locale);
+  if (path === '' || path === '/') return prefix || '/';
+  return `${prefix}${path.startsWith('/') ? path : `/${path}`}`;
+}

package/templates/nextjs/base/src/core/lib/reviews-disabled.ts

@@ -0,0 +1,19 @@
+import { BrainerceError } from 'brainerce';
+
+/**
+ * True when a reviews call failed because the merchant switched reviews off.
+ *
+ * Branch on the stable `details.code`, never on the message wording: a bare 403
+ * is also what the origin check and a suspended store answer. Any other failure
+ * (network, 5xx) is a real error and must not be treated as "reviews are off".
+ *
+ * Prefer reading `storeInfo.reviewsEnabled` first (see `reviewsAreOn`); this
+ * covers a backend too old to send the flag.
+ */
+export function isReviewsDisabledError(err: unknown): boolean {
+  return (
+    err instanceof BrainerceError &&
+    err.statusCode === 403 &&
+    (err.details as { code?: string } | undefined)?.code === 'REVIEWS_DISABLED'
+  );
+}

package/templates/nextjs/base/src/core/lib/server-messages.ts.ejs

@@ -0,0 +1,34 @@
+<% if (i18nEnabled) { %>import { getMessages, defaultLocale } from '@/i18n';
+
+/**
+ * One message namespace for a SERVER component, in the request locale.
+ *
+ * Page metadata, JSON-LD and breadcrumb names are rendered on the server, before
+ * any client i18n context exists, so they cannot use `useTranslations`. A locale
+ * with no message file falls back to the default locale's file (see `getMessages`),
+ * never to a hardcoded English string.
+ */
+export async function getServerNamespace(
+  namespace: string,
+  locale?: string
+): Promise<Record<string, string>> {
+  const all = await getMessages(locale ?? defaultLocale);
+  return (all[namespace] ?? {}) as Record<string, string>;
+}
+<% } else { %>import { messages } from '@/i18n';
+
+/**
+ * One message namespace for a SERVER component. Single-language storefront: the
+ * one message file is the answer for every request. Same signature as the
+ * multi-language build so callers do not branch.
+ */
+export async function getServerNamespace(
+  namespace: string,
+  _locale?: string
+): Promise<Record<string, string>> {
+  return ((messages as Record<string, Record<string, string>>)[namespace] ?? {}) as Record<
+    string,
+    string
+  >;
+}
+<% } %>

package/templates/nextjs/base/src/core/lib/store-info.ts

@@ -60,6 +60,14 @@ export interface PublicStoreInfo {
    * same change or it silently resolves to undefined.
    */
   stockAlertsEnabled?: boolean;
+  /**
+   * Whether the merchant has product reviews switched on. `false` means render
+   * no reviews UI at all: not the section, not the star rating on a product
+   * card, and no `aggregateRating` in the structured data. Absent means ON (an
+   * older backend sends no flag) — read it through {@link reviewsAreOn}, never
+   * with a bare truthiness check, or an old backend silently hides every review.
+   */
+  reviewsEnabled?: boolean;
   /**
    * IANA timezone the store operates in (e.g. "Asia/Jerusalem"). The checkout
    * date/time custom fields evaluate availability against THIS, never the
@@ -92,6 +100,18 @@ export function pickPublicStoreInfo(raw: StoreInfo): PublicStoreInfo {
     tracking: raw.tracking,
     seo: raw.seo,
     stockAlertsEnabled: raw.stockAlertsEnabled,
+    // `brainerce` 3.9.0 declares `reviewsEnabled` on StoreInfo; the pinned SDK is
+    // older, so widen the type here. The platform already sends the field, and
+    // this cast goes away when the pin passes 3.9.0.
+    reviewsEnabled: (raw as StoreInfo & { reviewsEnabled?: boolean }).reviewsEnabled,
     timezone: raw.timezone,
   };
 }
+
+/**
+ * Whether to render reviews UI. Absent counts as ON: an older backend sends no
+ * flag, and reviews are on by default. Only an explicit `false` hides them.
+ */
+export function reviewsAreOn(info: Pick<PublicStoreInfo, 'reviewsEnabled'> | null | undefined) {
+  return info?.reviewsEnabled !== false;
+}