create-brainerce-store 1.34.1 → 1.34.3

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.34.1",
+      version: "1.34.3",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"

package/package.json

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

package/templates/nextjs/base/.env.local.ejs

@@ -1,4 +1,7 @@
-# Brainerce Connection
+# Brainerce Sales Channel — preferred env var name.
+NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID=<%= connectionId %>
+# Legacy alias kept for backwards compatibility — both are accepted by the SDK.
+# @deprecated will be removed when SDK 2.0 ships.
 NEXT_PUBLIC_BRAINERCE_CONNECTION_ID=<%= connectionId %>
 
 # Store info (pre-fetched during setup to avoid flash on first load)

package/templates/nextjs/base/scripts/fetch-store-info.mjs

@@ -14,7 +14,7 @@ const envPath = join(process.cwd(), '.env.local');
 
 if (!existsSync(envPath)) {
   console.error(
-    '❌  .env.local not found. Create it first with NEXT_PUBLIC_BRAINERCE_CONNECTION_ID set.'
+    '❌  .env.local not found. Create it first with NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID set.'
   );
   process.exit(1);
 }
@@ -34,18 +34,24 @@ function setVar(content, key, value) {
   return content.trimEnd() + `\n${key}=${value}\n`;
 }
 
-const connectionId = getVar(envContent, 'NEXT_PUBLIC_BRAINERCE_CONNECTION_ID');
+// Read either env var name. The new one is preferred; the old one is a soft
+// alias kept for backwards compatibility — the SDK accepts both.
+const connectionId =
+  getVar(envContent, 'NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID') ||
+  getVar(envContent, 'NEXT_PUBLIC_BRAINERCE_CONNECTION_ID');
 const apiUrl = (getVar(envContent, 'BRAINERCE_API_URL') || 'https://api.brainerce.com').replace(
   /\/$/,
   ''
 );
 
 if (!connectionId) {
-  console.error('❌  NEXT_PUBLIC_BRAINERCE_CONNECTION_ID is not set in .env.local');
+  console.error(
+    '❌  NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID is not set in .env.local'
+  );
   process.exit(1);
 }
 
-console.log(`Fetching store info for connection: ${connectionId} ...`);
+console.log(`Fetching store info for sales channel: ${connectionId} ...`);
 
 let storeInfo;
 try {

package/templates/nextjs/base/src/app/api/auth/me/route.ts

@@ -6,7 +6,10 @@ const BACKEND_URL = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com
   ''
 );
 
-const CONNECTION_ID = process.env.NEXT_PUBLIC_BRAINERCE_CONNECTION_ID || '';
+const CONNECTION_ID =
+  process.env.NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID ||
+  process.env.NEXT_PUBLIC_BRAINERCE_CONNECTION_ID ||
+  '';
 
 const TOKEN_COOKIE = 'brainerce_customer_token';
 const LOGGED_IN_COOKIE = 'brainerce_logged_in';

package/templates/nextjs/base/src/app/api/auth/reset-password/route.ts

@@ -8,7 +8,10 @@ const BACKEND_URL = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com
   ''
 );
 
-const CONNECTION_ID = process.env.NEXT_PUBLIC_BRAINERCE_CONNECTION_ID || '';
+const CONNECTION_ID =
+  process.env.NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID ||
+  process.env.NEXT_PUBLIC_BRAINERCE_CONNECTION_ID ||
+  '';
 
 const RESET_TOKEN_COOKIE = 'brainerce_reset_token';
 

package/templates/nextjs/base/src/app/products/[slug]/product-client-section.tsx

@@ -8,6 +8,7 @@ import type {
   ProductImage,
   ProductMetafield,
   DownloadFile,
+  ModifierGroup,
 } from 'brainerce';
 import { getProductPriceInfo, getDescriptionContent } from 'brainerce';
 import { useCart } from '@/providers/store-provider';
@@ -22,6 +23,12 @@ import {
   validateCustomization,
   type CustomizationValues,
 } from '@/components/products/customization-fields';
+import {
+  ModifierGroupSelector,
+  buildInitialSelections,
+  toModifierSelections,
+  validateSelections,
+} from '@/components/products/modifier-group-selector';
 import { useTranslations } from '@/lib/translations';
 import { cn } from '@/lib/utils';
 import { sanitizeProductHtml } from '@/lib/sanitize-html';
@@ -138,6 +145,16 @@ export function ProductClientSection({ product: initialProduct }: ProductClientS
   });
   const [customizationErrors, setCustomizationErrors] = useState<Record<string, string>>({});
 
