create-brainerce-store 1.58.0 → 1.61.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.58.0",
+      version: "1.61.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"
@@ -43,6 +43,7 @@ var require_package = __commonJS({
       ],
       scripts: {
         build: "tsup",
+        "type-check": "tsc --noEmit",
         dev: "tsup --watch",
         clean: "rimraf dist",
         release: "pnpm build && node ../../scripts/publish-workspace-package.js .",
@@ -182,7 +183,11 @@ var BRAINERCE_RUNTIME_DEPS = Object.freeze({
   // SetCheckoutCustomerDto — the scaffolded checkout form types depend on it.
   // 1.46 adds getAddressSuggestions/getAddressDetails — the scaffolded
   // checkout form's address-autocomplete typeahead calls these directly.
-  brainerce: "^1.46.0",
+  // 1.52 adds ShippingRate.speedTier — the scaffolded shipping step reads it to
+  // label live carrier rates, so an older SDK fails type-check at scaffold time
+  // — plus getBusinessHoursForDate(), which the scaffolded DATETIME checkout
+  // field uses to tell "day closed" from "field isn't slot-based".
+  brainerce: "^1.52.0",
   "isomorphic-dompurify": "^3.8.0"
 });
 

package/messages/en.json

@@ -189,6 +189,9 @@
     "noShippingOptions": "No shipping options available for this address.",
     "noShippingOptionsHint": "Please try a different address or contact support.",
     "estimatedDelivery": "Estimated delivery:",
+    "shippingTierCheapest": "Standard delivery",
+    "shippingTierBalanced": "Express delivery",
+    "shippingTierFastest": "Priority delivery",
     "pickupLocation": "Pickup Location",
     "selectPickupLocation": "Select pickup location",
     "pickupLocationRequired": "Please select a pickup location",
@@ -245,6 +248,13 @@
     "customFieldsImageRemove": "Remove",
     "customFieldsImageUploading": "Uploading...",
     "customFieldsImageTooLarge": "File must be under 5MB",
+    "customFieldsDatePlaceholder": "Select a date",
+    "customFieldsDateToday": "Today",
+    "customFieldsDateClear": "Clear",
+    "customFieldsDatePrevMonth": "Previous month",
+    "customFieldsDateNextMonth": "Next month",
+    "customFieldsTimeLabel": "Time",
+    "customFieldsTimeClosed": "No delivery times are available on this date.",
     "changeOptions": "Change options",
     "surcharges": "Additional charges"
   },
@@ -335,6 +345,10 @@
     "goToRegister": "Go to Register",
     "authFailed": "Authentication failed",
     "authFailedDesc": "Missing authentication parameters. Please try again.",
+    "oauthErrorGeneric": "Sign-in could not be completed. Please try again.",
+    "oauthErrorCancelled": "Sign-in was cancelled.",
+    "oauthErrorExpired": "That sign-in attempt expired. Please try again.",
+    "oauthErrorVerifyEmailFirst": "This email address needs to be verified before you can sign in with a social account. Check your inbox for the verification email.",
     "backToLogin": "Back to Login",
     "completingSignIn": "Completing sign in...",
     "forgotPassword": "Forgot password?",
@@ -445,6 +459,14 @@
     "yourDownloads": "Your Downloads",
     "download": "Download"
   },
+  "orderStatus": {
+    "pageTitle": "Order Status",
+    "loading": "Loading your order...",
+    "errorTitle": "Order not found",
+    "notFound": "We couldn't find an order matching this link.",
+    "missingCheckoutInfo": "Missing order information.",
+    "returnHome": "Return Home"
+  },
   "reservation": {
     "expired": "Reservation expired. Items may no longer be available.",
     "hurry": "Hurry!",

package/messages/he.json

@@ -189,6 +189,9 @@
     "noShippingOptions": "אין אפשרויות משלוח זמינות לכתובת זו.",
     "noShippingOptionsHint": "נסו כתובת אחרת או פנו לתמיכה.",
     "estimatedDelivery": "זמן משלוח משוער:",
+    "shippingTierCheapest": "משלוח רגיל",
+    "shippingTierBalanced": "משלוח מהיר",
+    "shippingTierFastest": "משלוח אקספרס",
     "pickupLocation": "נקודת איסוף",
     "selectPickupLocation": "בחרו נקודת איסוף",
     "pickupLocationRequired": "יש לבחור נקודת איסוף",
@@ -245,6 +248,13 @@
     "customFieldsImageRemove": "הסר",
     "customFieldsImageUploading": "...מעלה",
     "customFieldsImageTooLarge": "הקובץ חייב להיות מתחת ל-5MB",
+    "customFieldsDatePlaceholder": "בחרו תאריך",
+    "customFieldsDateToday": "היום",
+    "customFieldsDateClear": "נקה",
+    "customFieldsDatePrevMonth": "חודש קודם",
+    "customFieldsDateNextMonth": "חודש הבא",
+    "customFieldsTimeLabel": "שעה",
+    "customFieldsTimeClosed": "אין שעות משלוח זמינות בתאריך הזה.",
     "changeOptions": "שנה אפשרויות",
     "surcharges": "תוספות"
   },
