@forgecart/cli 2.202606151453.0 → 2.202607070306.0

package/templates/storefront/src/components/ProductPurchase.tsx

@@ -1,19 +1,40 @@
 'use client';
 
-import type { Product, ProductVariant } from '@forgecart/sdk/shop';
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 
 import { useCart } from '../lib/cart-context';
-import { formatPrice } from '../lib/forgecart';
+import {
+  formatPrice,
+  getPlanCadenceLabel,
+  getPlanPreviewPrice,
+  getPlanSavingsLabel,
+  type Product,
+  type ProductVariant,
+  type SellingPlan,
+  type SellingPlanGroup,
+} from '../lib/forgecart';
 
 /**
- * Variant picker + add-to-cart for the product detail page.
+ * Variant picker + purchase-options + add-to-cart for the product detail page.
  *
  * The customer picks one value per option group (Size, Color, …); the matching
  * variant drives the displayed price and what gets added to the cart — you add a
  * **variant**, never the product. Single-variant products skip the selectors.
+ *
+ * When the selected variant has subscription selling plans (passed in as
+ * `planGroupsByVariant`, fetched server-side by the page), a "Purchase options"
+ * control appears above Add-to-cart: a one-time purchase plus one option per
+ * plan, each with a price preview and a savings/trial hint. The chosen plan id
+ * (or `undefined` for one-time) flows into the cart on Add. Variants with no
+ * plans keep the plain one-time add-to-cart path unchanged.
  */
-export function ProductPurchase({ product }: { product: Product }) {
+export function ProductPurchase({
+  product,
+  planGroupsByVariant = {},
+}: {
+  product: Product;
+  planGroupsByVariant?: Record<string, SellingPlanGroup[]>;
+}) {
   const { add, pending } = useCart();
   const [added, setAdded] = useState(false);
 
@@ -36,19 +57,77 @@ export function ProductPurchase({ product }: { product: Product }) {
     );
   }, [product.variants, selected]);
 
+  // The selling-plan groups the *selected* variant is eligible for.
+  const groups: SellingPlanGroup[] = useMemo(
+    () => (variant ? (planGroupsByVariant[variant.id] ?? []) : []),
+    [planGroupsByVariant, variant],
+  );
+
+  // The selectable plans (enabled only), flattened across applicable groups.
+  const plans: SellingPlan[] = useMemo(
+    () => groups.flatMap((g) => g.plans).filter((p) => p.enabled),
+    [groups],
+  );
+
+  // One-time is offered unless EVERY applicable group forbids it (subscription-only).
+  const oneTimeAllowed = groups.length === 0 || groups.some((g) => g.oneTimePurchaseAllowed);
+  const hasPurchaseOptions = plans.length > 0;
+
+  // `null` = one-time purchase; otherwise the chosen plan id.
+  const [selectedPlanId, setSelectedPlanId] = useState<string | null>(null);
+
+  // The set of valid choices changes with the variant (and thus its plans). Re-
+  // normalize the selection whenever that signature changes: keep a still-valid
+  // choice, otherwise default to one-time when allowed, else the first plan —
+  // never leave a stale id that is no longer offered for the current variant.
+  // `planIds` is a stable, primitive signature of the current plan set, so the
+  // effect re-runs exactly when the options (or the one-time gate) change and
+  // closes over no array identities.
+  const planIds = plans.map((p) => p.id).join(',');
+  useEffect(() => {
+    const ids = planIds ? planIds.split(',') : [];
+    const validIds = new Set(ids);
+    setSelectedPlanId((current) => {
+      if (current !== null && validIds.has(current)) {
+        return current;
+      }
+      if (oneTimeAllowed) {
+        return null;
+      }
+      return ids[0] ?? null;
+    });
+  }, [planIds, oneTimeAllowed]);
+
+  const selectedPlan: SellingPlan | undefined = useMemo(
+    () => plans.find((p) => p.id === selectedPlanId),
+    [plans, selectedPlanId],
+  );
+
+  // Price preview for the chosen option: one-time shows the variant price; a
+  // plan shows its policy-adjusted per-unit price.
+  const previewPrice = useMemo(() => {
+    if (!variant) {
+      return null;
+    }
+    if (!selectedPlan) {
+      return variant.priceWithTax;
+    }
+    return getPlanPreviewPrice(variant.priceWithTax, selectedPlan);
+  }, [variant, selectedPlan]);
+
   const onAdd = () => {
     if (!variant) {
       return;
     }
-    add(variant.id, 1);
+    add(variant.id, 1, selectedPlanId ?? undefined);
     setAdded(true);
     window.setTimeout(() => setAdded(false), 1500);
   };
 
   return (
     <div className="space-y-4">
-      {variant ? (
-        <p className="text-xl font-semibold text-gray-900">{formatPrice(variant.priceWithTax)}</p>
+      {variant && previewPrice !== null ? (
+        <p className="text-xl font-semibold text-gray-900">{formatPrice(previewPrice)}</p>
       ) : (
         <p className="text-sm text-gray-500">Select options to see the price.</p>
       )}
@@ -78,6 +157,38 @@ export function ProductPurchase({ product }: { product: Product }) {
         </div>
       ))}
 
+      {variant && hasPurchaseOptions && (
+        <div>
+          <h3 className="mb-1 text-sm font-medium text-gray-700">Purchase options</h3>
+          <div className="flex flex-col gap-2">
+            {oneTimeAllowed && (
+              <PurchaseOption
+                label="One-time purchase"
+                priceLabel={formatPrice(variant.priceWithTax)}
+                active={selectedPlanId === null}
+                onSelect={() => setSelectedPlanId(null)}
+              />
+            )}
+            {plans.map((plan) => {
+              const savings = getPlanSavingsLabel(plan);
+              const hint = [savings, plan.trialDays > 0 ? `${plan.trialDays}-day free trial` : null]
+                .filter(Boolean)
+                .join(' · ');
+              return (
+                <PurchaseOption
+                  key={plan.id}
+                  label={`Subscribe — ${getPlanCadenceLabel(plan)}`}
+                  hint={hint || undefined}
+                  priceLabel={formatPrice(getPlanPreviewPrice(variant.priceWithTax, plan))}
+                  active={selectedPlanId === plan.id}
+                  onSelect={() => setSelectedPlanId(plan.id)}
+                />
+              );
+            })}
+          </div>
+        </div>
+      )}
+
       <button
         type="button"
         onClick={onAdd}
@@ -89,3 +200,37 @@ export function ProductPurchase({ product }: { product: Product }) {
     </div>
   );
 }
