@forgecart/cli 2.202610052310.0 → 2.202610071755.0

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

@@ -0,0 +1,464 @@
+import 'server-only';
+
+import { ForgeCartShopClient, extractError } from '@forgecart/sdk/shop';
+import type {
+  ShopProductFieldFragment as Product,
+  ShopSellingPlanGroupFieldFragment as SellingPlanGroup,
+} from '@forgecart/sdk/shop';
+
+import type { AccountCallOutcome } from './account/account-link';
+import { UNREACHABLE_ERROR } from './action-result';
+import { getRequestLocale } from './locale/request-binding';
+
+/**
+ * Server-side ForgeCart shop client.
+ *
+ * The storefront talks to the ForgeCart shop GraphQL API on behalf of a single
+ * 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`).
+ *
+ * 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`,
+ * written by `forgecart init`):
+ *   - FORGECART_SHOP_API_URL  -> endpoint
+ *   - FORGECART_CHANNEL_TOKEN -> channelToken
+ *
+ * This module is server-only — the `import 'server-only'` above makes a client
+ * component's value-import of it a BUILD error, so the channel token and the
+ * SDK's websocket transport can never reach the browser. The same guard sits
+ * on every SDK-bearing server module (`cart-actions.ts` today; any future
+ * action module talking to the shop API adopts it the same way). Client
+ * components may still `import type` from here — type imports erase. Pure
+ * display helpers live in `./format`, which client components import freely.
+ * The construction mirrors the dashboard's `SdkClientService` (see
+ * app/dashboard/src/service/sdk-client.service.ts), adapted to read from env.
+ */
+
+const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
+const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
+
+/**
+ * One client per language (#1346, W1-8 / S1).
+ *
+ * The SDK's language is a per-CONNECTION header fixed at socket handshake, so
+ * a single instance structurally cannot serve two locales — and mutating a
+ * shared one with `setLanguageCode()` is worse than useless here: it DISPOSES
+ * the websocket, tearing down whatever concurrent request was mid-flight on
+ * it. Hence one client, one language, memoized for the process.
+ *
+ * The map is bounded by the channel's language count, not by traffic: it is
+ * keyed on the locale the layout RESOLVED, and the layout only resolves a
+ * language the channel offers — `/zz/`, `/qq/` … 404 before they ever reach a
+ * data read. Entries are never evicted: eviction would dispose a live socket
+ * and force a re-handshake, converting bounded memory into unbounded backend
+ * churn. Each idle socket is reaped by the SDK's own `lazyCloseTimeout`.
+ */
+const clientsByLocale = new Map<string, ForgeCartShopClient>();
+
+function assertShopConfigured(): void {
+  if (!SHOP_API_URL) {
+    throw new Error(
+      'FORGECART_SHOP_API_URL is not set. Add it to .env (forgecart init writes it for you).',
+    );
+  }
+  if (!CHANNEL_TOKEN) {
+    throw new Error(
+      'FORGECART_CHANNEL_TOKEN is not set. Add it to .env (forgecart init writes it for you).',
+    );
+  }
+}
+
+/**
+ * The client for an explicit language.
+ *
+ * `locale` must be one the channel offers — the caller has already resolved it
+ * through `getRequestLocale()`, whose decision function 404s anything else. It
+ * is not re-validated here, and it deliberately does NOT fall back to the
+ * default on a surprise: silently answering in another language than the
+ * document just declared in `<html lang>` is precisely the bug this slice
+ * exists to close, and it would look correct in every review.
+ */
+export function getShopClientForLocale(locale: string): ForgeCartShopClient {
+  assertShopConfigured();
+  const existing = clientsByLocale.get(locale);
+  if (existing) return existing;
+
+  const created = new ForgeCartShopClient({
+    endpoint: SHOP_API_URL,
+    channelToken: CHANNEL_TOKEN,
+    languageCode: locale,
+  });
+  clientsByLocale.set(locale, created);
+  return created;
+}
+
+/**
+ * The client for THIS request's language.
+ *
+ * Every read below goes through it, so a German page's product names, facets
+ * and selling plans come back in German — the half of the locale contract that
+ * `<html lang>` alone would only claim.
+ */
+export async function getShopClient(): Promise<ForgeCartShopClient> {
+  const { binding } = await getRequestLocale();
+  return getShopClientForLocale(binding.locale);
+}
+
+// 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';
+
+// Checkout-flow result types, aliased off the generated operation results so
+// the components and Server Actions speak the SDK's own shapes (indexed
+// access keeps them exactly as selected — no parallel hand-written types).
+import type {
+  AvailableCountriesQuery,
+  ConfirmPaymentSessionMutation,
+  CreatePaymentSessionMutation,
+  GetSessionTemplateQuery,
+  GetSessionVariablesQuery,
+  RefreshShippingRateGroupsMutation,
+  SeoEntriesQuery,
+  ShopEligiblePaymentProvidersQuery,
+  ShopOrderByCodeQuery,
+  ShopPageByRouteQuery,
+  ShopPageEntriesQuery,
+  ShopProductQuery,
+} from '@forgecart/sdk/shop';
+
+/**
+ * A single product AS SELECTED by the detail query — the display fields plus
+ * the per-language SEO sidecar (#1341) and `resolvedLanguageCode` (#1339).
+ *
+ * Distinct from `Product` (the list-row fragment) on purpose: only this shape
+ * carries what the slug law needs, and taking it by indexed access means the
+ * template cannot drift from what the operation actually asks for.
+ */
+export type ProductWithSeo = NonNullable<ShopProductQuery['product']>;
+
+/** One page of the XML sitemap's catalog feed (#1339). */
+export type SeoEntryFeedPage = SeoEntriesQuery['seoEntries'];
+
+/**
+ * An ACF page definition as `pageByRoute` selects it (#1934) — the merchant's
+ * own field definitions, in the order the editor arranged them.
+ *
+ * Taken by indexed access off the generated query rather than re-declared, like
+ * every other shape here: what the route renders and what the operation asks
+ * for cannot drift apart.
+ */
+export type PageGroup = NonNullable<ShopPageByRouteQuery['pageByRoute']>;
+/** One field definition of a page — the label and the identity of a value. */
+export type PageFieldDefinition = PageGroup['fieldDefinitions'][number];
+/**
+ * One record of a page, with its values, its repeater rows and its per-language
+ * SEO sidecar (#1375) — the page's title, description, indexability and
+ * alternates are read off `seo` by `lib/content/page-metadata.ts`.
+ */
+export type PageEntry = ShopPageEntriesQuery['entries']['items'][number];
+/** One stored value, discriminated by `__typename` over the ACF field types. */
+export type PageFieldValue = PageEntry['fields'][number];
+
+export type Country = AvailableCountriesQuery['availableCountries'][number];
+export type ShippingRateGroup =
+  RefreshShippingRateGroupsMutation['refreshShippingRateGroups'][number];
+export type ShippingRate = ShippingRateGroup['rates'][number];
+export type EligiblePaymentProvider =
+  ShopEligiblePaymentProvidersQuery['eligiblePaymentProviders'][number];
+export type PaymentSession = CreatePaymentSessionMutation['createPaymentSession'];
+export type PaymentTemplate = GetSessionTemplateQuery['getSessionTemplate'];
+export type PaymentVariables = GetSessionVariablesQuery['getSessionVariables'];
+export type ConfirmedPaymentSession = ConfirmPaymentSessionMutation['confirmPaymentSession'];
+export type CheckoutOrder = NonNullable<ShopOrderByCodeQuery['orderByCode']>;
+
+/**
+ * The order fields the checkout flow renders and gates on — the structural
+ * common denominator of every checkout mutation's Order selection (each
+ * operation selects a slightly different super-set of these, so no single
+ * generated type fits them all; this view is the one deliberate non-SDK
+ * shape, and every SDK result assigns to it).
+ */
+export interface CheckoutOrderView {
+  id: string;
+  code: string;
+  state: string;
+  currencyCode: string;
+  totalWithTax: number;
+  totalQuantity: number;
+}
+
+/**
+ * Fetch a page of products for the channel.
+ *
+ * `take` / `skip` map onto the shop API's `ListQueryOptions`.
+ */
+export async function getProducts(
+  options: { take?: number; skip?: number } = {},
+): Promise<{ items: Product[]; totalItems: number }> {
+  const { take = 24, skip = 0 } = options;
+  const { products } = await (
+    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.
+ *
+ * Typed as {@link ProductWithSeo}, not `Product`: the single-product query
+ * selects the per-language SEO sidecar (#1341) alongside the display fields,
+ * and the slug law in `lib/seo/resolve-path.ts` reads it to decide whether this
+ * URL is the locale's own address, a derived copy, or a redirect. The list
+ * queries deliberately do NOT select it — resolving the sidecar per row would
+ * pay for it once per card.
+ *
+ * The lookup resolves across languages (#1339): a slug that belongs to another
+ * language, or to this product's PREVIOUS slug, still finds it, and the
+ * returned `slug` is this locale's current one.
+ */
+export async function getProductBySlug(slug: string): Promise<ProductWithSeo | null> {
+  const { product } = await (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 { product } = await (await getShopClient()).product.shopProduct({ id });
+  return product ?? null;
+}
+
+/**
+ * Convenience: fetch a small set of products to feature on the home page.
+ */
+export async function getFeaturedProducts(count = 4): Promise<Product[]> {
+  const { items } = await getProducts({ take: count });
+  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 (
+    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 (
+    await getShopClient()
+  ).sellingPlan.channelSellingPlanGroups();
+  return channelSellingPlanGroups;
+}
+
+/**
+ * One page of the catalog entries the XML sitemap enumerates (#1339).
+ *
+ * The connection language is passed in rather than taken from the request,
+ * because this feed has no request locale to inherit: it returns EVERY
+ * language's path for every entry (languages without a translation row are
+ * omitted, never synthesized), so the answer is the same whichever language
+ * asks. `/sitemap.xml` is an unprefixed route by grammar — there is no locale
+ * in its URL to resolve — and the caller names the channel default so that the
+ * choice is visible instead of inherited from a header that is not there.
+ */
+export async function getProductSeoEntries(
+  languageCode: string,
+  options: { take: number; skip: number },
+): Promise<SeoEntryFeedPage> {
+  const { seoEntries } = await getShopClientForLocale(languageCode).seo.seoEntries({
+    input: { kind: 'PRODUCT', take: options.take, skip: options.skip },
+  });
+  return seoEntries;
+}
+
+/**
+ * The page definition mounted at a storefront route (#1934). `null` is "no page
+ * here" — an unknown route, a data definition's code, anything outside the
+ * route grammar — and the caller turns that into a real 404.
+ *
+ * METADATA only. Whether the page has content to show is the entries read
+ * below; keeping the two apart is what lets `resolvePage` state the whole 404
+ * decision in one place instead of splitting it across a query and a render.
+ */
+export async function getPageByRoute(route: string): Promise<PageGroup | null> {
+  const { pageByRoute } = await (await getShopClient()).acf.shopPageByRoute({ route });
+  return pageByRoute ?? null;
+}
+
+/**
+ * The record a page URL serves, as a list of at most one (#1934), with its SEO
+ * sidecar (#1375).
+ *
+ * `take: 1` because a route is ONE address; `createdAt ASC` because that makes
+ * it the page's ORIGINAL record. The shop API's own default is `createdAt
+ * DESC`, and inheriting it would mean that adding a second record to a live
+ * page silently REPLACES what the URL has been serving — a content change
+ * nobody asked for, made by a create. Ascending is a stable answer: the page a
+ * merchant published stays the page at that URL. The bound also prices the
+ * sidecar: `seo` costs one per-language resolve per returned record, which is
+ * why it rides this one-record read (`ShopPageEntries`) and never a listing.
+ *
+ * The list may come back EMPTY, and that is the feature's whole 404 arm: every
+ * storefront read is fenced to published content, so a page whose only records
+ * are DRAFT or SCHEDULED-not-yet-live looks exactly like a page with no records
+ * at all. `resolvePage` decides; this function only asks.
+ */
+export async function getPageEntries(definitionCode: string): Promise<PageEntry[]> {
+  const { entries } = await (
+    await getShopClient()
+  ).acf.shopPageEntries({
+    definitionCode,
+    options: { take: 1, sort: [{ field: 'createdAt', direction: 'ASC' }] },
+  });
+  return entries.items;
+}
+
+/**
+ * Every ACF page route the shop currently SERVES (#1934) — the sitemap's page
+ * feed.
+ *
+ * A stricter question than `getPageByRoute`'s, deliberately: this list must
+ * contain no URL that would answer 404, because a sitemap entry that does costs
+ * crawl budget and lands in Search Console as an error. The API applies that
+ * gate; unpublishing a page takes it out of this list, and out of the document
+ * on the next window.
+ *
+ * The connection language is named by the caller for the same reason
+ * `getProductSeoEntries` names it: `/sitemap.xml` is an unprefixed route with
+ * no request locale to inherit, and a route exists in every language alike.
+ */
+export async function getServedPageRoutes(languageCode: string): Promise<string[]> {
+  const { pageRoutes } = await getShopClientForLocale(languageCode).acf.shopPageRoutes();
+  return pageRoutes;
+}
+
+/**
+ * Countries the channel ships to — a PUBLIC channel read (no session), so it
+ * belongs on this server singleton: the checkout page prefetches it and hands
+ * the list to the client flow.
+ */
+export async function getAvailableCountries(): Promise<Country[]> {
+  const { availableCountries } = await (await getShopClient()).country.availableCountries();
+  return availableCountries;
+}
+
+/**
+ * ── The four CUSTOMER-ACCOUNT operations (#1472, #1471) ─────────────────────
+ *
+ * The platform mails a shopper a verification link and a password-reset link
+ * pointing at THIS storefront's origin (`/verify` and `/reset-password`), and
+ * three of these are the calls those two pages make. The fourth asks for the
+ * verification mail to be sent AGAIN — the prompt `/register` leaves a shopper
+ * on, for the one whose first mail never arrived (#1471). They are the only
+ * WRITES in this module, and the only functions in it that do not throw.
+ *
+ * Not throwing is the point. Every read above serves a page whose failure IS a
+ * failure — an unreachable catalog is a 500, and the route error boundary is
+ * the right answer. For these four, refusal is the ORDINARY case: a
+ * one-shot token is used exactly once, so the second click on the same link is
+ * an expected outcome to RENDER, not an incident to report. A thrown error
+ * would put the shopper on an error page for doing something entirely normal.
+ *
+ * They answer with {@link AccountCallOutcome} rather than the `ActionResult`
+ * envelope the checkout operations use, because there is nothing to carry: the
+ * API's answer to a one-shot credential is whether it was accepted and, if
+ * not, which `ErrorCode` it refused with. That is a pure, serializable value —
+ * it crosses the Server Action boundary unchanged — and `lib/account/*`
+ * interprets it in ONE place for both pages. The unreachable/unparseable arm
+ * borrows `UNREACHABLE_ERROR`'s code so the whole template spells that
+ * condition one way.
+ */
+
+/** Verify a customer's e-mail address with the token from their mail. */
+export async function verifyCustomerAccount(token: string): Promise<AccountCallOutcome> {
+  return runAccountOperation(async (client) => {
+    await client.customer.verifyCustomerAccount({ token });
+  });
+}
+
+/** Set a new password from the token in a password-reset mail. */
+export async function resetPassword(input: {
+  token: string;
+  password: string;
+}): Promise<AccountCallOutcome> {
+  return runAccountOperation(async (client) => {
+    await client.customer.resetPassword({ input });
+  });
+}
+
+/**
+ * Ask the platform to mail a password-reset link.
+ *
+ * The API's boolean answer (whether an account matched) is deliberately
+ * DISCARDED here rather than returned: surfacing it would let a visitor learn
+ * whether an address shops here, and a value this module returns is a value a
+ * page can render by accident. The neutral answer is decided once, in
+ * `lib/account/reset-password-state.ts`.
+ */
+export async function requestPasswordReset(emailAddress: string): Promise<AccountCallOutcome> {
+  return runAccountOperation(async (client) => {
+    await client.customer.requestPasswordReset({ emailAddress });
+  });
+}
+
+/**
+ * Ask the platform to send the verification mail again (#1471).
+ *
+ * The API's boolean is deliberately DISCARDED, exactly as the password-reset
+ * request's is: a value this module returns is a value a page can render by
+ * accident, and rendering whether an address is registered here is an
+ * enumeration oracle. The neutral answer is decided once, in
+ * `lib/account/register-state.ts`.
+ *
+ * Unauthenticated by necessity rather than by convenience. A shopper who never
+ * confirmed their address cannot log in at all, so a resend sitting behind a
+ * login would be unreachable by precisely the people who need it.
+ */
+export async function requestCustomerVerification(
+  emailAddress: string,
+): Promise<AccountCallOutcome> {
+  return runAccountOperation(async (client) => {
+    await client.customer.requestCustomerVerification({ emailAddress });
+  });
+}
+
+/**
+ * Run one account operation and report its outcome.
+ *
+ * The `try` covers `getShopClient()` as well as the call, and that is
+ * deliberate: an unconfigured scaffold throws there (`assertShopConfigured`),
+ * and the prewarm contract says a storefront with no `.env` must SERVE rather
+ * than crash — so that failure has to arrive as a rendered state like any
+ * other, not as an unhandled throw inside a render.
+ *
+ * This is the template's one sanctioned use of `catch`: wrapping an external
+ * SDK's errors at the call site, exactly as `shop-session.ts#runSessionOp` and
+ * `server/runner.ts` already do. Nothing is swallowed — every failure leaves
+ * here as a code the page renders.
+ */
+async function runAccountOperation(
+  operation: (client: ForgeCartShopClient) => Promise<void>,
+): Promise<AccountCallOutcome> {
+  try {
+    await operation(await getShopClient());
+    return { kind: 'ok' };
+  } catch (error) {
+    return { kind: 'error', code: extractError(error)?.code ?? UNREACHABLE_ERROR.code };
+  }
+}

package/templates/storefront-shadcn/src/lib/format.ts

@@ -0,0 +1,89 @@
+import type {
+  ShopProductFieldFragment as Product,
+  ShopSellingPlanFieldFragment as SellingPlan,
+} from '@forgecart/sdk/shop';
+
+import { toMajorUnits } from './money';
+
+/**
+ * Pure display helpers over SDK types — safe to import from ANY component.
+ *
+ * This module carries no runtime SDK dependency: the `@forgecart/sdk/shop`
+ * import above is type-only, so it erases at compile time and none of the
+ * client (`ForgeCartShopClient`, graphql-ws) ever reaches a browser bundle.
+ * Client components import their formatting from here; the SDK-bearing
+ * modules (`forgecart.ts`, `cart-actions.ts`) are `server-only` and reject a
+ * client value-import at build time.
+ */
+
+/**
+ * Format a minor-unit price as a currency string. Defaults to USD; pass a
+ * different ISO currency code as needed.
+ *
+ * The minor-unit divisor comes from {@link toMajorUnits}, which derives the
+ * currency's ISO-4217 exponent from CLDR — never a hardcoded hundred, which is
+ * wrong for zero-decimal yen and three-decimal fils. That derivation moved to
+ * `lib/money.ts` when the JSON-LD layer acquired the second consumer: the
+ * shopper-facing string and the machine-readable `Offer.price` disagreeing
+ * about what 2500 means would publish one price to people and another to
+ * search engines.
+ */
+export function formatPrice(minorUnits: number, currency = 'USD'): string {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(
+    toMajorUnits(minorUnits, currency),
+  );
+}
+
+/** 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) {
+    return null;
+  }
+  return product.variants.reduce(
+    (min, v) => (v.priceWithTax < min ? v.priceWithTax : min),
+    product.variants[0].priceWithTax,
+  );
+}
+
+/**
+ * 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()}`;
+}