@@ -335,6 +345,10 @@
     "goToRegister": "מעבר להרשמה",
     "authFailed": "ההתחברות נכשלה",
     "authFailedDesc": "חסרים פרמטרי התחברות. אנא נסו שוב.",
+    "oauthErrorGeneric": "לא הצלחנו להשלים את ההתחברות. אנא נסו שוב.",
+    "oauthErrorCancelled": "ההתחברות בוטלה.",
+    "oauthErrorExpired": "ניסיון ההתחברות פג. אנא נסו שוב.",
+    "oauthErrorVerifyEmailFirst": "יש לאמת את כתובת המייל הזו לפני התחברות עם חשבון חברתי. בדקו את תיבת הדואר שלכם עבור מייל האימות.",
     "backToLogin": "חזרה להתחברות",
     "completingSignIn": "משלים התחברות...",
     "forgotPassword": "שכחת סיסמא?",
@@ -445,6 +459,14 @@
     "yourDownloads": "ההורדות שלך",
     "download": "הורדה"
   },
+  "orderStatus": {
+    "pageTitle": "סטטוס הזמנה",
+    "loading": "טוען את ההזמנה שלך...",
+    "errorTitle": "ההזמנה לא נמצאה",
+    "notFound": "לא הצלחנו למצוא הזמנה שתואמת לקישור הזה.",
+    "missingCheckoutInfo": "חסר מידע הזמנה.",
+    "returnHome": "חזרה לדף הבית"
+  },
   "reservation": {
     "expired": "השריון פג. ייתכן שהמוצרים כבר לא זמינים.",
     "hurry": "מהרו!",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.58.0",
+  "version": "1.61.0",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "bin": {
     "create-brainerce-store": "dist/index.js"
@@ -12,6 +12,7 @@
   ],
   "scripts": {
     "build": "tsup",
+    "type-check": "tsc --noEmit",
     "dev": "tsup --watch",
     "clean": "rimraf dist",
     "release": "pnpm build && node ../../scripts/publish-workspace-package.js .",

package/templates/nextjs/base/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "brainerce-docs": {
+      "type": "http",
+      "url": "https://mcp-docs.brainerce.com/mcp"
+    }
+  }
+}

package/templates/nextjs/base/AGENTS.md.ejs