+
+/** A single selectable purchase option (one-time or a subscription plan). */
+function PurchaseOption({
+  label,
+  hint,
+  priceLabel,
+  active,
+  onSelect,
+}: {
+  label: string;
+  hint?: string;
+  priceLabel: string;
+  active: boolean;
+  onSelect: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onSelect}
+      aria-pressed={active}
+      className={`flex items-center justify-between gap-3 rounded-md border px-3 py-2 text-left text-sm transition ${
+        active
+          ? 'border-gray-900 ring-1 ring-gray-900'
+          : 'border-gray-300 hover:border-gray-900'
+      }`}
+    >
+      <span className="min-w-0">
+        <span className="block font-medium text-gray-900">{label}</span>
+        {hint && <span className="block text-xs text-gray-500">{hint}</span>}
+      </span>
+      <span className="shrink-0 font-medium text-gray-900">{priceLabel}</span>
+    </button>
+  );
+}

package/templates/storefront/src/instrumentation.ts

@@ -0,0 +1,69 @@
+/**
+ * DEV-ONLY server-error beacon via Next's `onRequestError` instrumentation hook.
+ *
+ * This is the PRIMARY server-side crash-detection surface for the in-pod dev-server:
+ * when a Server Component, a server action, or a route handler THROWS while rendering
+ * a request under `next dev`, Next invokes `onRequestError` with the structured error
+ * + request + routing context. The hook POSTs that detail SERVER-side, straight to the
+ * in-pod workspace-manager loopback receiver at
+ * `http://127.0.0.1:<FORGE_BEACON_PORT>/__forge_beacon`, which folds it into the
+ * supervisor's runtime state so the shop's recovery brain can originate a fix for a
+ * crash the `/ping` liveness probe cannot see (the dev-server process stays up and
+ * `/ping` stays 200, but `/` 500s per request).
+ *
+ * This complements the browser beacon (`ForgeErrorBeacon`): that one catches
+ * CLIENT-component / hydration throws that surface only in the browser; this one
+ * catches SERVER render throws that surface only in the dev-server. Both POST the
+ * same `/__forge_beacon` shape — the only difference is `source` (`'browser'` vs
+ * `'server'`).
+ *
+ * Gated entirely on `NODE_ENV === 'development'`: a deployed `next start` storefront
+ * registers no beacon (the literal check is inlined by the bundler, so the body is
+ * dead-code-eliminated from a production build) and the loopback receiver does not
+ * exist outside the pod. Next compiles `instrumentation.ts` for BOTH the Node and Edge
+ * runtimes; the loopback POST is a Node-only concern, so the hook also gates on the
+ * Node runtime — the Edge bundle then carries an inert no-op.
+ *
+ * The hook NEVER throws out of itself: a failed delivery is swallowed (the beacon is a
+ * best-effort backstop, never a hard dependency of the request), so a flapping receiver
+ * can never mask or replace the underlying request error Next is already reporting.
+ */
+
+const BEACON_PORT = process.env.FORGE_BEACON_PORT ?? '3002';
+
+interface OnRequestErrorRequest {
+  path: string;
+  method: string;
+  headers: { [key: string]: string | string[] | undefined };
+}
+
+interface OnRequestErrorContext {
+  routerKind: string;
+  routePath: string;
+  routeType: string;
+}
+
+export async function onRequestError(
+  error: unknown,
+  request: OnRequestErrorRequest,
+  context: OnRequestErrorContext,
+): Promise<void> {
+  if (process.env.NODE_ENV !== 'development' || process.env.NEXT_RUNTIME !== 'nodejs') {
+    return;
+  }
+
+  const err = error as { message?: string; digest?: string } | undefined;
+  const body = JSON.stringify({
+    message: typeof err?.message === 'string' ? err.message : String(error),
+    digest: typeof err?.digest === 'string' ? err.digest : undefined,
+    route: request.path,
+    routeType: context.routeType,
+    source: 'server',
+  });
+
+  await fetch(`http://127.0.0.1:${BEACON_PORT}/__forge_beacon`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body,
+  }).catch(() => undefined);
+}

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

