@forgecart/cli 2.202608121449.0 → 2.202608200713.0

package/templates/storefront/src/lib/forgecart.ts

@@ -1,7 +1,8 @@
-import { ForgeCartShopClient } from '@forgecart/sdk';
+import 'server-only';
+
+import { ForgeCartShopClient } from '@forgecart/sdk/shop';
 import type {
   ShopProductFieldFragment as Product,
-  ShopSellingPlanFieldFragment as SellingPlan,
   ShopSellingPlanGroupFieldFragment as SellingPlanGroup,
 } from '@forgecart/sdk/shop';
 
@@ -20,9 +21,14 @@ import type {
  *   - FORGECART_SHOP_API_URL  -> endpoint
  *   - FORGECART_CHANNEL_TOKEN -> channelToken
  *
- * This module is server-only: it is imported exclusively from Server
- * Components, so the channel token never reaches the browser. The construction
- * mirrors the dashboard's `SdkClientService` (see
+ * This module is server-only — the `import 'server-only'` above makes a client
+ * component's value-import of it a BUILD error, so the channel token and the
+ * SDK's websocket transport can never reach the browser. The same guard sits
+ * on every SDK-bearing server module (`cart-actions.ts` today; any future
+ * action module talking to the shop API adopts it the same way). Client
+ * components may still `import type` from here — type imports erase. Pure
+ * display helpers live in `./format`, which client components import freely.
+ * The construction mirrors the dashboard's `SdkClientService` (see
  * app/dashboard/src/service/sdk-client.service.ts), adapted to read from env.
  */
 
@@ -77,6 +83,48 @@ export type {
   ShopSellingPlanGroupFieldFragment as SellingPlanGroup,
 } from '@forgecart/sdk/shop';
 
