create-brainerce-store 1.71.0 → 1.73.0

package/templates/nextjs/base/src/components/account/order-status-timeline.tsx

@@ -1,66 +1,85 @@
-'use client';
-
-import type { Order, OrderStatus } from 'brainerce';
-import { useTranslations } from '@/core/lib/translations';
-import { cn } from '@/core/lib/utils';
-
-const STATUS_KEYS: Record<
-  OrderStatus,
-  | 'statusPending'
-  | 'statusProcessing'
-  | 'statusShipped'
-  | 'statusDelivered'
-  | 'statusCancelled'
-  | 'statusRefunded'
-> = {
-  pending: 'statusPending',
-  processing: 'statusProcessing',
-  shipped: 'statusShipped',
-  delivered: 'statusDelivered',
-  cancelled: 'statusCancelled',
-  refunded: 'statusRefunded',
-};
-
-interface OrderStatusTimelineProps {
-  history: Order['statusHistory'];
-  className?: string;
-}
-
-export function OrderStatusTimeline({ history, className }: OrderStatusTimelineProps) {
-  const t = useTranslations('account');
-  if (!history || history.length === 0) return null;
-
-  return (
-    <div className={cn('border-border border-t pt-2', className)}>
-      <p className="text-foreground mb-2 text-sm font-medium">{t('statusTimeline')}</p>
-      <ol className="space-y-1.5">
-        {history.map((entry, idx) => {
-          const key = STATUS_KEYS[entry.status] || 'statusPending';
-          const when = new Date(entry.at);
-          const whenStr = isNaN(when.getTime())
-            ? entry.at
-            : when.toLocaleString(undefined, {
-                year: 'numeric',
-                month: 'short',
-                day: 'numeric',
-                hour: '2-digit',
-                minute: '2-digit',
-              });
-          return (
-            <li key={`${entry.status}-${idx}`} className="flex items-center gap-2 text-xs">
-              <span
-                className={cn(
-                  'bg-primary inline-block h-2 w-2 flex-shrink-0 rounded-full',
-                  idx === history.length - 1 ? 'opacity-100' : 'opacity-60'
-                )}
-              />
-              <span className="text-foreground font-medium">{t(key)}</span>
-              <span className="text-muted-foreground">· {whenStr}</span>
-              {entry.note && <span className="text-muted-foreground truncate">— {entry.note}</span>}
-            </li>
-          );
-        })}
-      </ol>
-    </div>
-  );
-}
+'use client';
+
+import type { Order, OrderStatus } from 'brainerce';
+import { useTranslations } from '@/core/lib/translations';
+import { cn } from '@/core/lib/utils';
+
+/**
+ * Message key for every order status the API can return.
+ *
+ * The API sends these values UPPERCASE and verbatim (`PENDING`, `ON_HOLD`,
+ * ...). Never lowercase them before the lookup: a lowercase key silently
+ * misses and every row falls through to the default label.
+ */
+export type OrderStatusLabelKey =
+  | 'statusDraft'
+  | 'statusPending'
+  | 'statusProcessing'
+  | 'statusOnHold'
+  | 'statusPaid'
+  | 'statusShipped'
+  | 'statusDelivered'
+  | 'statusCompleted'
+  | 'statusFulfilled'
+  | 'statusCancelled'
+  | 'statusRefunded'
+  | 'statusPartiallyRefunded';
+
+export const ORDER_STATUS_LABEL_KEYS: Record<OrderStatus, OrderStatusLabelKey> = {
+  DRAFT: 'statusDraft',
+  PENDING: 'statusPending',
+  PROCESSING: 'statusProcessing',
+  ON_HOLD: 'statusOnHold',
+  PAID: 'statusPaid',
+  SHIPPED: 'statusShipped',
+  DELIVERED: 'statusDelivered',
+  COMPLETED: 'statusCompleted',
+  FULFILLED: 'statusFulfilled',
+  CANCELLED: 'statusCancelled',
+  REFUNDED: 'statusRefunded',
+  PARTIALLY_REFUNDED: 'statusPartiallyRefunded',
+};
+
+interface OrderStatusTimelineProps {
+  history: Order['statusHistory'];
+  className?: string;
+}
+
+export function OrderStatusTimeline({ history, className }: OrderStatusTimelineProps) {
+  const t = useTranslations('account');
+  if (!history || history.length === 0) return null;
+
+  return (
+    <div className={cn('border-border border-t pt-2', className)}>
+      <p className="text-foreground mb-2 text-sm font-medium">{t('statusTimeline')}</p>
+      <ol className="space-y-1.5">
+        {history.map((entry, idx) => {
+          const key = ORDER_STATUS_LABEL_KEYS[entry.status] || 'statusPending';
+          const when = new Date(entry.at);
+          const whenStr = isNaN(when.getTime())
+            ? entry.at
+            : when.toLocaleString(undefined, {
+                year: 'numeric',
+                month: 'short',
+                day: 'numeric',
+                hour: '2-digit',
+                minute: '2-digit',
+              });
+          return (
+            <li key={`${entry.status}-${idx}`} className="flex items-center gap-2 text-xs">
+              <span
+                className={cn(
+                  'bg-primary inline-block h-2 w-2 flex-shrink-0 rounded-full',
+                  idx === history.length - 1 ? 'opacity-100' : 'opacity-60'
+                )}
+              />
+              <span className="text-foreground font-medium">{t(key)}</span>
+              <span className="text-muted-foreground">· {whenStr}</span>
+              {entry.note && <span className="text-muted-foreground truncate">({entry.note})</span>}
+            </li>
+          );
+        })}
+      </ol>
+    </div>
+  );
+}

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

