create-brainerce-store 1.71.0 → 1.72.0

package/README.md

@@ -44,19 +44,40 @@ Full details: [TEMPLATE-ARCHITECTURE.md](./TEMPLATE-ARCHITECTURE.md).
 
 ## Flags
 
-| Flag | Description | Default |
-| --- | --- | --- |
-| `--connection-id <id>` | Brainerce vibe-coded connection ID (`vc_*`) | prompted |
-| `--canvas` | Bare unstyled `src/ui/` skeletons for AI-driven design | off |
-| `--language <lang>` | Store language (`en`, `he`) | fetched from store |
-| `--pkg-manager <pm>` | `npm`, `pnpm`, `yarn`, `bun` | auto-detected |
-| `--framework <fw>` | `nextjs` (Vite/Remix coming) | `nextjs` |
-| `--api-url <url>` | Brainerce API base URL (or `BRAINERCE_API_URL` env) | auto-discovered |
-| `--no-git` | Skip git initialization | git on |
-| `--no-install` | Skip dependency installation | install on |
+| Flag                   | Description                                            | Default            |
+| ---------------------- | ------------------------------------------------------ | ------------------ |
+| `--connection-id <id>` | Brainerce vibe-coded connection ID (`vc_*`)            | prompted           |
+| `--canvas`             | Bare unstyled `src/ui/` skeletons for AI-driven design | off                |
+| `--language <lang>`    | Store language (`en`, `he`)                            | fetched from store |
+| `--pkg-manager <pm>`   | `npm`, `pnpm`, `yarn`, `bun`                           | auto-detected      |
+| `--framework <fw>`     | `nextjs` (Vite/Remix coming)                           | `nextjs`           |
+| `--api-url <url>`      | Brainerce API base URL (or `BRAINERCE_API_URL` env)    | auto-discovered    |
+| `--no-git`             | Skip git initialization                                | git on             |
+| `--no-install`         | Skip dependency installation                           | install on         |
 
 Pass `.` as the project name to scaffold into the current directory.
 
+## Reading the connection
+
+Before scaffolding, the CLI reads the channel from `/api/vc/<id>/info` so the
+generated project gets the real store name, currency and language rather than
+guesses. It walks production first, then staging, and stops at the first
+environment that answers. When it has to fall back, it says so and names the
+URL the project will be wired to.
+
+That endpoint checks the request's `Origin` against the channel's **Domain**
+and **Allowed Origins**, and the match counts the **port**. A Test channel with
+an empty Domain box accepts anything; one with `localhost:3000` recorded will
+refuse a bare `http://localhost`. The CLI therefore presents
+`http://localhost:3000` first and plain `http://localhost` second, and reports
+what every environment said rather than only the last one. A `403` from
+production must never surface as "not found on staging".
+
+A channel it cannot read is a hard stop, not a warning. Build-time
+`NEXT_PUBLIC_*` values are inlined into the client bundle and cannot be
+corrected at deploy time, so guessing `USD` / `en` here would ship a storefront
+quoting the wrong currency.
+
 ## Requirements
 
 Node `^20.19.0 || ^22.13.0 || >=24.0.0`.

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.71.0",
+      version: "1.72.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"
@@ -226,7 +226,16 @@ var BRAINERCE_RUNTIME_DEPS = Object.freeze({
   // getMyProductReview() to decide whether to render a picker at all, and the
   // reviews list renders `review.images`. None of those exist on an older SDK,
   // so the scaffold fails type-check outright.
-  brainerce: "^1.63.0",
+  // 2.0 corrects OrderStatus to the twelve canonical UPPERCASE values. The API
+  // has always returned them that way; the 1.x union declared six lowercase
+  // ones, so the scaffolded order timeline and order history looked their
+  // status maps up with a value that could never match and rendered every
+  // order as "Pending". Both components are now keyed on the real twelve, as
+  // `Record<OrderStatus, ...>`, so a 1.x SDK fails type-check on excess and
+  // missing keys. 2.0 also stops forgotPassword sending `resetUrl`, which the
+  // API rejects with 400 under forbidNonWhitelisted, so a scaffold on 1.x has
+  // a broken password reset in the browser.
+  brainerce: "^2.0.0",
   "isomorphic-dompurify": "^3.8.0"
 });
 