+// Checkout-flow result types, aliased off the generated operation results so
+// the components and Server Actions speak the SDK's own shapes (indexed
+// access keeps them exactly as selected — no parallel hand-written types).
+import type {
+  AvailableCountriesQuery,
+  ConfirmPaymentSessionMutation,
+  CreatePaymentSessionMutation,
+  GetSessionTemplateQuery,
+  GetSessionVariablesQuery,
+  RefreshShippingRateGroupsMutation,
+  ShopEligiblePaymentProvidersQuery,
+  ShopOrderByCodeQuery,
+} from '@forgecart/sdk/shop';
+
+export type Country = AvailableCountriesQuery['availableCountries'][number];
+export type ShippingRateGroup =
+  RefreshShippingRateGroupsMutation['refreshShippingRateGroups'][number];
+export type ShippingRate = ShippingRateGroup['rates'][number];
+export type EligiblePaymentProvider =
+  ShopEligiblePaymentProvidersQuery['eligiblePaymentProviders'][number];
+export type PaymentSession = CreatePaymentSessionMutation['createPaymentSession'];
+export type PaymentTemplate = GetSessionTemplateQuery['getSessionTemplate'];
+export type PaymentVariables = GetSessionVariablesQuery['getSessionVariables'];
+export type ConfirmedPaymentSession = ConfirmPaymentSessionMutation['confirmPaymentSession'];
+export type CheckoutOrder = NonNullable<ShopOrderByCodeQuery['orderByCode']>;
+
+/**
+ * The order fields the checkout flow renders and gates on — the structural
+ * common denominator of every checkout mutation's Order selection (each
+ * operation selects a slightly different super-set of these, so no single
+ * generated type fits them all; this view is the one deliberate non-SDK
+ * shape, and every SDK result assigns to it).
+ */
+export interface CheckoutOrderView {
+  id: string;
+  code: string;
+  state: string;
+  currencyCode: string;
+  totalWithTax: number;
+  totalQuantity: number;
+}
+
 /**
  * Fetch a page of products for the channel.
  *
@@ -114,7 +162,8 @@ export async function getFeaturedProducts(count = 4): Promise<Product[]> {
 export async function getSellingPlanGroupsForVariant(
   variantId: string,
 ): Promise<SellingPlanGroup[]> {
-  const { sellingPlanGroupsForVariant } = await getShopClient().sellingPlan.sellingPlanGroupsForVariant({ variantId });
+  const { sellingPlanGroupsForVariant } =
+    await getShopClient().sellingPlan.sellingPlanGroupsForVariant({ variantId });
   return sellingPlanGroupsForVariant;
 }
 
@@ -125,77 +174,11 @@ export async function getChannelSellingPlanGroups(): Promise<SellingPlanGroup[]>
 }
 
 /**
- * Preview the per-unit price a plan yields from the one-time `priceWithTax`.
- *
- * Mirrors the server's pricing policy: `none` keeps the price, `percentage`
- * applies the percent discount (rounded to whole minor units), `fixed_amount`
- * subtracts the minor-unit adjustment (floored at zero). A `null`
- * `adjustmentValue` (only valid for `none`) is treated as no adjustment.
- */
-export function getPlanPreviewPrice(basePrice: number, plan: SellingPlan): number {
-  if (plan.pricingPolicy === 'percentage') {
-    const adjustment = plan.adjustmentValue ?? 0;
-    // `adjustmentValue` is a whole-number percent (e.g. 15 -> 15% off).
-    const PERCENT_BASE = 100;
-    return Math.round(basePrice * (1 - adjustment / PERCENT_BASE));
-  }
-  if (plan.pricingPolicy === 'fixed_amount') {
-    return Math.max(0, basePrice - (plan.adjustmentValue ?? 0));
-  }
-  return basePrice;
-}
-
-/**
- * A short human-readable savings hint for a plan, or `null` when it offers no
- * discount (policy `none`, a zero adjustment, or a non-positive percentage).
- */
-export function getPlanSavingsLabel(plan: SellingPlan, currency = 'USD'): string | null {
-  if (plan.pricingPolicy === 'percentage' && (plan.adjustmentValue ?? 0) > 0) {
-    return `Save ${plan.adjustmentValue}%`;
-  }
-  if (plan.pricingPolicy === 'fixed_amount' && (plan.adjustmentValue ?? 0) > 0) {
-    return `Save ${formatPrice(plan.adjustmentValue ?? 0, currency)}`;
-  }
-  return null;
-}
-
-/**
- * The billing cadence as a phrase, e.g. "every 1 monthly" or "every 2 weekly",
- * built from the plan's interval count and the (lower-cased) billing interval.
- */
-export function getPlanCadenceLabel(plan: SellingPlan): string {
-  return `every ${plan.intervalCount} ${plan.billingInterval.toLowerCase()}`;
-}
-
-/** Lowest variant price for a product, in minor units, or `null` if none. */
-export function getStartingPrice(product: Product): number | null {
-  if (product.variants.length === 0) {
-    return null;
-  }
-  return product.variants.reduce(
-    (min, v) => (v.priceWithTax < min ? v.priceWithTax : min),
-    product.variants[0].priceWithTax,
-  );
-}
-
-/**
- * Format a minor-unit price as a currency string. Defaults to USD; pass a
- * different ISO currency code as needed.
- *
- * ForgeCart prices are integers in the currency's smallest denomination, so
- * the divisor depends on the currency's ISO-4217 exponent: 2500 is $25.00
- * (two-decimal cents) but ¥2,500 (zero-decimal yen) and BHD 2.500
- * (three-decimal fils). The exponent is derived from the same
- * `Intl.NumberFormat` instance that renders the price — its
- * `resolvedOptions().maximumFractionDigits` carries the CLDR fraction digits
- * for the currency — so the divisor always agrees with the digits shown,
- * with a defensive fallback of 2 should the formatter resolve none.
+ * Countries the channel ships to — a PUBLIC channel read (no session), so it
+ * belongs on this server singleton: the checkout page prefetches it and hands
+ * the list to the client flow.
  */
