create-brainerce-store 1.75.0 → 1.76.0

package/templates/nextjs/base/src/components/referral/referral-greeting.tsx

@@ -0,0 +1,120 @@
+'use client';
+
+/**
+ * Referral landing greeting: the `?ref=` half of the loyalty program.
+ *
+ * A referral link is `https://your-store.com/?ref=<code>`, so this mounts on
+ * the home page (see `src/app/page.tsx`), which is where those links land.
+ *
+ * ⛔ `getReferralInfo()` IS THE ONE LOYALTY CALL THAT NEEDS NO CUSTOMER TOKEN.
+ * That is the entire reason this component can exist: it greets a visitor who
+ * has no account yet, which is precisely the audience a referral link is aimed
+ * at. Every other loyalty call requires a logged-in customer and would throw
+ * here.
+ *
+ * ⛔ IT AUTO-HIDES FOUR WAYS, AND RENDERS NOTHING IN ALL OF THEM: no `?ref=` in
+ * the URL, a malformed code, the merchant has referrals switched off
+ * (`hasReferralProgram`), or the API says the code is not valid. A store with
+ * no loyalty program never sees a trace of this. Build it anyway: the merchant
+ * turns referrals on from the dashboard without touching this code.
+ *
+ * ⛔ CAPTURING MATTERS MORE THAN GREETING. The banner is the visible half, but
+ * the useful half is `writeReferralCookie()`: almost nobody registers on the
+ * page they land on, so the code is persisted the moment it arrives and read
+ * back by the register form whenever the shopper gets round to signing up. Drop
+ * the banner in a redesign if you like; do not drop the capture, or referrers
+ * stop being credited and the failure is completely invisible.
+ *
+ * ⛔ Must be rendered inside a `<Suspense>` boundary. It uses
+ * `useSearchParams()`, which opts the whole route out of static rendering
+ * otherwise.
+ */
+
+import { useEffect, useState } from 'react';
+import { useSearchParams } from 'next/navigation';
+import type { ReferralInfo } from 'brainerce';
+import { Link } from '@/core/lib/navigation';
+import { getClient } from '@/core/lib/brainerce';
+import { useStoreCapabilities } from '@/core/providers/store-provider';
+import {
+  isGreetableReferral,
+  normalizeReferralCode,
+  writeReferralCookie,
+} from '@/core/lib/referral';
+import { useTranslations } from '@/core/lib/translations';
+import { cn } from '@/core/lib/utils';
+
+interface ReferralGreetingProps {
+  className?: string;
+}
+
+export function ReferralGreeting({ className }: ReferralGreetingProps) {
+  const t = useTranslations('loyalty');
+  const searchParams = useSearchParams();
+  const { capabilities } = useStoreCapabilities();
+  const [info, setInfo] = useState<ReferralInfo | null>(null);
+
+  const code = normalizeReferralCode(searchParams.get('ref'));
+
+  /**
+   * Capabilities are fetched once at boot and are null until they land, or
+   * forever if that fetch failed. Only an explicit `false` suppresses the
+   * lookup, mirroring `canOfferStockAlert()`: an undecided flag must not
+   * swallow a real referral, and `getReferralInfo()` independently answers
+   * `{ valid: false }` when the program is off, so the feature stays correct
+   * either way.
+   */
+  const referralsOff = capabilities?.features.hasReferralProgram === false;
+
+  useEffect(() => {
+    if (!code || referralsOff) return;
+
+    let cancelled = false;
+    getClient()
+      .getReferralInfo(code)
+      .then((result) => {
+        if (cancelled || !result.valid) return;
+        // Persist BEFORE rendering anything. The visitor may navigate away in
+        // the same second, and the code is the part that has to survive.
+        writeReferralCookie(code);
+        setInfo(result);
+      })
+      .catch(() => {
+        // Swallowed on purpose. An unreachable API on a landing page must not
+        // break the home page, and there is nothing useful to say to a shopper
+        // who does not yet know a referral was involved.
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [code, referralsOff]);
+
+  if (!isGreetableReferral(info)) return null;
+
+  const greeting = info.referrerFirstName
+    ? t('referralGreeting', { name: info.referrerFirstName })
+    : t('referralGreetingAnonymous');
+
+  return (
+    <aside
+      className={cn(
+        'border-primary/20 bg-primary/5 mx-auto max-w-3xl rounded-lg border px-4 py-3',
+        className
+      )}
+    >
+      <p className="text-foreground font-medium">{greeting}</p>
+      {info.reward && (
+        <p className="text-muted-foreground mt-1 text-sm">
+          {t('referralReward', { reward: info.reward.name })}
+        </p>
+      )}
+      <Link
+        href="/register"
+        className="text-primary mt-2 inline-flex text-sm font-medium underline underline-offset-2"
+      >
+        {t('referralCta')}
+      </Link>
+    </aside>
+  );
+}

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

@@ -1,155 +1,162 @@
-/**
- * Client-side auth helpers.
- *
- * Everything the SDK covers goes through an SDK method. Never hand-build a
- * REST path: the SDK owns the URL shape, and a string built here silently
- * rots the day a route moves. `getClient()` is configured with
- * `baseUrl: '/api/store'` + `proxyMode`, so each call still lands on the
- * same-origin BFF proxy, which adds the Authorization header from the
- * httpOnly cookie and strips the token out of the response. The SDK adds the
- * CSRF header the proxy requires on every non-GET request.
- *
- * Only the routes with no SDK equivalent are plain fetches: `/api/auth/me`,
- * `/api/auth/logout` and `/api/auth/reset-password` are this app's own Next
- * route handlers, not Brainerce endpoints.
- *
- * The token is managed server-side via httpOnly cookies, never exposed to JS.
- */
-import { getClient } from '@/core/lib/brainerce';
-
-const CSRF_HEADERS: Record<string, string> = {
-  'Content-Type': 'application/json',
-  'X-Requested-With': 'brainerce',
-};
-
-interface LoginResult {
-  customer: {
-    id: string;
-    email: string;
-    firstName?: string;
-    lastName?: string;
-    emailVerified: boolean;
-  };
-  expiresAt: string;
-  requiresVerification?: boolean;
-}
-
-interface RegisterResult {
-  customer: {
-    id: string;
-    email: string;
-    firstName?: string;
-    lastName?: string;
-    emailVerified: boolean;
-  };
-  expiresAt: string;
-  requiresVerification?: boolean;
-}
-
-interface AuthStatus {
-  isLoggedIn: boolean;
-  customer?: {
-    id: string;
-    email: string;
-    firstName?: string;
-    lastName?: string;
-    phone?: string;
-    emailVerified: boolean;
-  };
-  error?: string;
-}
-
-interface VerifyEmailResult {
-  verified: boolean;
-  message?: string;
-}
-
-async function handleResponse<T>(response: Response): Promise<T> {
-  const data = await response.json();
-  if (!response.ok) {
-    throw new Error(data.message || data.error || `Request failed (${response.status})`);
-  }
-  return data as T;
-}
-
-/**
- * Login via the SDK, routed through the BFF proxy, which sets the httpOnly
- * cookie on success and strips the token from the response. The narrow
- * `LoginResult` return type is deliberate: the SDK's own response type
- * declares a `token`, but the proxy removes it before it reaches the browser,
- * so nothing here should read one.
- */
-export async function proxyLogin(email: string, password: string): Promise<LoginResult> {
-  return getClient().loginCustomer(email, password);
-}
-
-/**
- * Register via the SDK, routed through the BFF proxy, which sets the httpOnly
- * cookie on success.
- */
-export async function proxyRegister(data: {
-  firstName: string;
-  lastName: string;
-  email: string;
-  password: string;
-  acceptsMarketing?: boolean;
-  /**
-   * Birthday month (1-12) and day (1-31), never a year. Powers the loyalty
-   * birthday gift. Send both or neither: one without the other is rejected
-   * with HTTP 400, and so is a day the month does not have. Required only when
-   * `getStoreInfo().requireBirthday` is true for this sales channel.
-   */
-  birthMonth?: number;
-  birthDay?: number;
-}): Promise<RegisterResult> {
-  return getClient().registerCustomer(data);
-}
-
-/**
- * Check auth status. Reads httpOnly cookie server-side and validates with backend.
- */
-export async function checkAuthStatus(): Promise<AuthStatus> {
-  const response = await fetch('/api/auth/me');
-  return response.json();
-}
-
-/**
- * Logout. Clears httpOnly auth cookies server-side.
- */
-export async function proxyLogout(): Promise<void> {
-  await fetch('/api/auth/logout', {
-    method: 'POST',
-    headers: { 'X-Requested-With': 'brainerce' },
-  });
-}
-
-/**
- * Verify email via the SDK. No token argument is passed: the auth token lives
- * in the httpOnly cookie (set during login/register) and the proxy attaches
- * the Authorization header. The SDK skips its own token check in proxy mode.
- */
-export async function proxyVerifyEmail(code: string): Promise<VerifyEmailResult> {
-  return getClient().verifyEmail(code);
-}
-
-/**
- * Resend the verification email via the SDK. Uses the auth token from the
- * httpOnly cookie, added by the proxy. Rate limited to 3 requests per hour.
- */
-export async function proxyResendVerification(): Promise<{ message: string }> {
-  return getClient().resendVerificationEmail();
-}
-
-/**
- * Reset password via BFF proxy.
- * The reset token is in an httpOnly cookie (set by /api/auth/reset-callback when the user
- * clicked the email link). The proxy reads it server-side — the token never reaches client JS.
- */
-export async function proxyResetPassword(newPassword: string): Promise<{ message: string }> {
-  const response = await fetch('/api/auth/reset-password', {
-    method: 'POST',
-    headers: CSRF_HEADERS,
-    body: JSON.stringify({ newPassword }),
-  });
-  return handleResponse<{ message: string }>(response);
-}
+/**
+ * Client-side auth helpers.
+ *
+ * Everything the SDK covers goes through an SDK method. Never hand-build a
+ * REST path: the SDK owns the URL shape, and a string built here silently
+ * rots the day a route moves. `getClient()` is configured with
+ * `baseUrl: '/api/store'` + `proxyMode`, so each call still lands on the
+ * same-origin BFF proxy, which adds the Authorization header from the
+ * httpOnly cookie and strips the token out of the response. The SDK adds the
+ * CSRF header the proxy requires on every non-GET request.
+ *
+ * Only the routes with no SDK equivalent are plain fetches: `/api/auth/me`,
+ * `/api/auth/logout` and `/api/auth/reset-password` are this app's own Next
+ * route handlers, not Brainerce endpoints.
+ *
+ * The token is managed server-side via httpOnly cookies, never exposed to JS.
+ */
+import { getClient } from '@/core/lib/brainerce';
+
+const CSRF_HEADERS: Record<string, string> = {
+  'Content-Type': 'application/json',
+  'X-Requested-With': 'brainerce',
+};
+
+interface LoginResult {
+  customer: {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    emailVerified: boolean;
+  };
+  expiresAt: string;
+  requiresVerification?: boolean;
+}
+
+interface RegisterResult {
+  customer: {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    emailVerified: boolean;
+  };
+  expiresAt: string;
+  requiresVerification?: boolean;
+}
+
+interface AuthStatus {
+  isLoggedIn: boolean;
+  customer?: {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    emailVerified: boolean;
+  };
+  error?: string;
+}
+
+interface VerifyEmailResult {
+  verified: boolean;
+  message?: string;
+}
+
+async function handleResponse<T>(response: Response): Promise<T> {
+  const data = await response.json();
+  if (!response.ok) {
+    throw new Error(data.message || data.error || `Request failed (${response.status})`);
+  }
+  return data as T;
+}
+
+/**
+ * Login via the SDK, routed through the BFF proxy, which sets the httpOnly
+ * cookie on success and strips the token from the response. The narrow
+ * `LoginResult` return type is deliberate: the SDK's own response type
+ * declares a `token`, but the proxy removes it before it reaches the browser,
+ * so nothing here should read one.
+ */
+export async function proxyLogin(email: string, password: string): Promise<LoginResult> {
+  return getClient().loginCustomer(email, password);
+}
+
+/**
+ * Register via the SDK, routed through the BFF proxy, which sets the httpOnly
+ * cookie on success.
+ */
+export async function proxyRegister(data: {
+  firstName: string;
+  lastName: string;
+  email: string;
+  password: string;
+  acceptsMarketing?: boolean;
+  /**
+   * Birthday month (1-12) and day (1-31), never a year. Powers the loyalty
+   * birthday gift. Send both or neither: one without the other is rejected
+   * with HTTP 400, and so is a day the month does not have. Required only when
+   * `getStoreInfo().requireBirthday` is true for this sales channel.
+   */
+  birthMonth?: number;
+  birthDay?: number;
+  /**
+   * Loyalty referral share code, captured from a `?ref=` link on the way in and
+   * read back out of the cookie by the register form. Validated asynchronously
+   * after registration: a stale or unknown code never fails the registration
+   * itself, so it is always safe to send whatever was captured.
+   */
+  referralCode?: string;
+}): Promise<RegisterResult> {
+  return getClient().registerCustomer(data);
+}
+
+/**
+ * Check auth status. Reads httpOnly cookie server-side and validates with backend.
+ */
+export async function checkAuthStatus(): Promise<AuthStatus> {
+  const response = await fetch('/api/auth/me');
+  return response.json();
+}
+
+/**
+ * Logout. Clears httpOnly auth cookies server-side.
+ */
+export async function proxyLogout(): Promise<void> {
+  await fetch('/api/auth/logout', {
+    method: 'POST',
+    headers: { 'X-Requested-With': 'brainerce' },
+  });
+}
+
+/**
+ * Verify email via the SDK. No token argument is passed: the auth token lives
+ * in the httpOnly cookie (set during login/register) and the proxy attaches
+ * the Authorization header. The SDK skips its own token check in proxy mode.
+ */
+export async function proxyVerifyEmail(code: string): Promise<VerifyEmailResult> {
+  return getClient().verifyEmail(code);
+}
+
+/**
+ * Resend the verification email via the SDK. Uses the auth token from the
+ * httpOnly cookie, added by the proxy. Rate limited to 3 requests per hour.
+ */
+export async function proxyResendVerification(): Promise<{ message: string }> {
+  return getClient().resendVerificationEmail();
+}
+
+/**
+ * Reset password via BFF proxy.
+ * The reset token is in an httpOnly cookie (set by /api/auth/reset-callback when the user
+ * clicked the email link). The proxy reads it server-side — the token never reaches client JS.
+ */
+export async function proxyResetPassword(newPassword: string): Promise<{ message: string }> {
+  const response = await fetch('/api/auth/reset-password', {
+    method: 'POST',
+    headers: CSRF_HEADERS,
+    body: JSON.stringify({ newPassword }),
+  });
+  return handleResponse<{ message: string }>(response);
+}

package/templates/nextjs/base/src/core/lib/referral.ts

@@ -0,0 +1,95 @@
+/**
+ * CLIENT-SAFE referral-code capture.
+ *
+ * ## Why a cookie, and why it outlives the visit
+ *
+ * A referral link is `https://your-store.com/?ref=<code>` (the shape the
+ * dashboard builds around `LoyaltyStatus.referralCode`). It lands on the home
+ * page, and almost nobody registers on that first page view: they browse, they
+ * leave, they come back. If the code lives in component state it is gone the
+ * moment they click a product, the referrer never gets credited, and the
+ * shopper never gets the welcome reward they were promised. So it is persisted
+ * the instant it arrives and read back at registration, however much later.
+ *
+ * Same reasoning and same shape as `region.ts`: not `httpOnly`, because a
+ * client component both writes it and reads it, and it holds a public share
+ * code that was already sitting in the URL.
+ */
+
+import type { ReferralInfo } from 'brainerce';
+
+export const REFERRAL_COOKIE = 'brainerce_referral';
+
+/**
+ * Thirty days. Long enough to cover browse-then-return-later, short enough that
+ * a code does not silently attach itself to an account created months later by
+ * a different person on a shared machine.
+ */
+const REFERRAL_COOKIE_MAX_AGE = 60 * 60 * 24 * 30;
+
+/** Codes are `REF-XXXXXXXX` today; the cap leaves room for that to change. */
+const MAX_REFERRAL_CODE_LENGTH = 64;
+
+/**
+ * Accept only a plausible share code.
+ *
+ * The value comes from the query string, which anybody can write anything into.
+ * It ends up in a cookie and in a registration payload, so it is charset- and
+ * length-checked here rather than trusted: `encodeURIComponent` already stops a
+ * `;` from splitting the cookie, and this stops the rest of the nonsense from
+ * being stored at all. An unknown-but-well-formed code is not rejected here on
+ * purpose; `getReferralInfo()` is the authority on whether it is real.
+ */
+export function normalizeReferralCode(raw: string | null | undefined): string | null {
+  if (!raw) return null;
+  const code = raw.trim();
+  if (!code || code.length > MAX_REFERRAL_CODE_LENGTH) return null;
+  if (!/^[A-Za-z0-9_-]+$/.test(code)) return null;
+  return code;
+}
+
+/** Read the captured referral code in the browser. Returns null during SSR. */
+export function readReferralCookie(): string | null {
+  if (typeof document === 'undefined') return null;
+  const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${REFERRAL_COOKIE}=([^;]*)`));
+  return match ? normalizeReferralCode(decodeURIComponent(match[1])) : null;
+}
+
+/**
+ * Persist a captured referral code. `SameSite=Lax` so the code survives the
+ * click in from an email, a social post or a messaging app, which is where
+ * referral links actually live; `Secure` only off localhost, where there is no
+ * https to attach it to.
+ */
+export function writeReferralCookie(code: string): void {
+  if (typeof document === 'undefined') return;
+  const safe = normalizeReferralCode(code);
+  if (!safe) return;
+  const secure = typeof location !== 'undefined' && location.protocol === 'https:';
+  document.cookie =
+    `${REFERRAL_COOKIE}=${encodeURIComponent(safe)}; path=/; max-age=${REFERRAL_COOKIE_MAX_AGE}; SameSite=Lax` +
+    (secure ? '; Secure' : '');
+}
+
+/**
+ * Drop the captured code. Called once registration succeeds: the code has been
+ * spent, and leaving it behind would attach the same referrer to the next
+ * account created in this browser.
+ */
+export function clearReferralCookie(): void {
+  if (typeof document === 'undefined') return;
+  document.cookie = `${REFERRAL_COOKIE}=; path=/; max-age=0; SameSite=Lax`;
+}
+
+/**
+ * Whether a referral lookup is worth greeting the visitor about.
+ *
+ * `getReferralInfo()` answers `{ valid: false }` for an unknown code, a
+ * disabled referral program and an inactive program alike, so this is the only
+ * gate that matters after the call. A valid referral with no configured reward
+ * is still worth showing: the referrer's name is the reason the visitor
+ * clicked.
+ */
+export function isGreetableReferral(info: ReferralInfo | null): info is ReferralInfo {
+  return info !== null && info.valid;
+}

package/templates/nextjs/base/src/ui/product/product-card.tsx

@@ -63,6 +63,11 @@ export function ProductCard({ product, className }: ProductCardProps) {
   const [adding, setAdding] = useState(false);
   const [added, setAdded] = useState(false);
 
+  // `!== false`, not `=== true`, and that matters for KIT products: a kit
+  // carries NO `inventory` object of its own (its availability is derived from
+  // its components), so a strict truthy check would render every kit as out of
+  // stock. A kit also falls through `isVariable` above and adds by `productId`
+  // alone, which is correct — kits take no variantId and no selections.
   const canPurchase = product.inventory?.canPurchase !== false;
 
   async function handleAddToCart(e: React.MouseEvent) {

package/templates/nextjs/designs/atelier/ui/product/product-card.tsx

@@ -63,6 +63,11 @@ export function ProductCard({ product, className }: ProductCardProps) {
   const [adding, setAdding] = useState(false);
   const [added, setAdded] = useState(false);
 
+  // `!== false`, not `=== true`, and that matters for KIT products: a kit
+  // carries NO `inventory` object of its own (its availability is derived from
+  // its components), so a strict truthy check would render every kit as out of
+  // stock. A kit also falls through `isVariable` above and adds by `productId`
+  // alone, which is correct — kits take no variantId and no selections.
   const canPurchase = product.inventory?.canPurchase !== false;
 
   const imageWellRef = useRef<HTMLDivElement>(null);

package/templates/nextjs/ui-canvas/product/product-card.tsx

@@ -58,6 +58,11 @@ export function ProductCard({ product, className }: ProductCardProps) {
   const [adding, setAdding] = useState(false);
   const [added, setAdded] = useState(false);
 
+  // `!== false`, not `=== true`, and that matters for KIT products: a kit
+  // carries NO `inventory` object of its own (its availability is derived from
+  // its components), so a strict truthy check would render every kit as out of
+  // stock. A kit also falls through `isVariable` above and adds by `productId`
+  // alone, which is correct — kits take no variantId and no selections.
   const canPurchase = product.inventory?.canPurchase !== false;
 
   async function handleAddToCart(e: React.MouseEvent) {