@forgecart/cli 2.202608110054.0 → 2.202608160103.0

package/templates/storefront/src/server/bootstrap.ts

@@ -0,0 +1,122 @@
+import 'server-only';
+import 'reflect-metadata';
+
+import type { INestApplicationContext } from '@nestjs/common';
+import { MetadataScanner, ModulesContainer, NestFactory, Reflector } from '@nestjs/core';
+
+import { AppModule } from './app.module';
+import { BACKEND_API_METHOD_NAMES } from './backend-api';
+import { BACKEND_METHOD_KEY } from './backend-method.decorator';
+import type { BackendSession } from './types';
+
+/** A discovered method, bound to its service instance. */
+export type RegisteredBackendMethod = (session: BackendSession, input: unknown) => Promise<unknown>;
+
+export interface BackendRuntime {
+  ctx: INestApplicationContext;
+  registry: ReadonlyMap<string, RegisteredBackendMethod>;
+}
+
+/**
+ * Boot-once accessor for the embedded NestJS backend.
+ *
+ * The cache is MODULE-scoped on purpose: under `next dev`, editing anything
+ * in the backend graph makes HMR re-execute this module with a fresh scope,
+ * so the next invocation boots a NEW context with the new code — that is how
+ * agent edits take effect without a server restart. The previous context's
+ * handle rides `globalThis` (which HMR does NOT reset) solely so the new
+ * boot can close it — retired containers must not leak lifecycle hooks. In
+ * production there is no HMR and this degrades to boot-exactly-once.
+ *
+ * A failed boot (e.g. the api-map drift check) stays cached as a rejection:
+ * every invocation reports the same loud error until the FIX edit re-executes
+ * this module. Failing closed and visible beats a half-registered backend.
+ */
+let runtimePromise: Promise<BackendRuntime> | undefined;
+const handoff = globalThis as { __forgecartBackendPrev?: BackendRuntime };
+
+export function getBackend(): Promise<BackendRuntime> {
+  runtimePromise ??= boot();
+  return runtimePromise;
+}
+
+async function boot(): Promise<BackendRuntime> {
+  const ctx = await NestFactory.createApplicationContext(AppModule, {
+    logger: ['warn', 'error'],
+  });
+  const registry = scanForBackendMethods(ctx);
+  validateAgainstApi(registry);
+
+  const previous = handoff.__forgecartBackendPrev;
+  if (previous) {
+    try {
+      await previous.ctx.close();
+    } catch {
+      // A mid-reload teardown race is fine — the old container is gone either way.
+    }
+  }
+  const runtime: BackendRuntime = { ctx, registry };
+  handoff.__forgecartBackendPrev = runtime;
+  return runtime;
+}
+
+/**
+ * Walk every provider in the booted module graph and collect the methods
+ * carrying `@BackendMethod()` — the decorator is the allowlist, so the map
+ * built here is the ONLY surface `sdk.backend` can reach. Names are global:
+ * a duplicate across services fails the boot rather than shadowing.
+ */
+function scanForBackendMethods(
+  ctx: INestApplicationContext,
+): ReadonlyMap<string, RegisteredBackendMethod> {
+  const registry = new Map<string, RegisteredBackendMethod>();
+  const modules = ctx.get(ModulesContainer);
+  const scanner = new MetadataScanner();
+  const reflector = new Reflector();
+
+  for (const moduleRef of modules.values()) {
+    for (const wrapper of moduleRef.providers.values()) {
+      const instance = wrapper.instance as Record<string, unknown> | null;
+      if (!instance || typeof instance !== 'object') continue;
+      const prototype = Object.getPrototypeOf(instance) as Record<string, unknown> | null;
+      if (!prototype) continue;
+
+      for (const name of scanner.getAllMethodNames(prototype)) {
+        const handler = prototype[name];
+        if (typeof handler !== 'function') continue;
+        if (reflector.get<boolean | undefined>(BACKEND_METHOD_KEY, handler) !== true) continue;
+        if (registry.has(name)) {
+          throw new Error(
+            `Duplicate @BackendMethod name "${name}" — backend method names must be unique across all services.`,
+          );
+        }
+        registry.set(name, (handler as RegisteredBackendMethod).bind(instance));
+      }
+    }
+  }
+  return registry;
+}
+
+/**
+ * The drift tripwire: the runtime scan and the compile-time surface
+ * (`backend-api.ts`) must agree EXACTLY, in both directions, or the typed
+ * proxy the browser compiles against would lie. The error names the exact
+ * method so the fix is a one-line edit.
+ */
+function validateAgainstApi(registry: ReadonlyMap<string, RegisteredBackendMethod>): void {
+  const declared = new Set<string>(BACKEND_API_METHOD_NAMES);
+  for (const name of registry.keys()) {
+    if (!declared.has(name)) {
+      throw new Error(
+        `@BackendMethod "${name}" is not declared in backend-api.ts — add its signature to BackendApi and its name to BACKEND_API_METHOD_NAMES.`,
+      );
+    }
+  }
+  for (const name of declared) {
+    if (!registry.has(name)) {
+      throw new Error(
+        `backend-api.ts declares "${name}" but no @BackendMethod with that name was discovered — decorate the service method (and wire its module into app.module.ts) or remove the declaration.`,
+      );
+    }
+  }
+}

