@forgecart/cli 2.202610052310.0 → 2.202610071755.0

package/templates/storefront-shadcn/src/lib/asset-alt.ts

@@ -0,0 +1,34 @@
+/**
+ * The `alt` attribute for an asset-backed `<img>` — the one place the template
+ * decides what an undescribed image announces (#1376).
+ *
+ * Alt text is the merchant's OWN description of the image, authored in the
+ * dashboard's media library. Its absence is therefore a decision rather than a
+ * gap: an image nobody described is announced as decorative (`alt=""`) and
+ * skipped by screen readers, which is exactly right for the product shots,
+ * badges and thumbnails that repeat text already sitting next to them.
+ *
+ * It is deliberately NEVER back-filled with the product or variant name. A
+ * derived placeholder is indistinguishable from a real description to both a
+ * screen reader and a crawler, while carrying nothing the adjacent markup does
+ * not already say — so it spends a listener's attention repeating the caption
+ * they just heard, and tells a crawler the image was described when it was
+ * not. The empty string is the honest answer and the accessible one, and this
+ * function exists so that judgement is stated once instead of re-derived at
+ * every `<img>` (all four of which read `alt={product.name}` before it).
+ *
+ * A blank-but-present description collapses to the same decorative default.
+ * `alt="   "` is the worst of both worlds — not a description, and not the
+ * empty string that marks an image skippable, so a reader falls back to
+ * announcing the file name. The dashboard already trims before it writes, but
+ * the field is equally writable through the admin API, so the guarantee is
+ * made here where it is actually rendered rather than assumed upstream.
+ *
+ * The parameter is structural, not the SDK's `Asset`: every selection that
+ * renders an image picks `altText` alongside `preview`, and asking only for
+ * the field actually read keeps this module free of the SDK import — which is
+ * what lets it be unit-tested directly (see tool/storefront-template-spec).
+ */
+export function getAssetAlt(asset: { altText?: string | null }): string {
+  return asset.altText?.trim() ?? '';
+}

package/templates/storefront-shadcn/src/lib/backend-actions.ts

@@ -0,0 +1,20 @@
+'use server';
+
+import 'server-only';
+
+import { invokeBackendMethod } from '../server/runner';
+import type { ActionResult } from './action-result';
+
+/**
+ * The ONE Server Action bridging the browser into the embedded NestJS
+ * backend (`src/server/`) — Next's native RPC is the transport, the booted
+ * registry is the authority. Components never import this directly: they
+ * call through `backend` (`lib/backend-client.ts`), which types the surface
+ * off `backend-api.ts` and guards the proxy's magic keys.
+ */
+export async function invokeBackend(
+  method: string,
+  input: unknown,
+): Promise<ActionResult<unknown>> {
+  return invokeBackendMethod(method, input);
+}

package/templates/storefront-shadcn/src/lib/backend-client.ts

@@ -0,0 +1,47 @@
+import type { BackendApi } from '../server/backend-api';
+import type { ActionResult } from './action-result';
+import { invokeBackend } from './backend-actions';
+
+/**
+ * `sdk.backend` — the typed browser gate onto the storefront's embedded
+ * NestJS backend.
+ *
+ * Compile time: the mapped type below projects `backend-api.ts` onto the
+ * proxy, so editors autocomplete exactly the registered methods and an
+ * unknown name fails the build. (The import is type-only — it erases, so no
+ * server code reaches the client bundle; the `server-only` guards enforce
+ * it.)
+ *
+ * Runtime: the proxy fabricates an invoker for ANY string key — the
+ * server-side registry is the real authority, answering
+ * BACKEND_METHOD_NOT_FOUND in the normal envelope for unknown or
+ * stale-bundle names. Magic keys are excluded so the object never
+ * masquerades as a thenable (`await backend` must not fire a wire call
+ * named "then").
+ *
+ * Usage, any client component:
+ *   const result = await backend.assignCustomerHash({});
+ *   if (!result.ok) return renderError(result.error);
+ */
+type BackendGate = {
+  [K in keyof BackendApi]: (
+    input: Parameters<BackendApi[K]>[0],
+  ) => Promise<ActionResult<Awaited<ReturnType<BackendApi[K]>>>>;
+};
+
+const RESERVED_KEYS = new Set([
+  'then',
+  'catch',
+  'finally',
+  'toJSON',
+  'valueOf',
+  'constructor',
+  '$$typeof',
+]);
+
+export const backend: BackendGate = new Proxy({} as BackendGate, {
+  get(_target, key) {
+    if (typeof key !== 'string' || RESERVED_KEYS.has(key)) return undefined;
+    return (input: unknown) => invokeBackend(key, input);
+  },
+});

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

@@ -0,0 +1,236 @@
+'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,
+  type ReactNode,
+} from 'react';
+
+import {
+  initShopSession,
+  isSessionReady,
+  readMirrorSession,
+  runSessionOp,
+  type ShopSessionConfig,
+} from './shop-session';
+
+/**
+ * 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.
+ *
+ * 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({
+  shopConfig,
+  children,
+}: {
+  shopConfig: ShopSessionConfig | null;
+  children: ReactNode;
+}) {
+  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<ActionResult<Order | null>>) => {
+    startTransition(async () => {
+      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(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(() =>
+        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 setSellingPlan = useCallback(
+    (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 value = useMemo<CartContextValue>(
+    () => ({
+      cart,
+      itemCount: cart?.totalQuantity ?? 0,
+      subtotal: cart?.subTotalWithTax ?? 0,
+      hydrated,
+      pending,
+      error,
+      add,
+      setQuantity,
+      remove,
+      setSellingPlan,
+      applyCoupon,
+      removeCoupon,
+      clearError,
+      refresh,
+    }),
+    [
+      cart,
+      hydrated,
+      pending,
+      error,
+      add,
+      setQuantity,
+      remove,
+      setSellingPlan,
+      applyCoupon,
+      removeCoupon,
+      clearError,
+      refresh,
+    ],
+  );
+
+  return <CartContext.Provider value={value}>{children}</CartContext.Provider>;
+}
+
+/** Access the cart. Must be used inside a `<CartProvider>`. */
+export function useCart(): CartContextValue {
+  const ctx = useContext(CartContext);
+  if (!ctx) {
+    throw new Error('useCart must be used within a CartProvider');
+  }
+  return ctx;
+}

