create-brainerce-store 1.78.0 → 1.80.0

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

@@ -0,0 +1,88 @@
+import type { InventoryInfo, Product } from 'brainerce';
+
+/**
+ * KIT stock, for every surface that shows availability.
+ *
+ * A `KIT` is one purchasable product assembled from other catalog products, and
+ * it carries **no `inventory` row of its own** — the component that runs out
+ * first decides how many kits can be sold, and the API reports that as
+ * `product.kitAvailable`:
+ *
+ *   - `null`      → unlimited (every component is untracked)
+ *   - `0`         → not sellable (a component is out, or the kit has none)
+ *   - a number    → that many kits
+ *   - `undefined` → not a kit; the field is absent on SIMPLE / VARIABLE
+ *
+ * ⛔ `null` and `undefined` mean OPPOSITE things here. Treating `null` as "no
+ * stock" renders an unlimited kit as sold out, which is the same bug as the one
+ * this file exists to fix, only inverted.
+ *
+ * Why a helper rather than `product.inventory` at each call site: reading
+ * `inventory` alone gave every kit two contradictory answers on one page — a red
+ * "Out of stock" badge (because `!inventory`) beside an ENABLED add-to-cart
+ * button (because `inventory?.canPurchase !== false` is `true` when inventory is
+ * null). Both now read the same resolved value.
+ */
+
+/** The subset of a product this module needs. Keeps it usable with list rows. */
+type StockSource = Pick<Product, 'type'> & {
+  inventory?: InventoryInfo | null;
+  kitAvailable?: number | null;
+};
+
+/**
+ * Build the `InventoryInfo` a kit would have if it had one.
+ *
+ * Mirrors the shape the backend synthesizes for the sales-channel read, so a
+ * storefront cannot disagree with the API about the same kit.
+ */
+export function kitInventory(kitAvailable: number | null): InventoryInfo {
+  const unlimited = kitAvailable === null;
+  const available = kitAvailable ?? 0;
+  return {
+    total: available,
+    reserved: 0,
+    available,
+    trackingMode: unlimited ? 'UNLIMITED' : 'TRACKED',
+    inStock: unlimited || available > 0,
+    canPurchase: unlimited || available > 0,
+    // A kit is never backorderable: its components decide, not the kit.
+    backorderMode: 'NONE',
+  };
+}
+
+/**
+ * The stock signal to render for a product — kit or not.
+ *
+ * Pass the selected variant's inventory as the second argument on a product
+ * page; it wins for VARIABLE products and is irrelevant for a kit, which takes
+ * no variant at all.
+ */
+export function resolveStockInfo(
+  product: StockSource | null | undefined,
+  variantInventory?: InventoryInfo | null
+): InventoryInfo | null {
+  if (variantInventory) return variantInventory;
+  if (!product) return null;
+  if (product.type === 'KIT') {
+    // `kitAvailable` first. Some reads also synthesize an `inventory` block for
+    // kits, so fall back to it before giving up — and only treat the kit as
+    // unresolved (`null`) when neither field arrived.
+    if (product.kitAvailable !== undefined) return kitInventory(product.kitAvailable);
+    return product.inventory ?? null;
+  }
+  return product.inventory ?? null;
+}
+
+/**
+ * Can this product go in the cart right now?
+ *
+ * `!== false` rather than `=== true` on purpose: a missing stock signal must not
+ * disable the button on a store that does not track inventory at all.
+ */
+export function canPurchaseProduct(
+  product: StockSource | null | undefined,
+  variantInventory?: InventoryInfo | null
+): boolean {
+  return resolveStockInfo(product, variantInventory)?.canPurchase !== false;
+}

package/templates/nextjs/base/src/ui/cart/gift-card-input.tsx

@@ -3,6 +3,7 @@
 import { useState } from 'react';
 import { Gift } from 'lucide-react';
 import type { Checkout } from 'brainerce';
+import { BrainerceError } from 'brainerce';
 import { getClient } from '@/core/lib/brainerce';
 import { useTranslations } from '@/core/lib/translations';
 import { LoadingSpinner } from '@/ui/shared/loading-spinner';