package/templates/storefront/src/server/customer-extras/customer-extras.module.ts

@@ -0,0 +1,13 @@
+import 'server-only';
+
+import { Module } from '@nestjs/common';
+
+import { CustomerExtrasService } from './service/customer-extras.service';
+
+/**
+ * The worked-example domain module. New backend features follow this shape:
+ * one folder per domain, services under `service/`, the module listing them,
+ * and one `imports:` line in `app.module.ts`.
+ */
+@Module({ providers: [CustomerExtrasService] })
+export class CustomerExtrasModule {}

package/templates/storefront/src/server/customer-extras/service/customer-extras.service.ts

@@ -0,0 +1,58 @@
+import 'server-only';
+
+import { randomBytes } from 'node:crypto';
+
+import { Injectable } from '@nestjs/common';
+
+import { BackendMethod } from '../../backend-method.decorator';
+import { BackendError } from '../../types';
+import type { BackendSession } from '../../types';
+
+import type {
+  AssignCustomerHashInput,
+  AssignCustomerHashResult,
+} from '../type/customer-extras.types';
+
+/** ACF definition this store keeps its per-customer extras under. */
+const DEFINITION_CODE = 'customer-extras';
+
+/**
+ * The worked example for the `sdk.backend` gate: mint a random hash for the
+ * signed-in customer and persist it as a custom field — an ACF entry under
+ * the `customer-extras` definition. That is an ADMIN-authority write the
+ * shop API has no surface for, which is exactly what the gate exists to
+ * unlock.
+ *
+ * Precondition: the channel has a `customer-extras` ACF definition with a
+ * `customerId` id field and a `referralHash` string field (Dashboard →
+ * Custom Fields). Without it the createEntry call fails and the typed
+ * envelope carries the API's error to the caller — nothing crashes.
+ */
+@Injectable()
+export class CustomerExtrasService {
+  @BackendMethod()
+  async assignCustomerHash(
+    session: BackendSession,
+    _input: AssignCustomerHashInput,
+  ): Promise<AssignCustomerHashResult> {
+    const { activeCustomer } = await session.shop.customer.activeCustomer();
+    if (!activeCustomer) {
+      // Shopper-invocable ≠ anonymous-invocable: this method is per-customer
+      // by definition, so an anonymous session is a typed business error.
+      throw new BackendError('BACKEND_CUSTOMER_SESSION_REQUIRED');
+    }
+
+    const referralHash = randomBytes(16).toString('hex');
+    await session.admin.acf.entry.acfCreateEntry({
+      definitionCode: DEFINITION_CODE,
+      input: {
+        fields: [
+          { name: 'customerId', idValue: activeCustomer.id },
+          { name: 'referralHash', stringValue: referralHash },
+        ],
+      },
+    });
+
+    return { customerId: activeCustomer.id, referralHash };
+  }
+}

