@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

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

@@ -0,0 +1,612 @@
+'use server'
+
+// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/actions.ts)
+//
+// Host Server Actions — the only place the generated storefront mutates the
+// backend cart and the session cookie. Next.js 16 `cookies()` may only be
+// written from a Server Action or Route Handler, so the guest cart identity and
+// the completed-session cookie are created and updated here, never during a
+// render.
+//
+// Every action resolves and validates the store context before the commerce
+// call. Cart mutations use the backend variant id for adds and the backend
+// line-item id for updates/removals; the Navbar's DELTA is normalized against
+// the authoritative cart line quantity. Completion is discriminated and never
+// blindly retried; reconciliation uses the active cart id when no completed
+// receipt cookie exists yet.
+
+import type { AccountOrderView, CheckoutFieldErrors, CheckoutShippingOption } from './state.core'
+import type { Customer, PaymentMethod } from '@thorprovider/types'
+import {
+  EMPTY_CART_STATE,
+  addVariant,
+  applyLineDelta,
+  applyPayment,
+  authenticate,
+  completeOrder,
+  createGuestCart,
+  endSession,
+  loadCheckoutCountries,
+  loadCustomer,
+  loadOrders,
+  loadOrdersPage,
+  loadPaymentMethods,
+  loadProductDetailById,
+  loadShippingMethods,
+  readCart,
+  reconcileOrder,
+  registerShopper,
+  removeLine,
+  resolveProductCartTarget,
+  saveShippingAddress,
+  selectShipping,
+  setLineQuantity,
+  toCheckoutFieldErrors,
+  toCheckoutShippingOptions,
+  validateAddress,
+  type AddressInput,
+  type CartStatePatch,
+  type PlaceOrderResult,
+} from './commerce'
+import { getStoreContext } from './store-context'
+import {
+  bindHostSessionCart,
+  clearAuthToken,
+  completeHostSessionCart,
+  readAuthToken,
+  readHostSession,
+  writeAuthToken,
+} from './session'
+
+// A `'use server'` module may export ONLY async functions. Next/Turbopack's
+// server-actions transform registers every export as a runtime server
+// reference, so a type export (even `export type`) is emitted as a value and
+// crashes at runtime (`X is not defined`). The result types below are local;
+// the shared shapes are imported from `./commerce` and never re-exported here.
+
+/** Structured result for a cart-mutating action. */
+type CartActionResult =
+  | { ok: true; cart: CartStatePatch }
+  | { ok: false; error: string }
+
+/** Structured result for a checkout action. */
+type CheckoutActionResult =
+  | {
+      ok: true
+      cart: CartStatePatch
+      countries?: { value: string; label: string }[]
+      paymentMethods?: PaymentMethod[]
+      shippingOptions?: CheckoutShippingOption[]
+      fieldErrors?: CheckoutFieldErrors
+    }
+  | { ok: false; error: string; fieldErrors?: CheckoutFieldErrors }
+
+/** Structured result for an auth action that may carry the current customer. */
+type AuthActionResult =
+  | { ok: true; customer: Customer | null }
+  | { ok: false; error: string }
+
+/** Structured result for logout; the authoritative cookie clear is the outcome. */
+type LogoutActionResult = { ok: true } | { ok: false; error: string }
+
+/** Structured result for the customer order-history load. */
+type OrdersActionResult =
+  | { ok: true; orders: AccountOrderView[] }
+  | { ok: false; error: string }
+
+/** Structured result for a paginated customer order-history load. */
+type OrdersPageActionResult =
+  | { ok: true; orders: AccountOrderView[]; count: number; limit: number; offset: number }
+  | { ok: false; error: string }
+
+/** Basic email shape check; a boundary guard, not a full RFC validation. */
+const EMAIL_PATTERN = /\S+@\S+\.\S+/
+
+/** Log a non-secret context line for a caught server error (never a secret). */
+function logServerError(scope: string, error: unknown): void {
+  const message = error instanceof Error ? error.message : String(error)
+  const code =
+    error && typeof error === 'object' && 'code' in error && typeof (error as { code?: unknown }).code === 'string'
+      ? (error as { code: string }).code
+      : undefined
+  console.error(`[storefront/actions] ${scope} failed`, { message, code })
+}
+
+function toError(error: unknown, fallback: string): string {
+  return error instanceof Error && error.message.trim() !== '' ? error.message : fallback
+}
+
+/**
+ * Resolve the active cart id, creating and binding a new backend cart when the
+ * session has none or its cart was completed. A new cart after a completed one
+ * keeps the SAME shopper and preserves the prior receipt cart id, so the
+ * receipt proof cookie is never lost.
+ */
+async function ensureActiveCartId(): Promise<{ cartId: string; context: ReturnType<typeof getStoreContext> }> {
+  const context = getStoreContext()
+  const session = await readHostSession(context)
+  if (session?.cartId) {
+    const existing = await readCart(session.cartId, context)
+    if (existing && !existing.cartCompleted) return { cartId: session.cartId, context }
+  }
+  const created = await createGuestCart(context)
+  if (!created.cartId) throw new Error('Cart creation returned no id')
+  await bindHostSessionCart(context, created.cartId)
+  return { cartId: created.cartId, context }
+}
+
+/** Ensure a guest cart exists and return its authoritative snapshot. */
+export async function ensureCartAction(): Promise<CartActionResult> {
+  try {
+    const { cartId, context } = await ensureActiveCartId()
+    return { ok: true, cart: (await readCart(cartId, context)) ?? EMPTY_CART_STATE }
+  } catch (error) {
+    return { ok: false, error: toError(error, 'No se pudo iniciar el carrito.') }
+  }
+}
+
+/** Add the explicitly selected backend variant id at the requested quantity. */
+export async function addToCartAction(input: {
+  variantId: string
+  quantity: number
+}): Promise<CartActionResult> {
+  try {
+    if (!input?.variantId) return { ok: false, error: 'Selecciona una variante antes de agregar.' }
+    const quantity = Number.isFinite(input.quantity) && input.quantity > 0 ? Math.floor(input.quantity) : 1
+    const { cartId, context } = await ensureActiveCartId()
+    return { ok: true, cart: await addVariant(cartId, input.variantId, quantity, context) }
+  } catch (error) {
+    return { ok: false, error: toError(error, 'No se pudo agregar el producto.') }
+  }
+}
+
+/**
+ * Add a product's FIRST purchasable variant by backend product id — the
+ * product-card shortcut. The variant is resolved server-side from the backend
+ * detail (card data carries no variant ids); a product with no purchasable
+ * variant returns a truthful error and adds nothing. The product detail remains
+ * the explicit-selection surface (change storefront-card-add-to-cart).
+ */
+export async function addToCartByProductAction(input: {
+  productId: string
+  quantity?: number
+}): Promise<CartActionResult> {
+  try {
+    const productId = typeof input?.productId === 'string' ? input.productId : ''
+    if (productId === '') return { ok: false, error: 'Producto no válido.' }
+    const quantity =
+      Number.isFinite(input?.quantity) && (input.quantity as number) > 0
+        ? Math.floor(input.quantity as number)
+        : 1
+    const detail = await loadProductDetailById(productId)
+    const target = resolveProductCartTarget(detail)
+    if (!target.ok) return { ok: false, error: target.error }
+    const { cartId, context } = await ensureActiveCartId()
+    return { ok: true, cart: await addVariant(cartId, target.variantId, quantity, context) }
+  } catch (error) {
+    return { ok: false, error: toError(error, 'No se pudo agregar el producto.') }
+  }
+}
+
+/** Set a backend cart line to an ABSOLUTE quantity by its line-item id. */
+export async function setLineQuantityAction(input: {
+  lineId: string
+  merchandiseId: string
+  quantity: number
+}): Promise<CartActionResult> {
+  try {
+    const quantity = Math.max(1, Math.floor(input.quantity))
+    const { cartId, context } = await ensureActiveCartId()
+    return {
+      ok: true,
+      cart: await setLineQuantity(cartId, input.lineId, input.merchandiseId, quantity, context),
+    }
+  } catch (error) {
+    return { ok: false, error: toError(error, 'No se pudo actualizar la cantidad.') }
+  }
+}
+
+/**
+ * Apply a quantity DELTA from the Navbar mini-cart. The delta is normalized
+ * against the authoritative current line quantity (the cart page emits an
+ * absolute quantity and uses `setLineQuantityAction`).
+ */
+export async function applyQuantityDeltaAction(input: {
+  lineId: string
+  delta: number
+}): Promise<CartActionResult> {
+  try {
+    const { cartId, context } = await ensureActiveCartId()
+    return { ok: true, cart: await applyLineDelta(cartId, input.lineId, input.delta, context) }
+  } catch (error) {
+    return { ok: false, error: toError(error, 'No se pudo actualizar la cantidad.') }
+  }
+}
+
+/** Remove a backend cart line by its line-item id. */
+export async function removeLineAction(input: { lineId: string }): Promise<CartActionResult> {
+  try {
+    const { cartId, context } = await ensureActiveCartId()
+    return { ok: true, cart: await removeLine(cartId, input.lineId, context) }
+  } catch (error) {
+    return { ok: false, error: toError(error, 'No se pudo quitar el producto.') }
+  }
+}
+
+/** Read the current cart snapshot (no creation). */
+export async function loadCartStateAction(): Promise<CartStatePatch> {
+  try {
+    const context = getStoreContext()
+    const session = await readHostSession(context)
+    if (!session?.cartId) return EMPTY_CART_STATE
+    return (await readCart(session.cartId, context)) ?? EMPTY_CART_STATE
+  } catch {
+    return EMPTY_CART_STATE
+  }
+}
+
+function toAddressInput(values: Record<string, unknown>): AddressInput {
+  const str = (key: string) => (typeof values[key] === 'string' ? (values[key] as string) : '')
+  return {
+    email: str('email'),
+    firstName: str('firstName'),
+    lastName: str('lastName'),
+    address1: str('address'),
+    city: str('city'),
+    province: str('state'),
+    postalCode: str('zipCode'),
+    countryCode: str('country'),
+    phone: str('phone'),
+  }
+}
+
+/**
+ * Validate and persist the checkout address against the cart region's eligible
+ * countries, then load the eligible shipping options and recalculated totals.
+ * A malformed or ineligible address returns structured per-field errors and
+ * never advances.
+ */
+export async function syncCheckoutAddressAction(
+  values: Record<string, unknown>,
+): Promise<CheckoutActionResult> {
+  try {
+    const { cartId, context } = await ensureActiveCartId()
+    const countries = await loadCheckoutCountries(cartId, context)
+    const validation = validateAddress(toAddressInput(values), countries)
+    if (!validation.success) {
+      return {
+        ok: false,
+        error: 'Revisa los datos de la dirección.',
+        fieldErrors: toCheckoutFieldErrors(validation.errors),
+      }
+    }
+    const cart = await saveShippingAddress(cartId, validation.address, context)
+    const methods = await loadShippingMethods(cartId, context)
+    return { ok: true, cart, shippingOptions: toCheckoutShippingOptions(methods) }
+  } catch (error) {
+    return { ok: false, error: toError(error, 'No se pudo validar la dirección.') }
+  }
+}
+
+/** Apply an eligible shipping method; the backend recalculates the totals. */
+export async function selectShippingMethodAction(input: {
+  methodId: string
+}): Promise<CheckoutActionResult> {
+  try {
+    const { cartId, context } = await ensureActiveCartId()
+    const cart = await selectShipping(cartId, input.methodId, context)
+    return { ok: true, cart }
+  } catch (error) {
+    return { ok: false, error: toError(error, 'No se pudo seleccionar el envío.') }
+  }
+}
+
+/** Load the checkout data (countries, payment methods, cart) for the form. */
+export async function loadCheckoutAction(): Promise<CheckoutActionResult> {
+  try {
+    const { cartId, context } = await ensureActiveCartId()
+    const [regionCountries, paymentMethods, methods, cart] = await Promise.all([
+      loadCheckoutCountries(cartId, context),
+      loadPaymentMethods(context),
+      loadShippingMethods(cartId, context),
+      readCart(cartId, context),
+    ])
+    return {
+      ok: true,
+      cart: cart ?? EMPTY_CART_STATE,
+      countries: regionCountries.map((country) => ({ value: country.code, label: country.name })),
+      paymentMethods,
+      shippingOptions: toCheckoutShippingOptions(methods),
+    }
+  } catch (error) {
+    return { ok: false, error: toError(error, 'No se pudo cargar el checkout.') }
+  }
+}
+
+/**
+ * Clear the active cart after a confirmed order. A cookie-write failure must
+ * NOT be reported as an ordinary failure — the order already exists — so it is
+ * logged (non-secret) and reported to the caller, which returns `unresolved`
+ * and leaves the committed cart reconcilable.
+ */
+async function clearConfirmedSession(
+  context: ReturnType<typeof getStoreContext>,
+  cartId: string,
+): Promise<boolean> {
+  try {
+    await completeHostSessionCart(context, cartId)
+    return true
+  } catch (error) {
+    logServerError('completeHostSessionCart', error)
+    return false
+  }
+}
+
+/**
+ * Place the order exactly once. The approved manual TEST payment is applied
+ * after shipping totals are final, then the cart is completed with its native
+ * discriminator. On a confirmed order the active cart is cleared and the
+ * receipt recorded. If the order committed but the session cookie could not be
+ * updated, the result is `unresolved` (reconcile the active committed cart) so
+ * the client never treats a committed order as a retryable failure.
+ */
+export async function placeOrderAction(): Promise<PlaceOrderResult> {
+  try {
+    const context = getStoreContext()
+    const session = await readHostSession(context)
+    if (!session?.cartId) {
+      return { status: 'error', message: 'No hay un carrito activo.' }
+    }
+    const cartId = session.cartId
+    try {
+      await applyPayment(cartId, context)
+    } catch (error) {
+      logServerError('applyPayment', error)
+      return { status: 'error', message: toError(error, 'No se pudo iniciar el pago.') }
+    }
+    const result = await completeOrder(cartId, context)
+    if (result.status !== 'order') return result
+    if (!(await clearConfirmedSession(context, cartId))) {
+      return {
+        status: 'unresolved',
+        message: 'El pedido se registró pero no se pudo actualizar la sesión. Reconcílialo.',
+        code: 'SESSION_CLEAR_FAILED',
+      }
+    }
+    return result
+  } catch (error) {
+    // An unexpected failure during completion is ambiguous: never a blind retry.
+    logServerError('placeOrderAction', error)
+    return {
+      status: 'unresolved',
+      message: 'No se pudo confirmar el pedido. Reconcílialo antes de reintentar.',
+      code: 'COMPLETE_UNRESOLVED',
+    }
+  }
+}
+
+/**
+ * Recover the receipt for a cart the verified cookie authorizes. A client
+ * order/cart id is never accepted. An ACTIVE cart the backend already committed
+ * is an unresolved completion and is reconciled first; otherwise the completed
+ * receipt cart carried by the cookie is reconciled. Read/network failures stay
+ * `unresolved` (reconcile-only) and are never a blind retry.
+ */
+export async function reconcileReceiptAction(): Promise<PlaceOrderResult> {
+  try {
+    const context = getStoreContext()
+    const session = await readHostSession(context)
+    if (!session) {
+      return { status: 'unresolved', message: 'No hay un comprobante autorizado para esta sesión.' }
+    }
+
+    // An active cart is reconciled first: the runtime does a single GET and
+    // only POSTs complete when the backend committed. A cart the backend did
+    // NOT commit returns CART_NOT_COMPLETED, surfaced as a controlled
+    // (retryable) error instead of a generic unresolved that never resolves.
+    // The active cart is only cleared when it is the committed cart; a new cart
+    // started after an earlier order is preserved by the session core.
+    if (session.cartId) {
+      const result = await reconcileOrder(session.cartId, context)
+      if (result.status === 'order') {
+        await clearConfirmedSession(context, session.cartId)
+        return result
+      }
+      if (result.status === 'unresolved' && result.code === 'CART_NOT_COMPLETED') {
+        return { status: 'error', message: result.message, code: result.code }
+      }
+      return result
+    }
+
+    const candidate = session.receiptCartId
+    if (!candidate) {
+      return { status: 'unresolved', message: 'No hay un comprobante autorizado para esta sesión.' }
+    }
+    const result = await reconcileOrder(candidate, context)
+    if (result.status === 'order') {
+      await clearConfirmedSession(context, candidate)
+      return result
+    }
+    // A reconcile that proves the backend never committed is definitive, not
+    // ambiguous: surface it as a controlled failure so the shopper may retry
+    // explicitly (never a blind retry of an ambiguous mutation).
+    if (result.status === 'unresolved' && result.code === 'CART_NOT_COMPLETED') {
+      return { status: 'error', message: result.message, code: result.code }
+    }
+    return result
+  } catch (error) {
+    logServerError('reconcileReceiptAction', error)
+    return {
+      status: 'unresolved',
+      message: 'No se pudo verificar el pedido. Reintenta la reconciliación.',
+      code: 'RECONCILE_UNRESOLVED',
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Customer auth actions (change: storefront-customer-auth, task 2.2)
+// ---------------------------------------------------------------------------
+//
+// Auth actions touch ONLY the auth cookie: they never read or write the guest
+// session cookie or the cart (guest continuity by construction, design D5).
+// Input is validated before any backend call, and no token or password is ever
+// logged or returned.
+
+/**
+ * Authenticate a shopper. Validates input first, then authenticates; a token
+ * from the backend is persisted in the httpOnly auth cookie. `requiresAction`
+ * is surfaced truthfully rather than faking a logged-in state.
+ */
+export async function loginAction(input: {
+  email: string
+  password: string
+}): Promise<AuthActionResult> {
+  const email = typeof input?.email === 'string' ? input.email.trim() : ''
+  const password = typeof input?.password === 'string' ? input.password : ''
+  if (!EMAIL_PATTERN.test(email)) return { ok: false, error: 'Ingresa un correo válido.' }
+  if (password.trim() === '') return { ok: false, error: 'Ingresa tu contraseña.' }
+  try {
+    const context = getStoreContext()
+    const outcome = await authenticate({ email, password })
+    if (outcome.requiresAction) {
+      return { ok: false, error: 'Se requiere un paso adicional para iniciar sesión.' }
+    }
+    if (outcome.token) await writeAuthToken(context, outcome.token)
+    return { ok: true, customer: outcome.customer }
+  } catch (error) {
+    logServerError('loginAction', error)
+    return { ok: false, error: toError(error, 'No se pudo iniciar sesión.') }
+  }
+}
+
+/**
+ * Register a shopper. Validates input first, then registers; a token from the
+ * backend is persisted in the httpOnly auth cookie.
+ */
+export async function registerAction(input: {
+  email: string
+  password: string
+  first_name: string
+  last_name: string
+  phone?: string
+}): Promise<AuthActionResult> {
+  const email = typeof input?.email === 'string' ? input.email.trim() : ''
+  const password = typeof input?.password === 'string' ? input.password : ''
+  const firstName = typeof input?.first_name === 'string' ? input.first_name.trim() : ''
+  const lastName = typeof input?.last_name === 'string' ? input.last_name.trim() : ''
+  const phone =
+    typeof input?.phone === 'string' && input.phone.trim() !== '' ? input.phone.trim() : undefined
+  if (!EMAIL_PATTERN.test(email)) return { ok: false, error: 'Ingresa un correo válido.' }
+  if (password.trim() === '') return { ok: false, error: 'Ingresa una contraseña.' }
+  if (firstName === '') return { ok: false, error: 'Ingresa tu nombre.' }
+  if (lastName === '') return { ok: false, error: 'Ingresa tu apellido.' }
+  try {
+    const context = getStoreContext()
+    const outcome = await registerShopper({
+      email,
+      password,
+      first_name: firstName,
+      last_name: lastName,
+      phone,
+    })
+    if (outcome.requiresAction) {
+      return { ok: false, error: 'Se requiere un paso adicional para iniciar sesión.' }
+    }
+    if (outcome.token) await writeAuthToken(context, outcome.token)
+    return { ok: true, customer: outcome.customer }
+  } catch (error) {
+    logServerError('registerAction', error)
+    return { ok: false, error: toError(error, 'No se pudo crear la cuenta.') }
+  }
+}
+
+/**
+ * Log out. The backend logout is best-effort: the authoritative clear is the
+ * auth cookie, so a backend failure is tolerated and still reported as success.
+ */
+export async function logoutAction(): Promise<LogoutActionResult> {
+  try {
+    const context = getStoreContext()
+    try {
+      await endSession()
+    } catch (error) {
+      logServerError('endSession', error)
+    }
+    await clearAuthToken(context)
+    return { ok: true }
+  } catch (error) {
+    logServerError('logoutAction', error)
+    return { ok: false, error: toError(error, 'No se pudo cerrar la sesión.') }
+  }
+}
+
+/** Resolve the current customer from the verified auth cookie, or null. */
+export async function loadAccountAction(): Promise<AuthActionResult> {
+  try {
+    const context = getStoreContext()
+    const token = await readAuthToken(context)
+    const customer = await loadCustomer(token)
+    return { ok: true, customer: customer ?? null }
+  } catch (error) {
+    logServerError('loadAccountAction', error)
+    return { ok: false, error: toError(error, 'No se pudo cargar la cuenta.') }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Customer orders action (change: storefront-customer-orders, task 2.1)
+// ---------------------------------------------------------------------------
+//
+// This action touches ONLY the auth cookie: it never reads or writes the guest
+// session cookie or the cart (guest continuity by construction), and no token
+// is ever logged or returned. An unauthenticated caller resolves to an empty
+// history without contacting the backend.
+
+/** Load the authenticated customer's order history from their verified token. */
+export async function loadOrdersAction(): Promise<OrdersActionResult> {
+  const context = getStoreContext()
+  const token = await readAuthToken(context)
+  if (!token) return { ok: true, orders: [] }
+  try {
+    const orders = await loadOrders(token, context)
+    return { ok: true, orders }
+  } catch (error) {
+    logServerError('loadOrdersAction', error)
+    return { ok: false, error: toError(error, 'No se pudieron cargar tus pedidos.') }
+  }
+}
+
+/**
+ * Load ONE bounded page of the authenticated customer's channel-scoped order
+ * history through the additive paginated contract, returning the backend's real
+ * `count`. A missing token resolves to an empty page with `count: 0` without
+ * contacting the backend. This action touches ONLY the auth cookie — never the
+ * guest session cookie or the cart — and no token is logged or returned.
+ */
+export async function loadOrdersPageAction(input?: {
+  page?: number
+  pageSize?: number
+}): Promise<OrdersPageActionResult> {
+  const context = getStoreContext()
+  const token = await readAuthToken(context)
+  const page = Number.isInteger(input?.page) && (input?.page as number) > 0 ? (input?.page as number) : 1
+  const pageSize =
+    Number.isInteger(input?.pageSize) && (input?.pageSize as number) > 0
+      ? (input?.pageSize as number)
+      : 10
+  if (!token) return { ok: true, orders: [], count: 0, limit: pageSize, offset: (page - 1) * pageSize }
+  try {
+    const result = await loadOrdersPage(token, { page, pageSize }, context)
+    return {
+      ok: true,
+      orders: result.orders,
+      count: result.count,
+      limit: result.limit,
+      offset: result.offset,
+    }
+  } catch (error) {
+    logServerError('loadOrdersPageAction', error)
+    return { ok: false, error: toError(error, 'No se pudieron cargar tus pedidos.') }
+  }
+}

package/assets/templates/app/lib/__STOREFRONT__/cart-state.ts

@@ -0,0 +1,66 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/cart-state.ts)
+//
+// Read-only cart state for Server Component renders. It reads the signed host
+// cookie and loads the backend cart, but NEVER creates one: a guest identity is
+// created only by a Server Action (`ensureCartAction`). A reload therefore
+// reattaches to the same persisted backend cart through the cookie identity.
+//
+// Server-only and Next-bound (it reads cookies through `./session`). It is
+// imported ONLY by the catch-all page (`app/[[...slug]]/page.tsx`), never by a
+// view module, so the client catalog graph stays free of `next/headers`.
+
+import type { CartStatePatch } from './commerce'
+import { EMPTY_CART_STATE, readCart } from './commerce'
+import { getStoreContext } from './store-context'
+import { readHostSession } from './session'
+
+/** Cart state for the initial render, plus recovery/read-failure flags. */
+export type CartRenderState = CartStatePatch & {
+  receiptAvailable: boolean
+  cartReadError: string | null
+}
+
+function message(error: unknown, fallback: string): string {
+  return error instanceof Error && error.message.trim() !== '' ? error.message : fallback
+}
+
+/**
+ * Read the shopper's active backend cart for rendering, or the empty cart slice
+ * when there is no trusted session or no active cart.
+ *
+ * A real backend read failure is NOT hidden behind a fake empty cart: the
+ * shopper identity is preserved and `cartReadError` is surfaced so the UI can
+ * show a visible error. `receiptAvailable` is true when the verified session
+ * still carries a completed receipt cart (even after a new cart was started).
+ */
+export async function readCartStateForRender(): Promise<CartRenderState> {
+  let context: ReturnType<typeof getStoreContext>
+  try {
+    context = getStoreContext()
+  } catch (error) {
+    return { ...EMPTY_CART_STATE, receiptAvailable: false, cartReadError: message(error, 'Configuración de tienda inválida.') }
+  }
+
+  let session: Awaited<ReturnType<typeof readHostSession>>
+  try {
+    session = await readHostSession(context)
+  } catch (error) {
+    return { ...EMPTY_CART_STATE, receiptAvailable: false, cartReadError: message(error, 'No se pudo leer la sesión.') }
+  }
+
+  const receiptAvailable = Boolean(session?.receiptCartId)
+  if (!session?.cartId) return { ...EMPTY_CART_STATE, receiptAvailable, cartReadError: null }
+
+  try {
+    const cart = await readCart(session.cartId, context)
+    return { ...(cart ?? EMPTY_CART_STATE), receiptAvailable, cartReadError: null }
+  } catch (error) {
+    // Preserve the identity and surface the failure — never a fake empty cart.
+    return {
+      ...EMPTY_CART_STATE,
+      cartId: session.cartId,
+      receiptAvailable,
+      cartReadError: message(error, 'No se pudo cargar el carrito.'),
+    }
+  }
+}