+  // Modifier groups (PRD §8.4) — only present on restaurant / build-your-own products.
+  const modifierGroups: ModifierGroup[] = useMemo(
+    () => (product as Product & { modifierGroups?: ModifierGroup[] }).modifierGroups ?? [],
+    [product]
+  );
+  const [modifierSelections, setModifierSelections] = useState<Record<string, string[]>>(() =>
+    buildInitialSelections(modifierGroups)
+  );
+  const [modifierError, setModifierError] = useState<string | null>(null);
+
   // Images list - switch main image when variant changes
   const images: ProductImage[] = useMemo(() => {
     return product?.images || [];
@@ -227,6 +244,24 @@ export function ProductClientSection({ product: initialProduct }: ProductClientS
     }
     setCustomizationErrors({});
 
+    // Client-side modifier validation mirrors the server's checks. The server
+    // is authoritative — `MODIFIER_VALIDATION_FAILED` envelope on add-to-cart
+    // failure is the source of truth — but pre-flighting catches the obvious
+    // issues without a round-trip.
+    if (modifierGroups.length > 0) {
+      const error = validateSelections(modifierGroups, modifierSelections);
+      if (error) {
+        setModifierError(error);
+        return;
+      }
+    }
+    setModifierError(null);
+
+    const selections =
+      modifierGroups.length > 0
+        ? toModifierSelections(modifierGroups, modifierSelections)
+        : undefined;
+
     try {
       setAddingToCart(true);
       const { getClient } = await import('@/lib/brainerce');
@@ -239,12 +274,20 @@ export function ProductClientSection({ product: initialProduct }: ProductClientS
           customizationFields.length > 0 && Object.keys(customizationValues).length > 0
             ? customizationValues
             : undefined,
+        ...(selections && selections.length > 0 ? { selections } : {}),
       });
       await refreshCart();
       setAddedMessage(true);
       setTimeout(() => setAddedMessage(false), 2000);
     } catch (err) {
-      console.error('Failed to add to cart:', err);
+      // Surface the structured `MODIFIER_VALIDATION_FAILED` envelope when present.
+      const e = err as { details?: { code?: string; errors?: Array<{ message: string }> } };
+      const validationErrors = e?.details?.errors;
+      if (e?.details?.code === 'MODIFIER_VALIDATION_FAILED' && validationErrors?.length) {
+        setModifierError(validationErrors.map((v) => v.message).join('; '));
+      } else {
+        console.error('Failed to add to cart:', err);
+      }
     } finally {
       setAddingToCart(false);
     }
@@ -439,6 +482,28 @@ export function ProductClientSection({ product: initialProduct }: ProductClientS
             />
           )}
 
+          {/* Modifier groups (toppings, sauce, bread type, …) */}
+          {modifierGroups.length > 0 && (
+            <div className="space-y-4">
+              {modifierGroups.map((group) => (
+                <ModifierGroupSelector
+                  key={group.attachmentId ?? group.id}
+                  group={group}
+                  value={modifierSelections[group.id] ?? []}
+                  onChange={(next) =>
+                    setModifierSelections((prev) => ({ ...prev, [group.id]: next }))
+                  }
+                  disabled={addingToCart}
+                />
+              ))}
+              {modifierError && (
+                <p className="text-destructive text-sm" role="alert">
+                  {modifierError}
+                </p>
+              )}
+            </div>
+          )}
+
           {/* Quantity + Add to Cart */}
           <div className="flex items-center gap-4">
             <div className="border-border flex items-center rounded border">

package/templates/nextjs/base/src/components/products/allergen-chips.tsx

