create-brainerce-store 1.87.0 → 1.88.0

package/templates/nextjs/base/src/components/checkout/checkout-form.tsx

@@ -7,6 +7,7 @@ import { cn } from '@/core/lib/utils';
 import { isValidEmail } from '@/core/lib/validation';
 import { getClient } from '@/core/lib/brainerce';
 import { useRegion } from '@/core/providers/store-provider';
+import { usePageExists } from '@/core/hooks/use-page-exists';
 
 // Debounce address-suggestion calls rather than firing on every keystroke —
 // both to avoid a jumpy dropdown and to keep autocomplete-session call volume
@@ -65,6 +66,7 @@ export function CheckoutForm({
   });
   const [errors, setErrors] = useState<Record<string, string>>({});
   const [privacyAccepted, setPrivacyAccepted] = useState(false);
+  const hasPrivacyPage = usePageExists('privacy');
   const [acceptsMarketing, setAcceptsMarketing] = useState(false);
   const [saveDetails, setSaveDetails] = useState(true);
   const t = useTranslations('checkoutForm');
@@ -568,14 +570,18 @@ export function CheckoutForm({
           />
           <span className="text-muted-foreground text-sm">
             {t('privacyAcceptPrefix')}{' '}
-            <a
-              href="/privacy"
-              target="_blank"
-              rel="noopener noreferrer"
-              className="text-primary underline underline-offset-2"
-            >
-              {t('privacyPolicyLink')}
-            </a>{' '}
+            {hasPrivacyPage === false ? (
+              <span className="text-foreground">{t('privacyPolicyLink')}</span>
+            ) : (
+              <a
+                href="/pages/privacy"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-primary underline underline-offset-2"
+              >
+                {t('privacyPolicyLink')}
+              </a>
+            )}{' '}
             <span className="text-destructive">*</span>
           </span>
         </label>

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

@@ -0,0 +1,37 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { getClient } from '@/core/lib/brainerce';
+
+/**
+ * Whether the merchant has published a PAGE with this slug (Content → Page).
+ *
+ * `false` only on a genuine 404. While loading, or if the lookup fails for any
+ * other reason, it stays `null`, so callers keep rendering the link: a flaky
+ * network must not strip the policy link off a consent checkbox.
+ *
+ * Why it exists: a brand-new store has no `privacy` page, and the required
+ * privacy checkbox at register and checkout linked straight to a 404
+ * (2026-10-04 QA). Callers show the policy name as plain text until the
+ * merchant creates the page.
+ */
+export function usePageExists(slug: string): boolean | null {
+  const [exists, setExists] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    getClient()
+      .content.page.getBySlug(slug)
+      .then((page) => {
+        if (!cancelled) setExists(page !== null);
+      })
+      .catch(() => {
+        // Not a 404: unknown, keep the link.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [slug]);
+
+  return exists;
+}

package/templates/nextjs/base/src/core/lib/add-to-cart-error.ts

@@ -5,7 +5,7 @@
  * each design maps this to its own `productDetail.*` string rather than showing
  * the raw API sentence. Shared by the product page hook and the grid quick-add.
  */
-export type AddToCartError = 'CART_FULL' | 'FAILED';
+export type AddToCartError = 'CART_FULL' | 'NOT_ENOUGH_STOCK' | 'ITEM_UNAVAILABLE' | 'FAILED';
 
 /**
  * The API's stable, machine-readable error code for a failed call, or
@@ -43,7 +43,32 @@ export function getErrorCode(err: unknown): string | undefined {
  * message rather than the silence this replaced.
  */
 export function toAddToCartError(err: unknown): AddToCartError {
-  if (getErrorCode(err) === 'CART_LINE_LIMIT_REACHED') return 'CART_FULL';
+  const code = getErrorCode(err);
+  if (code === 'CART_LINE_LIMIT_REACHED') return 'CART_FULL';
+  // Two PERMANENT refusals: "please try again" would send the shopper round a
+  // loop that cannot succeed, so each gets its own sentence.
+  if (code === 'INSUFFICIENT_STOCK') return 'NOT_ENOUGH_STOCK';
+  if (code === 'PRODUCT_UNAVAILABLE') return 'ITEM_UNAVAILABLE';
   const message = (err as { message?: string } | null)?.message ?? '';
   return /cart can hold at most/i.test(message) ? 'CART_FULL' : 'FAILED';
 }
+
+/**
+ * The `productDetail.*` message key for an add-to-cart refusal. Every surface
+ * renders `t(addToCartErrorMessageKey(error))`, so a new member of
+ * {@link AddToCartError} cannot silently fall through to "please try again".
+ */
+export function addToCartErrorMessageKey(
+  error: AddToCartError
+): 'cartFull' | 'addNotEnoughStock' | 'addItemUnavailable' | 'addToCartFailed' {
+  switch (error) {
+    case 'CART_FULL':
+      return 'cartFull';
+    case 'NOT_ENOUGH_STOCK':
+      return 'addNotEnoughStock';
+    case 'ITEM_UNAVAILABLE':
+      return 'addItemUnavailable';
+    default:
+      return 'addToCartFailed';
+  }
+}

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

@@ -1,121 +1,121 @@
-import { BrainerceClient } from 'brainerce';
-import { cache } from 'react';
-import { SALES_CHANNEL_ID } from '@/core/lib/brainerce';
-import { pickPublicStoreInfo, type PublicStoreInfo } from '@/core/lib/store-info';
-import { getRequestOrigin } from '@/core/lib/site-url';
-
-/**
- * SERVER-ONLY half of the SDK wiring. Kept apart from `brainerce.ts` on
- * purpose: everything here reaches `next/headers` (to resolve the request's
- * origin), and ~30 client components import `getClient` from `brainerce.ts`.
- * A single shared module would drag `next/headers` into the client bundle and
- * fail the build outright — which is exactly what happened when these two
- * functions still lived there.
- *
- * Import from here in Server Components, `generateMetadata`, route handlers,
- * `sitemap.ts` / `robots.ts`. Never from a `'use client'` file.
- */
-
-/**
- * Server-side client — calls the backend directly (no proxy needed for public
- * data). Used by Server Components for SSR data fetching.
- *
- * ⛔ ASYNC on purpose. The backend compares the `Origin` we send against the
- * domain configured on the sales channel, and a LIVE channel rejects both a
- * mismatched Origin AND a missing one with 403. The correct value is only
- * knowable from the request when no `SITE_URL` is configured — the norm for
- * AI-builder deploys — so resolving it needs an await. This previously read
- * `process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'`, which sent
- * localhost from every such deploy, so every SSR call failed the moment the
- * channel went Live.
- */
-export async function getServerClient(locale?: string): Promise<BrainerceClient> {
-  const apiUrl = process.env.BRAINERCE_API_URL || 'https://api.brainerce.com';
-  const client = new BrainerceClient({
-    salesChannelId: SALES_CHANNEL_ID,
-    baseUrl: apiUrl,
-    origin: await getRequestOrigin(),
-  });
-  if (locale) {
-    client.setLocale(locale);
-  }
-  return client;
-}
-
-/**
- * Reads a fetch `Response` body as text, self-healing an observed runtime bug:
- * on Next.js 15.5.26, a `fetch()` made from a Route Handler or Server
- * Component can return a Response whose body is still gzip-compressed bytes,
- * even though an identical request (same URL, same headers) made via plain
- * Node `fetch()` outside Next decompresses correctly — confirmed by diffing
- * the raw response bytes both ways. The exact point inside Next's
- * server-side fetch instrumentation that causes this isn't confirmed, only
- * the externally observable symptom is. Calling `.text()`/`.json()` on a
- * Response like that UTF-8-decodes still-gzipped bytes — lossy (replacement
- * characters) and unparseable as JSON.
- *
- * A correctly-behaving fetch (browsers; plain Node; this bug's absence) never
- * hands back bytes that still start with gzip's magic number (`1f 8b`) — real
- * compression has already been undone by the time a body reaches here — so
- * checking for it before ever decoding as text can't misfire into
- * double-decompressing an already-plain body.
- *
- * This only works because the fetch below pins `Accept-Encoding: gzip`
- * instead of the runtime default (which also offers Brotli) — Brotli has no
- * reliable magic-number signature and no Web Streams API decoder, so this
- * self-healing has no fallback for it. That header is correctness-critical
- * here, not a tuning choice: reverting it to the runtime default reintroduces
- * this exact corruption, just for Brotli-compressed responses instead of
- * gzip ones.
- */
-async function readBackendBody(response: Response): Promise<string> {
-  const buffer = new Uint8Array(await response.arrayBuffer());
-  if (buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b) {
-    const decompressed = new Blob([buffer])
-      .stream()
-      .pipeThrough(new DecompressionStream('gzip'));
-    return new TextDecoder('utf-8').decode(await new Response(decompressed).arrayBuffer());
-  }
-  return new TextDecoder('utf-8').decode(buffer);
-}
-
-/**
- * Server-side cached fetch of store info, used to seed `<StoreProvider>` at
- * SSR so client components don't render with `null` storeInfo and bake the
- * wrong currency symbol into the HTML Googlebot indexes.
- *
- * Two cache layers:
- *   - React `cache()` dedupes calls within a single request render so the
- *     layout + `generateMetadata` share one fetch.
- *   - Next.js `fetch({ next: { revalidate, tags } })` caches the response
- *     across requests for ~60s and lets the dashboard bust the cache via
- *     `revalidateTag('store-info')` on store-config save.
- *
- * Returns `null` on hard failure so the provider's client-side `useEffect`
- * fallback can take over — behaviour identical to pre-SSR-hydration.
- *
- * Bypasses {@link getServerClient} on purpose: the SDK's internal `fetch`
- * does not forward `next:` options, so it cannot participate in the Next.js
- * Data Cache today. Switch back to the SDK once it accepts `fetchOptions`.
- */
-export const fetchStoreInfo = cache(async (locale?: string): Promise<PublicStoreInfo | null> => {
-  const apiUrl = process.env.BRAINERCE_API_URL || 'https://api.brainerce.com';
-  const siteOrigin = await getRequestOrigin();
-  const url = `${apiUrl}/api/vc/${encodeURIComponent(SALES_CHANNEL_ID)}/info`;
-  try {
-    const res = await fetch(url, {
-      headers: {
-        Origin: siteOrigin,
-        // Pinned to gzip — see readBackendBody() for why.
-        'Accept-Encoding': 'gzip',
-        ...(locale ? { 'Accept-Language': locale } : {}),
-      },
-      next: { revalidate: 60, tags: ['store-info'] },
-    });
-    if (!res.ok) return null;
-    const text = await readBackendBody(res);
-    return pickPublicStoreInfo(text ? JSON.parse(text) : {});
-  } catch {
-    return null;
-  }
-});
+import { BrainerceClient } from 'brainerce';
+import { cache } from 'react';
+import { SALES_CHANNEL_ID } from '@/core/lib/brainerce';
+import { pickPublicStoreInfo, type PublicStoreInfo } from '@/core/lib/store-info';
+import { getRequestOrigin } from '@/core/lib/site-url';
+
+/**
+ * SERVER-ONLY half of the SDK wiring. Kept apart from `brainerce.ts` on
+ * purpose: everything here reaches `next/headers` (to resolve the request's
+ * origin), and ~30 client components import `getClient` from `brainerce.ts`.
+ * A single shared module would drag `next/headers` into the client bundle and
+ * fail the build outright — which is exactly what happened when these two
+ * functions still lived there.
+ *
+ * Import from here in Server Components, `generateMetadata`, route handlers,
+ * `sitemap.ts` / `robots.ts`. Never from a `'use client'` file.
+ */
+
+/**
+ * Server-side client — calls the backend directly (no proxy needed for public
+ * data). Used by Server Components for SSR data fetching.
+ *
+ * ⛔ ASYNC on purpose. The backend compares the `Origin` we send against the
+ * domain configured on the sales channel, and a LIVE channel rejects both a
+ * mismatched Origin AND a missing one with 403. The correct value is only
+ * knowable from the request when no `SITE_URL` is configured — the norm for
+ * AI-builder deploys — so resolving it needs an await. This previously read
+ * `process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'`, which sent
+ * localhost from every such deploy, so every SSR call failed the moment the
+ * channel went Live.
+ */
+export async function getServerClient(locale?: string): Promise<BrainerceClient> {
+  const apiUrl = process.env.BRAINERCE_API_URL || 'https://api.brainerce.com';
+  const client = new BrainerceClient({
+    salesChannelId: SALES_CHANNEL_ID,
+    baseUrl: apiUrl,
+    origin: await getRequestOrigin(),
+  });
+  if (locale) {
+    client.setLocale(locale);
+  }
+  return client;
+}
+
+/**
+ * Reads a fetch `Response` body as text, self-healing an observed runtime bug:
+ * on Next.js 15.5.26, a `fetch()` made from a Route Handler or Server
+ * Component can return a Response whose body is still gzip-compressed bytes,
+ * even though an identical request (same URL, same headers) made via plain
+ * Node `fetch()` outside Next decompresses correctly — confirmed by diffing
+ * the raw response bytes both ways. The exact point inside Next's
+ * server-side fetch instrumentation that causes this isn't confirmed, only
+ * the externally observable symptom is. Calling `.text()`/`.json()` on a
+ * Response like that UTF-8-decodes still-gzipped bytes — lossy (replacement
+ * characters) and unparseable as JSON.
+ *
+ * A correctly-behaving fetch (browsers; plain Node; this bug's absence) never
+ * hands back bytes that still start with gzip's magic number (`1f 8b`) — real
+ * compression has already been undone by the time a body reaches here — so
+ * checking for it before ever decoding as text can't misfire into
+ * double-decompressing an already-plain body.
+ *
+ * This only works because the fetch below pins `Accept-Encoding: gzip`
+ * instead of the runtime default (which also offers Brotli) — Brotli has no
+ * reliable magic-number signature and no Web Streams API decoder, so this
+ * self-healing has no fallback for it. That header is correctness-critical
+ * here, not a tuning choice: reverting it to the runtime default reintroduces
+ * this exact corruption, just for Brotli-compressed responses instead of
+ * gzip ones.
+ */
+async function readBackendBody(response: Response): Promise<string> {
+  const buffer = new Uint8Array(await response.arrayBuffer());
+  if (buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b) {
+    const decompressed = new Blob([buffer])
+      .stream()
+      .pipeThrough(new DecompressionStream('gzip'));
+    return new TextDecoder('utf-8').decode(await new Response(decompressed).arrayBuffer());
+  }
+  return new TextDecoder('utf-8').decode(buffer);
+}
+
+/**
+ * Server-side cached fetch of store info, used to seed `<StoreProvider>` at
+ * SSR so client components don't render with `null` storeInfo and bake the
+ * wrong currency symbol into the HTML Googlebot indexes.
+ *
+ * Two cache layers:
+ *   - React `cache()` dedupes calls within a single request render so the
+ *     layout + `generateMetadata` share one fetch.
+ *   - Next.js `fetch({ next: { revalidate, tags } })` caches the response
+ *     across requests for ~60s and lets the dashboard bust the cache via
+ *     `revalidateTag('store-info')` on store-config save.
+ *
+ * Returns `null` on hard failure so the provider's client-side `useEffect`
+ * fallback can take over — behaviour identical to pre-SSR-hydration.
+ *
+ * Bypasses {@link getServerClient} on purpose: the SDK's internal `fetch`
+ * does not forward `next:` options, so it cannot participate in the Next.js
+ * Data Cache today. Switch back to the SDK once it accepts `fetchOptions`.
+ */
+export const fetchStoreInfo = cache(async (locale?: string): Promise<PublicStoreInfo | null> => {
+  const apiUrl = process.env.BRAINERCE_API_URL || 'https://api.brainerce.com';
+  const siteOrigin = await getRequestOrigin();
+  const url = `${apiUrl}/api/vc/${encodeURIComponent(SALES_CHANNEL_ID)}/info`;
+  try {
+    const res = await fetch(url, {
+      headers: {
+        Origin: siteOrigin,
+        // Pinned to gzip — see readBackendBody() for why.
+        'Accept-Encoding': 'gzip',
+        ...(locale ? { 'Accept-Language': locale } : {}),
+      },
+      next: { revalidate: 60, tags: ['store-info'] },
+    });
+    if (!res.ok) return null;
+    const text = await readBackendBody(res);
+    return pickPublicStoreInfo(text ? JSON.parse(text) : {});
+  } catch {
+    return null;
+  }
+});

package/templates/nextjs/base/src/core/lib/coupon-error.ts

@@ -0,0 +1,29 @@
+import { getErrorCode } from '@/core/lib/add-to-cart-error';
+
+/**
+ * Message keys (under `coupon.*`) for the stable codes `applyCoupon` /
+ * `applyCheckoutCoupon` return. The API's `message` is English whatever the
+ * shopper's language, so a known code is always shown from our own messages.
+ * A refusal with no code (a checkout past its editable stage, say) returns
+ * `null` and the caller falls back to the API's message.
+ */
+const COUPON_ERROR_KEYS = {
+  COUPON_NOT_FOUND: 'invalidCode',
+  COUPON_NOT_ACTIVE: 'notActive',
+  COUPON_EXPIRED: 'expired',
+  COUPON_USAGE_LIMIT_REACHED: 'usageLimitReached',
+  COUPON_PER_CUSTOMER_LIMIT_REACHED: 'perCustomerLimitReached',
+  COUPON_MINIMUM_NOT_MET: 'minimumNotMet',
+  COUPON_REGION_RESTRICTED: 'regionRestricted',
+  COUPON_NO_ELIGIBLE_ITEMS: 'noEligibleItems',
+} as const;
+
+export type CouponErrorKey = (typeof COUPON_ERROR_KEYS)[keyof typeof COUPON_ERROR_KEYS];
+
+export function couponErrorKey(err: unknown): CouponErrorKey | null {
+  const code = getErrorCode(err);
+  if (code && code in COUPON_ERROR_KEYS) {
+    return COUPON_ERROR_KEYS[code as keyof typeof COUPON_ERROR_KEYS];
+  }
+  return null;
+}

package/templates/nextjs/base/src/ui/cart/cart-bundle-offer.tsx

@@ -6,7 +6,11 @@ import type { CartBundleOffer as CartBundleOfferType } from 'brainerce';
 import { formatPrice } from 'brainerce';
 import { useCurrency } from '@/core/lib/use-currency';
 import { useTranslations } from '@/core/lib/translations';
-import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
+import {
+  addToCartErrorMessageKey,
+  toAddToCartError,
+  type AddToCartError,
+} from '@/core/lib/add-to-cart-error';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Card } from '@/components/ui/card';
@@ -127,7 +131,7 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
       */}
       {addError && (
         <p role="alert" className="text-destructive mt-2 text-xs">
-          {addError === 'CART_FULL' ? tp('cartFull') : tp('addToCartFailed')}
+          {tp(addToCartErrorMessageKey(addError))}
         </p>
       )}
     </Card>

package/templates/nextjs/base/src/ui/cart/cart-upgrade-banner.tsx

@@ -8,7 +8,11 @@ import { formatPrice } from 'brainerce';
 import { getClient } from '@/core/lib/brainerce';
 import { useCurrency } from '@/core/lib/use-currency';
 import { useTranslations } from '@/core/lib/translations';
-import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
+import {
+  addToCartErrorMessageKey,
+  toAddToCartError,
+  type AddToCartError,
+} from '@/core/lib/add-to-cart-error';
 import { Button } from '@/components/ui/button';
 import { cn } from '@/core/lib/utils';
 
@@ -198,9 +202,7 @@ export function CartUpgradeBanner({
           <p role="alert" className="text-destructive mt-1 text-xs">
             {upgradeError === 'ORIGINAL_NOT_REMOVED'
               ? t('upgradeOriginalNotRemoved')
-              : upgradeError === 'CART_FULL'
-                ? tp('cartFull')
-                : tp('addToCartFailed')}
+              : tp(addToCartErrorMessageKey(upgradeError))}
           </p>
         )}
       </div>