-export function formatPrice(minorUnits: number, currency = 'USD'): string {
-  const formatter = new Intl.NumberFormat('en-US', {
-    style: 'currency',
-    currency,
-  });
-  const exponent = formatter.resolvedOptions().maximumFractionDigits ?? 2;
-  return formatter.format(minorUnits / 10 ** exponent);
+export async function getAvailableCountries(): Promise<Country[]> {
+  const { availableCountries } = await getShopClient().country.availableCountries();
+  return availableCountries;
 }

package/templates/storefront/src/lib/format.ts

@@ -0,0 +1,91 @@
+import type {
+  ShopProductFieldFragment as Product,
+  ShopSellingPlanFieldFragment as SellingPlan,
+} from '@forgecart/sdk/shop';
+
+/**
+ * Pure display helpers over SDK types — safe to import from ANY component.
+ *
+ * This module carries no runtime SDK dependency: the `@forgecart/sdk/shop`
+ * import above is type-only, so it erases at compile time and none of the
+ * client (`ForgeCartShopClient`, graphql-ws) ever reaches a browser bundle.
+ * Client components import their formatting from here; the SDK-bearing
+ * modules (`forgecart.ts`, `cart-actions.ts`) are `server-only` and reject a
+ * client value-import at build time.
+ */
+
+/**
+ * Format a minor-unit price as a currency string. Defaults to USD; pass a
+ * different ISO currency code as needed.
+ *
+ * ForgeCart prices are integers in the currency's smallest denomination, so
+ * the divisor depends on the currency's ISO-4217 exponent: 2500 is $25.00
+ * (two-decimal cents) but ¥2,500 (zero-decimal yen) and BHD 2.500
+ * (three-decimal fils). The exponent is derived from the same
+ * `Intl.NumberFormat` instance that renders the price — its
+ * `resolvedOptions().maximumFractionDigits` carries the CLDR fraction digits
+ * for the currency — so the divisor always agrees with the digits shown,
+ * with a defensive fallback of 2 should the formatter resolve none.
+ */
+export function formatPrice(minorUnits: number, currency = 'USD'): string {
+  const formatter = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+  });
+  const exponent = formatter.resolvedOptions().maximumFractionDigits ?? 2;
+  return formatter.format(minorUnits / 10 ** exponent);
+}
+
+/** Lowest variant price for a product, in minor units, or `null` if none. */
+export function getStartingPrice(product: Product): number | null {
+  if (product.variants.length === 0) {
+    return null;
+  }
+  return product.variants.reduce(
+    (min, v) => (v.priceWithTax < min ? v.priceWithTax : min),
+    product.variants[0].priceWithTax,
+  );
+}
+
+/**
+ * Preview the per-unit price a plan yields from the one-time `priceWithTax`.
+ *
+ * Mirrors the server's pricing policy: `none` keeps the price, `percentage`
+ * applies the percent discount (rounded to whole minor units), `fixed_amount`
+ * subtracts the minor-unit adjustment (floored at zero). A `null`
+ * `adjustmentValue` (only valid for `none`) is treated as no adjustment.
+ */
+export function getPlanPreviewPrice(basePrice: number, plan: SellingPlan): number {
+  if (plan.pricingPolicy === 'percentage') {
+    const adjustment = plan.adjustmentValue ?? 0;
+    // `adjustmentValue` is a whole-number percent (e.g. 15 -> 15% off).
+    const PERCENT_BASE = 100;
+    return Math.round(basePrice * (1 - adjustment / PERCENT_BASE));
+  }
+  if (plan.pricingPolicy === 'fixed_amount') {
+    return Math.max(0, basePrice - (plan.adjustmentValue ?? 0));
+  }
+  return basePrice;
+}
+
+/**
+ * A short human-readable savings hint for a plan, or `null` when it offers no
+ * discount (policy `none`, a zero adjustment, or a non-positive percentage).
+ */
+export function getPlanSavingsLabel(plan: SellingPlan, currency = 'USD'): string | null {
+  if (plan.pricingPolicy === 'percentage' && (plan.adjustmentValue ?? 0) > 0) {
+    return `Save ${plan.adjustmentValue}%`;
+  }
+  if (plan.pricingPolicy === 'fixed_amount' && (plan.adjustmentValue ?? 0) > 0) {
+    return `Save ${formatPrice(plan.adjustmentValue ?? 0, currency)}`;
+  }
+  return null;
+}
+
+/**
+ * The billing cadence as a phrase, e.g. "every 1 monthly" or "every 2 weekly",
+ * built from the plan's interval count and the (lower-cased) billing interval.
+ */
+export function getPlanCadenceLabel(plan: SellingPlan): string {
+  return `every ${plan.intervalCount} ${plan.billingInterval.toLowerCase()}`;
+}

