import type { Cart, CartAction } from '@platform-modules/commerce-cart'

/**
 * Injected, DB-free async data seam for browser-side cart ops (§1).
 * The host wires each method to an API route it owns; the route runs
 * applyToCart(store, cartId, action)/store.load/store.merge server-side and
 * enforces the price/currency/stock/authz floors. HTTP is the one production
 * transport; an in-process core wrapper + a mock are test doubles. The browser
 * island never holds a CartStore/db handle.
 */
export interface CartClient {
  /** Load the session's cart — the host route resolves identity from session/cookie. */
  getCart(): Promise<Cart>
  /** Persist an action — host route returns the server-authoritative Cart (the reconcile target). */
  apply(action: CartAction): Promise<Cart>
  /** Guest→user cart merge on sign-in → authoritative Cart. */
  merge(guestCartId: string): Promise<Cart>
}