@@ -24,6 +25,17 @@ interface GiftCardInputProps {
    * from being confused again.
    */
   tenders: NonNullable<Checkout['tenders']>;
+  /**
+   * Whether the checkout can still take a card.
+   *
+   * False from the moment a payment intent exists: the server refuses every
+   * tender change on a `PAYMENT_PENDING` / `PAYMENT_PROCESSING` checkout,
+   * because changing what a card pays underneath a created intent would leave
+   * the provider charging the wrong amount. That refusal is correct. What was
+   * wrong was leaving the field enabled in front of it, so a shopper typed a
+   * good code into a box that could never accept one.
+   */
+  locked: boolean;
   /** Formats an amount in the checkout's currency. */
   formatAmount: (value: string) => string;
   onUpdate: () => void;
@@ -60,12 +72,20 @@ interface GiftCardInputProps {
  *
  * The server answers identically for "no such code", "expired", "already spent"
  * and "wrong currency". That is deliberate: any response that distinguishes them
- * is an oracle someone walks the code space against. Show what the server said;
- * never guess a more specific reason.
+ * is an oracle someone walks the code space against. So this shows ONE message
+ * of its own for all of them, rather than forwarding the server's text -- which
+ * would put the API's English on a translated storefront and make the guarantee
+ * depend on the server never adding a more helpful sentence.
+ *
+ * Two refusals are NOT about the card and must not read as if they were: a 5xx
+ * or a dropped connection, and a checkout already locked for payment. Telling
+ * someone their card is bad in either case sends them to support over a card
+ * that works.
  */
 export function GiftCardInput({
   checkoutId,
   tenders,
+  locked,
   formatAmount,
   onUpdate,
   className,
@@ -77,6 +97,17 @@ export function GiftCardInput({
   const [removingId, setRemovingId] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
 
+  /**
+   * `CHECKOUT_LOCKED` is the one 4xx that is not a statement about the card.
+   * The code travels in the response body, which the SDK hands over whole as
+   * `details`; read it defensively, since an older backend may not send one.
+   */
+  function isCheckoutLocked(err: unknown): boolean {
+    if (!(err instanceof BrainerceError)) return false;
+    const details = err.details as { code?: unknown } | null | undefined;
+    return details?.code === 'CHECKOUT_LOCKED';
+  }
+
   async function handleApply() {
     const trimmed = code.trim();
     if (!trimmed || applying) return;
@@ -90,7 +121,25 @@ export function GiftCardInput({
       setCode('');
       onUpdate();
     } catch (err) {
-      setError(err instanceof Error ? err.message : t('invalidCode'));
+      // ONE message for every rejected code, written by this store.
+      //
+      // Echoing the server's text put raw English on a Hebrew storefront — the
+      // class-validator string for a too-short code came through verbatim. The
+      // deeper reason is that a refusal must not vary: the backend answers
+      // "expired", "revoked", "wrong currency" and "no such code" with a single
+      // sentence on purpose, because a response that tells them apart is an
+      // oracle for walking the code space. Forwarding whatever arrives makes
+      // that guarantee depend on the server never adding a more helpful
+      // message, which is not a guarantee at all.
+      //
+      // A 5xx or a dropped connection is NOT a refusal and must not read as
+      // one — telling someone their card is bad when the network failed sends
+      // them to support over a working card. Neither is a locked checkout,
+      // which is a 400 and says nothing whatever about the code typed in.
+      const refused = err instanceof BrainerceError && err.statusCode < 500;
+      setError(
+        isCheckoutLocked(err) ? t('locked') : refused ? t('invalidCode') : t('applyFailed')
+      );
     } finally {
       setApplying(false);
     }
@@ -104,7 +153,9 @@ export function GiftCardInput({
       await getClient().removeGiftCard(checkoutId, tenderId);
       onUpdate();
     } catch (err) {
-      setError(err instanceof Error ? err.message : t('removeFailed'));
+      // Same three cases as apply, and for the same reason: the server's own
+      // text is English, and a locked checkout is not a failed removal.
+      setError(isCheckoutLocked(err) ? t('locked') : t('removeFailed'));
     } finally {
       setRemovingId(null);
     }
@@ -128,19 +179,42 @@ export function GiftCardInput({
                   {t('applied', { amount: formatAmount(tender.amountApplied) })}
                 </span>
               </div>
-              <button
-                type="button"
-                onClick={() => handleRemove(tender.tenderId)}
-                disabled={removingId === tender.tenderId}
-                className="text-destructive hover:text-destructive/80 text-xs transition-colors disabled:opacity-40"
-              >
-                {removingId === tender.tenderId ? tc('removing') : tc('remove')}
-              </button>
+              {/* Gone rather than disabled once the checkout is locked. The
+                  server refuses a removal at that point too, and a dimmed
+                  button still reads as something to press. */}
+              {!locked && (
+                <button
+                  type="button"
+                  onClick={() => handleRemove(tender.tenderId)}
+                  disabled={removingId === tender.tenderId}
+                  className="text-destructive hover:text-destructive/80 text-xs transition-colors disabled:opacity-40"
+                >
+                  {removingId === tender.tenderId ? tc('removing') : tc('remove')}
+                </button>
+              )}
             </li>
           ))}
         </ul>
       )}
 
+      {/* The field is GONE once the checkout is locked, not disabled and not
+          silently broken.
+
+          Payment starts the moment the shopper picks a shipping rate, and from
+          then on the server refuses every tender change — correctly, since the
+          provider is already holding an amount. The box stayed on screen and
+          accepted typing anyway, so a shopper at the payment step could enter a
+          perfectly good code and be told the card was no good. A card is added
+          before payment or not at all, and saying so is kinder than a field
+          that cannot work. */}
+      {locked ? (
+        // Only to someone who has a card on this order. With nothing applied
+        // there is nothing to explain, and unprompted gift-card copy at the
+        // payment step is just noise.
+        tenders.length > 0 ? (
+          <p className="text-muted-foreground text-xs">{t('lockedHint')}</p>
+        ) : null
+      ) : (
       <div className="flex gap-2">
         <Input
           type="text"
@@ -180,6 +254,7 @@ export function GiftCardInput({
           )}
         </Button>
       </div>
+      )}
 
       {error && (
         <p role="alert" className="text-destructive text-xs">

package/templates/nextjs/base/src/ui/layout/newsletter-signup.tsx

@@ -21,17 +21,26 @@
  * commonest reason a signup never becomes a subscriber, and the resend cooldown
  * means no second copy arrives for 24 hours.
  *
- * **Discount codes.** Subscribing mints nothing. For a "10% off your first
- * order" offer, the merchant creates a coupon in the dashboard with the
- * `customer_first_order` condition and you render that fixed code in the
- * success state — see the commented line below. Show it immediately: it must
- * not wait for the confirmation click, or the shopper loses the reason they
- * filled the form in.
+ * **The welcome offer.** `marketing.getBenefit()` returns what the merchant is
+ * offering people who confirm, or `null` when they offer nothing. Show its
+ * terms beside the field so the shopper knows what they are signing up for.
+ *
+ * ⛔ DO NOT RENDER A COUPON CODE HERE, now or after the success state. No coupon
+ * exists at either moment. It is minted when the recipient clicks the link in
+ * their own mailbox and is emailed to them there — which is exactly what stops a
+ * forwarded link handing the discount to someone who never asked. The
+ * confirmation page is served by the API and already shows the code, its expiry
+ * and its terms, so there is nothing here to poll for either.
+ *
+ * ⛔ There is no eligibility check to call, deliberately: a per-address answer
+ * would let anyone test who already subscribed. The offer is one per address per
+ * store, forever. Say so in the terms rather than trying to detect it.
  *
  * Rate limited to 3 requests / 60s per IP.
  */
 
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
+import type { PublicNewsletterBenefitOffer } from 'brainerce';
 import { getClient } from '@/core/lib/brainerce';
 import { useTranslations } from '@/core/lib/translations';
 
@@ -42,6 +51,10 @@ export function NewsletterSignup() {
   const [loading, setLoading] = useState(false);
   const [done, setDone] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  // null covers both "no offer configured" and "the read failed". Neither is
+  // worth an error state on a footer signup: the form still works, it just
+  // promises nothing, and promising nothing is always safe.
+  const [offer, setOffer] = useState<PublicNewsletterBenefitOffer | null>(null);
 
   // Same source the contact form uses — <html lang> is set from the active
   // locale, and passing it is what decides the language of the confirmation
@@ -51,6 +64,31 @@ export function NewsletterSignup() {
     return undefined;
   }, []);
 
+  // Read once per mount. The offer belongs to the store, not to the visitor,
+  // so re-reading it per keystroke or per submit is wasted work.
+  useEffect(() => {
+    let cancelled = false;
+    getClient()
+      .marketing.getBenefit(locale)
+      .then((result) => {
+        if (!cancelled) setOffer(result);
+      })
+      .catch(() => {
+        // Silent on purpose. A failed offer read must not stop someone
+        // subscribing, and there is nothing the shopper could do about it.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [locale]);
+
+  const offerHeadline = offer
+    ? offer.headline?.trim() ||
+      (offer.discountType === 'PERCENTAGE'
+        ? t('offerPercent', { value: String(offer.discountValue) })
+        : t('offerAmount', { value: String(offer.discountValue) }))
+    : null;
+
   async function handleSubmit(e: React.FormEvent) {
     e.preventDefault();
     if (loading || !email.trim()) return;
@@ -80,11 +118,10 @@ export function NewsletterSignup() {
       <div className="space-y-1">
         <p className="text-sm font-medium">{t('checkEmailTitle')}</p>
         <p className="text-sm opacity-70">{t('checkEmailBody')}</p>
-        {/*
-          Merchant offering a signup discount? Render the coupon code here, now
-          — not after the confirmation click, which may never come:
-          <p className="text-sm font-medium">{t('discountCode', { code: 'WELCOME10' })}</p>
-        */}
+        {/* Says where the code comes from, without ever showing one. The coupon
+            is created by the confirmation click and arrives in the same inbox,
+            so "check your email" is the whole instruction. */}
+        {offer ? <p className="text-sm opacity-70">{t('offerByEmail')}</p> : null}
       </div>
     );
   }
@@ -96,6 +133,16 @@ export function NewsletterSignup() {
       </label>
       <p className="text-sm opacity-70">{t('subtitle')}</p>
 
+      {/* The merchant's own words when they wrote any, a plain statement of the
+          discount when they did not. Both are the promise the shopper is
+          agreeing to, so they belong above the input, not under the button. */}
+      {offerHeadline ? (
+        <div className="space-y-0.5">
+          <p className="text-sm font-medium">{offerHeadline}</p>
+          {offer?.terms ? <p className="text-xs opacity-70">{offer.terms}</p> : null}
+        </div>
+      ) : null}
+
       <div className="flex flex-wrap gap-2">
         <input
           id="newsletter-email"