package/templates/storefront/src/server/customer-extras/type/customer-extras.types.ts

@@ -0,0 +1,11 @@
+/**
+ * The `assignCustomerHash` backend-method contract (the sdk.backend worked
+ * example). Input is deliberately empty — the method derives everything from
+ * the caller's session; the result echoes the customer and the minted hash.
+ */
+export type AssignCustomerHashInput = Record<string, never>;
+
+export interface AssignCustomerHashResult {
+  customerId: string;
+  referralHash: string;
+}

package/templates/storefront/src/server/forgecart/forgecart-client.factory.ts

@@ -0,0 +1,69 @@
+import 'server-only';
+
+import { ForgeCartAdminClient, ForgeCartShopClient } from '@forgecart/sdk';
+import { Injectable } from '@nestjs/common';
+
+const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
+const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
+const ADMIN_SECRET = process.env.FORGECART_ADMIN_SECRET ?? '';
+/** The admin API is the shop API's sibling endpoint on the same host. */
+const ADMIN_API_URL = SHOP_API_URL.replace(/\/shop-api$/, '/admin-api');
+
+/**
+ * SDK clients for backend methods. The generated SDK is graphql-ws, so
+ * every client is a websocket. Two lifetimes on purpose: the ADMIN client is
+ * a process-long singleton (channel-scoped, secret auth); the SESSION shop
+ * client is per-invocation (shopper-scoped authentication — see buildShop).
+ */
+@Injectable()
+export class ForgeCartClientFactory {
+  private admin: ForgeCartAdminClient | null = null;
+
+  /**
+   * Whether the backend gate is fully configured: `forgecart init` wrote all
+   * three env values AND the admin endpoint is derivable from the shop URL.
+   * False during the image-build pre-warm (which renders with no env) — the
+   * runner then answers with a typed envelope instead of driving doomed
+   * clients, keeping the pre-warm contract (serve, never crash) intact.
+   */
+  isConfigured(): boolean {
+    return Boolean(SHOP_API_URL && CHANNEL_TOKEN && ADMIN_SECRET && ADMIN_API_URL !== SHOP_API_URL);
+  }
+
+  /**
+   * The ADMIN socket is a long-lived singleton: admin operations are
+   * channel-scoped (secret auth, no shopper session), so one connection
+   * serves every invocation for the life of the server process — never
+   * disposed per invocation. Session-scoped sockets are the opposite case:
+   * they belong to the shopper's browser, and the ONE server-side exception
+   * is {@link buildShop} below.
+   */
+  getAdmin(): ForgeCartAdminClient {
+    if (!this.admin) {
+      this.admin = new ForgeCartAdminClient({
+        endpoint: ADMIN_API_URL,
+        channelToken: CHANNEL_TOKEN,
+        adminSecret: ADMIN_SECRET,
+      });
+    }
+    return this.admin;
+  }
+
+  /**
+   * Per-invocation SESSION shop client — the deliberate server-side
+   * exception: a backend method must authenticate WHO the shopper is from
+   * the httpOnly session cookie before acting with admin authority (the
+   * browser cannot be trusted to claim an identity for an admin-gated op).
+   * Short-lived by design; the runner disposes it with the invocation.
+   */
+  buildShop(sessionToken: string | undefined): ForgeCartShopClient {
+    const client = new ForgeCartShopClient({
+      endpoint: SHOP_API_URL,
+      channelToken: CHANNEL_TOKEN,
+    });
+    if (sessionToken) {
+      client.setAuthToken(sessionToken);
+    }
+    return client;
+  }
+}

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