@@ -0,0 +1,78 @@
+'use client';
+
+/**
+ * <AllergenChips> — informational allergen markers for storefront PDPs.
+ * Pure presentation; no interactivity. Pairs with `<ModifierGroupSelector>`
+ * but works standalone next to a product as well.
+ *
+ * Allergens are descriptive only: the system surfaces them but does not
+ * auto-block purchase. Customer-side allergen filtering is a deferred SDK
+ * feature (PRD §16).
+ *
+ * Icon resolution (PRD §15 Q4): when `allergen.iconUrl` is set, use it.
+ * Otherwise fall back to a built-in emoji keyed by `allergen.code` for the
+ * 8 common allergens listed in PRD §5.7. Stores that want branded icons
+ * upload via `iconUrl` per allergen; the rest get a sensible default
+ * without any setup.
+ */
+
+import type { Allergen } from 'brainerce';
+
+/**
+ * Default emoji per canonical allergen code. The schema's @@unique on
+ * `(accountId, storeId, code)` means a store may have at most one of each;
+ * any code not in this map renders without an icon (the chip still shows
+ * the localized name, so the customer is informed regardless).
+ */
+const DEFAULT_EMOJI_BY_CODE: Record<string, string> = {
+  gluten: '🌾',
+  dairy: '🥛',
+  nuts: '🥜',
+  eggs: '🥚',
+  soy: '🫘',
+  fish: '🐟',
+  shellfish: '🦐',
+  sesame: '🌱',
+};
+
+interface AllergenChipsProps {
+  allergens: Allergen[];
+  /**
+   * When the storefront has more allergen icons than fit nicely, condense
+   * to "Contains: X, Y, +N more" instead of rendering every chip.
+   */
+  maxVisible?: number;
+}
+
+export function AllergenChips({ allergens, maxVisible = 6 }: AllergenChipsProps) {
+  if (!allergens || allergens.length === 0) return null;
+
+  const visible = allergens.slice(0, maxVisible);
+  const overflow = Math.max(0, allergens.length - visible.length);
+
+  return (
+    <span className="allergen-chips" role="list" aria-label="Contains">
+      {visible.map((allergen) => {
+        const fallbackEmoji = DEFAULT_EMOJI_BY_CODE[allergen.code];
+        return (
+          <span key={allergen.id} className="allergen-chip" role="listitem" title={allergen.name}>
+            {allergen.iconUrl ? (
+              <img
+                src={allergen.iconUrl}
+                alt=""
+                aria-hidden="true"
+                className="allergen-chip__icon"
+              />
+            ) : fallbackEmoji ? (
+              <span aria-hidden="true" className="allergen-chip__emoji">
+                {fallbackEmoji}
+              </span>
+            ) : null}
+            <span className="allergen-chip__name">{allergen.name}</span>
+          </span>
+        );
+      })}
+      {overflow > 0 && <span className="allergen-chip allergen-chip--more">+{overflow} more</span>}
+    </span>
+  );
+}

package/templates/nextjs/base/src/components/products/modifier-group-selector.tsx

