create-brainerce-store 1.80.0 → 1.82.0

package/templates/nextjs/base/package.json.ejs

@@ -1,52 +1,53 @@
-{
-  "name": "<%= projectName %>",
-  "version": "0.1.0",
-  "private": true,
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start",
-    "lint": "next lint",
-    "setup": "node scripts/fetch-store-info.mjs"
-  },
-  "dependencies": {
-    "brainerce": "<%= brainerceVersion %>",
-    "next": "^15.3.4",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "@radix-ui/react-accordion": "^1.2.0",
-    "@radix-ui/react-checkbox": "^1.1.1",
-    "@radix-ui/react-dialog": "^1.1.2",
-    "@radix-ui/react-label": "^2.1.0",
-    "@radix-ui/react-radio-group": "^1.2.0",
-    "@radix-ui/react-select": "^2.1.1",
-    "@radix-ui/react-separator": "^1.1.0",
-    "@radix-ui/react-slot": "^1.1.0",
-    "@radix-ui/react-tabs": "^1.1.0",
-    "@radix-ui/react-tooltip": "^1.1.4",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "lucide-react": "^0.462.0",
-    "tailwind-merge": "^2.5.2",
-    "tailwindcss-animate": "^1.0.7",
-    "isomorphic-dompurify": "<%= isomorphicDompurifyVersion %>",
-    "sharp": "^0.35.3"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "autoprefixer": "^10.4.0",
-    "eslint": "^9.0.0",
-    "eslint-config-next": "^15.3.4",
-    "postcss": "^8.4.49",
-    "tailwindcss": "^3.4.0",
-    "typescript": "^5.4.0"
-  },
-  "engines": {
-    "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": ["sharp"]
-  }
-}
+{
+  "name": "<%= projectName %>",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "setup": "node scripts/fetch-store-info.mjs",
+    "connect": "node scripts/connect.mjs"
+  },
+  "dependencies": {
+    "brainerce": "<%= brainerceVersion %>",
+    "next": "^15.3.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@radix-ui/react-accordion": "^1.2.0",
+    "@radix-ui/react-checkbox": "^1.1.1",
+    "@radix-ui/react-dialog": "^1.1.2",
+    "@radix-ui/react-label": "^2.1.0",
+    "@radix-ui/react-radio-group": "^1.2.0",
+    "@radix-ui/react-select": "^2.1.1",
+    "@radix-ui/react-separator": "^1.1.0",
+    "@radix-ui/react-slot": "^1.1.0",
+    "@radix-ui/react-tabs": "^1.1.0",
+    "@radix-ui/react-tooltip": "^1.1.4",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.462.0",
+    "tailwind-merge": "^2.5.2",
+    "tailwindcss-animate": "^1.0.7",
+    "isomorphic-dompurify": "<%= isomorphicDompurifyVersion %>",
+    "sharp": "^0.35.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "autoprefixer": "^10.4.0",
+    "eslint": "^9.0.0",
+    "eslint-config-next": "^15.3.4",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["sharp"]
+  }
+}

