@forgecart/cli 2.202608121449.0 → 2.202608200713.0

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

@@ -1,10 +1,15 @@
 'use client';
 
+import type { ExtractedError } from '@forgecart/sdk/shop';
+import type { ShopAddItemToOrderInput } from '@forgecart/sdk/shop';
+
+import type { ActionResult } from './action-result';
 import type { Order } from './forgecart';
 import {
   createContext,
   useCallback,
   useContext,
+  useEffect,
   useMemo,
   useState,
   useTransition,
@@ -12,80 +17,210 @@ import {
 } from 'react';
 
 import {
-  addToCart,
-  getCart,
-  removeLine as removeLineAction,
-  setCartSellingPlan,
-  updateLine,
-} from './cart-actions';
+  initShopSession,
+  isSessionReady,
+  readMirrorSession,
+  runSessionOp,
+  type ShopSessionConfig,
+} from './shop-session';
 
 /**
- * Cart state backed by the ForgeCart shop order API (see `cart-actions.ts`).
+ * Cart state on the shopper's OWN shop websocket (`shop-session.ts`) — the
+ * client half of the progressive stack.
+ *
+ * PPR-compatible boot: the server shell renders with NO cart (reading the
+ * session cookie would dynamize the whole layout), so the provider hydrates
+ * client-side. On mount it arms the session singleton with the serialized
+ * channel config; when the mirror cookie says a session exists, it reads the
+ * active order over the socket (`activeOrder` is nullable and NEVER mints —
+ * carts start with the first added item). `hydrated` stays false until that
+ * first read settles, so cart surfaces can render a skeleton instead of a
+ * false "empty cart" flash.
  *
- * `cart` is the live `Order` (the SDK type). The provider is seeded with the
- * server-fetched active order (`initialCart`) so the first paint is correct,
- * then every mutation calls a Server Action and replaces it with the order the
- * API returns. `pending` is true while a cart mutation is in flight.
+ * Every mutation runs on the same socket and replaces `cart` with the order
+ * from the typed `ActionResult` envelope; a failure keeps the last known
+ * cart AND surfaces the typed error on `error`. `pending` is true while a
+ * cart mutation is in flight. The first `add` on a fresh visitor mints the
+ * session client-side; `shop-session.ts` syncs the captured token back into
+ * the cookies so the next SSR pass sees this cart.
  */
 interface CartContextValue {
   cart: Order | null;
   itemCount: number;
   subtotal: number;
+  /** False until the mount-time cart read settles — render skeletons, not "empty". */
+  hydrated: boolean;
   pending: boolean;
+  error: ExtractedError | null;
   add: (variantId: string, quantity?: number, sellingPlanId?: string) => void;
   setQuantity: (lineId: string, quantity: number) => void;
   remove: (lineId: string) => void;
   setSellingPlan: (sellingPlanId: string | null) => void;
+  applyCoupon: (code: string) => void;
+  removeCoupon: (code: string) => void;
+  clearError: () => void;
   refresh: () => void;
 }
 
 const CartContext = createContext<CartContextValue | null>(null);
 
 export function CartProvider({
-  initialCart,
+  shopConfig,
   children,
 }: {
-  initialCart: Order | null;
+  shopConfig: ShopSessionConfig | null;
   children: ReactNode;
 }) {
-  const [cart, setCart] = useState<Order | null>(initialCart);
+  const [cart, setCart] = useState<Order | null>(null);
+  const [hydrated, setHydrated] = useState(false);
+  const [error, setError] = useState<ExtractedError | null>(null);
   const [pending, startTransition] = useTransition();
 
-  const run = useCallback((op: () => Promise<Order | null>) => {
+  const run = useCallback((op: () => Promise<ActionResult<Order | null>>) => {
     startTransition(async () => {
-      setCart(await op());
+      const result = await op();
+      if (result.ok) {
+        setCart(result.data);
+        setError(null);
+        return;
+      }
+      setError(result.error);
     });
   }, []);
 
+  // Arm the session singleton and hydrate the cart. An unconfigured scaffold
+  // (pre-`forgecart init`) or a visitor with no session hydrates to the
+  // legitimate empty state without touching the network.
+  useEffect(() => {
+    if (!shopConfig) {
+      setHydrated(true);
+      return;
+    }
+    initShopSession(shopConfig);
+    if (!readMirrorSession()) {
+      setHydrated(true);
+      return;
+    }
+    let cancelled = false;
+    void (async () => {
+      const result = await runSessionOp(
+        async (client) => (await client.order.activeOrder()).activeOrder ?? null,
+      );
+      if (cancelled) return;
+      if (result.ok) setCart(result.data);
+      setHydrated(true);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [shopConfig]);
+
   const add = useCallback(
     (variantId: string, quantity = 1, sellingPlanId?: string) =>
-      run(() => addToCart(variantId, quantity, sellingPlanId)),
+      run(async () => {
+        const input: ShopAddItemToOrderInput = { variantId, quantity };
+        if (sellingPlanId) {
+          input.sellingPlanId = sellingPlanId;
+        }
+        return runSessionOp(
+          async (client) => (await client.cart.addItemToOrder({ input })).addItemToOrder,
+        );
+      }),
     [run],
   );
   const setQuantity = useCallback(
-    (lineId: string, quantity: number) => run(() => updateLine(lineId, quantity)),
+    (lineId: string, quantity: number) =>
+      run(() =>
+        runSessionOp(
+          async (client) =>
+            (await client.cart.adjustOrderLine({ input: { lineId, quantity } })).adjustOrderLine,
+        ),
+      ),
+    [run],
+  );
+  const remove = useCallback(
+    (lineId: string) =>
+      run(() =>
+        runSessionOp(
+          async (client) => (await client.cart.removeOrderLine({ lineId })).removeOrderLine,
+        ),
+      ),
     [run],
   );
-  const remove = useCallback((lineId: string) => run(() => removeLineAction(lineId)), [run]);
   const setSellingPlan = useCallback(
-    (sellingPlanId: string | null) => run(() => setCartSellingPlan(sellingPlanId)),
+    (sellingPlanId: string | null) =>
+      run(() =>
+        runSessionOp(
+          async (client) =>
+            (await client.cart.setOrderSellingPlan({ input: { sellingPlanId } }))
+              .setOrderSellingPlan,
+        ),
+      ),
+    [run],
+  );
+  const applyCoupon = useCallback(
+    (code: string) =>
+      run(() =>
+        runSessionOp(
+          async (client) => (await client.cart.applyCouponCode({ code })).applyCouponCode,
+        ),
+      ),
+    [run],
+  );
+  const removeCoupon = useCallback(
+    (code: string) =>
+      run(() =>
+        runSessionOp(
+          async (client) => (await client.cart.removeCouponCode({ code })).removeCouponCode,
+        ),
+      ),
+    [run],
+  );
+  const clearError = useCallback(() => setError(null), []);
+  const refresh = useCallback(
+    () =>
+      run(async () => {
+        if (!isSessionReady() || !readMirrorSession()) {
+          return { ok: true, data: null };
+        }
+        return runSessionOp(
+          async (client) => (await client.order.activeOrder()).activeOrder ?? null,
+        );
+      }),
     [run],
   );
-  const refresh = useCallback(() => run(() => getCart()), [run]);
 
   const value = useMemo<CartContextValue>(
     () => ({
       cart,
       itemCount: cart?.totalQuantity ?? 0,
       subtotal: cart?.subTotalWithTax ?? 0,
+      hydrated,
       pending,
+      error,
       add,
       setQuantity,
       remove,
       setSellingPlan,
+      applyCoupon,
+      removeCoupon,
+      clearError,
       refresh,
     }),
-    [cart, pending, add, setQuantity, remove, setSellingPlan, refresh],
+    [
+      cart,
+      hydrated,
+      pending,
+      error,
+      add,
+      setQuantity,
+      remove,
+      setSellingPlan,
+      applyCoupon,
+      removeCoupon,
+      clearError,
+      refresh,
+    ],
   );
 
   return <CartContext.Provider value={value}>{children}</CartContext.Provider>;

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

@@ -0,0 +1,185 @@
+'use client';
+
+import type { CreateAddressInput, SelectRateInput, SetCustomerInput } from '@forgecart/sdk/shop';
+
+import type { ActionResult } from './action-result';
+import type {
+  CheckoutOrder,
+  CheckoutOrderView,
+  ConfirmedPaymentSession,
+  EligiblePaymentProvider,
+  PaymentSession,
+  PaymentTemplate,
+  PaymentVariables,
+  ShippingRateGroup,
+} from './forgecart';
+import { runSessionOp } from './shop-session';
+
+/**
+ * Checkout operations on the shopper's OWN websocket (`shop-session.ts`):
+ * contact → address → rates → payment → confirmation. Same names, same
+ * `ActionResult` envelopes as the retired Server-Action module — the flow
+ * components changed one import, not their contracts. Every operation here
+ * is session-scoped, which is exactly why it runs client-side; the only
+ * server-fetched checkout data is the public country list (channel read).
+ */
+
+/** Attach the guest contact (email + name) to the active order. */
+export async function setCustomer(
+  input: SetCustomerInput,
+): Promise<ActionResult<CheckoutOrderView | null>> {
+  return runSessionOp(
+    async (client) => (await client.cart.setCustomerForOrder({ input })).setCustomerForOrder,
+  );
+}
+
+/**
+ * Persist the shipping address. `countryId` accepts the canonical Country id
+ * OR an ISO code (an autocomplete suggestion's `countryCode` feeds it
+ * directly); `phoneNumber` is required server-side
+ * (SHIPPING_ADDRESS_PHONE_REQUIRED arrives as a typed field error otherwise).
+ */
+export async function setShippingAddress(
+  input: CreateAddressInput,
+): Promise<ActionResult<CheckoutOrderView | null>> {
+  return runSessionOp(
+    async (client) =>
+      (await client.checkout.setOrderShippingAddress({ input })).setOrderShippingAddress,
+  );
+}
+
+/** Type-ahead address suggestions ([] = no provider → manual entry). */
+export async function suggestAddresses(
+  query: string,
+  sessionToken: string,
+  countryCode?: string,
+): Promise<ActionResult<{ id: string; description: string }[]>> {
+  return runSessionOp(
+    async (client) =>
+      (await client.address.addressAutocomplete({ input: { query, sessionToken, countryCode } }))
+        .addressAutocomplete,
+  );
+}
+
+/** Resolve one suggestion into a structured address for the form. */
+export async function resolveAddressSuggestion(
+  id: string,
+  sessionToken: string,
+): Promise<
+  ActionResult<{
+    streetLine1: string;
+    streetLine2?: string | null;
+    city?: string | null;
+    province?: string | null;
+    postalCode?: string | null;
+    countryCode: string;
+  }>
+> {
+  return runSessionOp(
+    async (client) =>
+      (await client.address.addressSuggestion({ input: { id, sessionToken } })).addressSuggestion,
+  );
+}
+
+/**
+ * Explicit synchronous carrier re-quote — run on rate-step entry and after
+ * an address change. Per-provider failures arrive in each group's
+ * `lastRateErrors`; the read query never quotes (#863's read/refresh split).
+ */
+export async function refreshShippingRates(): Promise<ActionResult<ShippingRateGroup[]>> {
+  return runSessionOp(
+    async (client) => (await client.shipping.refreshShippingRateGroups()).refreshShippingRateGroups,
+  );
+}
+
+/** Read the persisted rate groups (no carrier quoting). */
+export async function getShippingRates(): Promise<ActionResult<ShippingRateGroup[]>> {
+  return runSessionOp(
+    async (client) => (await client.shipping.shippingRateGroups()).shippingRateGroups,
+  );
+}
+
+/** The CUSTOMER's rate pick — the ArrangingPayment gate requires one per group. */
+export async function selectShippingRate(
+  input: SelectRateInput,
+): Promise<ActionResult<CheckoutOrderView | null>> {
+  return runSessionOp(
+    async (client) => (await client.shipping.selectShippingRate({ input })).selectShippingRate,
+  );
+}
+
+/** Advance the order to ArrangingPayment (gated: address+phone, items, selected rates). */
+export async function transitionToPayment(): Promise<ActionResult<CheckoutOrderView | null>> {
+  return runSessionOp(
+    async (client) =>
+      (await client.checkout.transitionOrderToState({ input: { state: 'arrangingPayment' } }))
+        .transitionOrderToState,
+  );
+}
+
+/** Providers eligible for this order (eligibilityMessage is data, not an error). */
+export async function getEligiblePaymentProviders(
+  orderId: string,
+): Promise<ActionResult<EligiblePaymentProvider[]>> {
+  return runSessionOp(
+    async (client) =>
+      (await client.payment.shopEligiblePaymentProviders({ orderId })).eligiblePaymentProviders,
+  );
+}
+
+/** Create the payment session (ONE per order — coupon edits freeze at this point). */
+export async function createPaymentSession(
+  orderId: string,
+  providerCode?: string,
+): Promise<ActionResult<PaymentSession>> {
+  return runSessionOp(
+    async (client) =>
+      (await client.payment.createPaymentSession({ input: { orderId, providerCode } }))
+        .createPaymentSession,
+  );
+}
+
+/**
+ * Raw variables for the in-page payment adapter (`PaymentElementForm`):
+ * providerCode, publishableKey, scriptUrl, amount, currency — straight from
+ * the order + the channel's provider config, no session required.
+ */
+export async function getPaymentVariables(
+  orderId: string,
+): Promise<ActionResult<PaymentVariables>> {
+  return runSessionOp(
+    async (client) => (await client.payment.getSessionVariables({ orderId })).getSessionVariables,
+  );
+}
+
+/**
+ * The provider's hosted form for `PaymentFormEmbed`. `origin` is the
+ * embedding storefront's own origin — the template pins every postMessage of
+ * the #865 handshake (iframe-ready / payment-success / payment-error) to it.
+ */
+export async function getPaymentFormTemplate(
+  orderId: string,
+  origin: string,
+): Promise<ActionResult<PaymentTemplate>> {
+  return runSessionOp(
+    async (client) =>
+      (await client.payment.getSessionTemplate({ input: { orderId, origin } })).getSessionTemplate,
+  );
+}
+
+/** Confirm the session where the provider flow requires it (token/redirect models). */
+export async function confirmPaymentSession(
+  sessionId: string,
+): Promise<ActionResult<ConfirmedPaymentSession>> {
+  return runSessionOp(
+    async (client) =>
+      (await client.payment.confirmPaymentSession({ sessionId })).confirmPaymentSession,
+  );
+}
+
+/** The settled order for the confirmation step (by the code shown to the shopper). */
+export async function getOrderByCode(code: string): Promise<ActionResult<CheckoutOrder | null>> {
+  return runSessionOp(
+    async (client) => (await client.order.shopOrderByCode({ code })).orderByCode ?? null,
+  );
+}

package/templates/storefront/src/lib/error-messages.ts

@@ -0,0 +1,24 @@
+import type { ExtractedError } from '@forgecart/sdk/shop';
+
+/**
+ * Shopper-facing messages for the typed checkout error codes.
+ *
+ * The shop API's error contract ships CODES, never prose — `message` on an
+ * extracted error is the code string itself, and resolving human copy is the
+ * frontend's job (error-handling contract). A raw enum leaking into the UI is
+ * a defect (the address step rendered SHIPPING_ADDRESS_PHONE_REQUIRED
+ * verbatim, 2026-08-09).
+ */
+const SHOPPER_MESSAGES: Record<string, string> = {
+  SHIPPING_ADDRESS_PHONE_REQUIRED: 'A phone number is required for delivery updates.',
+  SHIPPING_ADDRESS_COUNTRY_REQUIRED: 'Please select a country.',
+  SHIPPING_ADDRESS_COUNTRY_INVALID: 'We can’t ship to the selected country yet.',
+};
+
+const FALLBACK_MESSAGE = 'Something went wrong. Please check your details and try again.';
+
+/** Human copy for a typed error — never the raw enum, never undefined. */
+export function shopperMessage(error: Pick<ExtractedError, 'code'> | null | undefined): string {
+  if (!error?.code) return FALLBACK_MESSAGE;
+  return SHOPPER_MESSAGES[error.code] ?? FALLBACK_MESSAGE;
+}

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

@@ -283,53 +283,51 @@ async function scheduleExposure(
  * whole render consistent — layout and page asking for the same key get one
  * resolution and at most ONE exposure emission per request.
  */
-export const getVariant = cache(
-  async (experimentKey: string): Promise<ExperimentVariantResult> => {
-    const inert: ExperimentVariantResult = {
-      variantKey: null,
-      assignmentSource: null,
-      payload: null,
-    };
-    if (!SLUG_REGEX.test(experimentKey)) return inert;
+export const getVariant = cache(async (experimentKey: string): Promise<ExperimentVariantResult> => {
+  const inert: ExperimentVariantResult = {
+    variantKey: null,
+    assignmentSource: null,
+    payload: null,
+  };
+  if (!SLUG_REGEX.test(experimentKey)) return inert;
 
-    const experiments = await getActiveExperiments();
-    const experiment = experiments.find((entry) => entry.experimentKey === experimentKey);
-    if (!experiment) return inert;
+  const experiments = await getActiveExperiments();
+  const experiment = experiments.find((entry) => entry.experimentKey === experimentKey);
+  if (!experiment) return inert;
 
-    if (experiment.subjectType === 'customer') {
-      // The storefront server has no verified customer id (auth lives behind
-      // the shop API session) — a customer-scoped experiment renders as
-      // non-participant control here, with no exposure. Customer-subject
-      // resolution belongs to clients that KNOW the customer id.
-      const control = experiment.variants[0];
-      if (!control) return inert;
-      return { variantKey: control.key, assignmentSource: null, payload: control.payload ?? null };
-    }
+  if (experiment.subjectType === 'customer') {
+    // The storefront server has no verified customer id (auth lives behind
+    // the shop API session) — a customer-scoped experiment renders as
+    // non-participant control here, with no exposure. Customer-subject
+    // resolution belongs to clients that KNOW the customer id.
+    const control = experiment.variants[0];
+    if (!control) return inert;
+    return { variantKey: control.key, assignmentSource: null, payload: control.payload ?? null };
+  }
 
-    const visitorId = await getRequestVisitorId();
-    const forcedVariantKey = (await getForcedVariantMap())[experimentKey] ?? null;
+  const visitorId = await getRequestVisitorId();
+  const forcedVariantKey = (await getForcedVariantMap())[experimentKey] ?? null;
 
-    let result: AssignmentResult;
-    try {
-      result = resolveExperimentAssignment(toAssignmentConfig(experiment), {
-        subjectKey: visitorId,
-        forcedVariantKey,
-      });
-    } catch {
-      // A malformed delivery (out-of-bounds weight, empty variants) must
-      // never break rendering — the caller falls back to its default branch.
-      return inert;
-    }
+  let result: AssignmentResult;
+  try {
+    result = resolveExperimentAssignment(toAssignmentConfig(experiment), {
+      subjectKey: visitorId,
+      forcedVariantKey,
+    });
+  } catch {
+    // A malformed delivery (out-of-bounds weight, empty variants) must
+    // never break rendering — the caller falls back to its default branch.
+    return inert;
+  }
 
-    if (result.exposed && result.variantKey !== null) {
-      await scheduleExposure(experiment, result, visitorId);
-    }
+  if (result.exposed && result.variantKey !== null) {
+    await scheduleExposure(experiment, result, visitorId);
+  }
 
-    const variant = experiment.variants.find((entry) => entry.key === result.variantKey);
-    return {
-      variantKey: result.variantKey,
-      assignmentSource: result.assignmentSource,
-      payload: variant?.payload ?? null,
-    };
-  },
-);
+  const variant = experiment.variants.find((entry) => entry.key === result.variantKey);
+  return {
+    variantKey: result.variantKey,
+    assignmentSource: result.assignmentSource,
+    payload: variant?.payload ?? null,
+  };
+});