package/templates/storefront/src/lib/session-actions.ts

@@ -0,0 +1,54 @@
+'use server';
+
+import 'server-only';
+
+import { cookies } from 'next/headers';
+
+/**
+ * Session custody glue for the PROGRESSIVE stack.
+ *
+ * The shopper's session lives CLIENT-SIDE (the browser's own shop websocket
+ * mints and carries it — see `shop-session.ts`); the server only needs to
+ * SEE it so SSR (checkout gating, any future server read) stays coherent
+ * with the cart the shopper built over their socket. Two cookies, one value:
+ *
+ *   - `forgecart-session`        httpOnly — the server-readable copy.
+ *   - `forgecart-session-client` JS-readable mirror — what the browser
+ *                                socket boots from on the next visit.
+ *
+ * The mirror is deliberately not httpOnly: the session token is the
+ *shopper's own low-privilege shop session (channel-scoped; the admin secret
+ * never reaches the browser), and the client socket cannot exist without
+ * reading it. Both cookies always carry the same value — this action is the
+ * single writer.
+ */
+
+const SESSION_COOKIE = 'forgecart-session';
+const SESSION_MIRROR_COOKIE = 'forgecart-session-client';
+const SESSION_MAX_AGE = 60 * 60 * 24 * 30;
+/** Session tokens are opaque but bounded — reject junk before it hits a header. */
+const MAX_TOKEN_LENGTH = 512;
+
+/**
+ * Persist (or clear, with `null`) the client-minted session token into both
+ * cookies. Called by the browser session layer whenever its socket captures
+ * a new token; idempotent when the value already matches.
+ */
+export async function syncShopSession(token: string | null): Promise<void> {
+  const store = await cookies();
+  if (token === null) {
+    store.delete(SESSION_COOKIE);
+    store.delete(SESSION_MIRROR_COOKIE);
+    return;
+  }
+  if (token.length === 0 || token.length > MAX_TOKEN_LENGTH) return;
+  if (
+    store.get(SESSION_COOKIE)?.value === token &&
+    store.get(SESSION_MIRROR_COOKIE)?.value === token
+  ) {
+    return;
+  }
+  const shared = { sameSite: 'lax' as const, path: '/', maxAge: SESSION_MAX_AGE };
+  store.set(SESSION_COOKIE, token, { ...shared, httpOnly: true });
+  store.set(SESSION_MIRROR_COOKIE, token, { ...shared, httpOnly: false });
+}

package/templates/storefront/src/lib/shop-config.ts

