@forgecart/cli 2.202607061936.0 → 2.202607070306.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgecart/cli",
-  "version": "2.202607061936.0",
+  "version": "2.202607070306.0",
   "type": "module",
   "description": "CLI for scaffolding and operating ForgeCart channel storefronts",
   "bin": {

package/templates/storefront/src/app/cart/page.tsx

@@ -1,88 +1,13 @@
-'use client';
+import { CartView } from '../../components/CartView';
+import { getChannelSellingPlanGroups } from '../../lib/forgecart';
 
-import Link from 'next/link';
+export const dynamic = 'force-dynamic';
 
-import { useCart } from '../../lib/cart-context';
-import { formatPrice } from '../../lib/forgecart';
+export default async function CartPage() {
+  // Channel-wide subscription plans are fetched server-side (the shop client is
+  // server-only) and handed to the client cart view, which renders the
+  // "Subscribe to your whole order" box only when there are any.
+  const channelGroups = await getChannelSellingPlanGroups();
 
-export default function CartPage() {
-  const { cart, itemCount, subtotal, setQuantity, remove, pending } = useCart();
-  const lines = cart?.lines ?? [];
-
-  if (itemCount === 0) {
-    return (
-      <div className="space-y-4">
-        <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
-        <p className="text-gray-500">Your cart is empty.</p>
-        <Link
-          href="/products"
-          className="inline-block rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700"
-        >
-          Browse products
-        </Link>
-      </div>
-    );
-  }
-
-  return (
-    <div className="space-y-6">
-      <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
-
-      <ul className="divide-y divide-gray-200 rounded-lg border border-gray-200 bg-white">
-        {lines.map((line) => (
-          <li key={line.id} className="flex items-center gap-4 p-4">
-            <div className="h-16 w-16 shrink-0 overflow-hidden rounded bg-gray-100">
-              {line.featuredAsset?.preview ? (
-                // eslint-disable-next-line @next/next/no-img-element
-                <img
-                  src={line.featuredAsset.preview}
-                  alt={line.productVariant.name}
-                  className="h-full w-full object-cover"
-                />
-              ) : null}
-            </div>
-
-            <div className="min-w-0 flex-1">
-              <p className="truncate font-medium text-gray-900">{line.productVariant.name}</p>
-              <p className="text-sm text-gray-500">{formatPrice(line.unitPriceWithTax)} each</p>
-            </div>
-
-            <div className="flex items-center gap-2">
-              <label className="sr-only" htmlFor={`qty-${line.id}`}>
-                Quantity
-              </label>
-              <input
-                id={`qty-${line.id}`}
-                type="number"
-                min={1}
-                value={line.quantity}
-                disabled={pending}
-                onChange={(e) => setQuantity(line.id, Number.parseInt(e.target.value, 10) || 1)}
-                className="w-16 rounded border border-gray-300 px-2 py-1 text-sm disabled:opacity-50"
-              />
-            </div>
-
-            <div className="w-24 text-right font-medium text-gray-900">
-              {formatPrice(line.linePriceWithTax)}
-            </div>
-
-            <button
-              type="button"
-              onClick={() => remove(line.id)}
-              disabled={pending}
-              className="text-sm text-gray-400 hover:text-red-600 disabled:opacity-50"
-              aria-label={`Remove ${line.productVariant.name}`}
-            >
-              Remove
-            </button>
-          </li>
-        ))}
-      </ul>
-
-      <div className="flex items-center justify-between rounded-lg border border-gray-200 bg-white p-4">
-        <span className="text-sm text-gray-600">Subtotal ({itemCount} items)</span>
-        <span className="text-lg font-semibold text-gray-900">{formatPrice(subtotal)}</span>
-      </div>
-    </div>
-  );
+  return <CartView channelGroups={channelGroups} />;
 }

package/templates/storefront/src/app/products/[slug]/page.tsx

@@ -2,7 +2,11 @@ import Link from 'next/link';
 import { notFound } from 'next/navigation';
 
 import { ProductPurchase } from '../../../components/ProductPurchase';
-import { getProductBySlug } from '../../../lib/forgecart';
+import {
+  getProductBySlug,
+  getSellingPlanGroupsForVariant,
+  type SellingPlanGroup,
+} from '../../../lib/forgecart';
 
 export const dynamic = 'force-dynamic';
 
@@ -19,6 +23,21 @@ export default async function ProductDetailPage({
     notFound();
   }
 
+  // Subscription selling plans are eligible per variant, so fetch the groups for
+  // each of the product's variants (in parallel) and pass a variantId -> groups
+  // map to the client purchase control. Variants with no plans get the plain
+  // one-time add-to-cart path.
+  const planGroupsByVariant: Record<string, SellingPlanGroup[]> = Object.fromEntries(
+    await Promise.all(
+      product.variants.map(
+        async (variant): Promise<[string, SellingPlanGroup[]]> => [
+          variant.id,
+          await getSellingPlanGroupsForVariant(variant.id),
+        ],
+      ),
+    ),
+  );
+
   return (
     <div className="space-y-6">
       <Link href="/products" className="text-sm text-gray-600 hover:text-gray-900">
@@ -52,8 +71,8 @@ export default async function ProductDetailPage({
             />
           )}
 
-          {/* Pick a variant (Size/Color) -> price + add-to-cart. */}
-          <ProductPurchase product={product} />
+          {/* Pick a variant (Size/Color) -> price + purchase options + add-to-cart. */}
+          <ProductPurchase product={product} planGroupsByVariant={planGroupsByVariant} />
         </div>
       </div>
     </div>

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

@@ -0,0 +1,161 @@
+'use client';
+
+import Link from 'next/link';
+
+import { useCart } from '../lib/cart-context';
+import {
+  formatPrice,
+  getPlanCadenceLabel,
+  getPlanSavingsLabel,
+  type SellingPlan,
+  type SellingPlanGroup,
+} from '../lib/forgecart';
+
+/**
+ * The interactive cart, rendered off the live order from `useCart()`.
+ *
+ * `channelGroups` are the channel-wide subscription selling plans, fetched
+ * server-side by the cart route and passed in (the shop client is server-only,
+ * so a client component can't fetch them itself). When present, a "Subscribe to
+ * your whole order" box lets the customer put the entire order on a recurring
+ * plan; the chosen plan is reflected by the order's `sellingPlanId`. Lines that
+ * carry their own `sellingPlanId` (per-line subscriptions added from a product
+ * page) get a small "Subscription" label.
+ */
+export function CartView({ channelGroups }: { channelGroups: SellingPlanGroup[] }) {
+  const { cart, itemCount, subtotal, setQuantity, remove, setSellingPlan, pending } = useCart();
+  const lines = cart?.lines ?? [];
+
+  if (itemCount === 0) {
+    return (
+      <div className="space-y-4">
+        <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
+        <p className="text-gray-500">Your cart is empty.</p>
+        <Link
+          href="/products"
+          className="inline-block rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700"
+        >
+          Browse products
+        </Link>
+      </div>
+    );
+  }
+
+  // Channel-wide plans (enabled only), flattened across the channel groups.
+  const channelPlans: SellingPlan[] = channelGroups.flatMap((g) => g.plans).filter((p) => p.enabled);
+  const activePlanId = cart?.sellingPlanId ?? null;
+
+  return (
+    <div className="space-y-6">
+      <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
+
+      <ul className="divide-y divide-gray-200 rounded-lg border border-gray-200 bg-white">
+        {lines.map((line) => (
+          <li key={line.id} className="flex items-center gap-4 p-4">
+            <div className="h-16 w-16 shrink-0 overflow-hidden rounded bg-gray-100">
+              {line.featuredAsset?.preview ? (
+                // eslint-disable-next-line @next/next/no-img-element
+                <img
+                  src={line.featuredAsset.preview}
+                  alt={line.productVariant.name}
+                  className="h-full w-full object-cover"
+                />
+              ) : null}
+            </div>
+
+            <div className="min-w-0 flex-1">
+              <p className="truncate font-medium text-gray-900">{line.productVariant.name}</p>
+              <p className="text-sm text-gray-500">{formatPrice(line.unitPriceWithTax)} each</p>
+              {line.sellingPlanId && (
+                <span className="mt-1 inline-block rounded bg-gray-900 px-1.5 py-0.5 text-xs font-medium text-white">
+                  Subscription
+                </span>
+              )}
+            </div>
+
+            <div className="flex items-center gap-2">
+              <label className="sr-only" htmlFor={`qty-${line.id}`}>
+                Quantity
+              </label>
+              <input
+                id={`qty-${line.id}`}
+                type="number"
+                min={1}
+                value={line.quantity}
+                disabled={pending}
+                onChange={(e) => setQuantity(line.id, Number.parseInt(e.target.value, 10) || 1)}
+                className="w-16 rounded border border-gray-300 px-2 py-1 text-sm disabled:opacity-50"
+              />
+            </div>
+
+            <div className="w-24 text-right font-medium text-gray-900">
+              {formatPrice(line.linePriceWithTax)}
+            </div>
+
+            <button
+              type="button"
+              onClick={() => remove(line.id)}
+              disabled={pending}
+              className="text-sm text-gray-400 hover:text-red-600 disabled:opacity-50"
+              aria-label={`Remove ${line.productVariant.name}`}
+            >
+              Remove
+            </button>
+          </li>
+        ))}
+      </ul>
+
+      {channelPlans.length > 0 && (
+        <div className="space-y-2 rounded-lg border border-gray-200 bg-white p-4">
+          <h2 className="text-sm font-medium text-gray-700">Subscribe to your whole order</h2>
+          <div className="flex flex-col gap-2">
+            <button
+              type="button"
+              onClick={() => setSellingPlan(null)}
+              disabled={pending}
+              aria-pressed={activePlanId === null}
+              className={`rounded-md border px-3 py-2 text-left text-sm transition disabled:opacity-50 ${
+                activePlanId === null
+                  ? 'border-gray-900 ring-1 ring-gray-900'
+                  : 'border-gray-300 hover:border-gray-900'
+              }`}
+            >
+              <span className="font-medium text-gray-900">No, one-time</span>
+            </button>
+            {channelPlans.map((plan) => {
+              const savings = getPlanSavingsLabel(plan);
+              const hint = [savings, plan.trialDays > 0 ? `${plan.trialDays}-day free trial` : null]
+                .filter(Boolean)
+                .join(' · ');
+              const active = activePlanId === plan.id;
+              return (
+                <button
+                  key={plan.id}
+                  type="button"
+                  onClick={() => setSellingPlan(plan.id)}
+                  disabled={pending}
+                  aria-pressed={active}
+                  className={`rounded-md border px-3 py-2 text-left text-sm transition disabled:opacity-50 ${
+                    active
+                      ? 'border-gray-900 ring-1 ring-gray-900'
+                      : 'border-gray-300 hover:border-gray-900'
+                  }`}
+                >
+                  <span className="block font-medium text-gray-900">
+                    Subscribe — {getPlanCadenceLabel(plan)}
+                  </span>
+                  {hint && <span className="block text-xs text-gray-500">{hint}</span>}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      )}
+
+      <div className="flex items-center justify-between rounded-lg border border-gray-200 bg-white p-4">
+        <span className="text-sm text-gray-600">Subtotal ({itemCount} items)</span>
+        <span className="text-lg font-semibold text-gray-900">{formatPrice(subtotal)}</span>
+      </div>
+    </div>
+  );
+}

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

@@ -1,7 +1,6 @@
-import type { Product } from '@forgecart/sdk/shop';
 import Link from 'next/link';
 
-import { formatPrice, getStartingPrice } from '../lib/forgecart';
+import { formatPrice, getStartingPrice, type Product } from '../lib/forgecart';
 
 /** A product tile linking to its detail page. Used by the home and grid pages. */
 export function ProductCard({ product }: { product: Product }) {

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/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>;

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

@@ -1,16 +1,22 @@
 import { ForgeCartShopClient } from '@forgecart/sdk';
-import type { Product, ProductList } from '@forgecart/sdk/shop';
+import type {
+  ShopProductFieldFragment as Product,
+  ShopSellingPlanFieldFragment as SellingPlan,
+  ShopSellingPlanGroupFieldFragment as SellingPlanGroup,
+} from '@forgecart/sdk/shop';
 
 /**
  * Server-side ForgeCart shop client.
  *
  * The storefront talks to the ForgeCart shop GraphQL API on behalf of a single
- * channel. The channel token is sent as the `forgecart-token` header on every
- * request (the SDK adds it from `channelToken`), and the endpoint points at the
- * channel's shop-api.
+ * channel through the SDK's generated, typed operations — every read here is a
+ * typed method on the client (no hand-written query documents), and every type
+ * the components render is the SDK's own (`@forgecart/sdk/shop`).
  *
- * Both values come from the environment (`.env.local`, written by
- * `forgecart init`):
+ * The channel token is sent as the `forgecart-token` header on every request
+ * (the SDK adds it from `channelToken`), and the endpoint points at the
+ * channel's shop-api. Both values come from the environment (`.env.local`,
+ * written by `forgecart init`):
  *   - FORGECART_SHOP_API_URL  -> endpoint
  *   - FORGECART_CHANNEL_TOKEN -> channelToken
  *
@@ -26,10 +32,12 @@ const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
 let client: ForgeCartShopClient | null = null;
 
 /**
- * Lazily construct and memoize the shop client.
+ * Lazily construct and memoize the channel-scoped shop client.
  *
- * Constructing per-request would open a fresh websocket transport each time, so
- * we keep a singleton for the lifetime of the server process.
+ * All reads here are anonymous (channel scope only), so one client instance
+ * serves the whole server process. Per-shopper session state lives in
+ * `cart-actions.ts`, which constructs a per-request client around the session
+ * cookie instead.
  */
 export function getShopClient(): ForgeCartShopClient {
   if (!SHOP_API_URL) {
@@ -54,73 +62,20 @@ export function getShopClient(): ForgeCartShopClient {
 /** Convenience singleton for direct use in Server Components. */
 export const shopClient = (): ForgeCartShopClient => getShopClient();
 
-/* ------------------------------------------------------------------ *
- * Typed product helpers
- *
- * The generated typed operations (`shopClient.product.shopProducts` /
- * `.shopProduct`) only select `id` + `optionGroups`, which is not enough to
- * render a storefront. We therefore use the SDK's supported raw-query escape
- * hatch (`ForgeCartShopClient.query<T>(document, variables)`) with documents
- * that select the display fields, typed against the SDK's own `Product` /
- * `ProductList` types (`@forgecart/sdk/shop`).
- * ------------------------------------------------------------------ */
-
-const PRODUCT_FIELDS = `
-  id
-  name
-  slug
-  description
-  featuredAsset {
-    id
-    preview
-  }
-  optionGroups {
-    id
-    name
-    code
-    options {
-      id
-      name
-      code
-    }
-  }
-  variants {
-    id
-    name
-    sku
-    price
-    priceWithTax
-    options {
-      id
-      name
-      code
-      groupId
-    }
-  }
-`;
-
-const PRODUCTS_QUERY = `query StorefrontProducts($options: ListQueryOptions) {
-  products(options: $options) {
-    items {${PRODUCT_FIELDS}}
-    totalItems
-  }
-}`;
-
-const PRODUCT_BY_SLUG_QUERY = `query StorefrontProduct($slug: String) {
-  product(slug: $slug) {${PRODUCT_FIELDS}}
-}`;
-
-const PRODUCT_BY_ID_QUERY = `query StorefrontProductById($id: ID) {
-  product(id: $id) {${PRODUCT_FIELDS}}
-}`;
-
-interface ProductsQueryResult {
-  products: Pick<ProductList, 'items' | 'totalItems'>;
-}
-
-interface ProductQueryResult {
-  product: Product | null;
-}
+// The SDK's operation-shaped fragment types, re-exported under their domain
+// names so components import them from one place. These are exactly what the
+// typed operations return: `Product`/`ProductVariant` carry the storefront
+// display fields (name, slug, assets, priced variants); `Order`/`OrderLine`
+// the live cart incl. the subscription fields; the selling-plan pair backs the
+// subscription selector and the whole-cart subscribe box.
+export type {
+  ShopOrderFieldFragment as Order,
+  ShopOrderLineFieldFragment as OrderLine,
+  ShopProductFieldFragment as Product,
+  ShopProductVariantFieldFragment as ProductVariant,
+  ShopSellingPlanFieldFragment as SellingPlan,
+  ShopSellingPlanGroupFieldFragment as SellingPlanGroup,
+} from '@forgecart/sdk/shop';
 
 /**
  * Fetch a page of products for the channel.
@@ -131,29 +86,20 @@ export async function getProducts(
   options: { take?: number; skip?: number } = {},
 ): Promise<{ items: Product[]; totalItems: number }> {
   const { take = 24, skip = 0 } = options;
-  const result = await getShopClient().query<ProductsQueryResult>(PRODUCTS_QUERY, {
-    options: { take, skip },
-  });
-  return {
-    items: result.products.items,
-    totalItems: result.products.totalItems,
-  };
+  const { products } = await getShopClient().product.shopProducts({ options: { take, skip } });
+  return { items: products.items, totalItems: products.totalItems };
 }
 
 /** Fetch a single product by its URL slug. Returns `null` if not found. */
 export async function getProductBySlug(slug: string): Promise<Product | null> {
-  const result = await getShopClient().query<ProductQueryResult>(PRODUCT_BY_SLUG_QUERY, {
-    slug,
-  });
-  return result.product ?? null;
+  const { product } = await getShopClient().product.shopProduct({ slug });
+  return product ?? null;
 }
 
 /** Fetch a single product by id. Returns `null` if not found. */
 export async function getProductById(id: string): Promise<Product | null> {
-  const result = await getShopClient().query<ProductQueryResult>(PRODUCT_BY_ID_QUERY, {
-    id,
-  });
-  return result.product ?? null;
+  const { product } = await getShopClient().product.shopProduct({ id });
+  return product ?? null;
 }
 
 /**
@@ -164,6 +110,63 @@ export async function getFeaturedProducts(count = 4): Promise<Product[]> {
   return items;
 }
 
+/** Fetch the subscription groups a given variant is eligible for (per-line subscribe). */
+export async function getSellingPlanGroupsForVariant(
+  variantId: string,
+): Promise<SellingPlanGroup[]> {
+  const { sellingPlanGroupsForVariant } = await getShopClient().sellingPlan.sellingPlanGroupsForVariant({ variantId });
+  return sellingPlanGroupsForVariant;
+}
+
+/** Fetch the channel-wide subscription groups (whole-cart subscribe box). */
+export async function getChannelSellingPlanGroups(): Promise<SellingPlanGroup[]> {
+  const { channelSellingPlanGroups } = await getShopClient().sellingPlan.channelSellingPlanGroups();
+  return channelSellingPlanGroups;
+}
+
+/**
+ * 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) {