create-brainerce-store 1.88.1 → 1.89.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.88.1",
+      version: "1.89.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       homepage: "https://brainerce.com",
       repository: {
@@ -57,8 +57,9 @@ var require_package = __commonJS({
         clean: "rimraf dist",
         release: "pnpm build && node ../../scripts/publish-workspace-package.js .",
         "check:template-parity": "node scripts/check-template-parity.js",
+        "check:agent-docs": "node scripts/check-agent-docs.js",
         "check:sdk-published": "node scripts/check-sdk-published.js",
-        prepublishOnly: "node scripts/check-template-parity.js && node scripts/check-sdk-published.js && node ../../scripts/check-publishable.js ./package.json"
+        prepublishOnly: "node scripts/check-template-parity.js && node scripts/check-agent-docs.js && node scripts/check-sdk-published.js && node ../../scripts/check-publishable.js ./package.json"
       },
       dependencies: {
         chalk: "^4.1.2",

package/messages/en.json

@@ -182,6 +182,25 @@
   "faq": {
     "title": "Frequently asked questions"
   },
+  "seo": {
+    "home": "Home",
+    "products": "Products",
+    "blog": "Blog",
+    "categoryNotFound": "Category not found",
+    "productNotFound": "Product not found",
+    "productsDescription": "Browse our full collection of products.",
+    "blogDescription": "Articles and stories from our store",
+    "pagination": "Catalog pages",
+    "previousPage": "Previous page",
+    "nextPage": "Next page"
+  },
+  "blog": {
+    "empty": "No posts yet.",
+    "readMore": "Read more",
+    "previous": "Previous",
+    "next": "Next",
+    "backToBlog": "Back to blog"
+  },
   "cart": {
     "pageTitle": "Shopping Cart",
     "title": "Shopping Cart",
@@ -258,6 +277,8 @@
     "paymentNotConfiguredDesc": "Payment has not been set up for this store yet. Please contact the store owner.",
     "paymentError": "Payment Error",
     "paymentUnavailable": "Payment is unavailable for this store right now. Please contact the store.",
+    "paymentSessionStuck": "This payment could not be continued. Start a new checkout to try again.",
+    "startNewCheckout": "Start a new checkout",
     "paymentRedirectBlocked": "Payment redirect blocked for security reasons. Please contact support.",
     "paymentLoadFailed": "The payment form didn't load. You can continue in a new tab instead.",
     "sandboxTitle": "Sandbox Mode",

package/messages/he.json

@@ -182,6 +182,25 @@
   "faq": {
     "title": "שאלות נפוצות"
   },
+  "seo": {
+    "home": "דף הבית",
+    "products": "מוצרים",
+    "blog": "בלוג",
+    "categoryNotFound": "הקטגוריה לא נמצאה",
+    "productNotFound": "המוצר לא נמצא",
+    "productsDescription": "כל קטלוג המוצרים שלנו.",
+    "blogDescription": "מאמרים וסיפורים מהחנות",
+    "pagination": "עמודי הקטלוג",
+    "previousPage": "העמוד הקודם",
+    "nextPage": "העמוד הבא"
+  },
+  "blog": {
+    "empty": "עדיין אין פוסטים.",
+    "readMore": "קרא עוד",
+    "previous": "הקודם",
+    "next": "הבא",
+    "backToBlog": "חזרה לבלוג"
+  },
   "cart": {
     "pageTitle": "עגלת קניות",
     "title": "עגלת קניות",
@@ -258,6 +277,8 @@
     "paymentNotConfiguredDesc": "התשלום עדיין לא הוגדר לחנות זו. אנא פנו לבעל החנות.",
     "paymentError": "שגיאת תשלום",
     "paymentUnavailable": "לא ניתן לשלם בחנות זו כרגע. ניתן לפנות לחנות.",
+    "paymentSessionStuck": "לא ניתן להמשיך את התשלום הזה. אפשר להתחיל תשלום חדש ולנסות שוב.",
+    "startNewCheckout": "להתחיל תשלום חדש",
     "paymentRedirectBlocked": "הפניית התשלום נחסמה מטעמי אבטחה. אנא פנו לתמיכה.",
     "paymentLoadFailed": "טופס התשלום לא נטען. אפשר להמשיך בכרטיסייה חדשה במקום.",
     "sandboxTitle": "מצב בדיקה",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.88.1",
+  "version": "1.89.0",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "homepage": "https://brainerce.com",
   "repository": {
@@ -26,8 +26,9 @@
     "clean": "rimraf dist",
     "release": "pnpm build && node ../../scripts/publish-workspace-package.js .",
     "check:template-parity": "node scripts/check-template-parity.js",
+    "check:agent-docs": "node scripts/check-agent-docs.js",
     "check:sdk-published": "node scripts/check-sdk-published.js",
-    "prepublishOnly": "node scripts/check-template-parity.js && node scripts/check-sdk-published.js && node ../../scripts/check-publishable.js ./package.json"
+    "prepublishOnly": "node scripts/check-template-parity.js && node scripts/check-agent-docs.js && node scripts/check-sdk-published.js && node ../../scripts/check-publishable.js ./package.json"
   },
   "dependencies": {
     "chalk": "^4.1.2",

package/templates/nextjs/base/.eslintrc.json

@@ -22,6 +22,7 @@
                   "!@/core/lib/coupon-error",
                   "!@/core/lib/navigation",
                   "!@/core/lib/product-options",
+                  "!@/core/lib/reviews-disabled",
                   "!@/core/lib/sanitize",
                   "!@/core/lib/tracking",
                   "!@/core/lib/sanitize-html",

package/templates/nextjs/base/AI-GUIDE.md

@@ -198,6 +198,35 @@ attention, confirms an action, or rewards exploration. Rules:
 - **Fonts**: any face used for body or headlines must include the store's
   script (e.g. Google Fonts `hebrew` subset). Latin-only display faces are
   accent-only.
+- **Public paths go through `localePath(locale, '/x')`** (`@/core/lib/locale-path`),
+  never `` `/${locale}/x` ``. The default locale arrives as a real `params.locale`
+  too, and the middleware 308-redirects `/{default}/x` to `/x`, so a canonical
+  tag, breadcrumb link or JSON-LD url built the second way points at a redirect.
+- **Every indexable page sets its own `alternates.canonical`; the root layout sets
+  none.** A layout-level canonical is inherited by every page without its own and
+  tells Google they are duplicates of it. `openGraph` on a page REPLACES the
+  layout's object (it does not merge), so repeat `siteName` there.
+- **Product meta description: `deriveSeoDescription(product)`**, never
+  `product.seoDescription` alone. The merchant's text can arrive under either
+  `seoDescription` or `metaDescription`; reading one silently falls back to the
+  start of the description.
+- **`og:type: product` and the `product:*` price/availability tags are real
+  `<meta property>` elements** (`components/seo/product-og-meta.tsx`). Next's
+  `openGraph.type` has no `product`, and `metadata.other` renders `name=`, which
+  the crawlers that read these tags ignore. Do not also set `openGraph.type` on
+  the product page, or it carries two `og:type` tags.
+- **`/products` and the home grid are server-seeded.** `app/products/page.tsx`
+  reads the URL (search, filters, sort, `?page=`) and passes the first render's
+  products through `ListingSeedProvider`; `core/lib/listing-query.ts` is the ONE
+  function turning a URL into a query, shared by that page and
+  `useProductListing`. Do not fork it, and do not put the listing back behind
+  `'use client'` or a `<Suspense>` fallback: the server HTML must contain the
+  products, not a spinner. A seeded hook starts with `loading` false.
+- **Metadata, JSON-LD and breadcrumb strings come from the message files**
+  (`getServerNamespace('seo', locale)`), not from literals or a
+  `locale === 'he'` ternary (English for every third language). The visible
+  breadcrumb and the BreadcrumbList JSON-LD are built from the SAME items; the
+  JSON-LD components take a required `breadcrumbs` prop.
 
 ## Never do
 
@@ -219,6 +248,12 @@ attention, confirms an action, or rewards exploration. Rules:
 
 - New homepage section → new component in `src/ui/home/`, composed in
   `home-client.tsx`, data via existing hooks only.
+- New place that shows a star rating or a review count (a card, a banner,
+  structured data) → gate it with `useReviewsEnabled()` (client) or
+  `reviewsAreOn(storeInfo)` from `src/core/lib/store-info` (server). Products
+  keep their stored `avgRating` and `reviewCount` while the merchant has reviews
+  switched off, so `reviewCount > 0` alone would show a rating for reviews nobody
+  can open.
 - New UI copy → add keys to **both** `messages/he.json` and
   `messages/en.json` (or all supported locales), use `useTranslations()`.
 - New microinteraction → CSS-first; JS only for things CSS cannot do.

package/templates/nextjs/base/TRANSLATIONS.md

@@ -79,6 +79,12 @@ The `StoreProvider` (`src/providers/store-provider.tsx`) calls `client.setLocale
 
 You never overlay translations yourself — the SDK does it on every request.
 
+### Meta descriptions
+
+On a product read, `seoDescription` is the **effective** meta description: the active locale's translation when there is one, otherwise the merchant's stored text (which is also served as `metaDescription`). It is `null` only when the merchant wrote none. Never read one of the two names alone: call `deriveSeoDescription(product)`, which takes whichever is present and falls back to a stripped `description`, then the name. The product page (`src/app/products/[slug]/page.tsx`) does exactly that.
+
+When you WRITE a product translation, send either name: `metaDescription` is accepted as `seoDescription`.
+
 ## RTL (Hebrew, Arabic, Persian, Urdu, Yiddish)
 
 `src/i18n.ts` exports `getDirection(locale)` that delegates to the SDK's `getDirectionForLocale()`. The layout uses it on `<html dir={…}>`:

package/templates/nextjs/base/scripts/agent-docs.mjs

@@ -0,0 +1,76 @@
+/**
+ * Keep CLAUDE.md and AGENTS.md truthful once `npm run connect` has connected
+ * the store.
+ *
+ * WHY THIS EXISTS. A project scaffolded with `--defer-connection` starts both
+ * files with a "Not connected yet" paragraph, rendered ONCE at scaffold time.
+ * `connect` then wrote the id into `.env.local` and never touched them, so a
+ * connected store kept telling every coding agent that read it that it was not
+ * connected. The agent believed the file, concluded the store had no channel and
+ * asked the user to connect it again.
+ *
+ * ⛔ THE PATTERN BELOW IS COUPLED TO TWO TEMPLATES. It must keep matching the
+ * deferred paragraph in `CLAUDE.md.ejs` and `AGENTS.md.ejs` (first words
+ * "**Not connected yet.**", last sentence "Once connected, everything below
+ * applies."). `scripts/check-template-parity.js` renders both files deferred and
+ * fails `prepublishOnly` if this stops matching, because a pattern that silently
+ * matches nothing is exactly the bug it fixes.
+ *
+ * Only the channel id goes into the prose, and only when it has the shape of one:
+ * the store NAME is owner-controlled text, and these files are read by agents as
+ * instructions. The name is not needed: the doc already says to read it from
+ * `resolveStoreName()`.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const AGENT_DOC_FILES = ['CLAUDE.md', 'AGENTS.md'];
+
+export const NOT_CONNECTED_PARAGRAPH =
+  /\*\*Not connected yet\.\*\*[\s\S]*?Once connected, everything below applies\./;
+
+const CHANNEL_ID = /^vc_[A-Za-z0-9_-]+$/;
+
+/** The paragraph a connected storefront's docs open with. Mirrors the
+ *  non-deferred branch of the two templates, minus the store name. */
+export function connectedParagraph(connectionId) {
+  return (
+    `**Sales channel \`${connectionId}\` — already connected.** Products, cart,\n` +
+    'checkout, coupons, discounts, orders and content flow in real time from the\n' +
+    'Brainerce dashboard. There is nothing to hook up.'
+  );
+}
+
+/**
+ * Rewrite the "Not connected yet" paragraph in each agent doc under `dir`.
+ * Returns the names of the files it changed. Never throws: a doc that cannot be
+ * read or written must not undo a connection that already succeeded.
+ *
+ * A doc whose paragraph was edited by hand no longer matches and is left alone.
+ * A project that already connected before this script existed is not helped
+ * either: it carries the old `connect.mjs`, which never calls this. Its owner
+ * deletes the paragraph by hand (see the create-brainerce-store CHANGELOG).
+ */
+export function markAgentDocsConnected(dir, connectionId) {
+  if (typeof connectionId !== 'string' || !CHANNEL_ID.test(connectionId)) return [];
+  const changed = [];
+  for (const name of AGENT_DOC_FILES) {
+    const path = resolve(dir, name);
+    try {
+      if (!existsSync(path)) continue;
+      const body = readFileSync(path, 'utf8');
+      if (!NOT_CONNECTED_PARAGRAPH.test(body)) continue;
+      // A function replacement, so `$` sequences in the id can never be read as
+      // replacement patterns.
+      const next = body.replace(NOT_CONNECTED_PARAGRAPH, () => connectedParagraph(connectionId));
+      // Keep a CRLF file CRLF (the paragraph is matched across either ending).
+      const out = body.includes('\r\n') ? next.replace(/\r?\n/g, '\r\n') : next;
+      writeFileSync(path, out);
+      changed.push(name);
+    } catch {
+      // Best effort by design.
+    }
+  }
+  return changed;
+}

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

@@ -35,6 +35,7 @@ import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setVar } from './env-file.mjs';
+import { markAgentDocsConnected } from './agent-docs.mjs';
 
 const API_BASE = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com').replace(/\/$/, '');
 const ENV_PATH = resolve(process.cwd(), '.env.local');
@@ -248,6 +249,11 @@ function writeEnv(connectionId) {
   let body = existsSync(ENV_PATH) ? readFileSync(ENV_PATH, 'utf8') : '';
   for (const key of KEYS) body = setVar(body, key, connectionId);
   writeFileSync(ENV_PATH, body);
+  // CLAUDE.md and AGENTS.md open with "Not connected yet" on a deferred scaffold.
+  // Left alone they tell the next coding agent this store has no channel, and it
+  // asks the user to connect it again.
+  const docs = markAgentDocsConnected(dirname(ENV_PATH), connectionId);
+  if (docs.length > 0) console.log(`Updated ${docs.join(' and ')}: the store is no longer "not connected".`);
 }
 
 /**

package/templates/nextjs/base/src/app/api/auth/oauth-callback/route.ts

@@ -1,96 +1,102 @@
-import { NextRequest, NextResponse } from 'next/server';
-
-const TOKEN_COOKIE = 'brainerce_customer_token';
-const LOGGED_IN_COOKIE = 'brainerce_logged_in';
-const COOKIE_MAX_AGE = 7 * 24 * 60 * 60; // 7 days
-
-const BACKEND_URL = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com').replace(
-  /\/$/,
-  ''
-);
-
-function isSecure(): boolean {
-  return process.env.NODE_ENV === 'production';
-}
-
-/**
- * Forward a failure to the client callback page as a stable snake_case code.
- *
- * The backend uses the RFC 6749 §4.1.2.1 shape (`oauth_error` = code,
- * `error_description` = English developer detail), so codes are what the page
- * switches on to pick localized copy. The description is deliberately NOT
- * forwarded — it is not shopper-facing copy.
- */
-function errorRedirect(base: URL, code: string): NextResponse {
-  base.searchParams.set('oauth_error', code);
-  const response = NextResponse.redirect(base);
-  response.headers.set('Referrer-Policy', 'no-referrer');
-  return response;
-}
-
-/**
- * OAuth callback handler.
- *
- * The backend redirects here with ?oauth_success=true&auth_code=<one-time-code>.
- * We exchange the auth_code for the real JWT via a server-to-server POST (so the
- * JWT never appears in any URL), then set an httpOnly cookie and redirect to the
- * client-side callback page.
- */
-export async function GET(request: NextRequest) {
-  const { searchParams } = request.nextUrl;
-  const authCode = searchParams.get('auth_code');
-  const oauthSuccess = searchParams.get('oauth_success');
-  const oauthError = searchParams.get('oauth_error');
-
-  const redirectUrl = new URL('/auth/callback', request.url);
-
-  if (oauthError) {
-    return errorRedirect(redirectUrl, oauthError);
-  }
-
-  if (oauthSuccess !== 'true' || !authCode) {
-    return errorRedirect(redirectUrl, 'invalid_request');
-  }
-
-  // Exchange the one-time auth_code for the real JWT.
-  // This is a server-to-server call — the JWT never enters the browser URL.
-  let token: string;
-  try {
-    const exchangeRes = await fetch(`${BACKEND_URL}/api/oauth/customer/exchange`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ code: authCode }),
-    });
-    if (!exchangeRes.ok) {
-      throw new Error(`exchange responded ${exchangeRes.status}`);
-    }
-    const data = await exchangeRes.json();
-    if (!data.token) throw new Error('missing token in exchange response');
-    token = data.token;
-  } catch (err) {
-    console.error('[oauth-callback] auth_code exchange failed:', err);
-    return errorRedirect(redirectUrl, 'server_error');
-  }
-
-  redirectUrl.searchParams.set('oauth_success', 'true');
-  const response = NextResponse.redirect(redirectUrl);
-
-  response.cookies.set(TOKEN_COOKIE, token, {
-    httpOnly: true,
-    secure: isSecure(),
-    sameSite: 'lax',
-    path: '/',
-    maxAge: COOKIE_MAX_AGE,
-  });
-
-  response.cookies.set(LOGGED_IN_COOKIE, '1', {
-    httpOnly: false,
-    secure: isSecure(),
-    sameSite: 'lax',
-    path: '/',
-    maxAge: COOKIE_MAX_AGE,
-  });
-
-  response.headers.set('Referrer-Policy', 'no-referrer');
-  return response;
-}
+import { NextRequest, NextResponse } from 'next/server';
+import { REFERRAL_COOKIE } from '@/core/lib/referral';
+
+const TOKEN_COOKIE = 'brainerce_customer_token';
+const LOGGED_IN_COOKIE = 'brainerce_logged_in';
+const COOKIE_MAX_AGE = 7 * 24 * 60 * 60; // 7 days
+
+const BACKEND_URL = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com').replace(
+  /\/$/,
+  ''
+);
+
+function isSecure(): boolean {
+  return process.env.NODE_ENV === 'production';
+}
+
+/**
+ * Forward a failure to the client callback page as a stable snake_case code.
+ *
+ * The backend uses the RFC 6749 §4.1.2.1 shape (`oauth_error` = code,
+ * `error_description` = English developer detail), so codes are what the page
+ * switches on to pick localized copy. The description is deliberately NOT
+ * forwarded — it is not shopper-facing copy.
+ */
+function errorRedirect(base: URL, code: string): NextResponse {
+  base.searchParams.set('oauth_error', code);
+  const response = NextResponse.redirect(base);
+  response.headers.set('Referrer-Policy', 'no-referrer');
+  return response;
+}
+
+/**
+ * OAuth callback handler.
+ *
+ * The backend redirects here with ?oauth_success=true&auth_code=<one-time-code>.
+ * We exchange the auth_code for the real JWT via a server-to-server POST (so the
+ * JWT never appears in any URL), then set an httpOnly cookie and redirect to the
+ * client-side callback page.
+ */
+export async function GET(request: NextRequest) {
+  const { searchParams } = request.nextUrl;
+  const authCode = searchParams.get('auth_code');
+  const oauthSuccess = searchParams.get('oauth_success');
+  const oauthError = searchParams.get('oauth_error');
+
+  const redirectUrl = new URL('/auth/callback', request.url);
+
+  if (oauthError) {
+    return errorRedirect(redirectUrl, oauthError);
+  }
+
+  if (oauthSuccess !== 'true' || !authCode) {
+    return errorRedirect(redirectUrl, 'invalid_request');
+  }
+
+  // Exchange the one-time auth_code for the real JWT.
+  // This is a server-to-server call — the JWT never enters the browser URL.
+  let token: string;
+  try {
+    const exchangeRes = await fetch(`${BACKEND_URL}/api/oauth/customer/exchange`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ code: authCode }),
+    });
+    if (!exchangeRes.ok) {
+      throw new Error(`exchange responded ${exchangeRes.status}`);
+    }
+    const data = await exchangeRes.json();
+    if (!data.token) throw new Error('missing token in exchange response');
+    token = data.token;
+  } catch (err) {
+    console.error('[oauth-callback] auth_code exchange failed:', err);
+    return errorRedirect(redirectUrl, 'server_error');
+  }
+
+  redirectUrl.searchParams.set('oauth_success', 'true');
+  const response = NextResponse.redirect(redirectUrl);
+
+  response.cookies.set(TOKEN_COOKIE, token, {
+    httpOnly: true,
+    secure: isSecure(),
+    sameSite: 'lax',
+    path: '/',
+    maxAge: COOKIE_MAX_AGE,
+  });
+
+  response.cookies.set(LOGGED_IN_COOKIE, '1', {
+    httpOnly: false,
+    secure: isSecure(),
+    sameSite: 'lax',
+    path: '/',
+    maxAge: COOKIE_MAX_AGE,
+  });
+
+  // The referral code rode the OAuth state and is now spent (or ignored, for
+  // an existing customer). Drop it so the next account created in this
+  // browser is not attributed to the same referrer — same as /register does.
+  response.cookies.set(REFERRAL_COOKIE, '', { path: '/', maxAge: 0, sameSite: 'lax' });
+
+  response.headers.set('Referrer-Policy', 'no-referrer');
+  return response;
+}