@@ -0,0 +1,9 @@
+import 'server-only';
+
+import { Module } from '@nestjs/common';
+
+import { ForgeCartClientFactory } from './forgecart-client.factory';
+
+/** Provides the SDK client factory to the backend's module graph. */
+@Module({ providers: [ForgeCartClientFactory], exports: [ForgeCartClientFactory] })
+export class ForgeCartModule {}

package/templates/storefront/src/server/runner.ts

@@ -0,0 +1,91 @@
+import 'server-only';
+
+import { extractError, type ExtractedError } from '@forgecart/sdk';
+import { cookies } from 'next/headers';
+
+import { UNREACHABLE_ERROR, type ActionResult } from '../lib/action-result';
+import { getBackend } from './bootstrap';
+import { ForgeCartClientFactory } from './forgecart/forgecart-client.factory';
+import { BackendError } from './types';
+import type { BackendSession } from './types';
+
+const SESSION_COOKIE = 'forgecart-session';
+
+/** The gate has no env yet (image pre-warm / before `forgecart init`). */
+const NOT_CONFIGURED: ExtractedError = {
+  code: 'BACKEND_NOT_CONFIGURED',
+  variables: {},
+  classification: 'INTERNAL_ERROR',
+};
+
+/**
+ * Dispatch one `sdk.backend` invocation: resolve the booted registry, build
+ * the per-invocation SDK clients, run the method, translate every failure
+ * into the in-band envelope, and dispose both client websockets with the
+ * invocation — the exact contract of `lib/shop-action.ts`, extended with the
+ * admin gate.
+ *
+ * Fail-closed rules: an unknown name (type-cast bypass, or a STALE browser
+ * bundle calling a method a newer deploy removed) answers
+ * BACKEND_METHOD_NOT_FOUND; a boot failure (the api-map drift check)
+ * answers BACKEND_BOOT_FAILED carrying the boot error's message so the
+ * agent sees the actionable text in the envelope too, not only in the logs.
+ */
+export async function invokeBackendMethod(
+  method: string,
+  input: unknown,
+): Promise<ActionResult<unknown>> {
+  let registry: ReadonlyMap<string, (session: BackendSession, input: unknown) => Promise<unknown>>;
+  let factory: ForgeCartClientFactory;
+  try {
+    const runtime = await getBackend();
+    registry = runtime.registry;
+    factory = runtime.ctx.get(ForgeCartClientFactory, { strict: false });
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: 'BACKEND_BOOT_FAILED',
+        variables: { reason: error instanceof Error ? error.message : String(error) },
+        classification: 'INTERNAL_ERROR',
+      },
+    };
+  }
+
+  const fn = registry.get(method);
+  if (!fn) {
+    return {
+      ok: false,
+      error: {
+        code: 'BACKEND_METHOD_NOT_FOUND',
+        variables: { method },
+        classification: 'BAD_USER_INPUT',
+      },
+    };
+  }
+  if (!factory.isConfigured()) {
+    return { ok: false, error: NOT_CONFIGURED };
+  }
+
+  const store = await cookies();
+  const sessionToken = store.get(SESSION_COOKIE)?.value;
+  const admin = factory.getAdmin();
+  const shop = factory.buildShop(sessionToken);
+  const session: BackendSession = { admin, shop, hasSession: Boolean(sessionToken) };
+  try {
+    const data = await fn(session, input);
+    return { ok: true, data };
+  } catch (error) {
+    if (error instanceof BackendError) {
+      return {
+        ok: false,
+        error: { code: error.code, variables: error.variables, classification: 'BAD_USER_INPUT' },
+      };
+    }
+    return { ok: false, error: extractError(error) ?? UNREACHABLE_ERROR };
+  } finally {
+    // Only the session client dies with the invocation — the admin socket is
+    // the factory's process-long singleton.
+    shop.dispose();
+  }
+}

package/templates/storefront/src/server/types.ts