@@ -300,16 +309,18 @@ function detectInvokingPackageManager() {
 // src/cli.ts
 async function runInteractive(defaults) {
   const questions = [];
-  questions.push({
-    type: "text",
-    name: "projectName",
-    message: "Project name:",
-    initial: defaults.projectName || "",
-    validate: (value) => {
-      const error = validateProjectName(value);
-      return error || true;
-    }
-  });
+  if (!defaults.projectName) {
+    questions.push({
+      type: "text",
+      name: "projectName",
+      message: "Project name:",
+      initial: defaults.projectNameSuggestion || "",
+      validate: (value) => {
+        const error = validateProjectName(value);
+        return error || true;
+      }
+    });
+  }
   if (!defaults.connectionId) {
     questions.push({
       type: "text",
@@ -334,37 +345,42 @@ async function runInteractive(defaults) {
       initial: 0
     });
   }
-  questions.push({
-    type: "select",
-    name: "pkgManager",
-    message: "Package manager:",
-    choices: [
-      {
-        title: `pnpm${detectInvokingPackageManager() === "pnpm" ? " (detected)" : ""}`,
-        value: "pnpm"
-      },
-      {
-        title: `npm${detectInvokingPackageManager() === "npm" ? " (detected)" : ""}`,
-        value: "npm"
-      },
-      {
-        title: `yarn${detectInvokingPackageManager() === "yarn" ? " (detected)" : ""}`,
-        value: "yarn"
-      },
-      {
-        title: `bun${detectInvokingPackageManager() === "bun" ? " (detected)" : ""}`,
-        value: "bun"
-      }
-    ],
-    initial: ["pnpm", "npm", "yarn", "bun"].indexOf(detectInvokingPackageManager())
-  });
+  if (!defaults.pkgManager) {
+    questions.push({
+      type: "select",
+      name: "pkgManager",
+      message: "Package manager:",
+      choices: [
+        {
+          title: `pnpm${detectInvokingPackageManager() === "pnpm" ? " (detected)" : ""}`,
+          value: "pnpm"
+        },
+        {
+          title: `npm${detectInvokingPackageManager() === "npm" ? " (detected)" : ""}`,
+          value: "npm"
+        },
+        {
+          title: `yarn${detectInvokingPackageManager() === "yarn" ? " (detected)" : ""}`,
+          value: "yarn"
+        },
+        {
+          title: `bun${detectInvokingPackageManager() === "bun" ? " (detected)" : ""}`,
+          value: "bun"
+        }
+      ],
+      initial: ["pnpm", "npm", "yarn", "bun"].indexOf(detectInvokingPackageManager())
+    });
+  }
   const response = await (0, import_prompts.default)(questions, {
     onCancel: () => {
       throw new Error("PROMPT_CANCELLED");
     }
   });
   return {
-    projectName: defaults.projectName || response.projectName,
+    // The typed answer wins. This read used to be the other way round, so a
+    // name typed at the prompt was silently replaced by the slug offered as
+    // its placeholder.
+    projectName: response.projectName || defaults.projectName || "",
     connectionId: defaults.connectionId || response.connectionId,
     language: response.language || defaults.language || "en",
     framework: defaults.framework || "nextjs",
@@ -625,13 +641,32 @@ var KNOWN_API_URLS = {
   production: "https://api.brainerce.com",
   staging: "https://api-staging.brainerce.com"
 };
-var ConnectionNotFoundError = class extends Error {
-  constructor(connectionId, baseUrl) {
-    super(`Connection "${connectionId}" not found at ${baseUrl}`);
-    this.code = "NOT_FOUND";
+var PROBE_ORIGINS = ["http://localhost:3000", "http://localhost"];
+var StoreInfoProbeError = class extends Error {
+  constructor(kind, baseUrl, message, originRetryable = false) {
+    super(message);
+    this.kind = kind;
+    this.baseUrl = baseUrl;
+    this.originRetryable = originRetryable;
+    this.name = "StoreInfoProbeError";
   }
 };
-async function fetchStoreInfo(connectionId, baseUrl = KNOWN_API_URLS.production) {
+function envLabel(baseUrl) {
+  if (baseUrl === KNOWN_API_URLS.production) return "production";
+  if (baseUrl === KNOWN_API_URLS.staging) return "staging";
+  return baseUrl;
+}
+async function readErrorMessage(res) {
+  try {
+    const body = await res.json();
+    if (typeof body.message === "string" && body.message.trim() !== "") {
+      return body.message.trim();
+    }
+  } catch {
+  }
+  return `HTTP ${res.status}`;
+}
+async function fetchStoreInfo(connectionId, baseUrl = KNOWN_API_URLS.production, origin = PROBE_ORIGINS[0]) {
   const url = `${baseUrl}/api/vc/${connectionId}/info`;
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 1e4);
@@ -639,35 +674,46 @@ async function fetchStoreInfo(connectionId, baseUrl = KNOWN_API_URLS.production)
   try {
     res = await fetch(url, {
       signal: controller.signal,
-      headers: { Origin: "http://localhost" }
+      headers: { Origin: origin }
     });
   } catch (err) {
     if (err.name === "AbortError") {
-      throw new Error(`Request to ${baseUrl} timed out`);
+      throw new StoreInfoProbeError("OTHER", baseUrl, "request timed out after 10s");
     }
-    throw new Error(`Failed to connect to ${baseUrl}: ${err.message}`);
+    throw new StoreInfoProbeError(
+      "OTHER",
+      baseUrl,
+      `could not connect (${err.message})`
+    );
   } finally {
     clearTimeout(timeout);
   }
   if (res.status === 404) {
-    throw new ConnectionNotFoundError(connectionId, baseUrl);
+    throw new StoreInfoProbeError("NOT_FOUND", baseUrl, "404 connection not found");
+  }
+  if (res.status === 403) {
+    const message = await readErrorMessage(res);
+    const originRetryable = message === "Origin not allowed for TEST channel";
+    throw new StoreInfoProbeError("ORIGIN_REFUSED", baseUrl, `403 ${message}`, originRetryable);
   }
   if (!res.ok) {
-    throw new Error(`${baseUrl} returned status ${res.status}`);
+    throw new StoreInfoProbeError("OTHER", baseUrl, `returned status ${res.status}`);
   }
   let json;
   try {
     json = await res.json();
   } catch {
-    throw new Error(`Invalid response from ${baseUrl}`);
+    throw new StoreInfoProbeError("OTHER", baseUrl, "invalid (non-JSON) response");
   }
   const storeName = json.storeName || json.name || "My Store";
   const displayName = json.channelName || storeName;
   const currency = json.currency;
   const language = json.language;
   if (!currency || !language) {
-    throw new Error(
-      `Malformed /info response from ${baseUrl} (missing ${!currency ? "currency" : "language"}).`
+    throw new StoreInfoProbeError(
+      "OTHER",
+      baseUrl,
+      `malformed /info response (missing ${!currency ? "currency" : "language"})`
     );
   }
   return {
@@ -678,32 +724,63 @@ async function fetchStoreInfo(connectionId, baseUrl = KNOWN_API_URLS.production)
     ...json.i18n ? { i18n: json.i18n } : {}
   };
 }
+function asProbeError(err, baseUrl) {
+  return err instanceof StoreInfoProbeError ? err : new StoreInfoProbeError("OTHER", baseUrl, err?.message || String(err));
+}
+async function probeStoreInfo(connectionId, baseUrl) {
+  let lastError;
+  for (const origin of PROBE_ORIGINS) {
+    try {
+      return await fetchStoreInfo(connectionId, baseUrl, origin);
+    } catch (err) {
+      const probeError = asProbeError(err, baseUrl);
+      lastError = probeError;
+      if (!probeError.originRetryable) throw probeError;
+    }
+  }
+  throw lastError ?? new StoreInfoProbeError("OTHER", baseUrl, "no origins to try");
+}
 async function resolveStoreInfo(connectionId, candidateUrls) {
   const urls = candidateUrls.filter((u, i) => u && candidateUrls.indexOf(u) === i);
   if (urls.length === 0) {
     throw new Error("No API URLs to try");
   }
-  let lastError;
-  let allNotFound = true;
+  const failures = [];
   for (let i = 0; i < urls.length; i++) {
     const baseUrl = urls[i];
     try {
-      const info = await fetchStoreInfo(connectionId, baseUrl);
+      const info = await probeStoreInfo(connectionId, baseUrl);
       return { info, apiBaseUrl: baseUrl, fellBack: i > 0 };
     } catch (err) {
-      lastError = err;
-      const isNotFound = err.code === "NOT_FOUND";
-      if (!isNotFound) {
-        allNotFound = false;
-      }
+      failures.push(asProbeError(err, baseUrl));
     }
   }
-  if (allNotFound) {
-    throw new Error(
-      `Connection "${connectionId}" not found in any known environment (${urls.join(", ")}). Check your dashboard.`
-    );
+  throw new Error(describeFailures(connectionId, failures));
+}
+function describeFailures(connectionId, failures) {
+  if (failures.every((f) => f.kind === "NOT_FOUND")) {
+    return `Connection "${connectionId}" was not found in any known environment (${failures.map((f) => envLabel(f.baseUrl)).join(", ")}). Check the connection ID in your dashboard.`;
   }
-  throw lastError || new Error("Failed to resolve store info");
+  const lines = failures.map((f) => {
+    const label = envLabel(f.baseUrl);
+    const where = label === f.baseUrl ? f.baseUrl : `${label} (${f.baseUrl})`;
+    return `    ${where}: ${f.message}`;
+  });
+  let report = `Connection "${connectionId}" could not be read:
+${lines.join("\n")}`;
+  const testRefusal = failures.find((f) => f.kind === "ORIGIN_REFUSED" && f.originRetryable);
+  if (testRefusal) {
+    return report + `
+
+  The channel exists on ${envLabel(testRefusal.baseUrl)} but refused this machine's origin. Its Domain / Allowed Origins cover neither ${PROBE_ORIGINS.join(" nor ")}. On a TEST channel you can clear the Domain field, which opens it to any origin, or add the origin your dev server runs on to Allowed Origins.`;
+  }
+  const liveRefusal = failures.find((f) => f.kind === "ORIGIN_REFUSED");
+  if (liveRefusal) {
+    report += `
+
+  ${envLabel(liveRefusal.baseUrl)} refused the request outright, which is what a LIVE (domain-locked) channel does: it answers its own registered domain and never localhost. Scaffold against a TEST channel instead.`;
+  }
+  return report;
 }
 
 // src/utils/logger.ts
@@ -787,6 +864,34 @@ async function checkForUpdate(name, current) {
     return null;
   }
 }
+async function resolveStoreInfoOrExit(connectionId, candidateApiUrls) {
+  const spinner = createSpinner("Fetching store info...");
+  spinner.start();
+  try {
+    const resolved = await resolveStoreInfo(connectionId, candidateApiUrls);
+    const info = resolved.info;
+    const i18nStatus = info.i18n?.enabled && info.i18n.supportedLocales.length > 1 ? ` | i18n: ${info.i18n.supportedLocales.join(", ")}` : "";
+    const channelLabel = info.name !== info.storeName ? `"${info.name}" (channel in "${info.storeName}")` : `"${info.name}"`;
+    spinner.succeed(
+      `Channel: ${channelLabel} | ${info.currency} | ${info.language}${i18nStatus} [${envLabel(resolved.apiBaseUrl)}]`
+    );
+    if (resolved.fellBack) {
+      logger.warn(
+        `Resolved on ${envLabel(resolved.apiBaseUrl)}, not production. This project will be wired to ${resolved.apiBaseUrl}.`
+      );
+    }
+    return { info, apiBaseUrl: resolved.apiBaseUrl };
+  } catch (err) {
+    spinner.fail("Could not fetch store info");
+    logger.error(
+      err instanceof Error ? err.message : "Could not reach the Brainerce API to read this connection."
+    );
+    logger.info(
+      "Re-run after verifying:\n  \u2022 the connection ID matches a real sales channel in your dashboard\n  \u2022 the machine running create-brainerce-store can reach the Brainerce API\n  \u2022 if you are offline / behind a firewall, scaffold from a machine that can reach the API"
+    );
+    process.exit(1);
+  }
+}
 var program = new import_commander.Command();
 program.name("create-brainerce-store").description("Scaffold a production-ready e-commerce storefront connected to Brainerce").version(pkg.version).argument("[project-name]", "Name for the project directory").option("--connection-id <id>", "Brainerce vibe-coded connection ID (vc_*)").option(
   "--api-url <url>",
@@ -863,33 +968,19 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
         logger.error(connError2);
         process.exit(1);
       }
-      const prefetchSpinner = createSpinner("Fetching store info...");
-      prefetchSpinner.start();
-      try {
-        const resolved = await resolveStoreInfo(connectionId, candidateApiUrls);
-        storeInfo = resolved.info;
-        resolvedApiUrl = resolved.apiBaseUrl;
-        const envLabel = resolved.apiBaseUrl === KNOWN_API_URLS.staging ? " [staging]" : resolved.apiBaseUrl === KNOWN_API_URLS.production ? "" : ` [${resolved.apiBaseUrl}]`;
-        const i18nStatus = storeInfo.i18n?.enabled && storeInfo.i18n.supportedLocales.length > 1 ? ` | i18n: ${storeInfo.i18n.supportedLocales.join(", ")}` : "";
-        const channelLabel = storeInfo.name !== storeInfo.storeName ? `"${storeInfo.name}" (channel in "${storeInfo.storeName}")` : `"${storeInfo.name}"`;
-        prefetchSpinner.succeed(
-          `Channel: ${channelLabel} | ${storeInfo.currency} | ${storeInfo.language}${i18nStatus}${envLabel}`
-        );
-      } catch (err) {
-        prefetchSpinner.fail("Could not fetch store info");
-        logger.warn(
-          err instanceof Error ? err.message : "Using defaults. Make sure the connection ID is correct and the Brainerce API is reachable."
-        );
-      }
+      const resolved = await resolveStoreInfoOrExit(connectionId, candidateApiUrls);
+      storeInfo = resolved.info;
+      resolvedApiUrl = resolved.apiBaseUrl;
     }
     const slugify = (s) => s.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().trim().replace(/[^a-z0-9._-]+/g, "-").replace(/^[.-]+|[.-]+$/g, "").slice(0, 50);
     const channelSlug = storeInfo ? slugify(storeInfo.name) : "";
     const storeSlug = storeInfo ? slugify(storeInfo.storeName) : "";
-    const projectNameDefault = projectName || channelSlug || storeSlug || void 0;
+    const projectNameSuggestion = channelSlug || storeSlug || void 0;
     const languageDefault = language || storeInfo?.language;
     if (!projectName || !connectionId || !language) {
       const answers = await runInteractive({
-        projectName: projectNameDefault,
+        projectName,
+        projectNameSuggestion,
         connectionId,
         language: languageDefault,
         framework,
@@ -915,28 +1006,9 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       process.exit(1);
     }
     if (!storeInfo) {
-      const spinner = createSpinner("Fetching store info...");
-      spinner.start();
-      try {
-        const resolved = await resolveStoreInfo(connectionId, candidateApiUrls);
-        storeInfo = resolved.info;
-        resolvedApiUrl = resolved.apiBaseUrl;
-        const envLabel = resolved.apiBaseUrl === KNOWN_API_URLS.staging ? " [staging]" : resolved.apiBaseUrl === KNOWN_API_URLS.production ? "" : ` [${resolved.apiBaseUrl}]`;
-        const i18nStatus = storeInfo.i18n?.enabled && storeInfo.i18n.supportedLocales.length > 1 ? ` | i18n: ${storeInfo.i18n.supportedLocales.join(", ")}` : "";
-        const channelLabel = storeInfo.name !== storeInfo.storeName ? `"${storeInfo.name}" (channel in "${storeInfo.storeName}")` : `"${storeInfo.name}"`;
-        spinner.succeed(
-          `Channel: ${channelLabel} | ${storeInfo.currency} | ${storeInfo.language}${i18nStatus}${envLabel}`
-        );
-      } catch (err) {
-        spinner.fail("Could not fetch store info");
-        logger.error(
-          err instanceof Error ? err.message : "Could not reach the Brainerce API to read this connection."
-        );
-        logger.info(
-          "Re-run after verifying:\n  \u2022 the connection ID matches a real sales channel in your dashboard\n  \u2022 the machine running create-brainerce-store can reach the Brainerce API\n  \u2022 if you are offline / behind a firewall, scaffold from a machine that can reach the API"
-        );
-        process.exit(1);
-      }
+      const resolved = await resolveStoreInfoOrExit(connectionId, candidateApiUrls);
+      storeInfo = resolved.info;
+      resolvedApiUrl = resolved.apiBaseUrl;
     }
     if (!pkgManager) {
       pkgManager = detectInvokingPackageManager();

package/messages/en.json

@@ -188,7 +188,8 @@
     "addBundleItem": "Add & Save",
     "addingBundle": "Adding...",
     "selectOptions": "Select options",
-    "outOfStock": "Out of stock"
+    "outOfStock": "Out of stock",
+    "unavailableItemsHint": "Remove the items marked out of stock or unavailable to continue to checkout."
   },
   "checkout": {
     "pageTitle": "Checkout",
@@ -419,12 +420,18 @@
     "memberSince": "Member since",
     "orderPrefix": "Order",
     "productFallback": "Product",
+    "statusDraft": "Draft",
     "statusPending": "Pending",
     "statusProcessing": "Processing",
+    "statusOnHold": "On hold",
+    "statusPaid": "Paid",
     "statusShipped": "Shipped",
     "statusDelivered": "Delivered",
+    "statusCompleted": "Completed",
+    "statusFulfilled": "Fulfilled",
     "statusCancelled": "Cancelled",
     "statusRefunded": "Refunded",
+    "statusPartiallyRefunded": "Partially refunded",
     "editProfile": "Edit Profile",
     "firstName": "First Name",
     "lastName": "Last Name",
@@ -501,6 +508,9 @@
   },
   "reservation": {
     "expired": "Reservation expired. Items may no longer be available.",
+    "expiredHint": "We refreshed your cart. Check it before you continue.",
+    "expiredCheckout": "Your reserved stock was released, so payment is on hold. Go back to your cart and review it.",
+    "backToCart": "Back to cart",
     "hurry": "Hurry!",
     "reservedFor": "Items reserved for"
   },

package/messages/he.json

@@ -188,7 +188,8 @@
     "addBundleItem": "הוסף וחסוך",
     "addingBundle": "מוסיף...",
     "selectOptions": "בחר אפשרויות",
-    "outOfStock": "אזל מהמלאי"
+    "outOfStock": "אזל מהמלאי",
+    "unavailableItemsHint": "הסירו את המוצרים שמסומנים כאזלו מהמלאי או כלא זמינים כדי להמשיך לתשלום."
   },
   "checkout": {
     "pageTitle": "תשלום",
@@ -419,12 +420,18 @@
     "memberSince": "חבר מאז",
     "orderPrefix": "הזמנה",
     "productFallback": "מוצר",
+    "statusDraft": "טיוטה",
     "statusPending": "ממתין",
     "statusProcessing": "בטיפול",
+    "statusOnHold": "מושהה",
+    "statusPaid": "שולם",
     "statusShipped": "נשלח",
     "statusDelivered": "נמסר",
+    "statusCompleted": "הושלם",
+    "statusFulfilled": "סופק",
     "statusCancelled": "בוטל",
     "statusRefunded": "הוחזר",
+    "statusPartiallyRefunded": "הוחזר חלקית",
     "editProfile": "עריכת פרופיל",
     "firstName": "שם פרטי",
     "lastName": "שם משפחה",
@@ -501,6 +508,9 @@
   },
   "reservation": {
     "expired": "השריון פג. ייתכן שהמוצרים כבר לא זמינים.",
+    "expiredHint": "רעננו עבורכם את העגלה. כדאי לבדוק אותה לפני שממשיכים.",
+    "expiredCheckout": "השריון על המלאי שוחרר, ולכן התשלום מושהה. חזרו לעגלה ובדקו אותה.",
+    "backToCart": "חזרה לעגלה",
     "hurry": "מהרו!",
     "reservedFor": "המוצרים שמורים למשך"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.71.0",
+  "version": "1.72.0",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "bin": {
     "create-brainerce-store": "dist/index.js"

package/templates/nextjs/base/TRANSLATIONS.md

@@ -157,22 +157,29 @@ return {
 
 ## Promotional surfaces: bundles, bumps, discount banners
 
-The same overlay applies to every promotional surface — you don't need locale-aware code:
+The same overlay applies to every promotional surface, so you don't need locale-aware code:
 
 ```tsx
-// Cart bundles (cross-sell) — locale-aware automatically:
+// Cart bundles (cross-sell), locale-aware automatically:
 const cart = await client.getCart(cartId);
 cart.bundles[0].name; // "ארוחת צהריים" (bundle's own label)
 cart.bundles[0].offeredProducts[0].name; // "פיצה גבינה" (each offered product)
 
-// Order bumps at checkout:
-const { bumps } = await client.getOrderBumps(checkoutId);
+// Order bumps at checkout. `getCheckoutBumps` takes a CHECKOUT id, not a cart id:
+const { bumps } = await client.getCheckoutBumps(checkoutId);
 bumps[0].title; // translated bump headline (or merchant override)
 bumps[0].bumpProduct.name; // translated product name
 
-// Discount-rule banners (rendered from rule.name + rule.displayConfig):
-const rules = await client.getActiveDiscountRules();
-rules[0].name; // translated rule name
+// Adding or removing a bump takes the CART id plus the bump config id
+// (bumps[i].id). Pass a variantId when bumps[i].requiresVariantSelection:
+await client.addOrderBump(cartId, bumps[0].id, selectedVariantId);
+await client.removeOrderBump(cartId, bumps[0].id);
+
+// Discount-rule banners. The API returns ready-to-render banner text, not the
+// rule object: DiscountBanner is { ruleId, text, type }, so there is no `name`
+// and no `displayConfig` to compose yourself.
+const banners = await client.getDiscountBanners();
+banners[0].text; // translated banner copy
 ```
 
 ## How merchants populate translations