package/templates/nextjs/base/scripts/connect.mjs

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+/**
+ * Connect this storefront to a Brainerce sales channel, and optionally fill it
+ * with a starter catalog.
+ *
+ * Run it when the build is finished, not before:
+ *
+ *   npm run connect
+ *   npm run connect -- --seed-products '[{"name":"Burr Grinder","basePrice":389}]'
+ *
+ * WHY THIS IS A SEPARATE STEP. Nothing in a storefront's code depends on WHICH
+ * store it points at — the pages, the routing, the cart, the checkout and every
+ * SDK call are identical either way. Only one environment variable differs. So
+ * a run scaffolded with `--defer-connection` builds the whole storefront
+ * uninterrupted and comes here at the end, instead of stopping for an approval
+ * before a single file exists.
+ *
+ * ⛔ WHY SEEDING LIVES HERE TOO. The approval leaves a short single-use grant on
+ * /api/device-auth/seed keyed to the device code, and this script is the only
+ * thing that holds that code. Seeding from here is also strictly better than
+ * seeding at scaffold time: by now the storefront exists, so the products can
+ * match what was actually built rather than what was guessed before any file
+ * was written. Without this the deferred path could only ever produce an empty
+ * store, and the merchant's first look at their own site is a blank grid.
+ *
+ * One click in a browser, and this writes the id into `.env.local`. A store and
+ * a sales channel are created for you if you have neither.
+ *
+ * ⛔ NEVER PROMPTS. This is run by coding agents in shells with no TTY, where a
+ * prompt does not fail — it hangs. Everything is printed and polled.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+
+const API_BASE = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com').replace(/\/$/, '');
+const ENV_PATH = resolve(process.cwd(), '.env.local');
+const KEYS = ['NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID', 'NEXT_PUBLIC_BRAINERCE_CONNECTION_ID'];
+
+// The seed route's own limits, mirrored here so a bad payload is refused before
+// the grant is touched.
+//
+// ⛔ THIS IS A HAND-KEPT COPY. The canonical one is
+// `packages/cli-shared/src/seed-products.ts`, which the scaffolder itself
+// imports; this file cannot, because it ships standalone into the user's
+// project where that package does not exist. When a limit moves, it moves
+// there first and this follows. All of it mirrors SeedDeviceAuthDto /
+// SeedProductDto in apps/backend/src/modules/device-auth/dto/device-auth.dto.ts,
+// which is what actually enforces them.
+const SEED_MIN_PRODUCTS = 1;
+const SEED_MAX_PRODUCTS = 20;
+const SEED_MAX_NAME = 191;
+const SEED_MAX_DESCRIPTION = 5000;
+const SEED_FIELDS = ['name', 'basePrice', 'description'];
+
+/**
+ * Read `--seed-products <json>` from argv, or `BRAINERCE_SEED_PRODUCTS`.
+ *
+ * The environment variable is not a nicety: `npm run connect -- --seed-products '[...]'`
+ * loses its quoting in PowerShell, which is the default shell for a large share
+ * of the agents that run this, and a JSON array mangled into eight arguments
+ * fails in a way nobody can read. The variable is the escape hatch for those.
+ */
+function readSeedArg(argv) {
+  const flag = argv.indexOf('--seed-products');
+  if (flag !== -1) return argv[flag + 1] ?? '';
+  const inline = argv.find((a) => a.startsWith('--seed-products='));
+  if (inline) return inline.slice('--seed-products='.length);
+  return process.env.BRAINERCE_SEED_PRODUCTS ?? null;
+}
+
+/**
+ * Parse and check the seed payload locally, before anything is sent.
+ *
+ * The seeding grant is single use and dies with the approval window, so a
+ * payload the API would reject must never reach it: there is no second attempt
+ * inside the run, and a second attempt would cost the user a second approval.
+ * Every rule here is one the backend enforces anyway — this only moves the
+ * refusal to a point where it is still free.
+ *
+ * The backend runs `forbidNonWhitelisted`, so ONE stray key (`sku`, `type`,
+ * `images` are the ones agents reach for) rejects the entire request rather
+ * than the row that carried it. That is why unknown keys are an error here and
+ * not something quietly dropped.
+ *
+ * Returns `{ products }` or `{ error }`. Pure: no I/O, no process state.
+ */
+function parseSeedProducts(raw) {
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    return {
+      error:
+        '--seed-products was passed with no value. Give it a JSON array of products, quoted as one shell argument, or drop the flag entirely to connect without seeding.',
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return {
+      error: `--seed-products is not valid JSON (${error.message}). Pass the array as a single quoted argument, or put it in BRAINERCE_SEED_PRODUCTS if your shell keeps breaking the quoting.`,
+    };
+  }
+
+  // A bare array is the documented shape. An object with a `products` key is
+  // the body the seed route itself takes, and an agent copying from the route
+  // reference will send that, so accept it rather than refusing a payload that
+  // is right in every way that matters.
+  const list = Array.isArray(parsed)
+    ? parsed
+    : parsed && typeof parsed === 'object' && Array.isArray(parsed.products)
+      ? parsed.products
+      : null;
+
+  if (!list) {
+    return {
+      error:
+        '--seed-products must be a JSON array of products, or an object with a "products" array. A single product object on its own is not accepted; wrap it in an array.',
+    };
+  }
+  if (list.length < SEED_MIN_PRODUCTS) {
+    return {
+      error:
+        '--seed-products was an empty list. Seeding needs at least one product; if the user has not described what they sell, leave the flag off and build against the empty catalog.',
+    };
+  }
+  if (list.length > SEED_MAX_PRODUCTS) {
+    return {
+      error: `--seed-products carries ${list.length} products and the limit is ${SEED_MAX_PRODUCTS}. This is a starter catalog, not an import: pick the ${SEED_MAX_PRODUCTS} that best show the store, and point the merchant at the dashboard or Apps > Browse > Migration Tool for the rest.`,
+    };
+  }
+
+  const products = [];
+
+  for (let i = 0; i < list.length; i += 1) {
+    const entry = list[i];
+    const at = `--seed-products product ${i + 1}`;
+
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      return {
+        error: `${at} is not an object. Each entry looks like {"name":"...","basePrice":0}.`,
+      };
+    }
+
+    const unknown = Object.keys(entry).filter((k) => !SEED_FIELDS.includes(k));
+    if (unknown.length > 0) {
+      return {
+        error: `${at} carries ${unknown.map((k) => `"${k}"`).join(', ')}, which the seed route does not accept and will not ignore — one unknown key rejects the whole request. Only ${SEED_FIELDS.join(', ')} are allowed: no sku, no type, no options or variants, no categories, no images. Every seeded product lands as a simple, active product.`,
+      };
+    }
+
+    if (typeof entry.name !== 'string' || entry.name.trim() === '') {
+      return { error: `${at} has no usable "name". It must be a non-empty string.` };
+    }
+    if (entry.name.length > SEED_MAX_NAME) {
+      return {
+        error: `${at} ("${entry.name.slice(0, 40)}...") has a name of ${entry.name.length} characters and the limit is ${SEED_MAX_NAME}.`,
+      };
+    }
+
+    if (!('basePrice' in entry)) {
+      return {
+        error: `${at} ("${entry.name}") has no "basePrice". Every seeded product needs one, as a number: {"name":"${entry.name}","basePrice":0} is the minimum shape.`,
+      };
+    }
+    if (typeof entry.basePrice === 'string') {
+      // The failure that actually happens: a price quoted as a string. The API
+      // validates with @IsNumber(), which does not coerce, so "149" is refused.
+      return {
+        error: `${at} ("${entry.name}") has a "basePrice" quoted as text. Send ${entry.basePrice.trim() === '' ? '149' : entry.basePrice} without the quotes — the API does not coerce a quoted price, it rejects it.`,
+      };
+    }
+    if (typeof entry.basePrice !== 'number' || !Number.isFinite(entry.basePrice)) {
+      return {
+        error: `${at} ("${entry.name}") has a "basePrice" that is not a number. It must be a plain finite number, not null, not a string and not an expression.`,
+      };
+    }
+    if (entry.basePrice < 0) {
+      return { error: `${at} ("${entry.name}") has a negative "basePrice".` };
+    }
+
+    if ('description' in entry) {
+      if (typeof entry.description !== 'string') {
+        return {
+          error: `${at} ("${entry.name}") has a "description" that is not a string. Omit the key entirely rather than sending null.`,
+        };
+      }
+      if (entry.description.length > SEED_MAX_DESCRIPTION) {
+        return {
+          error: `${at} ("${entry.name}") has a description of ${entry.description.length} characters and the limit is ${SEED_MAX_DESCRIPTION}.`,
+        };
+      }
+    }
+
+    const product = { name: entry.name, basePrice: entry.basePrice };
+    if ('description' in entry) product.description = entry.description;
+    products.push(product);
+  }
+
+  return { products };
+}
+
+/** Only ever hand the OS a URL on the host we asked. It arrives in a network
+ *  response, so it is untrusted input on the way to a process launch. */
+function openable(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return false;
+    const base = new URL(API_BASE).hostname.replace(/^api(-staging)?\./, '');
+    return url.hostname === base || url.hostname.endsWith(`.${base}`);
+  } catch {
+    return false;
+  }
+}
+
+function openBrowser(url) {
+  const [cmd, args] =
+    process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : process.platform === 'darwin'
+        ? ['open', [url]]
+        : ['xdg-open', [url]];
+  try {
+    // No shell, argument array: the URL cannot become a command.
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Rewrite in place so hand-added variables survive. A blind overwrite here
+ *  would silently drop a payment key someone pasted in an hour earlier. */
+function writeEnv(connectionId) {
+  let body = existsSync(ENV_PATH) ? readFileSync(ENV_PATH, 'utf8') : '';
+  for (const key of KEYS) {
+    const line = `${key}=${connectionId}`;
+    const pattern = new RegExp(`^${key}=.*$`, 'm');
+    body = pattern.test(body) ? body.replace(pattern, line) : `${body.trimEnd()}\n${line}\n`;
+  }
+  writeFileSync(ENV_PATH, body.startsWith('\n') ? body.slice(1) : body);
+}
+
+async function readError(res) {
+  try {
+    const body = await res.json();
+    const message = body?.message;
+    return Array.isArray(message) ? message.join('; ') : (message ?? `HTTP ${res.status}`);
+  } catch {
+    return `HTTP ${res.status}`;
+  }
+}
+
+/**
+ * Spend the seeding grant.
+ *
+ * ⛔ `deviceCode` is a 256-bit bearer credential and it stops here. It is the
+ * poll credential as well as the seed credential, so anything that put it on
+ * stdout or in a log would hand a reader inside the ten-minute window the
+ * ability to seed this store. It is never printed and never interpolated into
+ * an error string.
+ *
+ * Called once, with no retry. The route allows 5 requests a minute and the
+ * grant is single use, so a retry after an ambiguous failure would report "that
+ * window has closed" over a write that may well have landed.
+ */
+async function runSeed(deviceCode, products) {
+  let res;
+  try {
+    res = await fetch(`${API_BASE}/api/device-auth/seed`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ deviceCode, products }),
+    });
+  } catch (error) {
+    console.error('');
+    console.error(`  Could not reach the seeding endpoint (${error.message}).`);
+    console.error(
+      '  The request may or may not have landed, so do not claim either way: check the catalog'
+    );
+    console.error(
+      '  in the dashboard and add what is missing there. Do not run connect again to retry.'
+    );
+    return;
+  }
+
+  if (!res.ok) {
+    const message = await readError(res);
+    // A 400 from the route's own guard means the grant is gone. A 400 from the
+    // validation pipe means the controller never ran and the grant is intact —
+    // different facts, and telling the user the window closed when it has not
+    // is its own kind of wrong.
+    const windowClosed = message.startsWith('That seeding window has closed');
+    console.error('');
+    if (windowClosed) {
+      console.error('  The seeding window is closed — the grant was already spent, or more than');
+      console.error('  ten minutes passed since the approval. The connection itself is fine.');
+      console.error('  Add products in the dashboard; do not run connect again just to seed.');
+    } else {
+      console.error(`  The seed request was refused before the grant was touched: ${message}`);
+      console.error('  The store is connected and still empty. Report this message as written and');
+      console.error('  add the products in the dashboard rather than retrying.');
+    }
+    return;
+  }
+
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    console.error('');
+    console.error('  The seed endpoint answered with something that is not JSON. Products may');
+    console.error('  have been created. Check the catalog in the dashboard rather than assuming');
+    console.error('  either outcome.');
+    return;
+  }
+
+  const created = Array.isArray(body.created) ? body.created : [];
+  const failed = Array.isArray(body.failed) ? body.failed : [];
+
+  // Both halves, always. A per-product failure does not abort the rest, so a
+  // partial write is a normal outcome — and reporting one as a clean win is how
+  // a merchant finds three of five products missing a week later.
+  console.log('');
+  if (created.length > 0) {
+    console.log(`  Seeded ${created.length} product(s): ${created.map((p) => p.name).join(', ')}`);
+  }
+  for (const f of failed) {
+    console.log(`  Not created: ${f.name} — ${f.reason}`);
+  }
+  if (failed.length > 0) {
+    console.log('');
+    console.log(
+      `  ${created.length} of ${products.length} product(s) went in; ${failed.length} refused.`
+    );
+    console.log(
+      '  Report BOTH halves by name. The window is now spent, so the refused ones have to be'
+    );
+    console.log('  added in the dashboard.');
+  } else if (created.length > 0) {
+    console.log('  Anything more comes from the dashboard, or Apps > Browse > Migration Tool.');
+  }
+}
+
+async function main() {
+  const seedRaw = readSeedArg(process.argv.slice(2));
+  let seedProducts = null;
+  if (seedRaw !== null) {
+    const parsed = parseSeedProducts(seedRaw);
+    if (parsed.error) {
+      // Refuse before the approval, not after: a payload rejected on the other
+      // side of a click has already cost the user the click.
+      console.error(parsed.error);
+      process.exit(1);
+    }
+    seedProducts = parsed.products;
+  }
+
+  if (process.env.BRAINERCE_CONNECTION_ID) {
+    // Already known (CI, or a channel someone created by hand). Nothing to approve.
+    writeEnv(process.env.BRAINERCE_CONNECTION_ID.trim());
+    console.log('Wrote BRAINERCE_CONNECTION_ID from the environment into .env.local.');
+    if (seedProducts) {
+      // ⛔ Seeding is authenticated by the device code from an approval. There is
+      // no approval on this path, so there is nothing to seed with — say so
+      // rather than connecting and silently dropping the catalog.
+      console.error('');
+      console.error('  Seeding needs a browser approval and this run already had a connection id,');
+      console.error('  so no products were created. Add them in the dashboard, or in an agent');
+      console.error('  session use the Brainerce MCP server to create products directly.');
+    }
+    return;
+  }
+
+  let start;
+  try {
+    const res = await fetch(`${API_BASE}/api/device-auth/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ clientName: process.env.BRAINERCE_CLIENT_NAME || 'this storefront' }),
+    });
+    if (!res.ok) {
+      console.error(`Could not start the approval (HTTP ${res.status}).`);
+      console.error('Create a sales channel in the dashboard, then set the id in .env.local.');
+      process.exit(1);
+    }
+    start = await res.json();
+  } catch (error) {
+    console.error(`Could not reach Brainerce: ${error?.message ?? error}`);
+    process.exit(1);
+  }
+
+  const opened =
+    openable(start.verificationUriComplete) && openBrowser(start.verificationUriComplete);
+  console.log('');
+  console.log(
+    opened ? 'Opened your browser to approve this connection.' : 'Open this link to approve:'
+  );
+  console.log(`  ${start.verificationUriComplete}`);
+  // The code is the only thing a person can actually check: it proves the
+  // request came from this run and not from someone else's.
+  console.log(`  The page should show the code ${start.userCode}. Check that it matches.`);
+  console.log('');
+  console.log('Waiting for approval. A store and a sales channel are created if you have none.');
+
+  const deadline = Date.now() + start.expiresIn * 1000;
+  let interval = (start.interval || 5) * 1000;
+
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, interval));
+    let result;
+    try {
+      const res = await fetch(`${API_BASE}/api/device-auth/poll`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ deviceCode: start.deviceCode }),
+      });
+      result = await res.json();
+    } catch {
+      continue; // A blip mid-poll is not fatal; the deadline is the real bound.
+    }
+    if (result.status === 'approved' && result.connectionId) {
+      // Write the id BEFORE seeding. Seeding is the part that can fail, and a
+      // failed catalog must never cost the connection that already succeeded.
+      writeEnv(result.connectionId);
+      console.log('');
+      console.log('Connected. The sales channel id is in .env.local.');
+      if (seedProducts) await runSeed(start.deviceCode, seedProducts);
+      console.log('');
+      console.log('Start the storefront with: npm run dev');
+      return;
+    }
+    if (result.status === 'denied') {
+      console.error('The connection request was declined. Nothing was created.');
+      process.exit(1);
+    }
+    if (result.status === 'expired') {
+      console.error('The code expired before it was approved. Run this again.');
+      process.exit(1);
+    }
+    // Polled inside the interval: back off rather than hammering.
+    if (result.status === 'slow_down') interval += 1000;
+  }
+
+  console.error('Timed out waiting for approval. Run this again for a fresh code.');
+  process.exit(1);
+}
+
+main();

package/templates/nextjs/base/src/app/checkout/page.tsx

@@ -31,6 +31,7 @@ import { GiftCardInput } from '@/ui/cart/gift-card-input';
 import { ReservationCountdown } from '@/ui/cart/reservation-countdown';
 import { LoadingSpinner } from '@/ui/shared/loading-spinner';
 import { useTranslations } from '@/core/lib/translations';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { cn } from '@/core/lib/utils';
 import { isValidCheckoutId } from '@/core/lib/safe-redirect';
 import { trackBeginCheckout } from '@/core/lib/tracking';
@@ -52,6 +53,7 @@ function CheckoutContent() {
   const t = useTranslations('checkout');
   const tc = useTranslations('common');
   const tr = useTranslations('reservation');
+  const tp = useTranslations('productDetail');
 
   const [step, setStep] = useState<CheckoutStep>('address');
   const [checkout, setCheckout] = useState<Checkout | null>(null);
@@ -77,6 +79,7 @@ function CheckoutContent() {
   const [orderBumps, setOrderBumps] = useState<CheckoutBumpsResponse | null>(null);
   const [addedBumpIds, setAddedBumpIds] = useState<Set<string>>(new Set());
   const [bumpLoading, setBumpLoading] = useState<string | null>(null);
+  const [bumpError, setBumpError] = useState<AddToCartError | null>(null);
   const [customFields, setCustomFields] = useState<CheckoutCustomFieldDefinition[]>([]);
   const [customFieldValues, setCustomFieldValues] = useState<Record<string, unknown>>({});
   const [customFieldsLoading, setCustomFieldsLoading] = useState(false);
@@ -354,6 +357,7 @@ function CheckoutContent() {
   // Handle bump toggle
   async function handleBumpToggle(bumpId: string, add: boolean, variantId?: string) {
     if (!cart?.id || bumpLoading) return;
+    setBumpError(null);
     try {
       setBumpLoading(bumpId);
       const client = getClient();
@@ -370,6 +374,10 @@ function CheckoutContent() {
       }
       await refreshCart();
     } catch (err) {
+      // A bump is an extra cart line, so it can be refused by the 50-line cap
+      // like any other add. Logging alone left the checkbox springing back with
+      // no explanation, at the least forgiving point in the flow.
+      setBumpError(toAddToCartError(err));
       console.error('Failed to toggle order bump:', err);
     } finally {
       setBumpLoading(null);
@@ -1044,6 +1052,16 @@ function CheckoutContent() {
                     loading={bumpLoading === bump.id}
                   />
                 ))}
+
+                {/*
+                  Why the bump was refused. Without it the checkbox just springs
+                  back and the shopper is left guessing at checkout.
+                */}
+                {bumpError && (
+                  <p className="text-destructive text-xs" role="alert">
+                    {bumpError === 'CART_FULL' ? tp('cartFull') : tp('addToCartFailed')}
+                  </p>
+                )}
               </div>
             )}