create-brainerce-store 1.78.0 → 1.79.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/product/frequently-bought-together.tsx

@@ -1,197 +1,205 @@
-'use client';
-
-import { useState } from 'react';
-import { Image as ImageIcon } from 'lucide-react';
-import { CdnImage as Image } from '@/ui/shared/cdn-image';
-import type { Product, ProductRecommendation } from 'brainerce';
-import { formatPrice } from 'brainerce';
-import { useCart, useStoreInfo } from '@/core/providers/store-provider';
-import { useCurrency } from '@/core/lib/use-currency';
-import { useTranslations } from '@/core/lib/translations';
-import { Button } from '@/components/ui/button';
-import { Card } from '@/components/ui/card';
-import { Checkbox } from '@/components/ui/checkbox';
-import { cn } from '@/core/lib/utils';
-
-interface FrequentlyBoughtTogetherProps {
-  items: ProductRecommendation[];
-  currentProduct: Product;
-  className?: string;
-}
-
-// ⛔ STORE CURRENCY THROUGHOUT, deliberately. The cross-sells are
-// `ProductRecommendation`, a trimmed shape with no displayPrice/displayCurrency,
-// so there is nothing to convert them to. Converting only `currentProduct`
-// (which is a full Product and does carry FX fields) would add a euro amount to
-// two dollar amounts and print the result as one total. One currency wins, and
-// it has to be the one the cart actually charges.
-function getEffectivePrice(item: { basePrice: string; salePrice?: string | null }): number {
-  const sale = item.salePrice ? parseFloat(item.salePrice) : null;
-  const base = parseFloat(item.basePrice);
-  return sale != null && sale < base ? sale : base;
-}
-
-function ProductThumb({
-  name,
-  imageUrl,
-  price,
-  currency,
-  checked,
-  onToggle,
-  disabled,
-}: {
-  name: string;
-  imageUrl: string | null;
-  price: number;
-  currency: string;
-  checked: boolean;
-  onToggle?: () => void;
-  disabled?: boolean;
-}) {
-  return (
-    <label
-      className={cn(
-        'border-border bg-background relative flex cursor-pointer flex-col items-center rounded-lg border p-3 transition-all',
-        checked ? 'ring-primary ring-2' : 'opacity-60',
-        disabled && 'pointer-events-none'
-      )}
-    >
-      {onToggle && (
-        <Checkbox
-          checked={checked}
-          onCheckedChange={onToggle}
-          className="absolute start-2 top-2"
-        />
-      )}
-      <div className="bg-muted relative mb-2 h-20 w-20 overflow-hidden rounded">
-        {imageUrl ? (
-          <Image src={imageUrl} alt={name} fill sizes="80px" className="object-cover" />
-        ) : (
-          <div className="flex h-full w-full items-center justify-center">
-            <ImageIcon
-              className="text-muted-foreground h-8 w-8"
-              strokeWidth={1.5}
-              aria-hidden="true"
-            />
-          </div>
-        )}
-      </div>
-      <span className="text-foreground line-clamp-2 text-center text-xs font-medium">{name}</span>
-      <span className="text-muted-foreground mt-1 text-xs">
-        {formatPrice(price, { currency }) as string}
-      </span>
-    </label>
-  );
-}
-
-export function FrequentlyBoughtTogether({
-  items,
-  currentProduct,
-  className,
-}: FrequentlyBoughtTogetherProps) {
-  // Hooks must be called unconditionally and in the same order on every
-  // render — keep all of them above any early `return null` branch.
-  const { storeInfo } = useStoreInfo();
-  const { refreshCart } = useCart();
-  const t = useTranslations('productDetail');
-  const currency = useCurrency();
-
-  // Only show up to 3 cross-sells
-  const crossSells = items.slice(0, 3);
-
-  const [selected, setSelected] = useState<Set<string>>(() => new Set(crossSells.map((i) => i.id)));
-  const [adding, setAdding] = useState(false);
-
-  if (!storeInfo?.upsell?.frequentlyBoughtTogetherEnabled) return null;
-  if (crossSells.length === 0) return null;
-
-  const currentPrice = getEffectivePrice(currentProduct);
-  const currentImage = currentProduct.images?.[0];
-  const currentImageUrl = currentImage
-    ? typeof currentImage === 'string'
-      ? currentImage
-      : currentImage.url
-    : null;
-
-  const totalPrice = crossSells
-    .filter((item) => selected.has(item.id))
-    .reduce((sum, item) => sum + getEffectivePrice(item), currentPrice);
-
-  const toggleItem = (id: string) => {
-    setSelected((prev) => {
-      const next = new Set(prev);
-      if (next.has(id)) {
-        next.delete(id);
-      } else {
-        next.add(id);
-      }
-      return next;
-    });
-  };
-
-  async function handleAddAll() {
-    if (adding || selected.size === 0) return;
-    try {
-      setAdding(true);
-      const { getClient } = await import('@/core/lib/brainerce');
-      const client = getClient();
-      const selectedItems = crossSells.filter((item) => selected.has(item.id));
-      for (const item of selectedItems) {
-        await client.smartAddToCart({ productId: item.id, quantity: 1 });
-      }
-      await refreshCart();
-    } catch (err) {
-      console.error('Failed to add items to cart:', err);
-    } finally {
-      setAdding(false);
-    }
-  }
-
-  return (
-    <Card className={cn('shadow-none p-6', className)}>
-      <h2 className="text-foreground mb-4 text-xl font-semibold">
-        {t('frequentlyBoughtTogether')}
-      </h2>
-
-      <div className="flex flex-wrap items-center gap-3">
-        {/* Current product (always included, no checkbox) */}
-        <ProductThumb
-          name={currentProduct.name}
-          imageUrl={currentImageUrl}
-          price={currentPrice}
-          currency={currency}
-          checked={true}
-          disabled
-        />
-
-        {crossSells.map((item) => {
-          const img = item.images?.[0];
-          const imgUrl = img ? (typeof img === 'string' ? img : img.url) : null;
-          return (
-            <div key={item.id} className="flex items-center gap-3">
-              <span className="text-muted-foreground text-lg font-light">+</span>
-              <ProductThumb
-                name={item.name}
-                imageUrl={imgUrl}
-                price={getEffectivePrice(item)}
-                currency={currency}
-                checked={selected.has(item.id)}
-                onToggle={() => toggleItem(item.id)}
-              />
-            </div>
-          );
-        })}
-      </div>
-
-      {/* Total + Add button */}
-      <div className="mt-4 flex flex-wrap items-center gap-4">
-        <span className="text-foreground text-lg font-semibold">
-          {t('totalPrice', { price: formatPrice(totalPrice, { currency }) as string })}
-        </span>
-        <Button onClick={handleAddAll} disabled={adding || selected.size === 0} className="rounded px-5">
-          {adding ? t('addingAll') : t('addSelectedToCart')}
-        </Button>
-      </div>
-    </Card>
-  );
-}
+'use client';
+
+import { useState } from 'react';
+import { Image as ImageIcon } from 'lucide-react';
+import { CdnImage as Image } from '@/ui/shared/cdn-image';
+import type { Product, ProductRecommendation } from 'brainerce';
+import { formatPrice } from 'brainerce';
+import { useCart, useStoreInfo } from '@/core/providers/store-provider';
+import { useCurrency } from '@/core/lib/use-currency';
+import { useTranslations } from '@/core/lib/translations';
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+import { Checkbox } from '@/components/ui/checkbox';
+import { cn } from '@/core/lib/utils';
+
+interface FrequentlyBoughtTogetherProps {
+  items: ProductRecommendation[];
+  currentProduct: Product;
+  className?: string;
+}
+
+// ⛔ STORE CURRENCY THROUGHOUT, deliberately. The cross-sells are
+// `ProductRecommendation`, a trimmed shape with no displayPrice/displayCurrency,
+// so there is nothing to convert them to. Converting only `currentProduct`
+// (which is a full Product and does carry FX fields) would add a euro amount to
+// two dollar amounts and print the result as one total. One currency wins, and
+// it has to be the one the cart actually charges.
+function getEffectivePrice(item: { basePrice: string; salePrice?: string | null }): number {
+  const sale = item.salePrice ? parseFloat(item.salePrice) : null;
+  const base = parseFloat(item.basePrice);
+  return sale != null && sale < base ? sale : base;
+}
+
+function ProductThumb({
+  name,
+  imageUrl,
+  price,
+  currency,
+  checked,
+  onToggle,
+  disabled,
+}: {
+  name: string;
+  imageUrl: string | null;
+  price: number;
+  currency: string;
+  checked: boolean;
+  onToggle?: () => void;
+  disabled?: boolean;
+}) {
+  return (
+    <label
+      className={cn(
+        'border-border bg-background relative flex cursor-pointer flex-col items-center rounded-lg border p-3 transition-all',
+        checked ? 'ring-primary ring-2' : 'opacity-60',
+        disabled && 'pointer-events-none'
+      )}
+    >
+      {onToggle && (
+        <Checkbox
+          checked={checked}
+          onCheckedChange={onToggle}
+          className="absolute start-2 top-2"
+        />
+      )}
+      <div className="bg-muted relative mb-2 h-20 w-20 overflow-hidden rounded">
+        {imageUrl ? (
+          <Image src={imageUrl} alt={name} fill sizes="80px" className="object-cover" />
+        ) : (
+          <div className="flex h-full w-full items-center justify-center">
+            <ImageIcon
+              className="text-muted-foreground h-8 w-8"
+              strokeWidth={1.5}
+              aria-hidden="true"
+            />
+          </div>
+        )}
+      </div>
+      <span className="text-foreground line-clamp-2 text-center text-xs font-medium">{name}</span>
+      <span className="text-muted-foreground mt-1 text-xs">
+        {formatPrice(price, { currency }) as string}
+      </span>
+    </label>
+  );
+}
+
+export function FrequentlyBoughtTogether({
+  items,
+  currentProduct,
+  className,
+}: FrequentlyBoughtTogetherProps) {
+  // Hooks must be called unconditionally and in the same order on every
+  // render — keep all of them above any early `return null` branch.
+  const { storeInfo } = useStoreInfo();
+  const { refreshCart } = useCart();
+  const t = useTranslations('productDetail');
+  const currency = useCurrency();
+
+  // ⛔ KITs are dropped, not priced. A recommendation is a `ProductRecommendation`
+  // — an UNRESOLVED list shape, and the recommendations endpoint does not resolve
+  // kits, so `item.basePrice` on a kit is the stored PLACEHOLDER, wrong for every
+  // kit priced SUM / SUM_MINUS_PERCENT. This block sums those numbers into one
+  // "Total" beside a button that adds them all, so a wrong figure here is a
+  // number the shopper commits to. Adding a kit by its own `productId` would in
+  // fact be correct — it is the displayed price that cannot be trusted — so a
+  // kit still sells fine from its own product page, where the API resolves it.
+  // Only show up to 3 cross-sells.
+  const crossSells = items.filter((item) => item.type !== 'KIT').slice(0, 3);
+
+  const [selected, setSelected] = useState<Set<string>>(() => new Set(crossSells.map((i) => i.id)));
+  const [adding, setAdding] = useState(false);
+
+  if (!storeInfo?.upsell?.frequentlyBoughtTogetherEnabled) return null;
+  if (crossSells.length === 0) return null;
+
+  const currentPrice = getEffectivePrice(currentProduct);
+  const currentImage = currentProduct.images?.[0];
+  const currentImageUrl = currentImage
+    ? typeof currentImage === 'string'
+      ? currentImage
+      : currentImage.url
+    : null;
+
+  const totalPrice = crossSells
+    .filter((item) => selected.has(item.id))
+    .reduce((sum, item) => sum + getEffectivePrice(item), currentPrice);
+
+  const toggleItem = (id: string) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      return next;
+    });
+  };
+
+  async function handleAddAll() {
+    if (adding || selected.size === 0) return;
+    try {
+      setAdding(true);
+      const { getClient } = await import('@/core/lib/brainerce');
+      const client = getClient();
+      const selectedItems = crossSells.filter((item) => selected.has(item.id));
+      for (const item of selectedItems) {
+        await client.smartAddToCart({ productId: item.id, quantity: 1 });
+      }
+      await refreshCart();
+    } catch (err) {
+      console.error('Failed to add items to cart:', err);
+    } finally {
+      setAdding(false);
+    }
+  }
+
+  return (
+    <Card className={cn('shadow-none p-6', className)}>
+      <h2 className="text-foreground mb-4 text-xl font-semibold">
+        {t('frequentlyBoughtTogether')}
+      </h2>
+
+      <div className="flex flex-wrap items-center gap-3">
+        {/* Current product (always included, no checkbox) */}
+        <ProductThumb
+          name={currentProduct.name}
+          imageUrl={currentImageUrl}
+          price={currentPrice}
+          currency={currency}
+          checked={true}
+          disabled
+        />
+
+        {crossSells.map((item) => {
+          const img = item.images?.[0];
+          const imgUrl = img ? (typeof img === 'string' ? img : img.url) : null;
+          return (
+            <div key={item.id} className="flex items-center gap-3">
+              <span className="text-muted-foreground text-lg font-light">+</span>
+              <ProductThumb
+                name={item.name}
+                imageUrl={imgUrl}
+                price={getEffectivePrice(item)}
+                currency={currency}
+                checked={selected.has(item.id)}
+                onToggle={() => toggleItem(item.id)}
+              />
+            </div>
+          );
+        })}
+      </div>
+
+      {/* Total + Add button */}
+      <div className="mt-4 flex flex-wrap items-center gap-4">
+        <span className="text-foreground text-lg font-semibold">
+          {t('totalPrice', { price: formatPrice(totalPrice, { currency }) as string })}
+        </span>
+        <Button onClick={handleAddAll} disabled={adding || selected.size === 0} className="rounded px-5">
+          {adding ? t('addingAll') : t('addSelectedToCart')}
+        </Button>
+      </div>
+    </Card>
+  );
+}