@@ -1,58 +1,127 @@
-'use client';
-
-import { useEffect, useState } from 'react';
-import type {
-  Cart,
-  CartRecommendationsResponse,
-  CartUpgradesResponse,
-  CartBundlesResponse,
-} from 'brainerce';
-import { getClient } from '@/core/lib/brainerce';
-import { useCart } from '@/core/providers/store-provider';
-
-export interface UseCartPageResult {
-  cart: Cart | null;
-  cartLoading: boolean;
-  refreshCart: () => Promise<void>;
-  itemCount: number;
-  /** Cross-sell recommendations for the current cart contents. */
-  cartRecs: CartRecommendationsResponse | null;
-  /** Per-item upgrade suggestions keyed by productId. */
-  upgrades: CartUpgradesResponse | null;
-  /** Bundle offers matching the current cart. */
-  bundles: CartBundlesResponse | null;
-}
-
-/**
- * Cart-page behavior: the shared cart state (from StoreProvider) plus the
- * enrichment fetch (recommendations / upgrades / bundles) that runs whenever
- * the cart contents change. Pure data/behavior — rendering lives in
- * `ui/cart/cart-view.tsx`.
- */
-export function useCartPage(): UseCartPageResult {
-  const { cart, cartLoading, refreshCart, itemCount } = useCart();
-  const [cartRecs, setCartRecs] = useState<CartRecommendationsResponse | null>(null);
-  const [upgrades, setUpgrades] = useState<CartUpgradesResponse | null>(null);
-  const [bundles, setBundles] = useState<CartBundlesResponse | null>(null);
-
-  // Load recommendations, upgrades, and bundles in a single request
-  useEffect(() => {
-    if (!cart?.id || cart.items.length === 0) {
-      setCartRecs(null);
-      setUpgrades(null);
-      setBundles(null);
-      return;
-    }
-    const client = getClient();
-    client
-      .getCart(cart.id, { include: ['recommendations', 'upgrades', 'bundles'] })
-      .then((enriched) => {
-        setCartRecs(enriched.recommendations ?? null);
-        setUpgrades(enriched.upgrades ?? null);
-        setBundles(enriched.bundles ?? null);
-      })
-      .catch(() => {});
-  }, [cart?.id, cart?.items.length]);
-
-  return { cart, cartLoading, refreshCart, itemCount, cartRecs, upgrades, bundles };
-}
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type {
+  Cart,
+  CartItem,
+  CartRecommendationsResponse,
+  CartUpgradesResponse,
+  CartBundlesResponse,
+} from 'brainerce';
+import { getClient } from '@/core/lib/brainerce';
+import { useCart } from '@/core/providers/store-provider';
+
+export interface UseCartPageResult {
+  cart: Cart | null;
+  cartLoading: boolean;
+  refreshCart: () => Promise<void>;
+  itemCount: number;
+  /** Cross-sell recommendations for the current cart contents. */
+  cartRecs: CartRecommendationsResponse | null;
+  /** Per-item upgrade suggestions keyed by productId. */
+  upgrades: CartUpgradesResponse | null;
+  /** Bundle offers matching the current cart. */
+  bundles: CartBundlesResponse | null;
+  /**
+   * True once the stock reservation on this cart has run out and the refreshed
+   * cart still carries the same expired window. Goes back to false on its own
+   * if the server hands back a fresh reservation.
+   */
+  reservationExpired: boolean;
+  /** Lines the server says cannot be bought right now (`isAvailable === false`). */
+  unavailableItems: CartItem[];
+  /**
+   * False while the reservation is expired or any line is unavailable. The
+   * proceed-to-checkout action must be genuinely disabled on false, not just
+   * styled as disabled.
+   */
+  canProceedToCheckout: boolean;
+  /**
+   * Hand this to `<ReservationCountdown onExpire={...}>`. It refreshes the
+   * cart once per expiry window: the server, not the client timer, decides
+   * what is still purchasable.
+   */
+  onReservationExpired: () => void;
+}
+
+/**
+ * Cart-page behavior: the shared cart state (from StoreProvider) plus the
+ * enrichment fetch (recommendations / upgrades / bundles) that runs whenever
+ * the cart contents change. Pure data/behavior — rendering lives in
+ * `ui/cart/cart-view.tsx`.
+ */
+export function useCartPage(): UseCartPageResult {
+  const { cart, cartLoading, refreshCart, itemCount } = useCart();
+  const [cartRecs, setCartRecs] = useState<CartRecommendationsResponse | null>(null);
+  const [upgrades, setUpgrades] = useState<CartUpgradesResponse | null>(null);
+  const [bundles, setBundles] = useState<CartBundlesResponse | null>(null);
+
+  // Load recommendations, upgrades, and bundles in a single request
+  useEffect(() => {
+    if (!cart?.id || cart.items.length === 0) {
+      setCartRecs(null);
+      setUpgrades(null);
+      setBundles(null);
+      return;
+    }
+    const client = getClient();
+    client
+      .getCart(cart.id, { include: ['recommendations', 'upgrades', 'bundles'] })
+      .then((enriched) => {
+        setCartRecs(enriched.recommendations ?? null);
+        setUpgrades(enriched.upgrades ?? null);
+        setBundles(enriched.bundles ?? null);
+      })
+      .catch(() => {});
+  }, [cart?.id, cart?.items.length]);
+
+  // ---- Reservation expiry ----
+  //
+  // The countdown component only ticks. Expiry is handled here, once, so all
+  // three design variants share one behaviour and a user redesigning the
+  // countdown cannot delete the gate along with the markup.
+  //
+  // Both pieces of state key on the reservation's `expiresAt`, which is the
+  // only stable identity a reservation window has:
+  //  - `handledExpiryRef` stops the refresh loop (refresh remounts the
+  //    countdown, which would otherwise report the same expiry again).
+  //  - comparing `expiredWindow` to the CURRENT `expiresAt` means a server
+  //    that renews the reservation clears the expired state by itself.
+  const reservationExpiresAt = cart?.reservation?.expiresAt ?? null;
+  const handledExpiryRef = useRef<string | null>(null);
+  const [expiredWindow, setExpiredWindow] = useState<string | null>(null);
+
+  const onReservationExpired = useCallback(() => {
+    if (!reservationExpiresAt) return;
+    setExpiredWindow(reservationExpiresAt);
+    if (handledExpiryRef.current === reservationExpiresAt) return;
+    handledExpiryRef.current = reservationExpiresAt;
+    // Re-read from the server: it is the source of truth for what survived
+    // the released reservation. `isAvailable` on each line comes back updated.
+    void refreshCart();
+  }, [reservationExpiresAt, refreshCart]);
+
+  const reservationExpired =
+    expiredWindow !== null &&
+    expiredWindow === reservationExpiresAt &&
+    cart?.reservation?.hasReservation === true;
+
+  const unavailableItems = cart?.items.filter((item) => item.isAvailable === false) ?? [];
+
+  const canProceedToCheckout =
+    !!cart && cart.items.length > 0 && !reservationExpired && unavailableItems.length === 0;
+
+  return {
+    cart,
+    cartLoading,
+    refreshCart,
+    itemCount,
+    cartRecs,
+    upgrades,
+    bundles,
+    reservationExpired,
+    unavailableItems,
+    canProceedToCheckout,
+    onReservationExpired,
+  };
+}

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