@@ -0,0 +1,242 @@
+'use client';
+
+/**
+ * <ModifierGroupSelector> — reference React component for storefront authors
+ * (PRD §8.4).
+ *
+ * Drop-in renderer for a single modifier group (toppings, sauce, bread type, …).
+ * Storefront authors are encouraged to copy this file and tailor the styling /
+ * markup to their site — the data contract is what matters, not the markup.
+ *
+ * Behavior pinned by the contract:
+ *   - SINGLE   → renders as <input type="radio">,    max picks = 1
+ *   - MULTIPLE → renders as <input type="checkbox">, picks bounded by min..max
+ *   - effectiveMax === 0 → group is hidden entirely (variant-disable convention)
+ *   - available === false → modifier is disabled with "Sold out" badge
+ *   - free counter shows "{used} of {freeQuantity} free" when freeQuantity > 0
+ *   - defaultModifierIds + isDefault drive first-render checked state
+ *   - client-side guards mirror min/max (UX); the SERVER is authoritative — wire
+ *     `MODIFIER_VALIDATION_FAILED` errors back to the user when add-to-cart fails
+ *
+ * The price-delta side: this component does NOT compute totals. The server
+ * runs the free-allocation policy and returns the line's `unitPrice` /
+ * `modifiers[]` / `modifiersTotal` snapshot — render those after add-to-cart.
+ */
+
+import type { Modifier, ModifierGroup, ModifierSelection } from 'brainerce';
+import { AllergenChips } from './allergen-chips';
+
+interface ModifierGroupSelectorProps {
+  /**
+   * Effective group as returned by `GET /products/:id` (overrides already
+   * applied — `min`, `max`, `freeQuantity`, etc. are the values the server
+   * will validate against for the active variant).
+   */
+  group: ModifierGroup;
+  /** Currently-selected modifier IDs in click-order. */
+  value: string[];
+  onChange: (next: string[]) => void;
+  /** Disable all controls (e.g., while add-to-cart is in flight). */
+  disabled?: boolean;
+}
+
+export function ModifierGroupSelector({
+  group,
+  value,
+  onChange,
+  disabled = false,
+}: ModifierGroupSelectorProps) {
+  // PRD §7.2.2: variant-disable convention — group with effectiveMax=0 is hidden.
+  if (group.max === 0) return null;
+
+  const isSingle = group.selectionType === 'SINGLE';
+  // Client-side bound — server is authoritative.
+  const effectiveMax = isSingle ? 1 : (group.max ?? Infinity);
+
+  const handleToggle = (modifierId: string, checked: boolean) => {
+    if (disabled) return;
+
+    if (isSingle) {
+      // Radio behavior: replace the selection.
+      onChange(checked ? [modifierId] : []);
+      return;
+    }
+
+    if (checked) {
+      if (value.length >= effectiveMax) return; // would exceed max — ignore the click
+      if (value.includes(modifierId)) return;
+      onChange([...value, modifierId]);
+    } else {
+      onChange(value.filter((id) => id !== modifierId));
+    }
+  };
+
+  const sortedModifiers = [...group.modifiers].sort((a, b) => a.position - b.position);
+
+  // Counter: how many of the picked items are within the "free" window.
+  const usedFreeSlots = Math.min(value.length, group.freeQuantity);
+  const showFreeCounter = group.freeQuantity > 0;
+
+  return (
+    <fieldset className="modifier-group">
+      <legend className="modifier-group__legend">
+        <span className="modifier-group__name">{group.name}</span>
+        {group.required && <span className="modifier-group__required"> *</span>}
+        <span className="modifier-group__rules">{ruleSummary(group)}</span>
+      </legend>
+
+      {group.description && <p className="modifier-group__description">{group.description}</p>}
+
+      {showFreeCounter && (
+        <p className="modifier-group__counter" aria-live="polite">
+          {usedFreeSlots} of {group.freeQuantity} free
+        </p>
+      )}
+
+      <ul className="modifier-group__options">
+        {sortedModifiers.map((modifier) => {
+          const isChecked = value.includes(modifier.id);
+          const isAtCap = !isSingle && !isChecked && value.length >= effectiveMax;
+          const isDisabled = disabled || !modifier.available || isAtCap;
+
+          return (
+            <li key={modifier.id} className="modifier-option">
+              <label className="modifier-option__label">
+                <input
+                  type={isSingle ? 'radio' : 'checkbox'}
+                  name={`modifier-group-${group.id}`}
+                  value={modifier.id}
+                  checked={isChecked}
+                  disabled={isDisabled}
+                  onChange={(e) => handleToggle(modifier.id, e.target.checked)}
+                  className="modifier-option__input"
+                />
+                <span className="modifier-option__name">{modifier.name}</span>
+                <ModifierPriceLabel modifier={modifier} />
+                {!modifier.available && (
+                  <span
+                    className="modifier-option__badge modifier-option__badge--soldout"
+                    aria-label="Sold out"
+                  >
+                    Sold out
+                  </span>
+                )}
+                {modifier.allergens && modifier.allergens.length > 0 && (
+                  <AllergenChips allergens={modifier.allergens} />
+                )}
+              </label>
+              {modifier.description && (
+                <p className="modifier-option__description">{modifier.description}</p>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+    </fieldset>
+  );
+}
+
+/**
+ * Renders the modifier's price contribution next to its name.
+ *
+ * Negative deltas display with a leading minus sign (downsell modifiers per
+ * PRD §6.3.4); zero-delta modifiers render nothing — silence is the right
+ * affordance for a free option.
+ */
+function ModifierPriceLabel({ modifier }: { modifier: Modifier }) {
+  const delta = parseFloat(modifier.priceDelta);
+  if (Number.isNaN(delta) || delta === 0) return null;
+  const sign = delta > 0 ? '+' : '';
+  return (
+    <span className="modifier-option__price">
+      {sign}
+      {modifier.priceDelta}
+    </span>
+  );
+}
+
+function ruleSummary(group: ModifierGroup): string {
+  const parts: string[] = [];
+  if (group.selectionType === 'SINGLE') {
+    parts.push('Pick one');
+  } else if (group.max != null) {
+    if (group.min === 0) parts.push(`Up to ${group.max}`);
+    else if (group.min === group.max) parts.push(`Pick exactly ${group.min}`);
+    else parts.push(`${group.min}–${group.max}`);
+  } else if (group.min > 0) {
+    parts.push(`At least ${group.min}`);
+  }
+  return parts.length ? `(${parts.join(', ')})` : '';
+}
+
+/**
+ * Lightweight client-side validation that mirrors the server's checks. Use
+ * this to gate the add-to-cart button — but always treat the server's 400
+ * (`MODIFIER_VALIDATION_FAILED`) as the authoritative answer.
+ */
+export function validateSelections(
+  groups: ModifierGroup[],
+  selections: Record<string, string[]>
+): string | null {
+  for (const group of groups) {
+    if (group.max === 0) continue; // disabled-for-variant — skip
+    const picks = selections[group.id] ?? [];
+    if (group.required && picks.length === 0) {
+      return `${group.name} is required`;
+    }
+    if (picks.length < group.min) {
+      return `Pick at least ${group.min} from ${group.name}`;
+    }
+    if (group.max != null && picks.length > group.max) {
+      return `Pick at most ${group.max} from ${group.name}`;
+    }
+    if (group.selectionType === 'SINGLE' && picks.length > 1) {
+      return `Only one option allowed in ${group.name}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Adapter: convert the local Record<groupId, modifierIds> shape used by this
+ * component into the wire-format `ModifierSelection[]` array the SDK expects
+ * on `addToCart` / `updateCartItem`.
+ */
+export function toModifierSelections(
+  groups: ModifierGroup[],
+  selections: Record<string, string[]>
+): ModifierSelection[] {
+  const out: ModifierSelection[] = [];
+  for (const group of groups) {
+    if (group.max === 0) continue;
+    const picks = selections[group.id] ?? [];
+    if (picks.length === 0) continue;
+    out.push({ modifierGroupId: group.id, modifierIds: picks });
+  }
+  return out;
+}
+
+/**
+ * Build the initial selection map from the group's defaults — call once on
+ * first render for each group. Honors `defaultModifierIds` first (per-attach
+ * defaults), falling back to per-modifier `isDefault` flags. Sold-out
+ * modifiers are filtered out so the user doesn't start with an invalid pick.
+ */
+export function buildInitialSelections(groups: ModifierGroup[]): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const group of groups) {
+    if (group.max === 0) continue;
+    const fromDefaults = group.defaultModifierIds ?? [];
+    const fromIsDefault = group.modifiers
+      .filter((m) => m.isDefault && m.available)
+      .map((m) => m.id);
+    const merged =
+      fromDefaults.length > 0
+        ? fromDefaults.filter((id) => group.modifiers.some((m) => m.id === id && m.available))
+        : fromIsDefault;
+    // Cap by max for SINGLE groups — defaults can't violate selection rules.
+    const capped = group.selectionType === 'SINGLE' ? merged.slice(0, 1) : merged;
+    if (capped.length > 0) out[group.id] = capped;
+  }
+  return out;
+}

package/templates/nextjs/base/src/lib/auth.ts

@@ -4,7 +4,12 @@
  * The token is managed server-side via httpOnly cookies — never exposed to JS.
  */
 
-const CONNECTION_ID = process.env.NEXT_PUBLIC_BRAINERCE_CONNECTION_ID || '';
+// Read either env var name. The new one is preferred; the old one is a soft
+// alias kept for backwards compatibility — both are accepted by the SDK.
+const CONNECTION_ID =
+  process.env.NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID ||
+  process.env.NEXT_PUBLIC_BRAINERCE_CONNECTION_ID ||
+  '';
 
 const CSRF_HEADERS: Record<string, string> = {
   'Content-Type': 'application/json',

package/templates/nextjs/base/src/lib/brainerce.ts.ejs

@@ -1,6 +1,11 @@
 import { BrainerceClient } from 'brainerce';
 
-const CONNECTION_ID = process.env.NEXT_PUBLIC_BRAINERCE_CONNECTION_ID || '<%= connectionId %>';
+// Read either env var name. The new one is preferred; the old one is a soft
+// alias kept for backwards compatibility — both are accepted by the SDK.
+const SALES_CHANNEL_ID =
+  process.env.NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID ||
+  process.env.NEXT_PUBLIC_BRAINERCE_CONNECTION_ID ||
+  '<%= connectionId %>';
 
 // Singleton SDK client — routes through same-origin BFF proxy for httpOnly cookie auth
 let clientInstance: BrainerceClient | null = null;
@@ -8,7 +13,7 @@ let clientInstance: BrainerceClient | null = null;
 export function getClient(): BrainerceClient {
   if (!clientInstance) {
     clientInstance = new BrainerceClient({
-      connectionId: CONNECTION_ID,
+      salesChannelId: SALES_CHANNEL_ID,
       baseUrl: '/api/store', // same-origin proxy handles auth via httpOnly cookie
       proxyMode: true, // skip client-side token checks; proxy adds Authorization header
     });
@@ -52,7 +57,7 @@ export function initClient(): BrainerceClient {
 export function getServerClient(locale?: string): BrainerceClient {
   const apiUrl = process.env.BRAINERCE_API_URL || 'https://api.brainerce.com';
   const client = new BrainerceClient({
-    connectionId: CONNECTION_ID,
+    salesChannelId: SALES_CHANNEL_ID,
     baseUrl: apiUrl,
     origin: process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000',
   });