@@ -0,0 +1,36 @@
+import 'server-only';
+
+import type { ForgeCartAdminClient, ForgeCartShopClient } from '@forgecart/sdk';
+
+/**
+ * The per-invocation context every backend method receives as its first
+ * argument. Both SDK gates are built fresh for THIS invocation by the runner
+ * and disposed with it (they are per-invocation websockets — same discipline
+ * as `lib/shop-action.ts`), so methods never construct or dispose clients.
+ *
+ * `admin` carries FULL channel authority (FORGECART_ADMIN_SECRET). A backend
+ * method is shopper-invocable, so nothing upstream gates what the admin
+ * client is used for — the method body owns that decision.
+ */
+export interface BackendSession {
+  admin: ForgeCartAdminClient;
+  shop: ForgeCartShopClient;
+  /** True when the request carried a shopper session cookie. */
+  hasSession: boolean;
+}
+
+/**
+ * Typed failure a backend method throws for its own business rules
+ * (missing login, invalid input, unmet precondition). The runner translates
+ * it into the standard `ActionResult` envelope exactly like an SDK error,
+ * so the client renders `code`/`variables` through the same error spine.
+ */
+export class BackendError extends Error {
+  constructor(
+    readonly code: string,
+    readonly variables: Record<string, string> = {},
+  ) {
+    super(code);
+    this.name = 'BackendError';
+  }
+}

package/templates/storefront/tsconfig.json

@@ -6,6 +6,8 @@
     "skipLibCheck": true,
     "strict": true,
     "noEmit": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
     "esModuleInterop": true,
     "module": "esnext",
     "moduleResolution": "bundler",

package/templates/storefront/.env.example

@@ -1,12 +0,0 @@
-# ForgeCart channel credentials.
-#
-# `forgecart init` writes the real values to `.env` for you. This file
-# documents the variables the storefront reads. Both are required and used
-# server-side only (never exposed to the browser).
-
-# The channel token identifies which ForgeCart channel this storefront serves.
-# It is sent as the `forgecart-token` header on every shop API request.
-FORGECART_CHANNEL_TOKEN=
-
-# Base URL of the ForgeCart shop GraphQL API (the shop-api endpoint).
-FORGECART_SHOP_API_URL=https://api.forgecart.com/shop-api

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