@@ -1,15 +1,21 @@
 /**
- * Client-side auth helpers that call the BFF proxy API routes.
- * All mutating requests include the CSRF header.
- * The token is managed server-side via httpOnly cookies — never exposed to JS.
+ * Client-side auth helpers.
+ *
+ * Everything the SDK covers goes through an SDK method. Never hand-build a
+ * REST path: the SDK owns the URL shape, and a string built here silently
+ * rots the day a route moves. `getClient()` is configured with
+ * `baseUrl: '/api/store'` + `proxyMode`, so each call still lands on the
+ * same-origin BFF proxy, which adds the Authorization header from the
+ * httpOnly cookie and strips the token out of the response. The SDK adds the
+ * CSRF header the proxy requires on every non-GET request.
+ *
+ * Only the routes with no SDK equivalent are plain fetches: `/api/auth/me`,
+ * `/api/auth/logout` and `/api/auth/reset-password` are this app's own Next
+ * route handlers, not Brainerce endpoints.
+ *
+ * The token is managed server-side via httpOnly cookies, never exposed to JS.
  */
-
-// Read either env var name. The new one is preferred; the old one is a soft
-// alias kept for backwards compatibility — both are accepted by the SDK.
-const CONNECTION_ID =
-  process.env.NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID ||
-  process.env.NEXT_PUBLIC_BRAINERCE_CONNECTION_ID ||
-  '';
+import { getClient } from '@/core/lib/brainerce';
 
 const CSRF_HEADERS: Record<string, string> = {
   'Content-Type': 'application/json',
@@ -67,19 +73,19 @@ async function handleResponse<T>(response: Response): Promise<T> {
 }
 
 /**
- * Login via BFF proxy. The proxy sets the httpOnly cookie on success.
+ * Login via the SDK, routed through the BFF proxy, which sets the httpOnly
+ * cookie on success and strips the token from the response. The narrow
+ * `LoginResult` return type is deliberate: the SDK's own response type
+ * declares a `token`, but the proxy removes it before it reaches the browser,
+ * so nothing here should read one.
  */
 export async function proxyLogin(email: string, password: string): Promise<LoginResult> {
-  const response = await fetch(`/api/store/api/vc/${CONNECTION_ID}/customers/login`, {
-    method: 'POST',
-    headers: CSRF_HEADERS,
-    body: JSON.stringify({ email, password }),
-  });
-  return handleResponse<LoginResult>(response);
+  return getClient().loginCustomer(email, password);
 }
 
 /**
- * Register via BFF proxy. The proxy sets the httpOnly cookie on success.
+ * Register via the SDK, routed through the BFF proxy, which sets the httpOnly
+ * cookie on success.
  */
 export async function proxyRegister(data: {
   firstName: string;
@@ -96,12 +102,7 @@ export async function proxyRegister(data: {
   birthMonth?: number;
   birthDay?: number;
 }): Promise<RegisterResult> {
-  const response = await fetch(`/api/store/api/vc/${CONNECTION_ID}/customers/register`, {
-    method: 'POST',
-    headers: CSRF_HEADERS,
-    body: JSON.stringify(data),
-  });
-  return handleResponse<RegisterResult>(response);
+  return getClient().registerCustomer(data);
 }
 
 /**
@@ -123,28 +124,20 @@ export async function proxyLogout(): Promise<void> {
 }
 
 /**
- * Verify email via BFF proxy. The auth token is in the httpOnly cookie (set during login/register).
- * The proxy adds the Authorization header automatically.
+ * Verify email via the SDK. No token argument is passed: the auth token lives
+ * in the httpOnly cookie (set during login/register) and the proxy attaches
+ * the Authorization header. The SDK skips its own token check in proxy mode.
  */
 export async function proxyVerifyEmail(code: string): Promise<VerifyEmailResult> {
-  const response = await fetch(`/api/store/api/vc/${CONNECTION_ID}/customers/verify-email`, {
-    method: 'POST',
-    headers: CSRF_HEADERS,
-    body: JSON.stringify({ code }),
-  });
-  return handleResponse<VerifyEmailResult>(response);
+  return getClient().verifyEmail(code);
 }
 
 /**
- * Resend verification email via BFF proxy.
- * Uses the auth token from the httpOnly cookie.
+ * Resend the verification email via the SDK. Uses the auth token from the
+ * httpOnly cookie, added by the proxy. Rate limited to 3 requests per hour.
  */
 export async function proxyResendVerification(): Promise<{ message: string }> {
-  const response = await fetch(`/api/store/api/vc/${CONNECTION_ID}/customers/resend-verification`, {
-    method: 'POST',
-    headers: CSRF_HEADERS,
-  });
-  return handleResponse<{ message: string }>(response);
+  return getClient().resendVerificationEmail();
 }
 
 /**

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

@@ -37,22 +37,11 @@ export function initClientWithLocale(locale: string): BrainerceClient {
 }
 <% } %>
 
-// Cart ID helpers (not a security token — safe in localStorage)
-const CART_ID_KEY = 'brainerce_cart_id';
-
-export function getStoredCartId(): string | null {
-  if (typeof window === 'undefined') return null;
-  return localStorage.getItem(CART_ID_KEY);
-}
-
-export function setStoredCartId(cartId: string | null): void {
-  if (typeof window === 'undefined') return;
-  if (cartId) {
-    localStorage.setItem(CART_ID_KEY, cartId);
-  } else {
-    localStorage.removeItem(CART_ID_KEY);
-  }
-}
+// Cart identity belongs to the SDK. It owns the guest cart id, the session
+// cart and the logged-in cart cache, and `smartGetCart()` resolves the right
+// one. Do not mirror a cart id into localStorage here: a second copy drifts
+// out of step on login, cart merge and post-payment clear, and the SDK will
+// not read it back.
 
 // Initialize client (no token hydration — auth handled by httpOnly cookie)
 export function initClient(): BrainerceClient {

package/templates/nextjs/base/src/core/providers/store-provider.tsx.ejs

@@ -3,7 +3,7 @@
 import React, { createContext, useContext, useEffect, useState, useCallback } from 'react';
 import type { Cart, CustomerProfile } from 'brainerce';
 import { getCartTotals } from 'brainerce';
-import { getClient, initClient, setStoredCartId } from '@/core/lib/brainerce';
+import { getClient, initClient } from '@/core/lib/brainerce';
 import { pickPublicStoreInfo, type PublicStoreInfo } from '@/core/lib/store-info';
 import { checkAuthStatus, proxyLogout } from '@/core/lib/auth';
 <% if (i18nEnabled) { %>
@@ -170,13 +170,10 @@ export function StoreProvider({
     try {
       setCartLoading(true);
       const client = getClient();
+      // The SDK owns cart identity: smartGetCart() picks the guest, session or
+      // customer cart on its own. Never mirror the id into localStorage.
       const c = await client.smartGetCart();
       setCart(c);
-
-      // Persist server cart ID
-      if (c && c.id) {
-        setStoredCartId(c.id);
-      }
     } catch (err) {
       console.error('Failed to load cart:', err);
     } finally {