create-brainerce-store 1.65.0 → 1.67.0

package/templates/nextjs/base/src/core/lib/site-url.ts

@@ -0,0 +1,197 @@
+import { headers } from 'next/headers';
+
+/**
+ * The storefront's public origin — the value that ends up in canonical tags,
+ * sitemap.xml, robots.txt, JSON-LD, and the `Origin` header the backend
+ * compares against the sales channel's configured domain.
+ *
+ * ⛔ NEVER hardcode this, and never reintroduce a literal default. The
+ * scaffolder cannot know the answer: `npx create-brainerce-store` is very
+ * often run by an AI builder (ChatGPT, Lovable, Bolt) that deploys the result
+ * to a sandbox domain *it* owns, and the merchant moves it to their own domain
+ * later. The old `.env.local` shipped `NEXT_PUBLIC_SITE_URL=http://localhost:3000`
+ * as a confident wrong answer, which is worse than no answer — it silently
+ * wrote `http://localhost:3000` into every sitemap and canonical tag of every
+ * storefront not run from a laptop, and `https://example.com` into the ones
+ * where that env file never travelled at all (it is gitignored).
+ *
+ * Two resolvers, split by what the caller actually needs:
+ *
+ *   {@link getCanonicalSiteUrl} — the address the store should be KNOWN by.
+ *     Env first, because a canonical URL must be stable across preview deploys
+ *     and must not be forgeable by a request header.
+ *
+ *   {@link getRequestOrigin} — the address a request actually ARRIVED on.
+ *     Request headers first, because this is what the backend's origin check
+ *     has to match; claiming the production domain from a preview deployment
+ *     would pass a check that ought to fail.
+ */
+
+const DEV_FALLBACK = 'http://localhost:3000';
+
+function isLoopback(host: string): boolean {
+  const name = host.split(':')[0].toLowerCase();
+  return name === 'localhost' || name === '127.0.0.1' || name === '[::1]' || name === '::1';
+}
+
+/**
+ * Coerce a host (`shop.example.com`) or a full URL (`https://shop.example.com/`)
+ * into a bare origin. Returns null for anything unparseable, so a malformed env
+ * var degrades to the next source instead of throwing.
+ */
+function toOrigin(raw: string | undefined): string | null {
+  const trimmed = raw?.trim();
+  if (!trimmed) return null;
+  const hasProtocol = /^https?:\/\//i.test(trimmed);
+  const bare = trimmed.replace(/^\/\//, '');
+  const candidate = hasProtocol ? trimmed : `${isLoopback(bare) ? 'http' : 'https'}://${bare}`;
+  try {
+    return new URL(candidate).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Explicitly configured origin. `SITE_URL` is preferred; `NEXT_PUBLIC_SITE_URL`
+ * is accepted as a backwards-compatible alias for storefronts scaffolded before
+ * this resolver existed.
+ *
+ * The `NEXT_PUBLIC_` prefix was always a misnomer here — nothing client-side
+ * reads this value, every consumer is server-side — and the prefix implies a
+ * build-time inline that does not apply to server reads. Prefer `SITE_URL`.
+ */
+function fromExplicitEnv(): string | null {
+  return toOrigin(process.env.SITE_URL) ?? toOrigin(process.env.NEXT_PUBLIC_SITE_URL);
+}
+
+/**
+ * Origins injected by the hosting platform. These are present during
+ * `next build` as well as at runtime, so they answer correctly with no request
+ * in hand.
+ *
+ * Production domains are listed before per-deployment domains: a preview build
+ * must not stamp its throwaway URL into canonical tags.
+ *
+ * Netlify's `URL` is guarded behind `NETLIFY` — the bare name is too generic to
+ * trust on its own, and a merchant's own `URL` variable must not be mistaken
+ * for a site address.
+ */
+function fromPlatformEnv(): string | null {
+  const env = process.env;
+  const candidates = [
+    env.VERCEL_PROJECT_PRODUCTION_URL,
+    env.VERCEL_URL,
+    env.NETLIFY ? env.URL : undefined,
+    env.NETLIFY ? env.DEPLOY_PRIME_URL : undefined,
+    env.RENDER_EXTERNAL_URL,
+    env.RAILWAY_PUBLIC_DOMAIN,
+    env.CF_PAGES_URL,
+  ];
+  for (const candidate of candidates) {
+    const origin = toOrigin(candidate);
+    if (origin) return origin;
+  }
+  return null;
+}
+
+/**
+ * Origin derived from the incoming request.
+ *
+ * ⚠️ Caller-controlled. `curl -H 'Host: evil.example'` reaches this, so a
+ * storefront relying on it can have a canonical tag poisoned by whoever asks.
+ * That is an accepted trade for the AI-builder case — a sandbox injecting none
+ * of the platform vars above would otherwise have no correct source at all —
+ * and it disappears the moment `SITE_URL` is set, which is why every caller
+ * prefers the env.
+ */
+function fromForwardedHeaders(h: Headers): string | null {
+  // `x-forwarded-host` carries a comma-separated chain when several proxies
+  // append to it; the first entry is the original client-facing host.
+  const forwardedHost = h.get('x-forwarded-host')?.split(',')[0]?.trim();
+  const host = forwardedHost || h.get('host')?.trim();
+  if (!host) return null;
+  const proto =
+    h.get('x-forwarded-proto')?.split(',')[0]?.trim() || (isLoopback(host) ? 'http' : 'https');
+  return toOrigin(`${proto}://${host}`);
+}
+
+let warnedMissingSiteUrl = false;
+
+/**
+ * Alarm at the point of failure rather than fail open. Reaching the dev
+ * fallback in production means every absolute URL this process emits is wrong,
+ * and no downstream layer can detect that — a canonical tag pointing at
+ * localhost looks perfectly well-formed to a crawler.
+ */
+function warnUnresolved(): void {
+  if (warnedMissingSiteUrl || process.env.NODE_ENV !== 'production') return;
+  warnedMissingSiteUrl = true;
+  console.warn(
+    [
+      `[brainerce] Could not determine this storefront's public URL; falling back to ${DEV_FALLBACK}.`,
+      'Sitemap, robots.txt, canonical tags and JSON-LD will all be wrong.',
+      '  Fix: set SITE_URL to your public origin (e.g. SITE_URL=https://shop.example.com)',
+      "  in your hosting provider's environment variables.",
+      '  Also check the channel: a LIVE sales channel only accepts requests whose Origin',
+      '  matches the Domain configured on it. Add this host under Sales Channels -> your',
+      '  channel -> Domain in the Brainerce dashboard, or storefront API calls are rejected',
+      '  with 403 no matter what SITE_URL says.',
+    ].join('\n')
+  );
+}
+
+/**
+ * Env-only resolution, safe to call outside a request (module scope, build
+ * scripts, `next.config.ts`). Returns null rather than guessing.
+ */
+export function getSiteUrlFromEnv(): string | null {
+  return fromExplicitEnv() ?? fromPlatformEnv();
+}
+
+/**
+ * The origin this store should be known by — canonical tags, sitemap entries,
+ * JSON-LD `url` fields, OpenGraph. Stable across deploys when `SITE_URL` is set.
+ */
+export async function getCanonicalSiteUrl(): Promise<string> {
+  const configured = getSiteUrlFromEnv();
+  if (configured) return configured;
+
+  // Only reached when nothing is configured, so the `headers()` call — and the
+  // dynamic rendering it forces — is only paid in that case.
+  //
+  // ⛔ Deliberately NOT wrapped in try/catch. During static generation
+  // `headers()` throws Next's DynamicServerError, which is a *signal*, not a
+  // failure: Next catches it upstream and re-renders the route dynamically.
+  // Catching it here returns DEV_FALLBACK instead, and Next then bakes
+  // `http://localhost:3000` into the prerendered sitemap.xml and robots.txt —
+  // reproducing the exact bug this module exists to prevent. Verified: with
+  // the catch in place the build emitted localhost into `sitemap.xml.body`.
+  const fromRequest = fromForwardedHeaders(await headers());
+  if (fromRequest) return fromRequest;
+
+  warnUnresolved();
+  return DEV_FALLBACK;
+}
+
+/**
+ * The origin a request actually arrived on — used for the `Origin` header sent
+ * to the Brainerce backend, which must match the channel's configured domain.
+ *
+ * Pass the live request headers where you have them (route handlers, the BFF
+ * proxy); omit to read the ambient request context.
+ */
+export async function getRequestOrigin(requestHeaders?: Headers): Promise<string> {
+  // Same rule as above: no try/catch around the ambient `headers()` read, so
+  // Next's DynamicServerError propagates and the route is re-rendered
+  // dynamically rather than prerendered against a fallback origin.
+  const h = requestHeaders ?? (await headers());
+  const fromRequest = fromForwardedHeaders(h);
+  if (fromRequest) return fromRequest;
+
+  const configured = getSiteUrlFromEnv();
+  if (configured) return configured;
+
+  warnUnresolved();
+  return DEV_FALLBACK;
+}

package/templates/nextjs/base/src/ui/product/faq-section.tsx.ejs

@@ -0,0 +1,46 @@
+import type { Product } from 'brainerce';
+<% if (i18nEnabled) { %>import { getMessages, defaultLocale } from '@/i18n';<% } else { %>import { defaultLocale, messages } from '@/i18n';<% } %>
+
+type FaqStrings = Record<string, string>;
+
+<% if (i18nEnabled) { %>async function getFaqStrings(locale: string): Promise<FaqStrings> {
+  return ((await getMessages(locale)).faq ?? {}) as FaqStrings;
+}<% } else { %>async function getFaqStrings(_locale: string): Promise<FaqStrings> {
+  return ((messages as Record<string, unknown>).faq ?? {}) as FaqStrings;
+}<% } %>
+
+interface ProductFaqSectionProps {
+  product: Product;
+  locale?: string;
+}
+
+/**
+ * Visible product Q&A — the extractable question/answer format AI answer
+ * engines cite. The SAME pairs are emitted as FAQPage JSON-LD by
+ * <ProductJsonLd> (both read product.faq, so they can never drift). Server
+ * component on purpose: the pairs must be in the initial HTML payload — AI
+ * crawlers don't run JavaScript. Content inside a closed <details> is still
+ * present in the HTML, so the accordion costs nothing for extraction.
+ */
+export async function ProductFaqSection({
+  product,
+  locale = defaultLocale,
+}: ProductFaqSectionProps) {
+  const pairs = (product.faq ?? []).filter((item) => item?.q && item?.a);
+  if (pairs.length === 0) return null;
+  const t = await getFaqStrings(locale);
+
+  return (
+    <section className="mx-auto max-w-7xl px-4 py-10 sm:px-6 lg:px-8">
+      <h2 className="mb-6 text-2xl font-semibold">{t.title ?? 'Frequently asked questions'}</h2>
+      <div className="divide-y rounded-xl border">
+        {pairs.map((item) => (
+          <details key={item.q} className="px-5 py-4">
+            <summary className="cursor-pointer text-base font-medium">{item.q}</summary>
+            <p className="mt-2 text-sm leading-relaxed opacity-80">{item.a}</p>
+          </details>
+        ))}
+      </div>
+    </section>
+  );
+}