@@ -1,148 +1,131 @@
 'use server';
 
-import type { Order } from '@forgecart/sdk/shop';
+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 returning the live
- * `Order` (the SDK type) so callers render straight off it.
+ * 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 in the `forgecart-auth-token` response header on the first
- * mutation, which we persist into the httpOnly `forgecart-session` cookie and
- * send back as a bearer token on every subsequent request. The channel token and
- * the session never reach the browser — all cart calls run here, on the server.
+ * 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';
 
-/** The order fields the storefront renders (a subset of the SDK `Order` type). */
-const ORDER_FIELDS = `
-  id
-  totalQuantity
-  subTotalWithTax
-  totalWithTax
-  currencyCode
-  lines {
-    id
-    quantity
-    unitPriceWithTax
-    linePriceWithTax
-    productVariant {
-      id
-      name
-    }
-    featuredAsset {
-      preview
-    }
+/** 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);
   }
-`;
-
-interface GraphQLResponse<T> {
-  data?: T;
-  errors?: { message: string }[];
+  return client;
 }
 
 /**
- * Call the channel's shop API for a cart operation.
+ * Persist the session token the client captured during a mutation.
  *
- * `persist` MUST be `false` when called from a Server Component (the initial
- * cart read): Server Components cannot set cookies — only Server Actions (the
- * mutations) can, so they capture/refresh the session token.
+ * MUST only be called from Server Actions (the mutations): Server Components
+ * cannot set cookies, which is why the read path never persists.
  */
