create-brainerce-store 1.72.0 → 1.74.0

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

@@ -11,6 +11,7 @@ import type {
   ModifierGroup,
 } from 'brainerce';
 import { getProductPriceInfo, getDescriptionContent } from 'brainerce';
+import { resolveDisplayPrice, type DisplayPrice } from '@/core/lib/display-price';
 import { useCart, useStoreInfo } from '@/core/providers/store-provider';
 import { trackAddToCart, trackProductView } from '@/core/lib/tracking';
 import {
@@ -42,8 +43,25 @@ export interface UseProductPageResult {
   /** Variant selection. */
   selectedVariant: ProductVariant | null;
   setSelectedVariant: (variant: ProductVariant | null) => void;
-  /** Effective price info (variant price + discount-rule overlay). */
+  /**
+   * Effective price info in the STORE currency (variant price + discount-rule
+   * overlay).
+   *
+   * ⛔ This is the CHARGED amount, and it is what feeds `view_item` /
+   * `add_to_cart`. Analytics revenue has to be one currency across the store,
+   * so do NOT swap in a converted figure here. Render `displayPrice` instead.
+   */
   priceInfo: ProductPriceInfo;
+  /**
+   * The price to RENDER, region-aware: the FX-converted amounts when the
+   * product was read with a `regionId` whose currency differs from the store's,
+   * and `priceInfo` in the store currency otherwise.
+   *
+   * ⛔ Pass `displayPrice.currency` to `<PriceDisplay currency>` alongside the
+   * numbers. It defaults to the store currency, so a converted amount rendered
+   * without it is a euro figure wearing a dollar sign.
+   */
+  displayPrice: DisplayPrice;
   /** Variant inventory when a variant is selected, else product inventory. */
   inventory: InventoryInfo | null;
   canPurchase: boolean;
@@ -181,6 +199,19 @@ export function useProductPage(initialProduct: Product): UseProductPageResult {
     return getProductPriceInfo(product);
   }, [product, selectedVariant]);
 
+  // Region display pricing, variant-aware. The selected variant carries its own
+  // FX fields; fall back to the product's, then to the store-currency figures
+  // above. Same helper the product card uses, so a card and the page it opens
+  // can never quote different currencies for the same item.
+  const displayPrice = useMemo<DisplayPrice>(() => {
+    const fallback = {
+      price: priceInfo.originalPrice,
+      salePrice: priceInfo.isOnSale ? priceInfo.price : null,
+    };
+    const source = selectedVariant?.displayPrice != null ? selectedVariant : product;
+    return resolveDisplayPrice(source, fallback, currency);
+  }, [product, selectedVariant, priceInfo, currency]);
+
   // Inventory: use variant inventory if selected, else product inventory
   const inventory = selectedVariant?.inventory ?? product?.inventory ?? null;
   const canPurchase = inventory?.canPurchase !== false;
@@ -276,6 +307,7 @@ export function useProductPage(initialProduct: Product): UseProductPageResult {
     selectedVariant,
     setSelectedVariant,
     priceInfo,
+    displayPrice,
     inventory,
     canPurchase,
     description,

package/templates/nextjs/base/src/core/lib/capabilities.ts

@@ -0,0 +1,65 @@
+import type { StoreCapabilities } from 'brainerce';
+
+/**
+ * Fallback used until `getStoreCapabilities()` resolves, and whenever the call
+ * fails. Matches the platform default (`SalesChannel.lowStockThreshold`), so a
+ * store that never reaches the endpoint behaves exactly as it did before
+ * capabilities were wired in — it never renders a broken or empty badge.
+ */
+export const DEFAULT_LOW_STOCK_THRESHOLD = 5;
+
+/**
+ * The subset of {@link StoreCapabilities} the storefront actually renders from.
+ * Operational channel state (granted API scopes, sandbox payment flags,
+ * reservation strategy) is deliberately dropped: it tells a reader how the
+ * merchant's channel is provisioned and has no role in what a shopper sees.
+ *
+ * Uses indexed access on `StoreCapabilities` for nested types so this stays in
+ * step with the SDK without restating its shapes.
+ */
+export interface PublicStoreCapabilities {
+  /** Whether to call out low stock at all. False means the merchant switched the urgency messaging off. */
+  lowStockWarning: boolean;
+  /** Units at or below which stock counts as low. */
+  lowStockThreshold: number;
+  /** Whether "email me when this is back" should be offered on sold-out items. */
+  stockAlertsEnabled: boolean;
+  /** Minutes a checkout reservation is held before it expires. */
+  reservationTimeout: number;
+  /** Which optional features the merchant enabled — coupons, loyalty, shipping zones, and so on. */
+  features: StoreCapabilities['features'];
+}
+
+/**
+ * Project a raw capabilities response onto {@link PublicStoreCapabilities}.
+ * Add a field here only after confirming it is non-sensitive and that a
+ * storefront component actually needs it.
+ */
+export function pickPublicCapabilities(raw: StoreCapabilities): PublicStoreCapabilities {
+  return {
+    lowStockWarning: raw.connection.lowStockWarning,
+    lowStockThreshold: raw.connection.lowStockThreshold,
+    stockAlertsEnabled: raw.connection.stockAlertsEnabled,
+    reservationTimeout: raw.connection.reservationTimeout,
+    features: raw.features,
+  };
+}
+
+/**
+ * Resolve the low-stock threshold a badge should use.
+ *
+ * Three cases, in order:
+ *  1. Capabilities not loaded yet, or the fetch failed (`null`) — fall back to
+ *     {@link DEFAULT_LOW_STOCK_THRESHOLD} so the first paint is correct.
+ *  2. The merchant turned the low-stock warning off — return `0`. Stock counts
+ *     as low only at or below the threshold, and an in-stock item always has at
+ *     least one unit, so nothing is ever flagged low. The item still renders its
+ *     normal in-stock label; no string is left blank.
+ *  3. Otherwise, the merchant's configured threshold.
+ */
+export function resolveLowStockThreshold(
+  capabilities: PublicStoreCapabilities | null | undefined
+): number {
+  if (!capabilities) return DEFAULT_LOW_STOCK_THRESHOLD;
+  return capabilities.lowStockWarning ? capabilities.lowStockThreshold : 0;
+}

package/templates/nextjs/base/src/core/lib/display-price.ts

@@ -0,0 +1,139 @@
+import type { Product } from 'brainerce';
+import { getProductPriceInfo, getVariantPrice } from 'brainerce';
+
+/**
+ * Region display pricing (the FX overlay).
+ *
+ * When a product read was made with `regionId` AND the region's currency
+ * differs from the store currency, the backend attaches additive
+ * `displayPrice`, `displaySalePrice`, `displayPriceMin`, `displayPriceMax` and
+ * `displayCurrency` fields from the daily FX snapshot. They are DISPLAY ONLY:
+ * `basePrice` / `salePrice` stay in the store currency and the cart still
+ * charges in it.
+ *
+ * ⛔ NEVER read `displayPrice` on its own. It is absent whenever the region
+ * currency equals the store currency, which is every single-region store, so a
+ * bare read blanks the price on almost every storefront. Always fall back, and
+ * that is the entire reason these helpers exist.
+ *
+ * ⛔ EVERY PRODUCT PRICE ON SCREEN MUST GO THROUGH HERE. Convert one surface
+ * and not another and the shopper sees EUR on the card they clicked and USD on
+ * the page it opened, which is worse than never converting at all. This lives
+ * in `core/lib/` rather than beside one component precisely so a redesign
+ * cannot leave half the surfaces behind.
+ *
+ * ⛔ NOT FOR THE CART, CHECKOUT, ORDER TOTALS, OR THE TAX ESTIMATE. Those are
+ * charged amounts in the store currency. Using a display amount there would
+ * show a total that does not match what the card is billed.
+ *
+ * ⛔ NOT FOR ANALYTICS. `view_item` / `add_to_cart` must report one currency
+ * across the whole store or the revenue numbers are meaningless. Keep sending
+ * the store-currency figure.
+ */
+
+/** The additive FX fields, as they appear on both Product and ProductVariant. */
+interface DisplayPriceFields {
+  displayPrice?: string | null;
+  displaySalePrice?: string | null;
+  displayCurrency?: string | null;
+}
+
+export interface DisplayPrice {
+  /**
+   * Base (pre-sale) amount. Feeds `<PriceDisplay price>`.
+   *
+   * Always a number, never undefined: `getProductPriceInfo` returns 0 for a
+   * product with no usable price rather than nothing, so the render path has
+   * no undefined branch to guard.
+   */
+  price: number;
+  /** Sale amount, or null when not on sale. Feeds `<PriceDisplay salePrice>`. */
+  salePrice: number | null;
+  /**
+   * Currency `price` / `salePrice` are in.
+   *
+   * ⛔ ALWAYS pass this to `<PriceDisplay currency>` / `formatPrice`. It
+   * defaults to the STORE currency, so a converted number rendered without it
+   * comes out as a euro amount wearing a dollar sign, which is worse than an
+   * unconverted price because it looks right.
+   */
+  currency: string | undefined;
+}
+
+/**
+ * Prefer the region-converted amounts on `source`; otherwise return `fallback`
+ * in the store currency. The primitive the rest of this file is built from.
+ */
+export function resolveDisplayPrice(
+  source: DisplayPriceFields | null | undefined,
+  fallback: { price: number; salePrice: number | null },
+  fallbackCurrency: string | undefined
+): DisplayPrice {
+  if (source?.displayPrice != null && source.displayCurrency) {
+    const sale = source.displaySalePrice != null ? parseFloat(source.displaySalePrice) : null;
+    return {
+      // `displayPrice` is the BASE price converted, so it belongs in the base
+      // slot, never the sale slot.
+      price: parseFloat(source.displayPrice),
+      salePrice: sale != null && !Number.isNaN(sale) ? sale : null,
+      currency: source.displayCurrency,
+    };
+  }
+  return { ...fallback, currency: fallbackCurrency };
+}
+
+/**
+ * A product's own price for a card, a hero, or a recommendation tile.
+ *
+ * The same-currency fallback maps the SDK's shape onto `<PriceDisplay>`'s:
+ * `getProductPriceInfo().price` is the EFFECTIVE charged amount (the sale
+ * price when on sale), and `originalPrice` is the base.
+ */
+export function pickDisplayPrice(
+  product: Product,
+  fallbackCurrency: string | undefined
+): DisplayPrice {
+  const { price: effective, originalPrice, isOnSale } = getProductPriceInfo(product);
+  return resolveDisplayPrice(
+    product,
+    { price: originalPrice, salePrice: isOnSale ? effective : null },
+    fallbackCurrency
+  );
+}
+
+/**
+ * A variable product's "from X to Y" range.
+ *
+ * ⛔ `displayPriceMin` / `displayPriceMax` are their own fields. A range built
+ * from `priceMin` / `priceMax` (or by walking `variants`) stays in the store
+ * currency while the single-price card beside it converts, which is the same
+ * split-currency bug one level down. Returns null when there is no range to
+ * show, which is what a product with no variants and no bounds gives you.
+ */
+export function pickDisplayPriceRange(
+  product: Product,
+  fallbackCurrency: string | undefined
+): { min: number; max: number; currency: string | undefined } | null {
+  if (product.displayPriceMin && product.displayPriceMax && product.displayCurrency) {
+    const min = parseFloat(product.displayPriceMin);
+    const max = parseFloat(product.displayPriceMax);
+    if (!Number.isNaN(min) && !Number.isNaN(max)) {
+      return { min, max, currency: product.displayCurrency };
+    }
+  }
+
+  let min: number;
+  let max: number;
+  if (product.priceMin && product.priceMax) {
+    min = parseFloat(product.priceMin);
+    max = parseFloat(product.priceMax);
+  } else {
+    const variants = product.variants ?? [];
+    if (variants.length === 0) return null;
+    const prices = variants.map((v) => getVariantPrice(v, product.basePrice));
+    min = Math.min(...prices);
+    max = Math.max(...prices);
+  }
+  if (Number.isNaN(min) || Number.isNaN(max)) return null;
+  return { min, max, currency: fallbackCurrency };
+}

package/templates/nextjs/base/src/core/lib/region.server.ts

@@ -0,0 +1,112 @@
+import { cache } from 'react';
+import { cookies, headers } from 'next/headers';
+import type { PublicRegion } from 'brainerce';
+import { getServerClient } from '@/core/lib/brainerce.server';
+import { COUNTRY_HEADERS, REGION_COOKIE, normalizeCountry, pickRegion } from '@/core/lib/region';
+
+/**
+ * SERVER-ONLY half of region resolution. Everything here reaches
+ * `next/headers`; importing it from a `'use client'` file fails the build.
+ * Import it in Server Components, `generateMetadata`, and route handlers.
+ *
+ * Resolution order, highest first:
+ *   1. the `brainerce_region` cookie (the shopper used the switcher)
+ *   2. the edge geo header for this host
+ *   3. the store's default region
+ *
+ * The cookie wins because an IP guess is wrong for travellers, expats, VPNs
+ * and anyone on a corporate egress, and it is the shopper who knows.
+ */
+
+/**
+ * The buyer country as the edge saw it, or null.
+ *
+ * Read straight off the incoming request rather than forwarded by middleware:
+ * `headers()` in a Server Component already sees the original request headers,
+ * including through the locale rewrite, so a middleware hop would be a second
+ * copy of the same value that can drift out of step with this one.
+ *
+ * ⛔ Next 15 removed `request.geo`. The country lives in a header now, and
+ * which header depends on the host, so we try each in turn.
+ */
+export const getBuyerCountry = cache(async (): Promise<string | null> => {
+  try {
+    const h = await headers();
+    for (const name of COUNTRY_HEADERS) {
+      const code = normalizeCountry(h.get(name));
+      if (code) return code;
+    }
+  } catch {
+    // headers() throws outside a request scope (a build-time prerender).
+    // No country is a valid answer: the default region takes over.
+  }
+  return null;
+});
+
+/**
+ * The store's active regions, default first. `[]` on any failure.
+ *
+ * ⛔ Never throws. A brand-new store is empty, the channel may not be live
+ * yet, and the backend can hiccup. An empty list makes every caller below a
+ * no-op and the storefront behaves exactly as it did before regions existed,
+ * which is the only acceptable failure mode for a call this widely used.
+ */
+export const fetchRegions = cache(async (): Promise<PublicRegion[]> => {
+  try {
+    const client = await getServerClient();
+    const result = await client.getStoreRegions();
+    return Array.isArray(result?.data) ? result.data : [];
+  } catch {
+    return [];
+  }
+});
+
+export interface ResolvedRegion {
+  /** Every active region. Empty when the store has none or the call failed. */
+  regions: PublicRegion[];
+  /** The region to price this request in, or null when there are none. */
+  region: PublicRegion | null;
+  /** Buyer country from the edge, or null. Reused by the tax estimate. */
+  country: string | null;
+}
+
+/**
+ * Resolve the region for this request. `cache()`-wrapped, so the layout, a
+ * page and `generateMetadata` share one round trip.
+ *
+ * Returns `{ regions: [], region: null, country }` for a store with no
+ * regions. Callers spread `region?.id` into their SDK calls, so that case
+ * sends no `regionId` at all, which is the pre-regions behaviour.
+ */
+export const resolveRegion = cache(async (): Promise<ResolvedRegion> => {
+  const [regions, country] = await Promise.all([fetchRegions(), getBuyerCountry()]);
+  if (regions.length === 0) return { regions, region: null, country };
+
+  // 1. The shopper's explicit choice, if it still names a live region. A
+  //    stale id (the merchant deleted or deactivated that region) falls
+  //    through to the geo guess rather than pricing in a region that is gone.
+  let chosen: PublicRegion | null = null;
+  try {
+    const cookieValue = (await cookies()).get(REGION_COOKIE)?.value;
+    if (cookieValue) chosen = regions.find((r) => r.id === cookieValue) ?? null;
+  } catch {
+    // Same as headers(): outside a request scope there is no cookie jar.
+  }
+
+  // 2/3. Geo header, then the default region.
+  return { regions, region: chosen ?? pickRegion(regions, country), country };
+});
+
+/**
+ * Just the id, for spreading into an SDK call:
+ *
+ *   const regionId = await getRegionId();
+ *   await client.getProducts({ limit: 24, ...(regionId ? { regionId } : {}) });
+ *
+ * ⛔ Pass it to the product reads AND to `createCheckout`. Product reads only
+ * and the shopper is shown one price and charged another, which is worse than
+ * not having built regions at all.
+ */
+export async function getRegionId(): Promise<string | undefined> {
+  return (await resolveRegion()).region?.id;
+}

package/templates/nextjs/base/src/core/lib/region.ts

@@ -0,0 +1,112 @@
+/**
+ * CLIENT-SAFE half of region resolution. Nothing here may reach
+ * `next/headers`, because `<StoreProvider>` and the region switcher import it.
+ * The server half lives in `region.server.ts`.
+ *
+ * ## Why regions exist even when the merchant has never heard of them
+ *
+ * A store can split the world into regions, each with its own currency and
+ * payment providers. Every other optional feature in this project auto-hides
+ * when it is off, so forgetting one costs nothing until the merchant switches
+ * it on. Regions are the exception: a storefront that never sends `regionId`
+ * does not hide anything, it silently renders the DEFAULT region's prices to
+ * every shopper on earth. The page looks perfect and the prices are wrong.
+ *
+ * A single-region store is a complete no-op. `getStoreRegions()` returns one
+ * row, `regions.length <= 1`, the switcher renders nothing, and the `regionId`
+ * we attach to reads resolves to the default the backend would have used
+ * anyway. There is no empty dropdown and no extra chrome. The whole point is
+ * that the day a merchant adds a second region, this storefront is already
+ * correct instead of quietly overcharging half its customers.
+ */
+
+import type { PublicRegion } from 'brainerce';
+
+/**
+ * Manual region choice, set by the switcher. A cookie rather than React state
+ * on purpose: the server renders product pages and has to pick the same region
+ * the shopper chose, or SSR paints the geo-guessed prices and the client flips
+ * them a moment later.
+ *
+ * Not `httpOnly`, because the switcher is a client component and has to write
+ * it. It holds a region id, which is public data already present in the page.
+ */
+export const REGION_COOKIE = 'brainerce_region';
+
+/** One year. A region preference is not session state; it is where you live. */
+const REGION_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+
+/**
+ * Request headers that carry a buyer country, in priority order.
+ *
+ * Brainerce cannot derive this itself: the storefront SERVER is what reaches
+ * the Brainerce API, so the backend sees this machine's IP, not the shopper's.
+ * The country has to be extracted at the edge and forwarded, which is exactly
+ * what these headers are.
+ *
+ * `x-country` is last and is the manual escape hatch: a host with no geo
+ * header of its own can be made to set it in a proxy rule.
+ */
+export const COUNTRY_HEADERS = [
+  'cf-ipcountry', // Cloudflare
+  'x-vercel-ip-country', // Vercel
+  'client-geo-country', // Fastly
+  'x-country', // manual / self-hosted proxies
+] as const;
+
+/**
+ * Accept only a plausible ISO-3166-1 alpha-2 code. Cloudflare sends `XX` for
+ * unknown clients and `T1` for Tor, and both would otherwise be forwarded to
+ * the API as if they were countries.
+ */
+export function normalizeCountry(raw: string | null | undefined): string | null {
+  if (!raw) return null;
+  const code = raw.trim().toUpperCase();
+  if (!/^[A-Z]{2}$/.test(code)) return null;
+  if (code === 'XX' || code === 'T1') return null;
+  return code;
+}
+
+/**
+ * Pick the region for a country from an already-fetched list. Mirrors the
+ * SDK's `client.detectRegion(country, regions)` without needing a client
+ * instance, and keeps the return type narrowed to `PublicRegion`.
+ *
+ * Order: explicit country match → the default region → the first row. The last
+ * two fallbacks are what make a misconfigured store render prices instead of
+ * nothing.
+ */
+export function pickRegion(
+  regions: PublicRegion[],
+  country: string | null | undefined
+): PublicRegion | null {
+  if (regions.length === 0) return null;
+  const code = normalizeCountry(country);
+  if (code) {
+    const matched = regions.find((r) => r.countries.includes(code));
+    if (matched) return matched;
+  }
+  return regions.find((r) => r.isDefault) ?? regions[0] ?? null;
+}
+
+/** Read the manual region choice in the browser. Returns null during SSR. */
+export function readRegionCookie(): string | null {
+  if (typeof document === 'undefined') return null;
+  const match = document.cookie.match(
+    new RegExp(`(?:^|;\\s*)${REGION_COOKIE}=([^;]*)`)
+  );
+  return match ? decodeURIComponent(match[1]) : null;
+}
+
+/**
+ * Persist the manual region choice. `SameSite=Lax` so a link from an email or
+ * an ad still arrives with the shopper's chosen currency; `Secure` only off
+ * localhost, where there is no https to attach it to.
+ */
+export function writeRegionCookie(regionId: string): void {
+  if (typeof document === 'undefined') return;
+  const secure = typeof location !== 'undefined' && location.protocol === 'https:';
+  document.cookie =
+    `${REGION_COOKIE}=${encodeURIComponent(regionId)}; path=/; max-age=${REGION_COOKIE_MAX_AGE}; SameSite=Lax` +
+    (secure ? '; Secure' : '');
+}

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

@@ -49,6 +49,23 @@ export interface PublicStoreInfo {
    * Center). Both public by protocol design.
    */
   seo?: StoreInfo['seo'];
+  /**
+   * Whether this sales channel offers a back-in-stock alert on a sold-out
+   * product. Read by `/products/[slug]` and passed into
+   * `<ProductClientSection stockAlertsEnabled={...}>`.
+   *
+   * ⛔ It was READ before it was PICKED, so it arrived as `undefined` on every
+   * storefront and the page also failed `tsc --noEmit` out of the box. If you
+   * add a consumer of a StoreInfo field, add it to the projection below in the
+   * same change or it silently resolves to undefined.
+   */
+  stockAlertsEnabled?: boolean;
+  /**
+   * IANA timezone the store operates in (e.g. "Asia/Jerusalem"). The checkout
+   * date/time custom fields evaluate availability against THIS, never the
+   * shopper's browser timezone. Same story as above: read but not picked.
+   */
+  timezone?: string;
 }
 
 /**
@@ -74,5 +91,7 @@ export function pickPublicStoreInfo(raw: StoreInfo): PublicStoreInfo {
     shipping: raw.shipping,
     tracking: raw.tracking,
     seo: raw.seo,
+    stockAlertsEnabled: raw.stockAlertsEnabled,
+    timezone: raw.timezone,
   };
 }