@@ -1,139 +0,0 @@
-'use server';
-
-import { ForgeCartShopClient } from '@forgecart/sdk';
-import type { ShopAddItemToOrderInput } from '@forgecart/sdk/shop';
-import { cookies } from 'next/headers';
-
-import type { Order } from './forgecart';
-
-/**
- * Server-side cart, backed by the ForgeCart shop **order** API (the real cart),
- * not browser storage. Every export here is a Server Action driving the SDK's
- * generated, typed cart operations and returning the live `Order` (the SDK
- * type) so callers render straight off it.
- *
- * The anonymous active order is tracked by a session token: the shop API
- * returns a fresh token (result extensions) on the first mutation, which the
- * SDK client captures — we persist it into the httpOnly `forgecart-session`
- * cookie and replay it as the client's auth token on every subsequent request.
- * Session state is per shopper, so each action builds a short-lived client
- * around its own request's cookie (queries/mutations ride plain fetch — the
- * client only opens a websocket for subscriptions, which the cart never uses).
- * The channel token and the session never reach the browser — all cart calls
- * run here, on the server.
- */
-
-const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
-const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
-const SESSION_COOKIE = 'forgecart-session';
-
-/** A per-request shop client carrying this shopper's session, when one exists. */
-async function getCartClient(): Promise<ForgeCartShopClient> {
-  const store = await cookies();
-  const session = store.get(SESSION_COOKIE)?.value;
-  const client = new ForgeCartShopClient({
-    endpoint: SHOP_API_URL,
-    channelToken: CHANNEL_TOKEN,
-  });
-  if (session) {
-    client.setAuthToken(session);
-  }
-  return client;
-}
-
-/**
- * Persist the session token the client captured during a mutation.
- *
- * MUST only be called from Server Actions (the mutations): Server Components
- * cannot set cookies, which is why the read path never persists.
- */
-async function persistSession(client: ForgeCartShopClient): Promise<void> {
-  const token = client.getAuthToken();
-  if (!token) return;
-  const store = await cookies();
-  if (store.get(SESSION_COOKIE)?.value === token) return;
-  store.set(SESSION_COOKIE, token, {
-    httpOnly: true,
-    sameSite: 'lax',
-    path: '/',
-    maxAge: 60 * 60 * 24 * 30,
-  });
-}
-
-/**
- * Read the active order (cart). Safe to call from a Server Component.
- *
- * Before `forgecart init` writes `.env` (notably the image-build pre-warm,
- * which renders `/` with no env), there is no shop to talk to — return an empty
- * cart immediately instead of driving the client into a doomed fetch. The
- * layout renders on every route, so this read must never stall an unconfigured
- * scaffold.
- *
- * No session cookie ⇒ no cart, WITHOUT calling the API. The shop's activeOrder
- * read auto-creates an order for the session — and a Server Component can't
- * persist a session cookie — so an eager read used to MINT an anonymous
- * session plus an orphan order on every cookie-less page view. The order (and
- * the cookie, via persistSession) is created lazily by the first addToCart.
- */
-export async function getCart(): Promise<Order | null> {
-  if (!SHOP_API_URL || !CHANNEL_TOKEN) return null;
-  const store = await cookies();
-  if (!store.get(SESSION_COOKIE)?.value) return null;
-  const client = await getCartClient();
-  const { activeOrder } = await client.order.activeOrder();
-  return activeOrder ?? null;
-}
-
-/**
- * Add a variant to the cart (creates the order + session on first call).
- *
- * Pass `sellingPlanId` to add the line as a subscription on the given plan;
- * omit it (the default) for a one-time purchase. The id is only included in the
- * mutation input when present, so the one-time path sends the same shape as
- * before.
- */
-export async function addToCart(
-  variantId: string,
-  quantity = 1,
-  sellingPlanId?: string,
-): Promise<Order | null> {
-  const input: ShopAddItemToOrderInput = { variantId, quantity };
-  if (sellingPlanId) {
-    input.sellingPlanId = sellingPlanId;
-  }
-  const client = await getCartClient();
-  const { addItemToOrder } = await client.cart.addItemToOrder({ input });
-  await persistSession(client);
-  return addItemToOrder;
-}
-
-/**
- * Set (or clear) the subscription plan for the whole order.
- *
- * Pass a channel-wide selling plan id to subscribe the entire cart on that
- * plan, or `null` to clear it back to a one-time order. Returns the live order.
- */
-export async function setCartSellingPlan(sellingPlanId: string | null): Promise<Order | null> {
-  const client = await getCartClient();
-  const { setOrderSellingPlan } = await client.cart.setOrderSellingPlan({
-    input: { sellingPlanId },
-  });
-  await persistSession(client);
-  return setOrderSellingPlan;
-}
-
-/** Set the quantity of a cart line (0 removes it). */
-export async function updateLine(lineId: string, quantity: number): Promise<Order | null> {
-  const client = await getCartClient();
-  const { adjustOrderLine } = await client.cart.adjustOrderLine({ input: { lineId, quantity } });
-  await persistSession(client);
-  return adjustOrderLine;
-}
-
-/** Remove a line from the cart. */
-export async function removeLine(lineId: string): Promise<Order | null> {
-  const client = await getCartClient();
-  const { removeOrderLine } = await client.cart.removeOrderLine({ lineId });
-  await persistSession(client);
-  return removeOrderLine;
-}

package/templates/storefront/tailwind.config.js

@@ -1,8 +0,0 @@
-/** @type {import('tailwindcss').Config} */
-module.exports = {
-  content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'],
-  theme: {
-    extend: {},
-  },
-  plugins: [],
-};