import type { Order, StaleSplit } from '@platform-modules/commerce-checkout'

/** Server status union — the source of money-truth. `Order['status']` from the core. */
export type CheckoutStatus = Order['status']

/**
 * Browser-facing checkout start input. NO buyerRef — the host API route resolves
 * buyer identity from the session/cookie server-side (the browser never sends it).
 * `idempotencyKey` is minted + persisted by the sibling (§0.1) and arrives unchanged
 * on every retry/resume.
 */
export type CheckoutStartInput = {
  cartId: string
  priceMode: 'inclusive' | 'exclusive'
  currency: string
  buyerCountry: string
  idempotencyKey: string
}

/**
 * Injected, DB-free async data seam (§2). The host wires each method to an API route
 * it owns; the route runs startCheckout/getCheckoutStatus 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 db handle.
 *
 * Error contract the host's client MUST honor (the sibling branches on these):
 *  - 409 stale-items   → decode body via reviveStaleSplit, throw CheckoutWireError({ stale }).
 *  - 409 idempotency   → throw the core's OrderIdempotencyConflictError.
 *  - other failures     → throw CheckoutWireError (no stale) or a core typed error.
 */
export interface CheckoutClient {
  /** Claim/resume an order. Resolves orderId + (for card flows) a PSP clientSecret. */
  start(input: CheckoutStartInput): Promise<{ orderId: string; clientSecret?: string }>
  /** Poll server-authoritative order status. clientSecret reappears on requires_action. */
  getStatus(orderId: string): Promise<{ status: CheckoutStatus; clientSecret?: string }>
}