@@ -0,0 +1,44 @@
+import 'server-only';
+
+/**
+ * The channel's shop-API coordinates, read once from the environment
+ * (`forgecart init` writes them into `.env`).
+ *
+ * Two consumers, two exposure levels — and potentially TWO URLS (split
+ * horizon):
+ *   - Server modules (`forgecart.ts`, the embedded backend) read
+ *     `FORGECART_SHOP_API_URL` — in a workspace pod that is an INTERNAL
+ *     address (docker bridge / cluster network) only the pod can reach.
+ *   - The BROWSER receives its config via {@link getBrowserShopConfig} — the
+ *     layout serializes it into the client `CartProvider`, which boots the
+ *     shopper's own session websocket. The browser needs the PUBLIC
+ *     `FORGECART_SHOP_API_BROWSER_URL` (HTTPS, so the socket runs over WSS —
+ *     an internal ws:// endpoint is mixed content on an HTTPS page and
+ *     unreachable from a shopper's machine anyway). When the browser URL is
+ *     absent, the server URL serves both sides (deployed storefronts and
+ *     loopback dev, where one origin is reachable from everywhere).
+ *
+ * The channel token is the shop API's PUBLIC storefront token (it scopes
+ * reads/writes to the channel and a shopper session); the admin secret never
+ * takes this path.
+ */
+
+const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
+const SHOP_API_BROWSER_URL = process.env.FORGECART_SHOP_API_BROWSER_URL ?? SHOP_API_URL;
+const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
+
+export interface BrowserShopConfig {
+  apiUrl: string;
+  channelToken: string;
+}
+
+/** Whether `forgecart init` has written the shop env yet (pre-warm renders without it). */
+export function isShopConfigured(): boolean {
+  return Boolean(SHOP_API_URL && CHANNEL_TOKEN);
+}
+
+/** The client-socket coordinates, or null on an unconfigured scaffold. */
+export function getBrowserShopConfig(): BrowserShopConfig | null {
+  if (!isShopConfigured()) return null;
+  return { apiUrl: SHOP_API_BROWSER_URL, channelToken: CHANNEL_TOKEN };
+}

package/templates/storefront/src/lib/shop-session.ts

@@ -0,0 +1,114 @@
+'use client';
+
+// The /shop subpath is the ONLY SDK entry browser code may import: the SDK
+// compiles to CommonJS (never tree-shaken), and only the /shop module graph
+// is guaranteed admin-free — the root barrel would bundle the admin client
+// into every shopper's browser (the pod image build greps chunks for exactly
+// that and fails).
+import { ForgeCartShopClient, extractError } from '@forgecart/sdk/shop';
+
+import { UNREACHABLE_ERROR, type ActionResult } from './action-result';
+import { syncShopSession } from './session-actions';
+
+/**
+ * The shopper's OWN shop websocket — the client half of the progressive
+ * stack. Sockets are session-based, so the session socket lives where the
+ * session lives: in the browser, one long-lived client per tab. The server
+ * never builds session-bearing sockets (its two clients are the anonymous
+ * channel singleton in `forgecart.ts` and the embedded backend's admin
+ * singleton); it only prefetches public data and mirrors the session cookie.
+ *
+ * Lifecycle:
+ *   - `initShopSession(config)` (the CartProvider mount) arms the singleton
+ *     with the channel coordinates; the socket itself opens lazily on the
+ *     first operation and the SDK's `lazyCloseTimeout` parks it when idle.
+ *   - The client boots its auth from the JS-readable mirror cookie
+ *     (`forgecart-session-client`), so a returning shopper's socket adopts
+ *     the same session SSR saw.
+ *   - After every operation, a newly-captured session token (the SDK reads
+ *     it from result extensions on the first mutation) is synced back into
+ *     BOTH cookies via the `syncShopSession` server action — the next SSR
+ *     pass sees the cart this socket built.
+ *
+ * Every operation returns the same `ActionResult` envelope the old Server
+ * Actions used, so calling components keep their error contract: typed
+ * in-band errors, never a throw.
+ */
+
+export interface ShopSessionConfig {
+  apiUrl: string;
+  channelToken: string;
+}
+
+const SESSION_MIRROR_COOKIE = 'forgecart-session-client';
+
+let config: ShopSessionConfig | null = null;
+let client: ForgeCartShopClient | null = null;
+let syncedToken: string | null = null;
+
+/** Read the session mirror cookie (null outside the browser or when absent). */
+export function readMirrorSession(): string | null {
+  if (typeof document === 'undefined') return null;
+  const entry = document.cookie
+    .split('; ')
+    .find((candidate) => candidate.startsWith(`${SESSION_MIRROR_COOKIE}=`));
+  if (!entry) return null;
+  const value = decodeURIComponent(entry.slice(SESSION_MIRROR_COOKIE.length + 1));
+  return value.length > 0 ? value : null;
+}
+
+/** Arm the singleton with the channel coordinates (idempotent; provider mount). */
+export function initShopSession(next: ShopSessionConfig): void {
+  config = next;
+}
+
+/** Whether the session socket can exist (configured scaffold + browser). */
+export function isSessionReady(): boolean {
+  return config !== null && typeof window !== 'undefined';
+}
+
+function ensureClient(): ForgeCartShopClient {
+  if (!config) {
+    throw new Error(
+      'Shop session not initialized — CartProvider must mount with shopConfig first.',
+    );
+  }
+  if (!client) {
+    client = new ForgeCartShopClient({
+      endpoint: config.apiUrl,
+      channelToken: config.channelToken,
+    });
+    const existing = readMirrorSession();
+    if (existing) {
+      client.setAuthToken(existing);
+      syncedToken = existing;
+    }
+  }
+  return client;
+}
+
+/**
+ * Run one session operation on the shopper's socket and return the typed
+ * envelope. Session capture: when the operation minted or rotated the
+ * session, the new token is synced into the cookies fire-and-forget —
+ * a sync failure never breaks the shopper's interaction.
+ */
+export async function runSessionOp<T>(
+  op: (client: ForgeCartShopClient) => Promise<T>,
+): Promise<ActionResult<T>> {
+  if (!isSessionReady()) {
+    return { ok: false, error: UNREACHABLE_ERROR };
+  }
+  const live = ensureClient();
+  try {
+    const data = await op(live);
+    const token = live.getAuthToken();
+    if (token && token !== syncedToken) {
+      syncedToken = token;
+      void syncShopSession(token).catch(() => undefined);
+    }
+    return { ok: true, data };
+  } catch (error) {
+    return { ok: false, error: extractError(error) ?? UNREACHABLE_ERROR };
+  }
+}