@@ -1,65 +1,81 @@
-# AGENTS.md — this is a LIVE Brainerce storefront
-
-**Store: "<%- storeName %>" · sales channel `<%- connectionId %>` — already
-connected.** Products, cart, checkout, coupons, discounts, orders and content
-flow in real time from the Brainerce dashboard. There is nothing to hook up.
-
-- **NEVER suggest connecting this store to Shopify, WooCommerce, or "a real
-  system"** — Brainerce IS the commerce backend, and this store is wired to
-  it end-to-end.
-- **NEVER build standalone HTML mockups or demo pages** — design THIS Next.js
-  app. Run `pnpm dev` and you are working against live data.
-- **NEVER hardcode products, prices, or currency** — the catalog is live.
-- **No server side is needed** — the backend is Brainerce's cloud. This repo
-  is a frontend (plus thin, already-included API proxy routes under
-  `src/app/api/`). Do not scaffold databases, auth servers, or admin panels —
-  the merchant manages everything in the Brainerce dashboard.
-
-Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
-— AI-readable index: https://brainerce.com/llms.txt
-
-**Before building any feature the merchant asks for** (loyalty points,
-shipping zones, subscriptions, gift cards, multi-currency, reviews,
-abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
-already has it as a platform capability (dashboard toggle + hook/SDK
-method) that only needs a UI in `src/ui/`, not a feature built from scratch.
-
-Your job here is almost always **design**.
-
-## The one rule
-
-**`src/core/` is the platform's. `src/ui/` is yours.**
-
-The shipped `src/ui/` is a working reference, not a design to preserve —
-full delete-and-rebuild of ui files is encouraged and expected.
-Rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
-like — the store keeps working. Never modify `src/core/`, `src/app/api/`, or
-the checkout/auth/account components. Data and behavior come exclusively from
-`@/core/hooks/*` and `@/core/providers/store-provider` — hooks return state
-and handlers, never JSX. Never hardcode catalog content.
-
-**Read `AI-GUIDE.md` before any redesign** — it has the full file map, hook
-contracts, motion language, and hard-won RTL/i18n gotchas that will save you
-real debugging time.
-
-## Redesigning?
-
-Follow the process documented in AI-GUIDE.md: commit to one art direction,
-rewrite tokens first, then surfaces in order (header, home, card, product
-page, cart), then verify.
-
-## Verify before declaring done
-
-1. `pnpm exec tsc --noEmit` → 0 errors
-2. `pnpm dev` → drive the changed flow in a real browser (home → product →
-   add to cart → cart)
-3. Screenshot desktop (1440px) and mobile (390px)
-4. RTL stores: check anchoring and arrow directions
-
-## i18n
-
-Every user-facing string goes through `useTranslations()` with keys in **all**
-files under `messages/`. The shipped copy is example boutique content — a
-starting point meant to be rewritten in the store's real voice. Hebrew: no
-uppercase transforms, no wide letter-spacing on headings, logical CSS
-properties only (`ms-/me-`, `ps-/pe-`, `start-/end-`).
+# AGENTS.md — this is a LIVE Brainerce storefront
+
+**Store: "<%- storeName %>" · sales channel `<%- connectionId %>` — already
+connected.** Products, cart, checkout, coupons, discounts, orders and content
+flow in real time from the Brainerce dashboard. There is nothing to hook up.
+
+- **NEVER suggest connecting this store to Shopify, WooCommerce, or "a real
+  system"** — Brainerce IS the commerce backend, and this store is wired to
+  it end-to-end.
+- **NEVER build standalone HTML mockups or demo pages** — design THIS Next.js
+  app. Run `pnpm dev` and you are working against live data.
+- **NEVER hardcode products, prices, or currency** — the catalog is live.
+- **No server side is needed** — the backend is Brainerce's cloud. This repo
+  is a frontend (plus thin, already-included API proxy routes under
+  `src/app/api/`). Do not scaffold databases, auth servers, or admin panels —
+  the merchant manages everything in the Brainerce dashboard.
+
+Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
+— AI-readable index: https://brainerce.com/llms.txt
+
+## MCP servers
+
+- **`brainerce-docs`** — already connected via `.mcp.json`, no auth needed.
+  A live SDK/docs oracle: current SDK method shapes, type definitions, code
+  examples, and this store's actual capabilities/config. Prefer it over
+  guessing or relying on training data — it reflects what's actually toggled
+  on for `<%- connectionId %>` right now.
+- **Brainerce Admin MCP** — opt-in, not wired up by default. Lets an agent
+  directly manage this store's *live* data (products, orders, discounts,
+  shipping, …) instead of just reading docs. Only add it if the merchant
+  wants that: connect `https://api.brainerce.com/api/mcp` as a remote HTTP
+  MCP server (e.g. `claude mcp add --transport http brainerce-admin
+  https://api.brainerce.com/api/mcp`) — it opens a browser to log into the
+  Brainerce dashboard, pick this store, and grant scoped OAuth permissions.
+  Treat it like handing the agent write access to production commerce data.
+
+**Before building any feature the merchant asks for** (loyalty points,
+shipping zones, subscriptions, gift cards, multi-currency, reviews,
+abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
+already has it as a platform capability (dashboard toggle + hook/SDK
+method) that only needs a UI in `src/ui/`, not a feature built from scratch.
+
+Your job here is almost always **design**.
+
+## The one rule
+
+**`src/core/` is the platform's. `src/ui/` is yours.**
+
+The shipped `src/ui/` is a working reference, not a design to preserve —
+full delete-and-rebuild of ui files is encouraged and expected.
+Rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
+like — the store keeps working. Never modify `src/core/`, `src/app/api/`, or
+the checkout/auth/account components. Data and behavior come exclusively from
+`@/core/hooks/*` and `@/core/providers/store-provider` — hooks return state
+and handlers, never JSX. Never hardcode catalog content.
+
+**Read `AI-GUIDE.md` before any redesign** — it has the full file map, hook
+contracts, motion language, and hard-won RTL/i18n gotchas that will save you
+real debugging time.
+
+## Redesigning?
+
+Follow the process documented in AI-GUIDE.md: commit to one art direction,
+rewrite tokens first, then surfaces in order (header, home, card, product
+page, cart), then verify.
+
+## Verify before declaring done
+
+1. `pnpm exec tsc --noEmit` → 0 errors
+2. `pnpm dev` → drive the changed flow in a real browser (home → product →
+   add to cart → cart)
+3. Screenshot desktop (1440px) and mobile (390px)
+4. RTL stores: check anchoring and arrow directions
+
+## i18n
+
+Every user-facing string goes through `useTranslations()` with keys in **all**
+files under `messages/`. The shipped copy is example boutique content — a
+starting point meant to be rewritten in the store's real voice. Hebrew: no
+uppercase transforms, no wide letter-spacing on headings, logical CSS
+properties only (`ms-/me-`, `ps-/pe-`, `start-/end-`).

package/templates/nextjs/base/CLAUDE.md.ejs

@@ -1,76 +1,92 @@
-# CLAUDE.md — this is a LIVE Brainerce storefront
-
-**Store: "<%- storeName %>" · sales channel `<%- connectionId %>` — already
-connected.** Products, cart, checkout, coupons, discounts, orders and content
-flow in real time from the Brainerce dashboard. There is nothing to hook up.
-
-- **NEVER suggest connecting this store to Shopify, WooCommerce, or "a real
-  system"** — Brainerce IS the commerce backend, and this store is wired to
-  it end-to-end.
-- **NEVER build standalone HTML mockups or demo pages** — design THIS Next.js
-  app. Run `pnpm dev` and you are working against live data.
-- **NEVER hardcode products, prices, or currency** — the catalog is live.
-- **No server side is needed** — the backend is Brainerce's cloud. This repo
-  is a frontend (plus thin, already-included API proxy routes under
-  `src/app/api/`). Do not scaffold databases, auth servers, or admin panels —
-  the merchant manages everything in the Brainerce dashboard.
-
-Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
-— AI-readable index: https://brainerce.com/llms.txt
-
-**Before building any feature the merchant asks for** (loyalty points,
-shipping zones, subscriptions, gift cards, multi-currency, reviews,
-abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
-already has it as a platform capability (dashboard toggle + hook/SDK
-method) that only needs a UI in `src/ui/`, not a feature built from scratch.
-
-Your job here is almost always **design**.
-
-## The one rule
-
-**`src/core/` is the platform's. `src/ui/` is yours.**
-
-The shipped `src/ui/` is a working reference, not a design to preserve —
-full delete-and-rebuild of ui files is encouraged and expected. (Stores
-scaffolded with `--canvas` ship `src/ui/` as bare unstyled skeletons —
-there is no reference look at all; the design is entirely yours to create.)
-Rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
-like — the store keeps working. Never modify `src/core/`, `src/app/api/`, or
-the checkout/auth/account components. Data and behavior come exclusively from
-`@/core/hooks/*` and `@/core/providers/store-provider` — hooks return state
-and handlers, never JSX. Never hardcode catalog content.
-
-**Read `AI-GUIDE.md` before any redesign** — it has the full file map, hook
-contracts, motion language, and hard-won RTL/i18n gotchas that will save you
-real debugging time.
-
-## The dialect
-
-- `src/components/ui/` = official **shadcn/ui primitives** (Button, Card,
-  Badge, Input, Select, Accordion, Dialog, Sheet, Skeleton, …). Compose them;
-  extend looks via CVA **variants**, never repeated inline overrides.
-- Icons: **lucide-react only** — no inline `<svg>`, no emoji-as-icons.
-- Class merging: **`cn()`** from `@/core/lib/utils`.
-- Colors/radius come from the semantic HSL tokens in `globals.css`
-  (`--primary`, `--card`, `--ring`, `--radius`, …) — restyle via tokens.
-
-## Redesigning? Use the ready-made flow
-
-Run `/design <your art-direction brief>` — it walks the whole process:
-concept → implementation in `ui/` → verification.
-
-## Verify before declaring done
-
-1. `pnpm exec tsc --noEmit` → 0 errors
-2. `pnpm dev` → drive the changed flow in a real browser (home → product →
-   add to cart → cart)
-3. Screenshot desktop (1440px) and mobile (390px)
-4. RTL stores: check anchoring and arrow directions
-
-## i18n
-
-Every user-facing string goes through `useTranslations()` with keys in **all**
-files under `messages/`. The shipped copy is example boutique content — a
-starting point meant to be rewritten in the store's real voice. Hebrew: no
-uppercase transforms, no wide letter-spacing on headings, logical CSS
-properties only (`ms-/me-`, `ps-/pe-`, `start-/end-`).
+# CLAUDE.md — this is a LIVE Brainerce storefront
+
+**Store: "<%- storeName %>" · sales channel `<%- connectionId %>` — already
+connected.** Products, cart, checkout, coupons, discounts, orders and content
+flow in real time from the Brainerce dashboard. There is nothing to hook up.
+
+- **NEVER suggest connecting this store to Shopify, WooCommerce, or "a real
+  system"** — Brainerce IS the commerce backend, and this store is wired to
+  it end-to-end.
+- **NEVER build standalone HTML mockups or demo pages** — design THIS Next.js
+  app. Run `pnpm dev` and you are working against live data.
+- **NEVER hardcode products, prices, or currency** — the catalog is live.
+- **No server side is needed** — the backend is Brainerce's cloud. This repo
+  is a frontend (plus thin, already-included API proxy routes under
+  `src/app/api/`). Do not scaffold databases, auth servers, or admin panels —
+  the merchant manages everything in the Brainerce dashboard.
+
+Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
+— AI-readable index: https://brainerce.com/llms.txt
+
+## MCP servers
+
+- **`brainerce-docs`** — already connected via `.mcp.json`, no auth needed.
+  A live SDK/docs oracle: current SDK method shapes, type definitions, code
+  examples, and this store's actual capabilities/config. Prefer it over
+  guessing or relying on training data — it reflects what's actually toggled
+  on for `<%- connectionId %>` right now.
+- **Brainerce Admin MCP** — opt-in, not wired up by default. Lets an agent
+  directly manage this store's *live* data (products, orders, discounts,
+  shipping, …) instead of just reading docs. Only add it if the merchant
+  wants that: connect `https://api.brainerce.com/api/mcp` as a remote HTTP
+  MCP server (e.g. `claude mcp add --transport http brainerce-admin
+  https://api.brainerce.com/api/mcp`) — it opens a browser to log into the
+  Brainerce dashboard, pick this store, and grant scoped OAuth permissions.
+  Treat it like handing the agent write access to production commerce data.
+
+**Before building any feature the merchant asks for** (loyalty points,
+shipping zones, subscriptions, gift cards, multi-currency, reviews,
+abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
+already has it as a platform capability (dashboard toggle + hook/SDK
+method) that only needs a UI in `src/ui/`, not a feature built from scratch.
+
+Your job here is almost always **design**.
+
+## The one rule
+
+**`src/core/` is the platform's. `src/ui/` is yours.**
+
+The shipped `src/ui/` is a working reference, not a design to preserve —
+full delete-and-rebuild of ui files is encouraged and expected. (Stores
+scaffolded with `--canvas` ship `src/ui/` as bare unstyled skeletons —
+there is no reference look at all; the design is entirely yours to create.)
+Rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
+like — the store keeps working. Never modify `src/core/`, `src/app/api/`, or
+the checkout/auth/account components. Data and behavior come exclusively from
+`@/core/hooks/*` and `@/core/providers/store-provider` — hooks return state
+and handlers, never JSX. Never hardcode catalog content.
+
+**Read `AI-GUIDE.md` before any redesign** — it has the full file map, hook
+contracts, motion language, and hard-won RTL/i18n gotchas that will save you
+real debugging time.
+
+## The dialect
+
+- `src/components/ui/` = official **shadcn/ui primitives** (Button, Card,
+  Badge, Input, Select, Accordion, Dialog, Sheet, Skeleton, …). Compose them;
+  extend looks via CVA **variants**, never repeated inline overrides.
+- Icons: **lucide-react only** — no inline `<svg>`, no emoji-as-icons.
+- Class merging: **`cn()`** from `@/core/lib/utils`.
+- Colors/radius come from the semantic HSL tokens in `globals.css`
+  (`--primary`, `--card`, `--ring`, `--radius`, …) — restyle via tokens.
+
+## Redesigning? Use the ready-made flow
+
+Run `/design <your art-direction brief>` — it walks the whole process:
+concept → implementation in `ui/` → verification.
+
+## Verify before declaring done
+
+1. `pnpm exec tsc --noEmit` → 0 errors
+2. `pnpm dev` → drive the changed flow in a real browser (home → product →
+   add to cart → cart)
+3. Screenshot desktop (1440px) and mobile (390px)
+4. RTL stores: check anchoring and arrow directions
+
+## i18n
+
+Every user-facing string goes through `useTranslations()` with keys in **all**
+files under `messages/`. The shipped copy is example boutique content — a
+starting point meant to be rewritten in the store's real voice. Hebrew: no
+uppercase transforms, no wide letter-spacing on headings, logical CSS
+properties only (`ms-/me-`, `ps-/pe-`, `start-/end-`).

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

@@ -13,8 +13,16 @@ function isSecure(): boolean {
   return process.env.NODE_ENV === 'production';
 }
 
-function errorRedirect(base: URL, message: string): NextResponse {
-  base.searchParams.set('oauth_error', message);
+/**
+ * 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;
@@ -41,7 +49,7 @@ export async function GET(request: NextRequest) {
   }
 
   if (oauthSuccess !== 'true' || !authCode) {
-    return errorRedirect(redirectUrl, 'Authentication failed');
+    return errorRedirect(redirectUrl, 'invalid_request');
   }
 
   // Exchange the one-time auth_code for the real JWT.
@@ -61,7 +69,7 @@ export async function GET(request: NextRequest) {
     token = data.token;
   } catch (err) {
     console.error('[oauth-callback] auth_code exchange failed:', err);
-    return errorRedirect(redirectUrl, 'Authentication failed');
+    return errorRedirect(redirectUrl, 'server_error');
   }
 
   redirectUrl.searchParams.set('oauth_success', 'true');

package/templates/nextjs/base/src/app/auth/callback/page.tsx

@@ -7,6 +7,21 @@ import { useAuth } from '@/core/providers/store-provider';
 import { LoadingSpinner } from '@/ui/shared/loading-spinner';
 import { useTranslations } from '@/core/lib/translations';
 
+/**
+ * `oauth_error` is a stable snake_case code, not a message — the backend sends
+ * the RFC 6749 §4.1.2.1 pair (`oauth_error` + an English `error_description`
+ * meant for developers). Map codes to translated copy here; anything unknown,
+ * including provider-specific codes, falls through to the generic message.
+ */
+const OAUTH_ERROR_MESSAGE_KEYS: Record<string, string> = {
+  access_denied: 'oauthErrorCancelled',
+  invalid_request: 'oauthErrorExpired',
+  invalid_state: 'oauthErrorExpired',
+  state_already_used: 'oauthErrorExpired',
+  state_expired: 'oauthErrorExpired',
+  link_blocked_unverified_password_account: 'oauthErrorVerifyEmailFirst',
+};
+
 function OAuthCallbackContent() {
   const router = useRouter();
   const searchParams = useSearchParams();
@@ -25,7 +40,7 @@ function OAuthCallbackContent() {
     processedRef.current = true;
 
     if (oauthError) {
-      setError(oauthError);
+      setError(t(OAUTH_ERROR_MESSAGE_KEYS[oauthError] ?? 'oauthErrorGeneric'));
       return;
     }