@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/assets/templates/app/lib/__STOREFRONT__/commerce.ts

@@ -0,0 +1,608 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/commerce.ts)
+//
+// Host commerce boundary — the single seam between the generated storefront and
+// `@thorprovider/runtime/commerce`. Every backend call the host makes goes
+// through here so the contract is owned once, the layer boundary is explicit,
+// and a future change to the runtime provider is absorbed in one file.
+//
+// Boundary rules (change B):
+// - Server-only, JSX-free, Next-free. No `'use client'`, no React import.
+// - Context-scoped: every cart/checkout call takes the validated single-store
+//   context, and the runtime verifies the backend cart belongs to it.
+// - The backend is authoritative: totals are mapped from the backend cart and
+//   never computed locally; a missing amount is omitted, never invented.
+// - Optional images are normalized (an absent image is omitted, never `""`).
+// - Add uses the selected backend VARIANT id; update/remove use the backend
+//   cart LINE-ITEM id. The Navbar's DELTA is normalized to an absolute quantity
+//   against the authoritative line via `toAbsoluteLineUpdate`.
+// - Completion is discriminated and never blind-retried; reconciliation reads
+//   the committed cart (`completedAt`) and completes once only when committed.
+
+import type {
+  Cart,
+  Customer,
+  LoginCredentials,
+  Money,
+  Order,
+  PaymentMethod,
+  RegisterData,
+  ShippingMethod,
+  StoreContext,
+} from '@thorprovider/types'
+import {
+  addCartLines,
+  applyManualTestPayment,
+  APPROVED_MANUAL_TEST_PROVIDER_ID,
+  completeCart,
+  createCartForContext,
+  getCartForContext,
+  getCheckoutCountries,
+  getCurrentCustomer,
+  getCustomerOrders,
+  getEligibleShippingMethods,
+  getPaymentMethodsByRegion,
+  getProductDetailByHandle,
+  loginCustomer,
+  logoutCustomer,
+  reconcileCart,
+  registerCustomer,
+  removeCartLines,
+  selectShippingMethod,
+  toAbsoluteLineUpdate,
+  updateCartLines,
+  updateShippingAddress,
+  validateCheckoutAddressForRegion,
+  type AuthOutcome,
+  type CartCompletionResult,
+  type CatalogProductDetail,
+  type CheckoutAddress,
+  type CheckoutFieldError,
+  type RegionCountry,
+} from '@thorprovider/runtime/commerce'
+import type {
+  AccountOrderItemView,
+  AccountOrderView,
+  CartLineState,
+  CartTotalsState,
+  CheckoutFieldErrors,
+  CheckoutShippingOption,
+  StorefrontOrder,
+  StorefrontOrderLineView,
+} from './state.core'
+import { assertBackendConfigured, getDataSource, getStoreContext, type StoreDataSource } from './store-context'
+
+// ---------------------------------------------------------------------------
+// Projections (serializable; the UI state holds these)
+// ---------------------------------------------------------------------------
+
+/** The cart slice of the storefront state. */
+export interface CartStatePatch {
+  cart: CartLineState[]
+  cartTotals: CartTotalsState | null
+  cartId: string | null
+  cartQuantity: number
+  cartCompleted: boolean
+  /** The shipping OPTION id the checkout UI selects (`so_`), not the applied
+   *  shipping-method record id (`sm_`) used as payment proof. */
+  cartSelectedShippingOptionId: string | null
+}
+
+/** The empty cart slice, used when there is no active cart. */
+export const EMPTY_CART_STATE: CartStatePatch = {
+  cart: [],
+  cartTotals: null,
+  cartId: null,
+  cartQuantity: 0,
+  cartCompleted: false,
+  cartSelectedShippingOptionId: null,
+}
+
+/** Result of a completion attempt. `unresolved` must never be blindly retried. */
+export type PlaceOrderResult =
+  | { status: 'order'; order: StorefrontOrder; lines: StorefrontOrderLineView[] }
+  | { status: 'error'; message: string; code?: string }
+  | { status: 'cart-error'; message: string; code?: string }
+  | { status: 'unresolved'; message: string; code?: string }
+
+// ---------------------------------------------------------------------------
+// Mapping helpers (pure; no I/O)
+// ---------------------------------------------------------------------------
+
+/** Normalize an optional image URL: absent/blank is omitted, never `""`. */
+export function normalizeImageUrl(url: string | null | undefined): string | undefined {
+  if (typeof url !== 'string') return undefined
+  const trimmed = url.trim()
+  return trimmed === '' ? undefined : trimmed
+}
+
+function lineVariantLabel(line: Cart['lines'][number]): string | undefined {
+  const options = line.merchandise.selectedOptions
+    .map((option) => option.value)
+    .filter((value) => value.trim() !== '')
+  if (options.length > 0) return options.join(' / ')
+  return line.merchandise.title.trim() === '' ? undefined : line.merchandise.title
+}
+
+/**
+ * A stable, unique line id. The backend line id is authoritative; when a
+ * provider omits it, a deterministic composite keeps list keys unique without
+ * pretending the synthetic id is a valid mutation identity.
+ */
+export function stableLineId(line: Cart['lines'][number], index: number): string {
+  if (typeof line.id === 'string' && line.id.trim() !== '') return line.id
+  return `${line.merchandise.id}::${index}`
+}
+
+export function toCartLine(line: Cart['lines'][number], index: number): CartLineState {
+  return {
+    id: stableLineId(line, index),
+    merchandiseId: line.merchandise.id,
+    name: line.merchandise.product.title || line.merchandise.title,
+    variant: lineVariantLabel(line),
+    quantity: line.quantity,
+    lineTotal: line.cost.totalAmount,
+    // The backend unit price is carried through when supplied (including a
+    // legitimate zero). It is never derived from `total / quantity`; when the
+    // backend omits it, the field is omitted so the UI shows an unavailable
+    // unit price rather than an invented one.
+    unitPrice: line.cost.unitPrice,
+    image: normalizeImageUrl(line.merchandise.product.featuredImage?.url),
+    handle: line.merchandise.product.handle || undefined,
+  }
+}
+
+/**
+ * Map the canonical cart to the host state slice. Totals come from the backend
+ * cart; only the fields the backend supplies are set, the rest are omitted.
+ */
+export function toCartState(cart: Cart): CartStatePatch {
+  // The backend may expose a zero shipping amount as a placeholder before a
+  // method is selected. Showing it would render a false "free shipping"; omit
+  // shipping from the breakdown until the cart actually has a selected method.
+  const hasSelectedShipping = Boolean(
+    cart.selectedShippingMethodId || cart.selectedShippingOptionId,
+  )
+  return {
+    cart: cart.lines.map(toCartLine),
+    cartTotals: {
+      subtotal: cart.cost.subtotalAmount,
+      total: cart.cost.totalAmount,
+      tax: cart.cost.totalTaxAmount,
+      discount: cart.cost.discountAmount,
+      shipping: hasSelectedShipping ? cart.cost.shippingAmount : undefined,
+    },
+    cartId: cart.id ?? null,
+    cartQuantity: cart.totalQuantity,
+    cartCompleted: Boolean(cart.completedAt),
+    // The UI selects/highlights by the shipping OPTION id (`so_`). The applied
+    // shipping-method record id (`selectedShippingMethodId`, `sm_`) is the
+    // runtime's payment proof and is never exposed to the selection UI.
+    cartSelectedShippingOptionId: cart.selectedShippingOptionId ?? null,
+  }
+}
+
+export function toStorefrontOrder(order: Order): StorefrontOrder {
+  return {
+    number: order.orderNumber,
+    placedAt: order.createdAt,
+    email: order.email,
+    shipping: order.shippingAddress
+      ? {
+          name: `${order.shippingAddress.firstName} ${order.shippingAddress.lastName}`.trim(),
+          lines: [order.shippingAddress.address1, order.shippingAddress.city, order.shippingAddress.countryCode]
+            .filter((value): value is string => typeof value === 'string' && value.trim() !== ''),
+        }
+      : undefined,
+    totals: {
+      subtotal: order.subtotal,
+      discount: order.discount,
+      tax: order.tax,
+      shipping: order.shipping,
+      total: order.total,
+    },
+  }
+}
+
+export function toOrderLines(order: Order): StorefrontOrderLineView[] {
+  return order.items.map((item) => ({
+    id: item.id,
+    name: item.title,
+    variant: item.variantTitle,
+    quantity: item.quantity,
+    lineTotal: item.total,
+    unitPrice: item.price,
+    image: normalizeImageUrl(item.image?.url),
+  }))
+}
+
+export function toCheckoutShippingOptions(methods: ShippingMethod[]): CheckoutShippingOption[] {
+  return methods.map((method) => ({
+    id: method.id,
+    name: method.name,
+    price: method.price,
+    description: method.description,
+    estimatedDays: method.estimatedDays,
+  }))
+}
+
+/** Group the runtime's structured field errors into the block's error shape. */
+export function toCheckoutFieldErrors(errors: CheckoutFieldError[]): CheckoutFieldErrors {
+  const grouped: CheckoutFieldErrors = {}
+  for (const error of errors) {
+    grouped[error.field] = [...(grouped[error.field] ?? []), { message: error.message }]
+  }
+  return grouped
+}
+
+/** Map the runtime's discriminated completion to the host result union. */
+export function toPlaceOrderResult(result: CartCompletionResult): PlaceOrderResult {
+  if (result.type === 'order') {
+    return { status: 'order', order: toStorefrontOrder(result.order), lines: toOrderLines(result.order) }
+  }
+  if (result.type === 'cart') {
+    return { status: 'cart-error', message: result.error.message, code: result.error.code }
+  }
+  return { status: 'unresolved', message: result.error.message, code: result.error.code }
+}
+
+// ---------------------------------------------------------------------------
+// Reads
+// ---------------------------------------------------------------------------
+
+export interface CatalogDetailResult {
+  detail: CatalogProductDetail | undefined
+  source: StoreDataSource
+}
+
+/** Directed product-detail lookup by handle, priced in the store context region. */
+export async function loadProductDetail(handle: string): Promise<CatalogDetailResult> {
+  const context = getStoreContext()
+  const source = getDataSource()
+  assertBackendConfigured(source)
+  const detail = await getProductDetailByHandle(handle, context)
+  return { detail, source }
+}
+
+/** The context-scoped backend cart projected for the UI, or undefined when absent. */
+export async function readCart(
+  cartId: string,
+  context: StoreContext = getStoreContext(),
+): Promise<CartStatePatch | undefined> {
+  assertBackendConfigured()
+  const cart = await getCartForContext(cartId, context)
+  return cart ? toCartState(cart) : undefined
+}
+
+export async function loadCheckoutCountries(
+  cartId: string,
+  context: StoreContext = getStoreContext(),
+): Promise<RegionCountry[]> {
+  assertBackendConfigured()
+  return getCheckoutCountries(cartId, context)
+}
+
+export async function loadShippingMethods(
+  cartId: string,
+  context: StoreContext = getStoreContext(),
+): Promise<ShippingMethod[]> {
+  assertBackendConfigured()
+  return getEligibleShippingMethods(cartId, context)
+}
+
+/**
+ * Label the approved manual TEST provider explicitly as a test provider rather
+ * than letting a legacy adapter name (for example "Cash on Delivery") imply a
+ * delivery/COD guarantee. Other methods pass through unchanged.
+ */
+export function toDisplayPaymentMethods(methods: PaymentMethod[]): PaymentMethod[] {
+  return methods.map((method) =>
+    method.id === APPROVED_MANUAL_TEST_PROVIDER_ID
+      ? {
+          ...method,
+          name: 'Pago manual TEST',
+          description: 'Proveedor manual de prueba; no cobra fondos reales.',
+        }
+      : method,
+  )
+}
+
+export async function loadPaymentMethods(
+  context: StoreContext = getStoreContext(),
+): Promise<PaymentMethod[]> {
+  assertBackendConfigured()
+  const methods = await getPaymentMethodsByRegion(context.regionId)
+  return toDisplayPaymentMethods(methods)
+}
+
+// ---------------------------------------------------------------------------
+// Cart mutations (context-scoped)
+// ---------------------------------------------------------------------------
+
+/** Create a fresh backend guest cart in the store context region. */
+export async function createGuestCart(
+  context: StoreContext = getStoreContext(),
+): Promise<CartStatePatch> {
+  assertBackendConfigured()
+  const cart = await createCartForContext(context)
+  return toCartState(cart)
+}
+
+/** Add the explicitly selected backend variant at its requested quantity. */
+export async function addVariant(
+  cartId: string,
+  variantId: string,
+  quantity: number,
+  context: StoreContext = getStoreContext(),
+): Promise<CartStatePatch> {
+  assertBackendConfigured()
+  const cart = await addCartLines(cartId, [{ merchandiseId: variantId, quantity }], context)
+  return toCartState(cart)
+}
+
+/** Set a line to an ABSOLUTE quantity by its backend line-item id. */
+export async function setLineQuantity(
+  cartId: string,
+  lineId: string,
+  merchandiseId: string,
+  quantity: number,
+  context: StoreContext = getStoreContext(),
+): Promise<CartStatePatch> {
+  assertBackendConfigured()
+  const cart = await updateCartLines(cartId, [{ id: lineId, merchandiseId, quantity }], context)
+  return toCartState(cart)
+}
+
+/** Apply a relative DELTA by normalizing it against the authoritative line. */
+export async function applyLineDelta(
+  cartId: string,
+  lineId: string,
+  delta: number,
+  context: StoreContext = getStoreContext(),
+): Promise<CartStatePatch> {
+  assertBackendConfigured()
+  const current = await getCartForContext(cartId, context)
+  if (!current) throw new Error(`Cart not found: ${cartId}`)
+  const update = toAbsoluteLineUpdate(current, lineId, delta)
+  const cart = await updateCartLines(cartId, [update], context)
+  return toCartState(cart)
+}
+
+/** Remove a line by its backend line-item id. */
+export async function removeLine(
+  cartId: string,
+  lineId: string,
+  context: StoreContext = getStoreContext(),
+): Promise<CartStatePatch> {
+  assertBackendConfigured()
+  const cart = await removeCartLines(cartId, [lineId], context)
+  return toCartState(cart)
+}
+
+// ---------------------------------------------------------------------------
+// Checkout mutations (context-scoped)
+// ---------------------------------------------------------------------------
+
+/** The validated checkout address shape (runtime contract). */
+export type AddressInput = CheckoutAddress
+
+/** Validate an untrusted address against the cart region's eligible countries. */
+export function validateAddress(
+  input: unknown,
+  countries: RegionCountry[],
+): { success: true; address: CheckoutAddress } | { success: false; errors: CheckoutFieldError[] } {
+  return validateCheckoutAddressForRegion(input, countries)
+}
+
+/** True when the provider simply does not persist an address. */
+function isUnsupportedAddressUpdate(error: unknown): boolean {
+  return error instanceof Error && /does not support updateShippingAddress/i.test(error.message)
+}
+
+/**
+ * Persist the cart's address when the provider supports it; the backend then
+ * recalculates totals on the next read. A provider that does not persist an
+ * address (for example the mock fixture) is tolerated: the address has already
+ * been validated and shipping eligibility is resolved from the cart region.
+ */
+export async function saveShippingAddress(
+  cartId: string,
+  address: AddressInput,
+  context: StoreContext = getStoreContext(),
+): Promise<CartStatePatch> {
+  assertBackendConfigured()
+  const current = await getCartForContext(cartId, context)
+  if (!current) throw new Error(`Cart not found before address update: ${cartId}`)
+  try {
+    // The runtime address validator treats province/phone as optional; the
+    // address-setter input still declares them, so pass an empty string when the
+    // shopper did not supply one rather than failing the type contract.
+    await updateShippingAddress(cartId, {
+      email: address.email,
+      firstName: address.firstName,
+      lastName: address.lastName,
+      address1: address.address1,
+      address2: address.address2,
+      company: address.company,
+      city: address.city,
+      province: address.province ?? '',
+      postalCode: address.postalCode,
+      countryCode: address.countryCode,
+      phone: address.phone ?? '',
+    })
+  } catch (error) {
+    if (isUnsupportedAddressUpdate(error)) return toCartState(current)
+    throw error
+  }
+  const cart = await getCartForContext(cartId, context)
+  return toCartState(cart ?? current)
+}
+
+/** Apply an eligible shipping method and return the recalculated cart. */
+export async function selectShipping(
+  cartId: string,
+  methodId: string,
+  context: StoreContext = getStoreContext(),
+): Promise<CartStatePatch> {
+  assertBackendConfigured()
+  const cart = await selectShippingMethod(cartId, methodId, context)
+  return toCartState(cart)
+}
+
+/** Apply the single approved manual TEST payment provider (requires shipping). */
+export async function applyPayment(
+  cartId: string,
+  context: StoreContext = getStoreContext(),
+): Promise<void> {
+  assertBackendConfigured()
+  await applyManualTestPayment(cartId, context)
+}
+
+/** Complete the cart exactly once, preserving the native discriminator. */
+export async function completeOrder(
+  cartId: string,
+  context: StoreContext = getStoreContext(),
+): Promise<PlaceOrderResult> {
+  assertBackendConfigured()
+  return toPlaceOrderResult(await completeCart(cartId, context))
+}
+
+/**
+ * Reconcile a committed cart into its order. The caller MUST have authorized
+ * this cart through the verified session cookie; this never accepts a bare
+ * order/cart id as authorization. Reads `completedAt` first and completes once
+ * only when the backend committed.
+ */
+export async function reconcileOrder(
+  cartId: string,
+  context: StoreContext = getStoreContext(),
+): Promise<PlaceOrderResult> {
+  assertBackendConfigured()
+  return toPlaceOrderResult(await reconcileCart(cartId, context))
+}
+
+// ---------------------------------------------------------------------------
+// Customer auth boundary (change: storefront-customer-auth, task 2.2)
+// ---------------------------------------------------------------------------
+//
+// The host never talks to the backend SDK directly. These helpers delegate to
+// `@thorprovider/runtime/commerce`, which builds a request-scoped provider
+// carrying exactly the caller's token. No token is logged or returned to the
+// client; the runtime outcome is passed through unchanged.
+
+/** Authenticate a shopper; the caller persists the returned token in its cookie. */
+export async function authenticate(credentials: LoginCredentials): Promise<AuthOutcome> {
+  return loginCustomer(credentials)
+}
+
+/** Register a shopper; the caller persists the returned token in its cookie. */
+export async function registerShopper(data: RegisterData): Promise<AuthOutcome> {
+  return registerCustomer(data)
+}
+
+/** Best-effort backend logout; the authoritative clear is the host cookie. */
+export async function endSession(): Promise<void> {
+  return logoutCustomer()
+}
+
+/** Resolve the current customer for a request token, or null when absent. */
+export async function loadCustomer(token: string | null): Promise<Customer | null> {
+  return getCurrentCustomer(token)
+}
+
+// ---------------------------------------------------------------------------
+// Customer orders boundary (change: storefront-customer-orders, task 2.1)
+// ---------------------------------------------------------------------------
+//
+// The host never talks to the backend SDK directly. `getCustomerOrders`
+// delegates to `@thorprovider/runtime/commerce`, which builds a request-scoped
+// provider carrying exactly the caller's token. The boundary maps the backend
+// orders to a serializable display shape: Money is formatted from the order's
+// own `currencyCode` (never hardcoded, never divided by 100) and a field the
+// backend omits is omitted, never invented.
+
+/**
+ * Format backend Money for display from its own currency, or undefined when the
+ * amount is absent/blank/non-finite. The decimal-string amount is already in
+ * major units, so it is never divided by 100.
+ */
+function formatMoney(money?: Money): string | undefined {
+  if (!money) return undefined
+  const amount = money.amount
+  if (typeof amount !== 'string' || amount.trim() === '') return undefined
+  const value = Number(amount)
+  if (!Number.isFinite(value)) return undefined
+  return new Intl.NumberFormat(undefined, {
+    style: 'currency',
+    currency: money.currencyCode,
+  }).format(value)
+}
+
+/** Format an ISO timestamp as a locale date, or return the raw value unchanged. */
+function formatOrderDate(value: string): string {
+  const parsed = new Date(value)
+  if (Number.isNaN(parsed.getTime())) return value
+  return parsed.toLocaleDateString()
+}
+
+/** Join the present address parts, filtering blanks; undefined when none apply. */
+function formatAddress(address: Order['shippingAddress']): string | undefined {
+  if (!address) return undefined
+  const name = `${address.firstName ?? ''} ${address.lastName ?? ''}`.trim()
+  const parts = [name, address.address1, address.city, address.countryCode].filter(
+    (value): value is string => typeof value === 'string' && value.trim() !== '',
+  )
+  if (parts.length === 0) return undefined
+  return parts.join(', ')
+}
+
+/** Map one backend order line to its display view, omitting absent optional fields. */
+export function toAccountOrderItemView(item: Order['items'][number]): AccountOrderItemView {
+  const view: AccountOrderItemView = {
+    id: item.id,
+    name: item.title,
+    quantity: item.quantity,
+    lineTotal: formatMoney(item.total) ?? '',
+  }
+  if (typeof item.variantTitle === 'string' && item.variantTitle.trim() !== '') {
+    view.variant = item.variantTitle
+  }
+  const image = normalizeImageUrl(item.image?.url)
+  if (image !== undefined) view.image = image
+  return view
+}
+
+/** Map a backend order to the account view row, omitting absent optional fields. */
+export function toAccountOrderView(order: Order): AccountOrderView {
+  const view: AccountOrderView = {
+    id: order.id,
+    number: order.orderNumber,
+    date: formatOrderDate(order.createdAt),
+    status: order.status,
+    total: formatMoney(order.total) ?? '',
+    items: order.items.map(toAccountOrderItemView),
+  }
+  const subtotal = formatMoney(order.subtotal)
+  if (subtotal !== undefined) view.subtotal = subtotal
+  const tax = formatMoney(order.tax)
+  if (tax !== undefined) view.tax = tax
+  const shipping = formatMoney(order.shipping)
+  if (shipping !== undefined) view.shipping = shipping
+  const address = formatAddress(order.shippingAddress)
+  if (address !== undefined) view.address = address
+  return view
+}
+
+/**
+ * Load the authenticated customer's order history for a request token, mapped
+ * to the account view rows. A missing token yields an empty list (the runtime
+ * builds no provider); it never fabricates an order.
+ */
+export async function loadOrders(
+  token: string | null,
+  context: StoreContext = getStoreContext(),
+): Promise<AccountOrderView[]> {
+  const orders = await getCustomerOrders(token, { salesChannelId: context.salesChannelId })
+  return orders.map(toAccountOrderView)
+}
+
+export type { Money }