package/templates/storefront/src/lib/track-forward.ts

@@ -74,6 +74,16 @@ export interface ForwardHeaders {
   sessionToken: string | null;
   /** The browser's own User-Agent, forwarded for device enrichment. */
   userAgent: string;
+  /**
+   * The browser's low-entropy Client Hints (`sec-ch-ua`, `sec-ch-ua-mobile`,
+   * `sec-ch-ua-platform`), mirrored verbatim so device identification can
+   * outrank the frozen UA per-field (#1014). Chromium sends the trio on
+   * every request — no handshake, no `Accept-CH` — so this is a pure
+   * pass-through; absent on non-Chromium browsers.
+   */
+  secChUa?: string;
+  secChUaMobile?: string;
+  secChUaPlatform?: string;
   /**
    * Client IP as `x-forwarded-for` (the proxy-standard contract the shop API
    * trusts) — NEVER ForgeCart's edge-secret-gated client-IP override header
@@ -119,7 +129,7 @@ export function isObviousBot(userAgent: string): boolean {
  */
 export async function forwardTrackEvent(
   input: TrackEventInput,
-  { sessionToken, userAgent, forwardedFor }: ForwardHeaders,
+  { sessionToken, userAgent, forwardedFor, secChUa, secChUaMobile, secChUaPlatform }: ForwardHeaders,
 ): Promise<UpstreamOutcome> {
   const upstream = getUpstreamConfig();
   if (!upstream) return { accepted: false, eventId: null, sessionToken: null };
@@ -131,6 +141,9 @@ export async function forwardTrackEvent(
   if (sessionToken) headers['Authorization'] = `Bearer ${sessionToken}`;
   if (userAgent) headers['user-agent'] = userAgent;
   if (forwardedFor) headers['x-forwarded-for'] = forwardedFor;
+  if (secChUa) headers['sec-ch-ua'] = secChUa;
+  if (secChUaMobile) headers['sec-ch-ua-mobile'] = secChUaMobile;
+  if (secChUaPlatform) headers['sec-ch-ua-platform'] = secChUaPlatform;
 
   try {
     const response = await fetch(upstream.shopApiUrl, {

package/templates/storefront/src/lib/uuid.ts

@@ -0,0 +1,19 @@
+/**
+ * v4 UUID that works in EVERY browsing context this storefront serves from.
+ *
+ * `crypto.randomUUID` is secure-context gated: it exists on https origins and
+ * on localhost, but NOT on plain-http LAN/preview hosts — exactly the local
+ * k3s preview origin (`http://<code>.127.0.0.1.nip.io:8081`) the dev recipe
+ * and the dashboard-e2e forge suite drive. A bare call there is a TypeError
+ * mid-render (the checkout AddressStep crash, 2026-08-09). `getRandomValues`
+ * carries no such gate, so mint the same v4 shape by hand when the fast path
+ * is missing.
+ */
+export function mintUuid(): string {
+  if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/templates/storefront/src/server/app.module.ts

@@ -0,0 +1,18 @@
+import 'server-only';
+
+import { Module } from '@nestjs/common';
+
+import { CustomerExtrasModule } from './customer-extras/customer-extras.module';
+import { ForgeCartModule } from './forgecart/forgecart.module';
+
+/**
+ * Root of the storefront's embedded NestJS backend.
+ *
+ * `bootstrap.ts` boots this module as an APPLICATION CONTEXT — the module
+ * system, DI container, and lifecycle only; Next.js keeps owning HTTP — and
+ * scans it for `@BackendMethod()` methods, which become the `sdk.backend`
+ * surface. Every domain module registers here; a module that is not
+ * imported does not exist to the scan.
+ */
+@Module({ imports: [ForgeCartModule, CustomerExtrasModule] })
+export class AppModule {}

package/templates/storefront/src/server/backend-api.ts

@@ -0,0 +1,26 @@
+import 'server-only';
+
+import type {
+  AssignCustomerHashInput,
+  AssignCustomerHashResult,
+} from './customer-extras/type/customer-extras.types';
+
+/**
+ * The compile-time surface of the backend gate — the typed twin of the
+ * runtime `@BackendMethod()` scan.
+ *
+ * `lib/backend-client.ts` types the `sdk.backend` proxy from this interface
+ * (a type-only import, so nothing here reaches the client bundle), and
+ * `bootstrap.ts` validates at boot that the decorator scan discovered
+ * EXACTLY the names below — a mismatch in either direction fails the boot
+ * with a message naming the drifted method.
+ *
+ * Adding a method = the decorated service method + one signature here (+
+ * the name in the list below). See the `backend-feature-authoring` recipe.
+ */
+export interface BackendApi {
+  assignCustomerHash: (input: AssignCustomerHashInput) => Promise<AssignCustomerHashResult>;
+}
+
+/** The declared names, for the boot-time drift check against the scan. */
+export const BACKEND_API_METHOD_NAMES: readonly (keyof BackendApi)[] = ['assignCustomerHash'];

package/templates/storefront/src/server/backend-method.decorator.ts

@@ -0,0 +1,23 @@
+import 'server-only';
+
+import { SetMetadata, type CustomDecorator } from '@nestjs/common';
+
+/** Metadata key marking a service method as browser-invocable via `sdk.backend`. */
+export const BACKEND_METHOD_KEY = 'forgecart:backend-method';
+
+/**
+ * Opt a service method into the `sdk.backend` gate.
+ *
+ * The decorator IS the allowlist: the bootstrap scan exposes decorated
+ * methods and nothing else, so a method becomes browser-callable only by
+ * carrying this marker (plus its line in `backend-api.ts` — the boot-time
+ * drift check keeps the two in lock-step). Method names must be unique
+ * across ALL services; a duplicate fails the boot loudly.
+ *
+ * A decorated method runs shopper-invocable with the ADMIN client available
+ * in its session — the method body owns the decision of what that authority
+ * may be used for, and must treat its `input` as untrusted data.
+ */
+export function BackendMethod(): CustomDecorator<string> {
+  return SetMetadata(BACKEND_METHOD_KEY, true);
+}