@forgecart/cli 2.202610280649.0 → 2.202610280926.0

package/templates/storefront-blank/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-blank/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,
+  };
+}

package/templates/storefront-blank/src/lib/content/render-fields.tsx

@@ -0,0 +1,256 @@
+import type { ReactNode } from 'react';
+
+import { getAssetAlt } from '../asset-alt';
+import type { PageEntry, PageFieldValue } from '../forgecart';
+
+/**
+ * The generic renderer for an ACF page record (#1934, epic launch#50).
+ *
+ * A page definition is whatever the merchant built in the dashboard, so this
+ * file cannot know the fields it will be handed — it renders by ACF field TYPE,
+ * driven by the `__typename` the shop API discriminates every value with. The
+ * layout is deliberately plain: this is the scaffold a merchant edits, and a
+ * template that guessed at a design would be undone before it shipped.
+ *
+ * Order and labels come from the DEFINITIONS, not the values: the shop API
+ * returns field definitions in the order the editor arranged them, while the
+ * value list is storage order and means nothing to a reader. A definition with
+ * no value (a display-only field — a divider, a chart) simply has nothing to
+ * match and renders nothing, which is why no field-category test appears here.
+ *
+ * Repeater rows render one level deep, and the bound is a real one rather than
+ * an oversight: the shop operation unrolls the group tree three levels
+ * (fragments cannot recurse), so each level is a DIFFERENT generated type and a
+ * general recursion has no single shape to stand on. One level covers the
+ * "sections of a page" shape this route exists for; deeper trees are a
+ * follow-up with the operation change they need.
+ */
+
+/** What this renderer needs of a field definition — nothing about its storage. */
+export interface RenderableDefinition {
+  readonly fieldName: string;
+  readonly title?: string | null;
+  readonly hideTitle?: boolean | null;
+  readonly children?: readonly RenderableDefinition[] | null;
+}
+
+/** One repeater as an entry carries it: a named group of rows. */
+type PageRepeater = PageEntry['groups'][number];
+
+export function PageFields({
+  definitions,
+  entry,
+}: {
+  definitions: readonly RenderableDefinition[];
+  entry: PageEntry;
+}): ReactNode {
+  return (
+    <div className="space-y-8">
+      {definitions.map((definition) => (
+        <PageField
+          key={definition.fieldName}
+          definition={definition}
+          value={entry.fields.find((field) => field.name === definition.fieldName)}
+          repeater={entry.groups.find((group) => group.name === definition.fieldName)}
+        />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * One definition's section — its label and whatever it holds.
+ *
+ * A field with neither a value nor rows renders NOTHING, not an empty section:
+ * an unpublished column reads as null (the shop API's live-column gating) and a
+ * merchant who left a field blank meant to leave it blank. Either way a bare
+ * heading over nothing is noise on a public page.
+ */
+function PageField({
+  definition,
+  value,
+  repeater,
+}: {
+  definition: RenderableDefinition;
+  value: PageFieldValue | undefined;
+  repeater: PageRepeater | undefined;
+}): ReactNode {
+  const body = repeater ? renderRepeater(repeater, definition.children ?? []) : renderValue(value);
+  if (body === null) return null;
+
+  return (
+    // `data-fc-field` carries the field's identity into the DOM: it is what a
+    // merchant styles a single field by, and the stable hook the storefront
+    // e2e reads.
+    <section className="space-y-2" data-fc-field={definition.fieldName}>
+      {definition.hideTitle !== true && definition.title ? (
+        <h2 className="text-xl font-semibold tracking-tight">{definition.title}</h2>
+      ) : null}
+      {body}
+    </section>
+  );
+}
+
+/** A repeater's rows, each row rendering its own members through the same law. */
+function renderRepeater(
+  repeater: PageRepeater,
+  members: readonly RenderableDefinition[],
+): ReactNode {
+  if (repeater.entries.length === 0) return null;
+  return (
+    <div className="space-y-6">
+      {repeater.entries.map((row) => (
+        <div key={row.id} className="space-y-2">
+          {members.map((member) => {
+            const body = renderValue(row.fields.find((field) => field.name === member.fieldName));
+            if (body === null) return null;
+            return (
+              <div key={member.fieldName} data-fc-field={member.fieldName}>
+                {member.hideTitle !== true && member.title ? (
+                  <h3 className="text-sm font-semibold text-base-content/70">{member.title}</h3>
+                ) : null}
+                {body}
+              </div>
+            );
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * One stored value as markup, or `null` when it holds nothing to show.
+ *
+ * An exhaustive `switch` over the discriminated union rather than a lookup
+ * table, and the `default` arm is the reason: it assigns the value to `never`,
+ * so adding an ACF field type without teaching this file about it is a COMPILE
+ * error in the merchant's scaffold instead of a section that silently renders
+ * blank on a live page.
+ */
+function renderValue(value: PageFieldValue | undefined): ReactNode {
+  if (value === undefined) return null;
+
+  switch (value.__typename) {
+    case 'AcfStringValue':
+      return text(value.stringValue);
+    case 'AcfIntValue':
+      return absent(value.intValue) ? null : text(String(value.intValue));
+    case 'AcfFloatValue':
+      return absent(value.floatValue) ? null : text(String(value.floatValue));
+    case 'AcfBoolValue':
+      return absent(value.boolValue) ? null : text(value.boolValue ? 'Yes' : 'No');
+    case 'AcfDateValue':
+      // The API serializes DateTime as ISO 8601; rendered as `<time>` with the
+      // machine-readable value intact, and NOT locale-formatted here — a
+      // formatted date is a merchant presentation choice, and guessing one in
+      // the scaffold would be a decision nobody made.
+      return absent(value.dateValue) ? null : (
+        <time dateTime={value.dateValue} className="text-base-content/80">
+          {value.dateValue}
+        </time>
+      );
+    case 'AcfStringListValue':
+      return list(value.stringListValue);
+    case 'AcfJsonValue':
+      // Shown verbatim in a code block: JSON on a page is structured data the
+      // merchant's own components consume, and pretty-printing it here would be
+      // this file inventing a shape for someone else's payload.
+      return absent(value.jsonValue) ? null : (
+        <pre className="overflow-x-auto rounded-box bg-base-200 p-4 text-xs">{value.jsonValue}</pre>
+      );
+    case 'AcfRichTextValue':
+      // The server-rendered projection, never the raw delta: `html` is produced
+      // by the API's own sanitizing renderer, which is the one place that
+      // decision belongs.
+      //
+      // The guard is also what satisfies the seam: `dangerouslySetInnerHTML`
+      // takes `string | TrustedHTML`, so the projection is rendered only once
+      // it IS a string — never coerced past an absence with a `?? ''`, which
+      // would publish an empty rich-text section as if the merchant had
+      // written one.
+      return absent(value.html) ? null : (
+        <div
+          className="max-w-none text-base leading-relaxed text-base-content/80"
+          dangerouslySetInnerHTML={{ __html: value.html }}
+        />
+      );
+    case 'AcfAssetValue':
+      return value.asset ? <AssetImage asset={value.asset} /> : null;
+    case 'AcfAssetListValue':
+      return value.assets.length === 0 ? null : (
+        <div className="grid grid-cols-2 gap-4 sm:grid-cols-3">
+          {value.assets.map((asset) => (
+            <AssetImage key={asset.id} asset={asset} />
+          ))}
+        </div>
+      );
+    case 'AcfRelationValue':
+      // The API resolves the related row's display summary; the id alone would
+      // be meaningless on a storefront, and a dangling reference resolves to
+      // no summary at all, which renders as nothing rather than as a raw uuid.
+      return value.entity ? text(value.entity.label) : null;
+    case 'AcfRelationListValue':
+      return list(value.entities.map((entity) => entity.label));
+    default:
+      return exhausted(value);
+  }
+}
+
+/** One asset as an image — decorative unless the merchant described it. */
+function AssetImage({ asset }: { asset: { preview: string; altText?: string | null } }): ReactNode {
+  return (
+    // eslint-disable-next-line @next/next/no-img-element
+    <img
+      src={asset.preview}
+      alt={getAssetAlt(asset)}
+      className="w-full rounded-box border border-base-300 object-cover"
+    />
+  );
+}
+
+function text(content: string | null | undefined): ReactNode {
+  if (absent(content) || content.trim() === '') return null;
+  return <p className="text-base leading-relaxed text-base-content/80">{content}</p>;
+}
+
+function list(items: readonly string[] | null | undefined): ReactNode {
+  if (absent(items) || items.length === 0) return null;
+  return (
+    <ul className="list-inside list-disc space-y-1 text-base-content/80">
+      {items.map((item, index) => (
+        <li key={`${item}-${String(index)}`}>{item}</li>
+      ))}
+    </ul>
+  );
+}
+
+/**
+ * Is there nothing here?
+ *
+ * The generated SDK marks every nullable selection OPTIONAL as well as
+ * nullable (`stringValue?: Maybe<string>`), so "the merchant left this empty"
+ * reaches this file as `null` from the API answering today and as `undefined`
+ * from any pod whose SDK does not carry the selection at all. Both mean the
+ * same thing to a reader, and collapsing them in ONE predicate is what keeps a
+ * `String(undefined)`, an empty `<time>` or a bare `No` off a live page — each
+ * of which a `=== null` check alone would have rendered.
+ */
+function absent<T>(value: T | null | undefined): value is null | undefined {
+  return value === null || value === undefined;
+}
+
+/**
+ * The compile-time exhaustiveness check for the switch above: the parameter is
+ * `never`, so a new ACF field type stops this file from building until it is
+ * handled.
+ *
+ * At RUNTIME it renders nothing rather than throwing, and the asymmetry is
+ * deliberate. The only way to reach it is a pod whose generated SDK is older
+ * than the API answering it, and in that state the honest behaviour is to show
+ * the fields this build understands — a throw would blank the merchant's whole
+ * live page over one unknown section.
+ */
+function exhausted(_value: never): null {
+  return null;
+}