@pcreative/commerce-contract 1.0.0

package/src/index.d.ts

@@ -0,0 +1,397 @@
+/**
+ * Contrato de datos de commerce (v1.0).
+ *
+ * Un tema NO importa el SDK del backend. Consume estas entidades y llama a este
+ * cliente; el adaptador traduce. De ahí salen las dos propiedades que sostienen
+ * el producto: el mismo tema sirve para otro backend mañana, y el backend no
+ * queda casado con temas de un solo framework.
+ *
+ * Los importes son SIEMPRE decimales en unidades mayores (19.99, no 1999) y
+ * llevan su moneda al lado, para que ningún tema tenga que adivinar la escala.
+ */
+
+// ── Entidades ─────────────────────────────────────────────────────────────
+
+export interface Money {
+  /** Importe en unidades mayores: 19.99 €. */
+  amount: number
+  /** ISO 4217 en minúsculas: "eur". */
+  currency: string
+  /** true si `amount` ya lleva impuestos incluidos. */
+  taxIncluded?: boolean
+}
+
+export interface Image {
+  url: string
+  alt?: string
+  width?: number
+  height?: number
+}
+
+export interface OptionValue {
+  /** Nombre de la opción: "Talla", "Color". */
+  name: string
+  value: string
+}
+
+export interface Variant {
+  id: string
+  title: string
+  sku?: string
+  barcode?: string
+  price: Money
+  /** Precio anterior si hay rebaja. */
+  compareAt?: Money | null
+  /** null = el backend no lleva stock de esta variante. */
+  stock: number | null
+  available: boolean
+  options: OptionValue[]
+  weight?: number | null
+  image?: Image | null
+}
+
+export interface Product {
+  id: string
+  handle: string
+  title: string
+  subtitle?: string | null
+  description?: string | null
+  brand?: string | null
+  /**
+   * Quién vende este producto en un marketplace.
+   *
+   * AUSENTE significa que lo vende la propia tienda, que es el caso de
+   * cualquier instalación sin marketplace. Opcional a propósito: un tema escrito
+   * antes de que esto existiera sigue funcionando sin tocar una línea.
+   */
+  seller?: { id: string; name: string; slug: string } | null
+  images: Image[]
+  thumbnail?: string | null
+  /** Precio mínimo entre las variantes: el «desde X €» de la tarjeta. */
+  price: Money
+  variants: Variant[]
+  categories: CategoryRef[]
+  tags?: string[]
+  rating?: number | null
+  reviewCount?: number
+  available: boolean
+  metadata?: Record<string, unknown>
+}
+
+export interface CategoryRef {
+  id: string
+  handle: string
+  name: string
+}
+
+export interface Category extends CategoryRef {
+  description?: string | null
+  parentId?: string | null
+  children?: Category[]
+  image?: Image | null
+  productCount?: number
+}
+
+export interface Address {
+  firstName?: string
+  lastName?: string
+  company?: string
+  address1?: string
+  address2?: string
+  city?: string
+  province?: string
+  postalCode?: string
+  countryCode?: string
+  phone?: string
+}
+
+export interface LineItem {
+  id: string
+  productId: string
+  variantId: string
+  handle?: string
+  title: string
+  variantTitle?: string
+  thumbnail?: string | null
+  quantity: number
+  unitPrice: Money
+  total: Money
+  /**
+   * Es un CARGO, no mercancía: recargo por forma de pago y parecidos. No se
+   * envía y no tiene variante. Un tema que lo enseñe aparte debe excluirlo del
+   * subtotal, o lo cuenta dos veces.
+   */
+  isFee?: boolean
+}
+
+/** Un sitio del que sale mercancía: un paquete, un porte. */
+export interface ShippingGroup {
+  /** Identificador opaco. El tema lo devuelve tal cual al elegir. */
+  grupo: string
+  /** Nombre del vendedor que lo manda. Vacío = lo manda la tienda. */
+  vendedor?: string | null
+  vendedor_id?: string | null
+  lineas: { id: string; titulo: string; cantidad: number }[]
+  /**
+   * Lo que puede elegir ESTE paquete.
+   *
+   * Va por grupo y no en común porque cada vendedor puede tener sus propias
+   * tarifas, y porque un precio calculado (por peso) depende de lo que lleva
+   * ese paquete, no el carrito entero.
+   *
+   * `precio` en unidades mayores; vacío = todavía no se sabe (tarifa calculada
+   * que el transportista no ha resuelto). El tema debe decirlo, no inventarlo.
+   */
+  opciones: { id: string; nombre: string; precio: number | null; calculado: boolean }[]
+  /** Lo ya elegido, para pintar la selección al recargar. */
+  option_id?: string | null
+}
+
+export interface ShippingGroups {
+  grupos: ShippingGroup[]
+  moneda: string
+}
+
+export interface EleccionEnvio {
+  grupo: string
+  optionId: string
+}
+
+export interface ShippingOption {
+  id: string
+  name: string
+  price: Money
+  /** El backend calcula el precio al elegirla (envío por peso, por ejemplo). */
+  priceCalculated?: boolean
+  description?: string | null
+}
+
+export interface PaymentMethod {
+  id: string
+  /** Identificador del proveedor: "transfer", "cod", "bizum", "card"… */
+  provider: string
+  name?: string
+  /**
+   * Recargo de esta forma de pago, en unidades mayores. Sin definir = ninguno.
+   *
+   * Es para ENSEÑARLO. Quien lo cobra es el backend al elegir la forma de pago,
+   * leyéndolo de la configuración de la tienda: si viniera del escaparate,
+   * cualquiera podría pedir un recargo de cero.
+   */
+  surcharge?: number
+}
+
+/**
+ * Cómo sigue el comprador para pagar.
+ *
+ * La misma forma que usa `@pcreative/payments-contract`, escrita otra vez a
+ * propósito: este paquete no depende de nada, y atarlo al de pagos obligaría a
+ * instalarlo para pintar un catálogo.
+ */
+export type SiguientePago =
+  /** Mandar el navegador a la pasarela. */
+  | { tipo: "redirigir"; url: string; proveedor?: string }
+  /** Confirmar en el navegador con el SDK de la pasarela. `datos` es opaco. */
+  | {
+      tipo: "confirmar_en_cliente"
+      pasarela: string
+      datos: Record<string, unknown>
+      proveedor?: string
+    }
+
+export interface Cart {
+  id: string
+  items: LineItem[]
+  subtotal: Money
+  shipping: Money
+  discount: Money
+  tax: Money
+  total: Money
+  itemCount: number
+  email?: string | null
+  shippingAddress?: Address | null
+  billingAddress?: Address | null
+  shippingMethods: { id: string; name: string; price: Money }[]
+  regionId?: string
+  promoCodes?: string[]
+  /**
+   * El paso que falta para pagar, si el método elegido lo pide. `null` con los
+   * métodos sin pasarela: ahí pagar es confirmar el pedido y ya está.
+   */
+  pago?: SiguientePago | null
+}
+
+export interface Order {
+  id: string
+  displayId?: number
+  email?: string
+  status: string
+  items: LineItem[]
+  subtotal: Money
+  shipping: Money
+  discount: Money
+  tax: Money
+  total: Money
+  shippingAddress?: Address | null
+  createdAt?: string
+}
+
+export interface Customer {
+  id: string
+  email: string
+  firstName?: string | null
+  lastName?: string | null
+  phone?: string | null
+}
+
+export interface Post {
+  id: string
+  handle: string
+  title: string
+  excerpt?: string | null
+  content?: string | null
+  image?: string | null
+  publishedAt?: string | null
+  tags?: string[]
+}
+
+/**
+ * Una página suelta del escaparate: «sobre nosotros», el aviso legal, los
+ * envíos. La escribe quien lleva la tienda desde el panel.
+ *
+ * 🔴 NO es una entrada de blog aunque se le parezca. Una entrada tiene fecha y
+ * se ordena por ella; una página tiene un ORDEN que decide una persona, porque
+ * lo que se pinta con ellas es el pie. Meterlas en el mismo tipo obligaría a
+ * inventarle una fecha al aviso legal.
+ */
+export interface PaginaSuelta {
+  handle: string
+  title: string
+  /** Solo al pedir UNA. El listado no lo trae: el pie no lo necesita. */
+  content?: string | null
+  /** Lo decide quien la escribe. Es el orden del pie. */
+  order?: number
+  seoTitle?: string | null
+  seoDescription?: string | null
+}
+
+// ── Parámetros ────────────────────────────────────────────────────────────
+
+export type SortProductos = "relevance" | "price_asc" | "price_desc" | "newest" | "rating"
+
+export interface ListProductsParams {
+  q?: string
+  /** Handle de categoría. */
+  category?: string
+  categoryId?: string
+  ids?: string[]
+  tags?: string[]
+  limit?: number
+  offset?: number
+  sort?: SortProductos
+}
+
+export interface Page<T> {
+  items: T[]
+  /** Total de resultados, no de esta página. */
+  count: number
+  limit: number
+  offset: number
+}
+
+// ── El cliente ────────────────────────────────────────────────────────────
+
+export interface CommerceClient {
+  /** Identificador del adaptador: "pcreative", "static"… */
+  readonly adapter: string
+
+  listProducts(params?: ListProductsParams): Promise<Page<Product>>
+  getProduct(handle: string): Promise<Product | null>
+  getProductsByIds(ids: string[]): Promise<Product[]>
+  listCategories(): Promise<Category[]>
+  getCategory(handle: string): Promise<Category | null>
+  search(q: string, limit?: number): Promise<Product[]>
+  /** Pedido por id, para la página de confirmación tras el checkout. */
+  getOrder(id: string): Promise<Order | null>
+
+  cart: {
+    get(id: string): Promise<Cart | null>
+    create(): Promise<Cart>
+    addItem(cartId: string, variantId: string, quantity: number): Promise<Cart>
+    updateItem(cartId: string, lineId: string, quantity: number): Promise<Cart>
+    removeItem(cartId: string, lineId: string): Promise<Cart>
+    applyPromo(cartId: string, code: string): Promise<Cart>
+    removePromo(cartId: string, code: string): Promise<Cart>
+  }
+
+  checkout: {
+    setEmail(cartId: string, email: string): Promise<Cart>
+    setAddresses(cartId: string, shipping: Address, billing?: Address): Promise<Cart>
+    listShippingOptions(cartId: string): Promise<ShippingOption[]>
+    setShippingMethod(cartId: string, optionId: string): Promise<Cart>
+    /**
+     * Opcional: de cuántos sitios sale el carrito.
+     *
+     * Una tienda normal devuelve un grupo y el tema puede ignorar todo esto y
+     * seguir con `listShippingOptions` / `setShippingMethod`. Un marketplace con
+     * vendedores que mandan lo suyo devuelve uno por sitio, y ahí un porte único
+     * sería cobrar un paquete y enviar tres.
+     *
+     * Un adaptador que no lo implemente no tiene marketplace: el tema lo
+     * comprueba con `typeof` y sigue por el camino de siempre.
+     */
+    listShippingGroups?(cartId: string): Promise<ShippingGroups>
+    /**
+     * Fija los portes de TODOS los grupos a la vez.
+     *
+     * El conjunto entero, siempre. No es capricho de la firma: en el backend,
+     * mandar un porte suelto borra los demás sin avisar de nada. Un método
+     * «cambia el porte del grupo X» dejaría el carrito con uno solo.
+     */
+    setShippingMethods?(cartId: string, elecciones: EleccionEnvio[]): Promise<void>
+    listPaymentMethods(cartId: string): Promise<PaymentMethod[]>
+    /**
+     * @param datos Lo que el escaparate quiera pasarle al proveedor de pago del
+     * backend. Se usa para la ruta de vuelta, que depende del idioma.
+     */
+    selectPaymentMethod(cartId: string, provider: string, datos?: Record<string, unknown>): Promise<Cart>
+    complete(cartId: string): Promise<{ order: Order } | { cart: Cart; error: string }>
+  }
+
+  /** Opcional: un adaptador puede no soportar cuentas de cliente. */
+  account?: {
+    login(email: string, password: string): Promise<{ token: string }>
+    register(datos: { email: string; password: string; firstName?: string; lastName?: string }): Promise<Customer>
+    me(token: string): Promise<Customer | null>
+    orders(token: string): Promise<Order[]>
+  }
+
+  /** Opcional: contenido editorial servido por el backend. */
+  content?: {
+    listPosts(limit?: number): Promise<Post[]>
+    getPost(handle: string): Promise<Post | null>
+    /**
+     * Las páginas publicadas, SIN su contenido: es lo que pinta el pie, y
+     * traerse el texto de ocho páginas para enseñar ocho enlaces es tráfico
+     * tirado en cada visita.
+     */
+    listPages?(): Promise<PaginaSuelta[]>
+    getPage?(handle: string): Promise<PaginaSuelta | null>
+  }
+}
+
+// ── API ───────────────────────────────────────────────────────────────────
+
+export declare const CONTRACT_VERSION: string
+
+/** Formatea un importe con la moneda que lleva dentro. */
+export declare function formatMoney(money: Money, locale?: string): string
+
+/** Suma importes comprobando que son de la misma moneda. */
+export declare function sumMoney(...importes: Money[]): Money
+
+/** Construye un Money, con 0 como valor por defecto. */
+export declare function money(amount: number | null | undefined, currency: string, taxIncluded?: boolean): Money
+
+/** Comprueba que un objeto implementa el contrato; devuelve lo que falta. */
+export declare function assertCommerceClient(cliente: unknown): string[]