-async function shopFetch<T>(
-  query: string,
-  variables: Record<string, unknown>,
-  persist: boolean,
-): Promise<GraphQLResponse<T>> {
+async function persistSession(client: ForgeCartShopClient): Promise<void> {
+  const token = client.getAuthToken();
+  if (!token) return;
   const store = await cookies();
-  const session = store.get(SESSION_COOKIE)?.value;
-
-  const headers: Record<string, string> = {
-    'content-type': 'application/json',
-    'forgecart-token': CHANNEL_TOKEN,
-  };
-  if (session) {
-    headers.authorization = `Bearer ${session}`;
-  }
-
-  const res = await fetch(SHOP_API_URL, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify({ query, variables }),
-    cache: 'no-store',
+  if (store.get(SESSION_COOKIE)?.value === token) return;
+  store.set(SESSION_COOKIE, token, {
+    httpOnly: true,
+    sameSite: 'lax',
+    path: '/',
+    maxAge: 60 * 60 * 24 * 30,
   });
-
-  if (persist) {
-    const token = res.headers.get('forgecart-auth-token');
-    if (token && token !== session) {
-      store.set(SESSION_COOKIE, token, {
-        httpOnly: true,
-        sameSite: 'lax',
-        path: '/',
-        maxAge: 60 * 60 * 24 * 30,
-      });
-    }
-  }
-
-  return (await res.json()) as GraphQLResponse<T>;
 }
 
-function unwrap<T>(res: GraphQLResponse<T>): T {
-  if (res.errors?.length) {
-    throw new Error(res.errors[0].message);
-  }
-  if (!res.data) {
-    throw new Error('Empty response from shop API');
-  }
-  return res.data;
+/**
+ * Read the active order (cart). Safe to call from a Server Component.
+ *
+ * Before `forgecart init` writes `.env.local` (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.
+ */
+export async function getCart(): Promise<Order | null> {
+  if (!SHOP_API_URL || !CHANNEL_TOKEN) return null;
+  const client = await getCartClient();
+  const { activeOrder } = await client.order.activeOrder();
+  return activeOrder ?? null;
 }
 
-/** Read the active order (cart). Safe to call from a Server Component. */
-export async function getCart(): Promise<Order | null> {
-  const res = await shopFetch<{ activeOrder: Order | null }>(
-    `query { activeOrder { ${ORDER_FIELDS} } }`,
-    {},
-    false,
-  );
-  return res.data?.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;
 }
 
-/** Add a variant to the cart (creates the order + session on first call). */
-export async function addToCart(variantId: string, quantity = 1): Promise<Order | null> {
-  const data = unwrap(
-    await shopFetch<{ addItemToOrder: Order }>(
-      `mutation($input: ShopAddItemToOrderInput!) { addItemToOrder(input: $input) { ${ORDER_FIELDS} } }`,
-      { input: { variantId, quantity } },
-      true,
-    ),
-  );
-  return data.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 data = unwrap(
-    await shopFetch<{ adjustOrderLine: Order }>(
-      `mutation($input: ShopAdjustOrderLineInput!) { adjustOrderLine(input: $input) { ${ORDER_FIELDS} } }`,
-      { input: { lineId, quantity } },
-      true,
-    ),
-  );
-  return data.adjustOrderLine;
+  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 data = unwrap(
-    await shopFetch<{ removeOrderLine: Order }>(
-      `mutation($lineId: ID!) { removeOrderLine(lineId: $lineId) { ${ORDER_FIELDS} } }`,
-      { lineId },
-      true,
-    ),
-  );
-  return data.removeOrderLine;
+  const client = await getCartClient();
+  const { removeOrderLine } = await client.cart.removeOrderLine({ lineId });
+  await persistSession(client);
+  return removeOrderLine;
 }

package/templates/storefront/src/lib/cart-context.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import type { Order } from '@forgecart/sdk/shop';
+import type { Order } from './forgecart';
 import {
   createContext,
   useCallback,
@@ -11,7 +11,13 @@ import {
   type ReactNode,
 } from 'react';
 
-import { addToCart, getCart, removeLine as removeLineAction, updateLine } from './cart-actions';
+import {
+  addToCart,
+  getCart,
+  removeLine as removeLineAction,
+  setCartSellingPlan,
+  updateLine,
+} from './cart-actions';
 
 /**
  * Cart state backed by the ForgeCart shop order API (see `cart-actions.ts`).
@@ -26,9 +32,10 @@ interface CartContextValue {
   itemCount: number;
   subtotal: number;
   pending: boolean;
-  add: (variantId: string, quantity?: number) => void;
+  add: (variantId: string, quantity?: number, sellingPlanId?: string) => void;
   setQuantity: (lineId: string, quantity: number) => void;
   remove: (lineId: string) => void;
+  setSellingPlan: (sellingPlanId: string | null) => void;
   refresh: () => void;
 }
 
@@ -51,7 +58,8 @@ export function CartProvider({
   }, []);
 
   const add = useCallback(
-    (variantId: string, quantity = 1) => run(() => addToCart(variantId, quantity)),
+    (variantId: string, quantity = 1, sellingPlanId?: string) =>
+      run(() => addToCart(variantId, quantity, sellingPlanId)),
     [run],
   );
   const setQuantity = useCallback(
@@ -59,6 +67,10 @@ export function CartProvider({
     [run],
   );
   const remove = useCallback((lineId: string) => run(() => removeLineAction(lineId)), [run]);
+  const setSellingPlan = useCallback(
+    (sellingPlanId: string | null) => run(() => setCartSellingPlan(sellingPlanId)),
+    [run],
+  );
   const refresh = useCallback(() => run(() => getCart()), [run]);
 
   const value = useMemo<CartContextValue>(
@@ -70,9 +82,10 @@ export function CartProvider({
       add,
       setQuantity,
       remove,
+      setSellingPlan,
       refresh,
     }),
-    [cart, pending, add, setQuantity, remove, refresh],
+    [cart, pending, add, setQuantity, remove, setSellingPlan, refresh],
   );
 
   return <CartContext.Provider value={value}>{children}</CartContext.Provider>;