npm - create-brainerce-store - Versions diffs - 1.72.0 → 1.74.0 - Mend

create-brainerce-store 1.72.0 → 1.74.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (88) hide show

package/templates/nextjs/base/src/app/layout.tsx.ejs CHANGED Viewed

@@ -4,10 +4,12 @@ import type { Metadata } from 'next';
 import { StoreProvider } from '@/core/providers/store-provider';
 import { AnnouncementBar } from '@/ui/layout/announcement-bar';
 import { SiteHeader } from '@/ui/layout/site-header';
+import { DiscountBannerStrip } from '@/ui/home/discount-banner-strip';
 import { SiteFooter } from '@/ui/layout/site-footer';
 import { BrainerceBotWidget } from '@/components/brainerce-bot';
 import { TrackingBootstrap } from '@/components/tracking-bootstrap';
 import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce.server';
+import { resolveRegion } from '@/core/lib/region.server';
 import { getDirection, getMessages, supportedLocales } from '@/i18n';
 import { getNonce } from '@/core/lib/nonce';
 import { getCanonicalSiteUrl } from '@/core/lib/site-url';
@@ -71,7 +73,8 @@ export default async function RootLayout({
   // seeded a particular content type yet. New stores ship with default rows
   // seeded by the backend (StoresService.seedDefaultContent).
   const client = await getServerClient(locale);
-  const [announcements, siteHeader, siteFooter, storeInfo, messages] = await Promise.all([
+  const [announcements, siteHeader, siteFooter, storeInfo, messages, discountBanners, regionInfo] =
+    await Promise.all([
     client.content.announcement.list(locale).catch(() => []),
     client.content.header.get('main', locale).catch(() => null),
     client.content.footer.get('main', locale).catch(() => null),
@@ -83,6 +86,18 @@ export default async function RootLayout({
     // without this, every page (and every locale switch) shows raw
     // "namespace.key" strings until the client-only fetch resolves.
     getMessages(locale),
+    // Store-wide discount banners. Fetched here rather than on the home
+    // page so they render below the header on EVERY page. `.catch(() => [])`
+    // keeps a store with no active discounts (and an API hiccup) silent:
+    // the strip itself returns null on an empty array.
+    client.getDiscountBanners().catch(() => []),
+    // Which region prices this request: the shopper's cookie, else the edge
+    // geo header, else the store default. Resolved here so SSR and the client
+    // agree from frame 0 and every page shares one round trip (it is
+    // `cache()`-wrapped). Never throws: a store with no regions answers
+    // `{ regions: [], region: null }` and every consumer then sends no
+    // `regionId`, which is what this storefront did before regions existed.
+    resolveRegion(),
   ]);
   return (
@@ -123,7 +138,14 @@ export default async function RootLayout({
         />
       </head>
       <body className={font.className}>
-        <StoreProvider locale={locale} initialStoreInfo={storeInfo} initialMessages={messages}>
+        <StoreProvider
+          locale={locale}
+          initialStoreInfo={storeInfo}
+          initialMessages={messages}
+          initialRegions={regionInfo.regions}
+          initialRegion={regionInfo.region}
+          initialCountry={regionInfo.country}
+        >
           {/* Mounted ahead of the page tree on purpose: React runs effects in
               tree order, so booting the tags here guarantees fbq/ttq exist by
               the time a page component fires its first e-commerce event. */}
@@ -131,6 +153,7 @@ export default async function RootLayout({
           <div className="min-h-screen flex flex-col">
             <AnnouncementBar announcements={announcements} />
             <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />
+            <DiscountBannerStrip banners={discountBanners} />
             <main className="flex-1">{children}</main>
             <SiteFooter footer={siteFooter} storeName={<%- storeNameJs %>} />
           </div>
@@ -146,10 +169,12 @@ import type { Metadata } from 'next';
 import { StoreProvider } from '@/core/providers/store-provider';
 import { AnnouncementBar } from '@/ui/layout/announcement-bar';
 import { SiteHeader } from '@/ui/layout/site-header';
+import { DiscountBannerStrip } from '@/ui/home/discount-banner-strip';
 import { SiteFooter } from '@/ui/layout/site-footer';
 import { BrainerceBotWidget } from '@/components/brainerce-bot';
 import { TrackingBootstrap } from '@/components/tracking-bootstrap';
 import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce.server';
+import { resolveRegion } from '@/core/lib/region.server';
 import { getNonce } from '@/core/lib/nonce';
 import { getCanonicalSiteUrl } from '@/core/lib/site-url';
 import './globals.css';
@@ -205,7 +230,8 @@ export default async function RootLayout({
   // seeded a particular content type yet. New stores ship with default rows
   // seeded by the backend (StoresService.seedDefaultContent).
   const client = await getServerClient();
-  const [announcements, siteHeader, siteFooter, storeInfo] = await Promise.all([
+  const [announcements, siteHeader, siteFooter, storeInfo, discountBanners, regionInfo] =
+    await Promise.all([
     client.content.announcement.list().catch(() => []),
     client.content.header.get('main').catch(() => null),
     client.content.footer.get('main').catch(() => null),
@@ -213,6 +239,18 @@ export default async function RootLayout({
     // render with the real currency, feature flags, and i18n config at frame 0
     // — without this, Googlebot sees USD/defaults baked into the HTML.
     fetchStoreInfo(),
+    // Store-wide discount banners. Fetched here rather than on the home
+    // page so they render below the header on EVERY page. `.catch(() => [])`
+    // keeps a store with no active discounts (and an API hiccup) silent:
+    // the strip itself returns null on an empty array.
+    client.getDiscountBanners().catch(() => []),
+    // Which region prices this request: the shopper's cookie, else the edge
+    // geo header, else the store default. Resolved here so SSR and the client
+    // agree from frame 0 and every page shares one round trip (it is
+    // `cache()`-wrapped). Never throws: a store with no regions answers
+    // `{ regions: [], region: null }` and every consumer then sends no
+    // `regionId`, which is what this storefront did before regions existed.
+    resolveRegion(),
   ]);
   return (
@@ -253,7 +291,12 @@ export default async function RootLayout({
         />
       </head>
       <body className={font.className}>
-        <StoreProvider initialStoreInfo={storeInfo}>
+        <StoreProvider
+          initialStoreInfo={storeInfo}
+          initialRegions={regionInfo.regions}
+          initialRegion={regionInfo.region}
+          initialCountry={regionInfo.country}
+        >
           {/* Mounted ahead of the page tree on purpose: React runs effects in
               tree order, so booting the tags here guarantees fbq/ttq exist by
               the time a page component fires its first e-commerce event. */}
@@ -261,6 +304,7 @@ export default async function RootLayout({
           <div className="min-h-screen flex flex-col">
             <AnnouncementBar announcements={announcements} />
             <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />
+            <DiscountBannerStrip banners={discountBanners} />
             <main className="flex-1">{children}</main>
             <SiteFooter footer={siteFooter} storeName={<%- storeNameJs %>} />
           </div>

package/templates/nextjs/base/src/app/order-confirmation/page.tsx CHANGED Viewed

@@ -2,10 +2,14 @@
 import { Suspense, useEffect, useState } from 'react';
 import { useSearchParams } from 'next/navigation';
+import { CdnImage as Image } from '@/ui/shared/cdn-image';
 import { Link } from '@/core/lib/navigation';
-import type { WaitForOrderResult, OrderDownloadLink } from 'brainerce';
+import type { Order, WaitForOrderResult, OrderDownloadLink } from 'brainerce';
+import { formatPrice } from 'brainerce';
 import { getClient } from '@/core/lib/brainerce';
 import { useCart } from '@/core/providers/store-provider';
+import { useCurrency } from '@/core/lib/use-currency';
+import { OrderCustomizations } from '@/components/account/order-customizations';
 import { LoadingSpinner } from '@/ui/shared/loading-spinner';
 import { useTranslations } from '@/core/lib/translations';
 import { trackPurchase } from '@/core/lib/tracking';
@@ -18,6 +22,10 @@ function OrderConfirmationContent() {
   const t = useTranslations('orderConfirmation');
   const tc = useTranslations('common');
   const [result, setResult] = useState<WaitForOrderResult | null>(null);
+  // The real Order behind the checkout. `waitForOrder` resolves to a status
+  // envelope that carries no line items at all, so this second fetch is the
+  // only way this page can show what was actually bought.
+  const [order, setOrder] = useState<Order | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -88,10 +96,17 @@ function OrderConfirmationContent() {
         // Read the real order rather than the pre-payment cart so value, tax,
         // shipping and coupon match what was actually charged; `trackPurchase`
         // de-duplicates on the order id, so a refresh cannot double-count it.
+        //
+        // The same Order is what this page renders its line items from, so
+        // keep it rather than discarding it after the conversion call.
+        // `getOrderByCheckout` is typed `Promise<Order>` and REJECTS on 404 —
+        // it never resolves to null — so the catch below is what degrades this
+        // page to the order-number-only view instead of breaking it.
         if (orderResult.success) {
           try {
-            const order = await client.getOrderByCheckout(checkoutId!);
-            trackPurchase(order);
+            const fetchedOrder = await client.getOrderByCheckout(checkoutId!);
+            setOrder(fetchedOrder);
+            trackPurchase(fetchedOrder);
           } catch (err) {
             // A conversion we failed to report must never break the page the
             // shopper is looking at — but it should be visible, because a
@@ -179,6 +194,11 @@ function OrderConfirmationContent() {
         <p className="text-muted-foreground mt-2">{t('confirmationEmail')}</p>
+        {/* What was actually bought. Renders nothing at all when the order
+            fetch failed or came back with no lines, leaving the number-only
+            view above intact. */}
+        <ConfirmationLineItems order={order} />
         {result.status.orderId && (
           <ConfirmationDownloads orderId={result.status.orderId} checkoutId={checkoutId!} />
         )}
@@ -242,6 +262,81 @@ function OrderConfirmationContent() {
   );
 }
+/**
+ * Line items on the confirmation page.
+ *
+ * `OrderItem` is FLAT — `item.name`, `item.price`, `item.image` — unlike the
+ * nested `CartItem` / `CheckoutLineItem` shapes used elsewhere in this
+ * storefront. Do not copy a cart row renderer here; `item.product.name` does
+ * not exist on an order.
+ *
+ * Auto-hides: returns null when the order fetch failed (`order === null`) or
+ * the order carries no lines, so the number-only confirmation still renders.
+ */
+function ConfirmationLineItems({ order }: { order: Order | null }) {
+  // Named `tch` rather than `t` on purpose: the other components in this file
+  // bind `t` to the `orderConfirmation` namespace, and a same-named alias on a
+  // different namespace is how a wrong-namespace key slips through review.
+  const tch = useTranslations('checkout');
+  const ta = useTranslations('account');
+  const tc = useTranslations('common');
+  const currency = useCurrency(order?.currency);
+  if (!order || !order.items || order.items.length === 0) return null;
+  const totalAmount = order.totalAmount || order.total || '0';
+  return (
+    <div className="border-border bg-muted/30 mx-auto mt-8 max-w-md rounded-lg border p-6 text-start">
+      <h3 className="text-foreground mb-3 text-sm font-semibold">{tch('orderSummary')}</h3>
+      <div className="space-y-3">
+        {order.items.map((item, index) => (
+          <div key={`${item.productId}-${index}`} className="space-y-1">
+            <div className="flex items-center gap-3">
+              <div className="bg-muted relative h-12 w-12 flex-shrink-0 overflow-hidden rounded">
+                {item.image ? (
+                  <Image
+                    src={item.image}
+                    alt={item.name || ta('productFallback')}
+                    fill
+                    sizes="48px"
+                    className="object-cover"
+                  />
+                ) : null}
+              </div>
+              <div className="min-w-0 flex-1">
+                <p className="text-foreground truncate text-sm">
+                  {item.name || ta('productFallback')}
+                </p>
+                <p className="text-muted-foreground text-xs">
+                  {tc('qty')} {item.quantity}
+                </p>
+              </div>
+              <span className="text-foreground flex-shrink-0 text-sm">
+                {formatPrice(parseFloat(item.price), { currency }) as string}
+              </span>
+            </div>
+            {/* What the buyer typed / uploaded / picked, with the merchant's
+                own labels. Renders nothing when the line has none. */}
+            {item.customizations && <OrderCustomizations customizations={item.customizations} />}
+          </div>
+        ))}
+      </div>
+      <div className="border-border mt-3 flex items-center justify-between border-t pt-3">
+        <span className="text-foreground text-sm font-medium">{tc('total')}</span>
+        <span className="text-foreground text-sm font-semibold">
+          {formatPrice(parseFloat(totalAmount), { currency }) as string}
+        </span>
+      </div>
+    </div>
+  );
+}
 function ConfirmationDownloads({ orderId, checkoutId }: { orderId: string; checkoutId: string }) {
   const t = useTranslations('orderConfirmation');
   const [downloads, setDownloads] = useState<OrderDownloadLink[] | null>(null);

package/templates/nextjs/base/src/app/products/[slug]/page.tsx CHANGED Viewed

@@ -2,6 +2,7 @@ import type { Metadata } from 'next';
 import { notFound, permanentRedirect } from 'next/navigation';
 import { BrainerceError, getProductPriceInfo } from 'brainerce';
 import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce.server';
+import { getRegionId } from '@/core/lib/region.server';
 import { resolveCurrency } from '@/core/lib/resolve-currency';
 import { buildMetaDescription } from '@/core/lib/seo';
 import { decodeSlug } from '@/core/lib/utils';
@@ -43,8 +44,16 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
     // Fetch product + store info in parallel; storeInfo gives us the live
     // currency for OG price tags (with env-var + USD fallbacks so we never
     // silently emit a wrong currency when the API is briefly unreachable).
+    // ⛔ `regionId` belongs on EVERY product read. Without it the backend
+    // prices in the default region, so a shopper elsewhere gets the wrong
+    // currency in the OG price meta that link previews and Merchant Center
+    // read. `getRegionId()` is `cache()`-wrapped and shared with the layout
+    // and the page body below, so this is not an extra round trip. It
+    // resolves to `undefined` on a store with no regions, and the SDK then
+    // omits the query param entirely.
+    const regionId = await getRegionId();
     const [product, storeInfo] = await Promise.all([
-      client.getProductBySlug(slug),
+      client.getProductBySlug(slug, { regionId }),
       fetchStoreInfo(locale),
     ]);
     const imageUrl = product.images?.[0]?.url;
@@ -138,9 +147,12 @@ export default async function ProductDetailPage({ params }: Props) {
   const slug = decodeSlug(rawSlug);
   const client = await getServerClient(locale);
+  // Same region as the metadata above (one shared `cache()`d resolve), so the
+  // price in the <head> and the price on the page cannot disagree.
+  const regionId = await getRegionId();
   let product;
   try {
-    product = await client.getProductBySlug(slug);
+    product = await client.getProductBySlug(slug, { regionId });
   } catch (err) {
     // Only a genuine 404 may become a storefront 404. Anything else — a 403
     // from the channel's origin check, a network failure, a 5xx — is a

package/templates/nextjs/base/src/components/account/loyalty-panel.tsx ADDED Viewed

@@ -0,0 +1,226 @@
+'use client';
+/**
+ * Loyalty — points balance, tier progress, and the reward catalogue.
+ *
+ * ⛔ REDEEMING DOES NOT DISCOUNT ANYTHING BY ITSELF. `redeemLoyaltyReward()`
+ * spends the points and mints a ONE-TIME COUPON CODE, which the shopper still
+ * has to apply at checkout. If the panel says "redeemed!" and stops there, the
+ * points are gone and the discount never happens — so the code is shown, kept
+ * on screen, and copyable. Points are the shopper's money-equivalent and the
+ * spend is not reversible from the storefront.
+ *
+ * ⛔ IT AUTO-HIDES, AND THAT IS THE POINT. `status.program` is null for a store
+ * with no loyalty program, which is most stores on day one. Render nothing
+ * then — never an empty "0 points" card, which reads as a broken feature rather
+ * than an absent one. Build the panel anyway: the merchant turns the program on
+ * from the dashboard without touching this code.
+ *
+ * ⛔ `pointsBalance` EXCLUDES PENDING POINTS. Points from a recent order sit
+ * pending for a merchant-set number of days before they can be spent, so a
+ * shopper who just bought something sees a balance that does not include it.
+ * That is correct, and it is why the copy says "ready to spend" rather than
+ * "earned".
+ *
+ * ⛔ A REWARD CAN BE VISIBLE AND UNREDEEMABLE. Two independent gates:
+ * `pointsCost` above the balance, and `minTierLevel` above the shopper's tier.
+ * Both are enforced server-side, so a button that ignores them produces a
+ * failed call, not a discount. They are shown disabled with the reason instead
+ * of hidden — a locked reward is the thing that makes the next tier worth
+ * reaching.
+ *
+ * ⛔ `program.status` DRAFT / PAUSED both stop EARNING. An existing balance is
+ * still spendable, so the panel keeps working; it just stops promising that the
+ * next order adds anything.
+ *
+ * Requires a logged-in customer — the calls go through the BFF proxy, which
+ * attaches the httpOnly cookie. Mount it inside the account page, never on a
+ * public route.
+ */
+import { useEffect, useState } from 'react';
+import type { LoyaltyStatus, LoyaltyReward } from 'brainerce';
+import { getClient } from '@/core/lib/brainerce';
+import { useTranslations } from '@/core/lib/translations';
+import { cn } from '@/core/lib/utils';
+interface LoyaltyPanelProps {
+  className?: string;
+}
+interface RedeemedCoupon {
+  rewardId: string;
+  couponCode: string;
+}
+export function LoyaltyPanel({ className }: LoyaltyPanelProps) {
+  const t = useTranslations('loyalty');
+  const [status, setStatus] = useState<LoyaltyStatus | null>(null);
+  const [rewards, setRewards] = useState<LoyaltyReward[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [redeemingId, setRedeemingId] = useState<string | null>(null);
+  const [redeemed, setRedeemed] = useState<RedeemedCoupon | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  useEffect(() => {
+    let cancelled = false;
+    async function load() {
+      const client = getClient();
+      // Settled, not all: a store with rewards configured and none active
+      // still has a balance worth showing, and vice versa.
+      const [statusResult, rewardsResult] = await Promise.allSettled([
+        client.getLoyaltyStatus(),
+        client.getAvailableRewards(),
+      ]);
+      if (cancelled) return;
+      if (statusResult.status === 'fulfilled') setStatus(statusResult.value);
+      if (rewardsResult.status === 'fulfilled') setRewards(rewardsResult.value);
+      setLoading(false);
+    }
+    load();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+  // No program on this store, or the status call failed: render nothing at all.
+  // An empty card is worse than no card.
+  if (loading || !status?.program) return null;
+  const pointsName = status.program.pointsName || t('pointsFallback');
+  const earningPaused = status.program.status !== 'ACTIVE';
+  const tierLevel = status.tier?.level ?? 0;
+  async function redeem(reward: LoyaltyReward) {
+    setRedeemingId(reward.id);
+    setError(null);
+    try {
+      const result = await getClient().redeemLoyaltyReward(reward.id);
+      setRedeemed({ rewardId: reward.id, couponCode: result.couponCode });
+      // The server is the authority on the new balance — take it from the
+      // response rather than subtracting pointsCost locally, which drifts the
+      // moment a reward is repriced between load and redeem.
+      setStatus((prev) => (prev ? { ...prev, pointsBalance: result.pointsBalance } : prev));
+    } catch (err) {
+      setError(err instanceof Error ? err.message : t('redeemError'));
+    } finally {
+      setRedeemingId(null);
+    }
+  }
+  return (
+    <section className={cn('border-border rounded-lg border p-6', className)}>
+      <div className="flex flex-wrap items-baseline justify-between gap-2">
+        <h2 className="text-foreground text-lg font-semibold">{t('title')}</h2>
+        <p className="text-foreground text-2xl font-bold">
+          {status.pointsBalance.toLocaleString()}{' '}
+          <span className="text-muted-foreground text-sm font-normal">{pointsName}</span>
+        </p>
+      </div>
+      <p className="text-muted-foreground mt-1 text-sm">
+        {earningPaused ? t('earningPaused') : t('readyToSpend')}
+      </p>
+      {/* Tier progress. Rendered only when the store configured tiers — the
+          whole block is absent otherwise, rather than a full bar with no name. */}
+      {status.tier && (
+        <div className="mt-5">
+          <div className="flex items-baseline justify-between text-sm">
+            <span className="text-foreground font-medium">{status.tier.name}</span>
+            {status.nextTier && (
+              // `pointsToNextTier` is named for points and is NOT always points:
+              // it is whatever the next tier qualifies on, so a SPEND tier
+              // reports a currency amount. Saying "points" over a spend
+              // threshold tells the shopper to earn the wrong thing.
+              <span className="text-muted-foreground">
+                {t(
+                  status.nextTier.qualificationType === 'SPEND'
+                    ? 'toNextTierSpend'
+                    : 'toNextTierPoints',
+                  {
+                    amount: (status.pointsToNextTier ?? 0).toLocaleString(),
+                    pointsName,
+                    tier: status.nextTier.name,
+                  }
+                )}
+              </span>
+            )}
+          </div>
+          <div className="bg-muted mt-2 h-2 w-full overflow-hidden rounded-full">
+            <div
+              className="bg-primary h-full rounded-full transition-[width]"
+              style={{ width: `${Math.round(Math.min(1, status.progressToNextTier) * 100)}%` }}
+            />
+          </div>
+        </div>
+      )}
+      {/* Rewards. An empty catalogue is a normal state — the merchant has not
+          created any yet — so the list simply does not render. */}
+      {rewards.length > 0 && (
+        <div className="mt-6">
+          <h3 className="text-foreground mb-3 text-sm font-semibold">{t('rewardsTitle')}</h3>
+          <ul className="space-y-3">
+            {rewards.map((reward) => {
+              const tooExpensive = reward.pointsCost > status.pointsBalance;
+              const tierLocked =
+                reward.minTierLevel !== null && tierLevel < (reward.minTierLevel ?? 0);
+              const justRedeemed = redeemed?.rewardId === reward.id;
+              return (
+                <li
+                  key={reward.id}
+                  className="border-border flex flex-wrap items-center justify-between gap-3 rounded border p-3"
+                >
+                  <div className="min-w-0">
+                    <p className="text-foreground font-medium">{reward.name}</p>
+                    {reward.description && (
+                      <p className="text-muted-foreground text-sm">{reward.description}</p>
+                    )}
+                    <p className="text-muted-foreground mt-1 text-xs">
+                      {t('pointsCost', {
+                        points: reward.pointsCost.toLocaleString(),
+                        pointsName,
+                      })}
+                      {tierLocked && ` · ${t('tierLocked')}`}
+                    </p>
+                  </div>
+                  {justRedeemed ? (
+                    // The code IS the reward. It stays on screen; the shopper
+                    // has to carry it to checkout, and the points are already
+                    // spent either way.
+                    <div className="text-right">
+                      <p className="text-muted-foreground text-xs">{t('yourCode')}</p>
+                      <code className="bg-muted text-foreground rounded px-2 py-1 font-mono text-sm">
+                        {redeemed.couponCode}
+                      </code>
+                      <p className="text-muted-foreground mt-1 text-xs">{t('applyAtCheckout')}</p>
+                    </div>
+                  ) : (
+                    <button
+                      type="button"
+                      disabled={tooExpensive || tierLocked || redeemingId === reward.id}
+                      onClick={() => redeem(reward)}
+                      className="bg-primary text-primary-foreground rounded px-4 py-2 text-sm font-medium transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-50"
+                    >
+                      {redeemingId === reward.id
+                        ? t('redeeming')
+                        : tooExpensive
+                          ? t('notEnoughPoints')
+                          : t('redeem')}
+                    </button>
+                  )}
+                </li>
+              );
+            })}
+          </ul>
+        </div>
+      )}
+      {error && <p className="text-destructive mt-4 text-sm">{error}</p>}
+    </section>
+  );
+}