package/templates/storefront-shadcn/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-shadcn/src/lib/content/page-metadata.ts

@@ -0,0 +1,113 @@
+import { staticPathsByLocale } from '../seo/alternates';
+import { entityMetadata } from '../seo/metadata';
+import type { MetadataInput, SeoMetaRow } from '../seo/metadata';
+import { advertisedPathsByLocale, ownContentRow } from '../seo/sidecar';
+import type { SeoLanguageRow } from '../seo/sidecar';
+import type { PageResolution } from './resolve-page';
+
+/**
+ * What a page URL claims about its own CONTENT (#1375, epic launch#54 D11 as
+ * amended by ruling ANSWER-1547Z) — the half of `/pages/<route>`'s metadata the
+ * page decides, as a value the route spreads into `routeMetadata`.
+ *
+ * Every claim is read off the page record's per-language SEO sidecar, through
+ * the SAME rules the product route uses, so a page and a product can never
+ * disagree about what a language without its own copy is (ruling Q6: product
+ * parity):
+ *
+ *  - title, description and social image come from `entityMetadata` — the
+ *    sidecar's row for this locale, the title falling back to the page
+ *    definition's own name, and the social card armed only by a STORED image
+ *    (a page's mapped image never arms it);
+ *  - the alternates cluster is the route's address in every language the
+ *    channel offers, narrowed to the languages that hold content of their own
+ *    (`advertisedPathsByLocale`) — an untranslated language is never an
+ *    hreflang alternate, and its own copy claims no canonical;
+ *  - indexability is the merchant's choice for a language with its own copy,
+ *    and `false` for a derived fallback (`ownContentRow`).
+ *
+ * PURE BY CONTRACT, for the reason `resolve-page.ts` is: the template-spec
+ * imports it by relative path, which is what makes these claims a table of
+ * vectors rather than something only a running pod can exercise. The inputs
+ * are structural for the same reason — the generated query types satisfy them,
+ * so the scaffold's own compiler proves the assignment.
+ */
+
+/** One language of a page record's sidecar, as these claims read it. */
+export type PageSeoRow = SeoLanguageRow & SeoMetaRow;
+
+/** The definition fields these claims read. */
+export interface ClaimingPageGroup {
+  /** The merchant's name for the page — the title when the sidecar names none. */
+  readonly name: string;
+}
+
+/**
+ * The record fields these claims read.
+ *
+ * The sidecar is optional AND nullable because the generated selection is: the
+ * shop API answers `seo: null` for a definition that is not a page kind. A
+ * resolution that reached its `ok` arm has already proven the definition IS a
+ * page, so a null here means the API and the definition disagree — read, like a
+ * missing language row, as "no language has content of its own".
+ */
+export interface ClaimingPageEntry {
+  readonly seo?: { readonly languages: readonly PageSeoRow[] } | null;
+}
+
+/** Where the page is being rendered, and every language its route exists in. */
+export interface PageClaimsContext {
+  /** The locale this page is being rendered in. */
+  locale: string;
+  /** Every language the channel offers — the languages a page ROUTE exists in. */
+  languageCodes: readonly string[];
+  /** The locale-STRIPPED address of this page (`/pages/<route>`). */
+  pathname: string;
+}
+
+/** The content half of a page's `MetadataInput`, every key decided. */
+export type PageContentClaims = Required<
+  Pick<
+    MetadataInput,
+    'pathsByLocale' | 'title' | 'description' | 'socialImage' | 'contentIndexable'
+  >
+>;
+
+/** The sidecar a record without one is read as: no language holds its own copy. */
+const NO_SIDECAR: NonNullable<ClaimingPageEntry['seo']> = { languages: [] };
+
+/**
+ * A URL that is not a page claims nothing about content: no name of its own, no
+ * alternates, and not indexable — the refusal the product route states for a
+ * missing product, stated here rather than left to whatever Next does with the
+ * head of a page that answers 404.
+ */
+const NOT_FOUND_CLAIMS: PageContentClaims = {
+  pathsByLocale: {},
+  title: null,
+  description: null,
+  socialImage: null,
+  contentIndexable: false,
+};
+
+/**
+ * Decide the content claims of one page URL from the resolution the route acts
+ * on — the same value that decides its status, so the head and the response
+ * can never disagree about what the URL is.
+ */
+export function pageContentClaims(
+  resolution: PageResolution<ClaimingPageGroup, ClaimingPageEntry>,
+  { locale, languageCodes, pathname }: PageClaimsContext,
+): PageContentClaims {
+  if (resolution.kind === 'notFound') return NOT_FOUND_CLAIMS;
+
+  const seo = resolution.entry.seo ?? NO_SIDECAR;
+  const entity = entityMetadata({ name: resolution.group.name, seo }, locale);
+  return {
+    pathsByLocale: advertisedPathsByLocale(staticPathsByLocale(languageCodes, pathname), seo),
+    title: entity.title,
+    description: entity.description,
+    socialImage: entity.socialImage,
+    contentIndexable: ownContentRow(seo, locale)?.indexable ?? false,
+  };
+}