package/src/index.js

@@ -0,0 +1,80 @@
+/**
+ * @pcreative/commerce-contract — el contrato de datos que consume un tema.
+ *
+ * Aquí solo hay las utilidades comunes y el comprobador de conformidad: las
+ * entidades viven en `index.d.ts` (son forma, no código) y cada adaptador
+ * traduce lo suyo. Sin dependencias, para que valga igual en Next, Astro, Nuxt
+ * o un runtime edge.
+ */
+
+export const CONTRACT_VERSION = "1.0"
+
+/** Construye un importe. Los nulos del backend se vuelven 0, no NaN. */
+export function money(amount, currency, taxIncluded) {
+  const m = { amount: Number(amount ?? 0) || 0, currency: String(currency ?? "eur").toLowerCase() }
+  if (taxIncluded !== undefined) m.taxIncluded = taxIncluded
+  return m
+}
+
+/**
+ * Formatea con `Intl`. Los importes del contrato son unidades mayores, así que
+ * no hay que dividir por 100 en ningún sitio — que es de donde salen la mitad
+ * de los errores de precio en las tiendas.
+ */
+export function formatMoney(m, locale = "es-ES") {
+  if (!m) return ""
+  try {
+    return new Intl.NumberFormat(locale, {
+      style: "currency",
+      currency: (m.currency ?? "eur").toUpperCase(),
+    }).format(m.amount ?? 0)
+  } catch {
+    return `${(m.amount ?? 0).toFixed(2)} ${(m.currency ?? "").toUpperCase()}`
+  }
+}
+
+/** Suma importes. Mezclar monedas es un error, no algo que redondear. */
+export function sumMoney(...importes) {
+  const validos = importes.filter(Boolean)
+  if (validos.length === 0) return money(0, "eur")
+  const currency = validos[0].currency
+  for (const m of validos) {
+    if (m.currency !== currency) {
+      throw new Error(`no se pueden sumar importes en ${currency} y en ${m.currency}`)
+    }
+  }
+  return money(
+    validos.reduce((n, m) => n + (m.amount ?? 0), 0),
+    currency,
+    validos[0].taxIncluded
+  )
+}
+
+const REQUERIDO = {
+  raiz: ["listProducts", "getProduct", "getProductsByIds", "listCategories", "getCategory", "search", "getOrder"],
+  cart: ["get", "create", "addItem", "updateItem", "removeItem"],
+  checkout: ["setEmail", "setAddresses", "listShippingOptions", "setShippingMethod", "listPaymentMethods", "selectPaymentMethod", "complete"],
+}
+
+/**
+ * Comprueba que un adaptador implementa el contrato. Devuelve la lista de lo
+ * que falta (vacía si cumple). Un tema puede llamarlo en desarrollo para
+ * enterarse al arrancar y no en mitad del checkout.
+ */
+export function assertCommerceClient(cliente) {
+  const faltan = []
+  if (!cliente || typeof cliente !== "object") return ["el cliente no es un objeto"]
+  for (const m of REQUERIDO.raiz) {
+    if (typeof cliente[m] !== "function") faltan.push(m)
+  }
+  for (const grupo of ["cart", "checkout"]) {
+    if (!cliente[grupo] || typeof cliente[grupo] !== "object") {
+      faltan.push(grupo)
+      continue
+    }
+    for (const m of REQUERIDO[grupo]) {
+      if (typeof cliente[grupo][m] !== "function") faltan.push(`${grupo}.${m}`)
+    }
+  }
+  return faltan
+}