@pcreative/commerce-contract 1.0.0 → 1.3.0

package/src/index.d.ts

@@ -32,6 +32,7 @@ export interface OptionValue {
   /** Nombre de la opción: "Talla", "Color". */
   name: string
   value: string
+  color?: string | null
 }
 
 export interface Variant {
@@ -48,6 +49,84 @@ export interface Variant {
   options: OptionValue[]
   weight?: number | null
   image?: Image | null
+  images?: Image[]
+  tiers?: PriceTier[]
+  digital?: boolean
+  requiresShipping?: boolean
+  bundle?: BundleComponent[] | null
+  bundleGroups?: BundleGroup[] | null
+  measure?: { quantity: number; unit: string } | null
+  unitPrice?: { amount: number; currency: string; unit: string } | null
+}
+
+export interface BundleGroup {
+  id: string
+  title: string
+  min: number
+  max: number
+  options: { variantId: string; title: string; price: number | null; image?: string | null; available: boolean }[]
+}
+
+export interface WithdrawalState {
+  disponible: boolean
+  pais: string
+  dias: number | null
+  diasHabiles: boolean
+  caduca: string | null
+  dentroDePlazo: boolean
+  lineas: { id: string; titulo: string; cantidad: number; excluida: string | null }[]
+  solicitudes: { id: string; recibidoEn: string; acuseEn: string | null; atendidoEn: string | null }[]
+}
+
+export interface BundleComponent {
+  variantId: string
+  title: string
+  quantity: number
+  handle?: string | null
+  image?: string | null
+}
+
+export interface Download {
+  id: string
+  lineId: string
+  name: string
+  bytes: number
+  version: number
+  status: "bloqueada" | "activa" | "suspendida" | "revocada"
+  remaining: number | null
+  expiresAt: string | null
+  downloaded: number
+  firstDownloadAt: string | null
+  url: string | null
+}
+
+export interface PriceTier {
+  minQuantity: number
+  maxQuantity?: number | null
+  price: Money
+  savePercent: number
+  unitPrice?: { amount: number; currency: string; unit: string } | null
+}
+
+export interface CustomField {
+  key: string
+  label: string
+  type: "texto" | "texto_largo" | "numero" | "lista" | "casilla" | "fecha" | "fichero"
+  required: boolean
+  help?: string | null
+  config: Record<string, unknown>
+  variantIds: string[]
+  condition?: { field: string; equals: string } | null
+  personalizes: boolean
+  surcharge: { mode: string; amount: number; freeChars: number }
+  values: { id: string; label: string; surcharge: { mode: string; amount: number }; variantIds: string[] }[]
+}
+
+export interface QuantityRules {
+  scope: "variant" | "product"
+  min: number
+  max?: number | null
+  increment: number
 }
 
 export interface Product {
@@ -75,6 +154,8 @@ export interface Product {
   rating?: number | null
   reviewCount?: number
   available: boolean
+  quantityRules?: QuantityRules | null
+  customization?: CustomField[]
   metadata?: Record<string, unknown>
 }
 
@@ -122,6 +203,14 @@ export interface LineItem {
    * subtotal, o lo cuenta dos veces.
    */
   isFee?: boolean
+  quantityRule?: (QuantityRules & { counted: number }) | null
+  tier?: { from: number; regularUnitPrice: Money } | null
+  nextTier?: { from: number; missing: number; unitPrice: Money } | null
+  problem?: { code: string; message: string } | null
+  customization?: { label: string; value: string; surcharge: number }[] | null
+  personalized?: boolean
+  digital?: boolean
+  bundle?: { title: string; quantity: number }[] | null
 }
 
 /** Un sitio del que sale mercancía: un paquete, un porte. */
@@ -147,6 +236,35 @@ export interface ShippingGroup {
   option_id?: string | null
 }
 
+export interface StoreInfo {
+  name: string | null
+  legalName: string | null
+  taxId: string | null
+  address: string | null
+  email: string | null
+  phone: string | null
+  country?: string | null
+  legal?: {
+    digital?: {
+      pais: string
+      exigir: boolean
+      texto: string
+      version: number
+    }
+    personalizados: {
+      pais: string
+      excluye: boolean
+      puedeExcluir: boolean
+      porLey: boolean
+      dias: number | null
+      diasHabiles: boolean
+      prohibeNoDevoluciones: boolean
+      texto: string
+      garantias: string | null
+    }
+  } | null
+}
+
 export interface ShippingGroups {
   grupos: ShippingGroup[]
   moneda: string
@@ -164,6 +282,10 @@ export interface ShippingOption {
   /** El backend calcula el precio al elegirla (envío por peso, por ejemplo). */
   priceCalculated?: boolean
   description?: string | null
+  /** Plazo de entrega tal y como lo escribió la tienda: "24-48 h". */
+  deliveryTime?: string | null
+  /** El cliente recoge el pedido: no hay porte ni reparto. */
+  pickup?: boolean
 }
 
 export interface PaymentMethod {
@@ -171,6 +293,10 @@ export interface PaymentMethod {
   /** Identificador del proveedor: "transfer", "cod", "bizum", "card"… */
   provider: string
   name?: string
+  /** Texto corto que la tienda escribe para explicarla en la caja. */
+  description?: string | null
+  /** Lo que el comprador tiene que hacer para pagar (datos de una transferencia). */
+  instructions?: string | null
   /**
    * Recargo de esta forma de pago, en unidades mayores. Sin definir = ninguno.
    *
@@ -214,6 +340,10 @@ export interface Cart {
   shippingMethods: { id: string; name: string; price: Money }[]
   regionId?: string
   promoCodes?: string[]
+  hasDigital?: boolean
+  digitalConsent?: { at: string; version: number } | null
+  vatNumber?: { number: string; valid: boolean; checked: boolean; name: string | null } | null
+  taxExempt?: { reason: "intra_eu"; articles: string[] } | null
   /**
    * 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á.
@@ -313,18 +443,36 @@ export interface CommerceClient {
   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>
+  /** Sube un fichero que el cliente adjunta a una personalización. */
+  subirFichero?(archivo: File): Promise<{ id: string; nombre: string; tipo: string; bytes: number; firma: string }>
+  /** Opcional: las descargas de un pedido con contenido digital. */
+  getDownloads?(orderId: string): Promise<Download[]>
+  /** Opcional: estado del derecho de desistimiento de un pedido. */
+  getWithdrawal?(orderId: string): Promise<WithdrawalState | null>
+  /** Opcional: solicita el desistimiento de un pedido (botón obligatorio en la UE). */
+  requestWithdrawal?(orderId: string, datos?: { lineas?: string[]; motivo?: string }): Promise<{ solicitud: string; aceptadas: number }>
 
   cart: {
     get(id: string): Promise<Cart | null>
     create(): Promise<Cart>
-    addItem(cartId: string, variantId: string, quantity: number): Promise<Cart>
+    addItem(
+      cartId: string,
+      variantId: string,
+      quantity: number,
+      personalizacion?: Record<string, unknown>,
+      pack?: Record<string, string[]>
+    ): Promise<Cart>
     updateItem(cartId: string, lineId: string, quantity: number): Promise<Cart>
     removeItem(cartId: string, lineId: string): Promise<Cart>
+    /** Consentimiento previo para entregar contenido digital ya (UE, Reino Unido). */
+    consentirDigital?(cartId: string, aceptado: boolean): Promise<Cart>
     applyPromo(cartId: string, code: string): Promise<Cart>
     removePromo(cartId: string, code: string): Promise<Cart>
   }
 
   checkout: {
+    listCountries?(): Promise<string[]>
+    setVatNumber?(cartId: string, vatNumber: string | null): Promise<Cart>
     setEmail(cartId: string, email: string): Promise<Cart>
     setAddresses(cartId: string, shipping: Address, billing?: Address): Promise<Cart>
     listShippingOptions(cartId: string): Promise<ShippingOption[]>
@@ -360,12 +508,23 @@ export interface CommerceClient {
 
   /** Opcional: un adaptador puede no soportar cuentas de cliente. */
   account?: {
-    login(email: string, password: string): Promise<{ token: string }>
+    login(email: string, password: string, cartId?: 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[]>
+    confirmEmail?(sessionToken: string, token: string): Promise<{ adopted: number } | null>
   }
 
+  /** Opcional: nombre y datos legales de la tienda, tal y como los tiene el panel. */
+  getStore?(): Promise<StoreInfo | null>
+
+  /**
+   * Opcional: manda a la tienda un mensaje del formulario de contacto. Rechaza
+   * con `status` 400 si faltan datos, 429 si hay demasiados envíos y 503 si la
+   * tienda no tiene a dónde mandarlo.
+   */
+  sendContact?(mensaje: { name?: string; email: string; subject?: string; message: string }): Promise<void>
+
   /** Opcional: contenido editorial servido por el backend. */
   content?: {
     listPosts(limit?: number): Promise<Post[]>

package/src/index.js

@@ -1,26 +1,12 @@
-/**
- * @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 {
@@ -33,7 +19,6 @@ export function formatMoney(m, locale = "es-ES") {
   }
 }
 
-/** 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")
@@ -56,11 +41,6 @@ const REQUERIDO = {
   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"]