@pcreative/commerce-contract 1.0.0

package/src/adapters/api.js

@@ -0,0 +1,825 @@
+/**
+ * Adaptador HTTP del contrato de datos.
+ *
+ * Habla con la API de tienda por `fetch` a pelo, sin SDK. No es purismo: un SDK
+ * trae su propio manejo de sesión y presupone un entorno de navegador, y eso es
+ * justo lo que impedía que un tema Astro, un runtime edge o una app nativa
+ * usaran el mismo código. `fetch` está en todos.
+ *
+ *   import { createCommerce } from "@pcreative/commerce-contract/api"
+ *   const commerce = createCommerce({
+ *     baseUrl: process.env.COMMERCE_URL,
+ *     publishableKey: process.env.COMMERCE_KEY,
+ *   })
+ */
+import { money } from "../index.js"
+
+const PRODUCT_FIELDS = [
+  "id", "title", "subtitle", "handle", "description", "thumbnail", "metadata",
+  "*images", "*categories", "*tags", "*variants", "*variants.calculated_price",
+  "+variants.inventory_quantity", "variants.options.value", "variants.options.option.title",
+  // Marketplace: quién vende el producto. Con `+` porque no es un campo de
+  // serie del catálogo — sale de un enlace entre módulos. Si la instalación no
+  // tiene marketplace, sencillamente no viene nada y `seller` queda vacío.
+  "+vendedor.id", "+vendedor.nombre", "+vendedor.slug",
+].join(",")
+
+const CART_FIELDS =
+  "*items,*items.variant,*items.product,*region,*shipping_address,*billing_address,*shipping_methods,*promotions,*payment_collection,*payment_collection.payment_sessions"
+
+export function createCommerce({
+  baseUrl,
+  /**
+   * Usar el catálogo PROPIO (`/tienda/*`) en vez del del motor (`/store/*`).
+   *
+   * ── 🔴 POR QUÉ AHORA VIENE ENCENDIDO ────────────────────────────────────
+   *
+   * Venía APAGADO, y era el mismo fallo que ya se arregló en el panel el
+   * 2026-08-18 sin arreglarlo aquí. Aquel día `npm start` pasó a levantar el
+   * servidor propio, que sirve `/tienda/*` y NO sirve `/store/*`.
+   *
+   * Con el interruptor apagado por defecto, cualquier tema recién hecho pedía
+   * el catálogo al motor, recibía un 404 y salía con la tienda VACÍA. Y no
+   * daba un error: pintaba la portada entera, bien maquetada, sin un solo
+   * producto. Se descubrió probando un tema antes de publicarlo.
+   *
+   * Un valor por defecto que solo funciona si alguien se acuerda de cambiarlo
+   * no es un valor por defecto.
+   *
+   * Se pone a `false` a propósito para volver al motor, y va emparejado con
+   * `npm run start:motor` en el backend. Uno sin el otro es media vuelta
+   * atrás, que es peor que ninguna.
+   */
+  catalogoPropio = true,
+  publishableKey,
+  /** Código de país de la región por defecto, p.ej. "es". */
+  countryCode,
+  /**
+   * Idioma en el que se quiere el contenido, p.ej. "en-US".
+   *
+   * Va en una cabecera y no en cada llamada a propósito: el idioma es del
+   * VISITANTE, no de la consulta. Si hubiera que pasarlo función por función,
+   * bastaría con que un tema se olvidara en una sola pantalla para que esa
+   * página saliera en otro idioma — y ese fallo es de los que no se ven hasta
+   * que lo dice un cliente.
+   *
+   * Lo que no esté traducido vuelve en el idioma original, así que poner un
+   * idioma nunca deja la tienda vacía.
+   */
+  locale,
+  /** `fetch` alternativo (para tests o para inyectar caché del framework). */
+  fetch: fetchImpl,
+  /** Opciones extra por petición: `next: { revalidate }` en Next, `cache` en el edge… */
+  requestInit = {},
+} = {}) {
+  if (!baseUrl) throw new Error("createCommerce: falta baseUrl")
+  const f = fetchImpl ?? globalThis.fetch
+  const raiz = String(baseUrl).replace(/\/$/, "")
+
+  let regionPromesa = null
+
+  async function api(ruta, { method = "GET", body, token, ...extra } = {}) {
+    const cabeceras = { accept: "application/json", ...(extra.headers ?? {}) }
+    if (publishableKey) cabeceras["x-publishable-api-key"] = publishableKey
+    if (locale) cabeceras["x-pcc-locale"] = locale
+    if (body !== undefined) cabeceras["content-type"] = "application/json"
+    if (token) cabeceras.authorization = `Bearer ${token}`
+
+    const res = await f(`${raiz}${ruta}`, {
+      method,
+      ...requestInit,
+      ...extra,
+      headers: cabeceras,
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    })
+
+    if (!res.ok) {
+      let detalle = ""
+      try {
+        detalle = (await res.json())?.message ?? ""
+      } catch {
+        /* respuesta sin JSON */
+      }
+      // El código HTTP viaja en el error: un 404 de producto no es lo mismo que
+      // un 401 por clave publicable mal puesta, y el tema debe poder distinguirlo.
+      const err = new Error(`${method} ${ruta} → ${res.status}${detalle ? `: ${detalle}` : ""}`)
+      err.status = res.status
+      throw err
+    }
+    return res.status === 204 ? null : res.json()
+  }
+
+  /** La región fija moneda e impuestos. Se resuelve una vez y se reutiliza. */
+  function region() {
+    // Con el catálogo propio, las regiones también salen de nuestras rutas: si
+    // no, la tienda leería la moneda del motor y los precios del nuestro.
+    regionPromesa ??= api(catalogoPropio ? "/tienda/regiones" : "/store/regions")
+      .then(({ regions = [] }) => {
+        if (countryCode) {
+          const r = regions.find((x) => (x.countries ?? []).some((c) => c.iso_2 === countryCode.toLowerCase()))
+          if (r) return r
+        }
+        return regions[0] ?? null
+      })
+      .catch(() => null)
+    return regionPromesa
+  }
+
+  // ── Mapeo ───────────────────────────────────────────────────────────────
+
+  const monedaDe = (v, fallback) =>
+    (v?.calculated_price?.currency_code ?? fallback ?? "eur").toLowerCase()
+
+  function mapVariant(v, fallbackCurrency) {
+    const cp = v?.calculated_price ?? {}
+    const precio = money(cp.calculated_amount, monedaDe(v, fallbackCurrency), true)
+    const original = cp.original_amount
+    return {
+      id: v.id,
+      title: v.title ?? "",
+      sku: v.sku ?? undefined,
+      barcode: v.barcode ?? undefined,
+      price: precio,
+      compareAt:
+        original != null && original > (cp.calculated_amount ?? 0)
+          ? money(original, precio.currency, true)
+          : null,
+      // `inventory_quantity` solo viene si la variante gestiona inventario;
+      // si no, no hay número que enseñar y `null` es la respuesta honesta.
+      stock: v.manage_inventory === false ? null : v.inventory_quantity ?? null,
+      available:
+        v.manage_inventory === false ||
+        v.allow_backorder === true ||
+        (v.inventory_quantity ?? 0) > 0,
+      options: (v.options ?? []).map((o) => ({
+        name: o.option?.title ?? "",
+        value: o.value ?? "",
+      })),
+      weight: v.weight ?? null,
+      image: null,
+    }
+  }
+
+  function mapProduct(p, fallbackCurrency) {
+    const variants = (p.variants ?? []).map((v) => mapVariant(v, fallbackCurrency))
+    const conPrecio = variants.filter((v) => v.price.amount > 0)
+    const minimo = conPrecio.length
+      ? conPrecio.reduce((a, b) => (b.price.amount < a.price.amount ? b : a))
+      : variants[0]
+
+    return {
+      id: p.id,
+      handle: p.handle,
+      title: p.title,
+      subtitle: p.subtitle ?? null,
+      description: p.description ?? null,
+      brand: p.metadata?.brand ?? p.metadata?.marca ?? null,
+      // El enlace puede llegar como objeto o como lista de uno, según por dónde
+      // se pida. Se normaliza aquí para que el tema no tenga que saberlo.
+      seller: (() => {
+        const v = Array.isArray(p.vendedor) ? p.vendedor[0] : p.vendedor
+        return v?.id ? { id: v.id, name: v.nombre, slug: v.slug } : null
+      })(),
+      images: (p.images ?? []).map((i) => ({ url: i.url, alt: p.title })),
+      thumbnail: p.thumbnail ?? p.images?.[0]?.url ?? null,
+      price: minimo?.price ?? money(0, fallbackCurrency ?? "eur", true),
+      variants,
+      categories: (p.categories ?? []).map((c) => ({ id: c.id, handle: c.handle, name: c.name })),
+      tags: (p.tags ?? []).map((t) => t.value ?? t.name).filter(Boolean),
+      rating: null,
+      reviewCount: 0,
+      available: variants.some((v) => v.available),
+      metadata: p.metadata ?? {},
+    }
+  }
+
+  function mapCategory(c) {
+    return {
+      id: c.id,
+      handle: c.handle,
+      name: c.name,
+      description: c.description ?? null,
+      parentId: c.parent_category_id ?? null,
+      children: (c.category_children ?? []).map(mapCategory),
+      image: c.metadata?.image ? { url: String(c.metadata.image), alt: c.name } : null,
+    }
+  }
+
+  /**
+   * Del producto que devuelve NUESTRO catálogo al del contrato.
+   *
+   * Viene casi con la forma correcta a propósito: el catálogo propio se
+   * escribió para hablar el contrato, no el idioma del motor.
+   */
+  function mapProductoPropio(p) {
+    return {
+      id: p.id,
+      handle: p.handle,
+      title: p.title,
+      subtitle: p.subtitle ?? null,
+      description: p.description ?? null,
+      // El `alt` se pone aquí, como en el camino del motor: una imagen sin
+      // texto alternativo es una ficha que no se puede leer con un lector de
+      // pantalla y que el buscador no entiende.
+      images: (p.images ?? []).map((i) => ({ url: i.url, alt: i.alt ?? p.title })),
+      thumbnail: p.thumbnail ?? null,
+      price: p.price,
+      // Los cuatro que faltaban. No son adorno: la marca y las etiquetas las
+      // pinta la ficha, y `reviewCount` decide si sale el bloque de reseñas.
+      // Al no venir, un tema los leía como `undefined` y dejaba huecos sin
+      // dar ningún error.
+      brand: p.brand ?? p.metadata?.brand ?? p.metadata?.marca ?? null,
+      tags: p.tags ?? [],
+      rating: p.rating ?? null,
+      reviewCount: p.reviewCount ?? 0,
+      variants: (p.variants ?? []).map((v) => ({
+        id: v.id,
+        title: v.title,
+        sku: v.sku ?? undefined,
+        barcode: v.barcode ?? undefined,
+        price: v.price,
+        compareAt: v.compareAt ?? null,
+        // `null` = esa variante no lleva la cuenta unidad a unidad. NO es cero:
+        // decir cero sería afirmar que no queda, y el tema lo pintaría agotado.
+        stock: v.stock ?? null,
+        available: v.available,
+        options: v.options ?? [],
+      })),
+      categories: p.categories ?? [],
+      available: p.available,
+      metadata: p.metadata,
+    }
+  }
+
+  function mapLineItem(i, currency) {
+    return {
+      id: i.id,
+      productId: i.product_id ?? i.product?.id ?? "",
+      variantId: i.variant_id ?? i.variant?.id ?? "",
+      handle: i.product?.handle ?? i.product_handle ?? undefined,
+      title: i.product_title ?? i.title ?? "",
+      variantTitle: i.variant_title ?? i.variant?.title ?? undefined,
+      thumbnail: i.thumbnail ?? null,
+      quantity: i.quantity ?? 0,
+      unitPrice: money(i.unit_price, currency, true),
+      total: money(i.total ?? (i.unit_price ?? 0) * (i.quantity ?? 0), currency, true),
+      // Un CARGO, no mercancía: el recargo por forma de pago, por ejemplo. No
+      // tiene variante y no se envía. El tema lo necesita para no contarlo dos
+      // veces cuando además lo enseña por separado.
+      isFee: i.requires_shipping === false && !(i.variant_id ?? i.variant?.id),
+    }
+  }
+
+  function mapCart(c) {
+    if (!c) return null
+    const currency = (c.currency_code ?? c.region?.currency_code ?? "eur").toLowerCase()
+    const items = (c.items ?? []).map((i) => mapLineItem(i, currency))
+    return {
+      id: c.id,
+      items,
+      subtotal: money(c.item_subtotal ?? c.subtotal, currency, true),
+      shipping: money(c.shipping_total, currency, true),
+      discount: money(c.discount_total, currency, true),
+      tax: money(c.tax_total, currency, true),
+      total: money(c.total, currency, true),
+      itemCount: items.reduce((n, i) => n + i.quantity, 0),
+      email: c.email ?? null,
+      shippingAddress: mapAddress(c.shipping_address),
+      billingAddress: mapAddress(c.billing_address),
+      shippingMethods: (c.shipping_methods ?? []).map((m) => ({
+        id: m.shipping_option_id ?? m.id,
+        name: m.name ?? "",
+        price: money(m.amount, currency, true),
+      })),
+      regionId: c.region_id ?? c.region?.id,
+      promoCodes: (c.promotions ?? []).map((p) => p.code).filter(Boolean),
+      pago: siguientePago(c),
+    }
+  }
+
+  /**
+   * Cómo tiene que seguir el comprador para pagar.
+   *
+   * Las pasarelas se reparten en dos familias: unas mandan al comprador a su
+   * página y otras le hacen confirmar en el navegador con un secreto. Sin esto
+   * el tema no puede hacer ninguna de las dos, y el comprador se queda mirando
+   * un botón que no lleva a ningún sitio.
+   *
+   * El dato lo pone el proveedor de pago del backend en la sesión. Los métodos
+   * sin pasarela —transferencia, contrarreembolso— no ponen nada, y entonces
+   * pagar es simplemente confirmar el pedido.
+   */
+  function siguientePago(c) {
+    const sesiones = c?.payment_collection?.payment_sessions ?? []
+    // La última pendiente: si alguien cambia de método, la anterior queda ahí
+    // y usarla mandaría a pagar por una pasarela que ya descartó.
+    const sesion = [...sesiones].reverse().find((s) => s.status === "pending" || s.status === "requires_more")
+    const paso = sesion?.data?.siguiente
+    if (!paso || typeof paso !== "object" || !paso.tipo) return null
+    if (paso.tipo === "redirigir" && typeof paso.url === "string") {
+      return { tipo: "redirigir", url: paso.url, proveedor: sesion.provider_id }
+    }
+    if (paso.tipo === "confirmar_en_cliente") {
+      return {
+        tipo: "confirmar_en_cliente",
+        pasarela: String(paso.pasarela ?? ""),
+        datos: paso.datos ?? {},
+        proveedor: sesion.provider_id,
+      }
+    }
+    return null
+  }
+
+  function mapAddress(a) {
+    if (!a) return null
+    return {
+      firstName: a.first_name ?? undefined,
+      lastName: a.last_name ?? undefined,
+      company: a.company ?? undefined,
+      address1: a.address_1 ?? undefined,
+      address2: a.address_2 ?? undefined,
+      city: a.city ?? undefined,
+      province: a.province ?? undefined,
+      postalCode: a.postal_code ?? undefined,
+      countryCode: a.country_code ?? undefined,
+      phone: a.phone ?? undefined,
+    }
+  }
+
+  const aDireccionApi = (a = {}) => ({
+    first_name: a.firstName,
+    last_name: a.lastName,
+    company: a.company,
+    address_1: a.address1,
+    address_2: a.address2,
+    city: a.city,
+    province: a.province,
+    postal_code: a.postalCode,
+    country_code: a.countryCode?.toLowerCase(),
+    phone: a.phone,
+  })
+
+  function mapOrder(o) {
+    const currency = (o.currency_code ?? "eur").toLowerCase()
+    return {
+      id: o.id,
+      displayId: o.display_id,
+      email: o.email,
+      status: o.status ?? "pending",
+      items: (o.items ?? []).map((i) => mapLineItem(i, currency)),
+      subtotal: money(o.item_subtotal ?? o.subtotal, currency, true),
+      shipping: money(o.shipping_total, currency, true),
+      discount: money(o.discount_total, currency, true),
+      tax: money(o.tax_total, currency, true),
+      total: money(o.total, currency, true),
+      shippingAddress: mapAddress(o.shipping_address),
+      createdAt: o.created_at,
+    }
+  }
+
+  // ── Catálogo ────────────────────────────────────────────────────────────
+
+  async function listProducts(params = {}) {
+    if (catalogoPropio) {
+      const q = new URLSearchParams()
+      if (params.limit) q.set("limite", String(params.limit))
+      if (params.offset) q.set("desde", String(params.offset))
+      if (params.categoryId) q.set("categoria", params.categoryId)
+      // 🔴 EL TÉRMINO DE BÚSQUEDA. Sin esta línea `search()` devolvía el
+      // CATÁLOGO ENTERO para cualquier cosa que se escribiera: el buscador
+      // parecía funcionar —salían productos— y no eran los buscados. No daba
+      // ningún error; simplemente el buscador no buscaba.
+      if (params.q) q.set("q", String(params.q))
+      const r = await api(`/tienda/productos?${q}`)
+      return {
+        items: (r.productos ?? []).map(mapProductoPropio),
+        count: r.total ?? 0,
+        limit: params.limit ?? 24,
+        offset: params.offset ?? 0,
+      }
+    }
+    const r = await region()
+    const limit = params.limit ?? 24
+    const offset = params.offset ?? 0
+
+    let categoryId = params.categoryId
+    if (!categoryId && params.category) {
+      const c = await getCategoryRaw(params.category)
+      if (!c) return { items: [], count: 0, limit, offset }
+      categoryId = c.id
+    }
+
+    const qs = new URLSearchParams({ limit: String(limit), offset: String(offset), fields: PRODUCT_FIELDS })
+    if (r?.id) qs.set("region_id", r.id)
+    if (params.q) qs.set("q", params.q)
+    if (categoryId) qs.append("category_id[]", categoryId)
+    for (const id of params.ids ?? []) qs.append("id[]", id)
+    if (params.sort === "newest") qs.set("order", "-created_at")
+
+    const { products = [], count = 0 } = await api(`/store/products?${qs}`)
+    let items = products.map((p) => mapProduct(p, r?.currency_code))
+
+    // Ordenar por precio en el cliente sería mentir: solo ordenaría la página
+    // actual. Se delega en el endpoint del backend, y si no está, se avisa.
+    if (params.sort === "price_asc" || params.sort === "price_desc") {
+      const ordenados = await idsPorPrecio({ ...params, limit, offset, categoryId, region: r })
+      // Se exige la forma esperada, no solo que la respuesta no sea nula: un
+      // proxy mal configurado puede contestar 200 con cualquier otra cosa.
+      if (Array.isArray(ordenados?.ids)) {
+        const porId = new Map(items.map((p) => [p.id, p]))
+        const faltantes = ordenados.ids.filter((id) => !porId.has(id))
+        if (faltantes.length) {
+          for (const p of await getProductsByIds(faltantes)) porId.set(p.id, p)
+        }
+        items = ordenados.ids.map((id) => porId.get(id)).filter(Boolean)
+        return { items, count: ordenados.count, limit, offset }
+      }
+    }
+
+    return { items, count, limit, offset }
+  }
+
+  /**
+   * La Store API no sabe ordenar por precio (los precios viven en otro módulo y
+   * `order=variants.calculated_price` devuelve 500). El backend expone
+   * `/tienda/products-by-price`; si no está, se devuelve null y el llamador se
+   * queda con el orden por defecto en vez de romper.
+   */
+  async function idsPorPrecio({ q, categoryId, sort, limit, offset, region: r }) {
+    const qs = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset),
+      order: sort === "price_desc" ? "desc" : "asc",
+    })
+    if (q) qs.set("q", q)
+    if (categoryId) qs.set("category_id", categoryId)
+    if (r?.currency_code) qs.set("currency_code", r.currency_code)
+    try {
+      return await api(`/tienda/products-by-price?${qs}`)
+    } catch {
+      return null
+    }
+  }
+
+  async function getProduct(handle) {
+    if (catalogoPropio) {
+      try {
+        const r = await api(`/tienda/productos/${encodeURIComponent(handle)}`)
+        return r.producto ? mapProductoPropio(r.producto) : null
+      } catch (e) {
+        // Un 404 aquí es «no existe», no un fallo: el escaparate lo trata como
+        // página no encontrada, no como tienda caída.
+        if (e?.status === 404) return null
+        throw e
+      }
+    }
+    const r = await region()
+    const qs = new URLSearchParams({ handle, limit: "1", fields: PRODUCT_FIELDS })
+    if (r?.id) qs.set("region_id", r.id)
+    const { products = [] } = await api(`/store/products?${qs}`)
+    return products[0] ? mapProduct(products[0], r?.currency_code) : null
+  }
+
+  async function getProductsByIds(ids) {
+    if (!ids?.length) return []
+    const r = await region()
+    const qs = new URLSearchParams({ limit: String(ids.length), fields: PRODUCT_FIELDS })
+    if (r?.id) qs.set("region_id", r.id)
+    for (const id of ids) qs.append("id[]", id)
+    const { products = [] } = await api(`/store/products?${qs}`)
+    return products.map((p) => mapProduct(p, r?.currency_code))
+  }
+
+  async function getCategoryRaw(handle) {
+    if (catalogoPropio) {
+      const { product_categories = [] } = await api(`/tienda/categorias?handle=${encodeURIComponent(handle)}`)
+      return product_categories[0] ?? null
+    }
+    const qs = new URLSearchParams({ handle, limit: "1", fields: "id,name,handle,description,parent_category_id,metadata" })
+    const { product_categories = [] } = await api(`/store/product-categories?${qs}`)
+    return product_categories[0] ?? null
+  }
+
+  async function listCategories() {
+    if (catalogoPropio) {
+      const { product_categories = [] } = await api("/tienda/categorias")
+      // 🔴 Solo las de primer nivel: vienen planas Y anidadas a la vez, así que
+      // devolverlas todas duplicaría cada hija dentro y fuera de su madre, y un
+      // menú saldría con las subcategorías repetidas al final.
+      return product_categories.filter((c) => !c.parent_category_id).map(mapCategory)
+    }
+    const qs = new URLSearchParams({
+      limit: "200",
+      fields: "id,name,handle,description,parent_category_id,metadata,*category_children",
+    })
+    const { product_categories = [] } = await api(`/store/product-categories?${qs}`)
+    return product_categories.map(mapCategory)
+  }
+
+  async function getCategory(handle) {
+    const c = await getCategoryRaw(handle)
+    return c ? mapCategory(c) : null
+  }
+
+  /** Pedido por id, para la página de confirmación. */
+  async function getOrder(id) {
+    try {
+      const { order } = await api(`/store/orders/${id}`)
+      return mapOrder(order)
+    } catch (e) {
+      if (e.status === 404 || e.status === 401) return null
+      throw e
+    }
+  }
+
+  async function search(q, limit = 24) {
+    const { items } = await listProducts({ q, limit })
+    return items
+  }
+
+  // ── Carrito ─────────────────────────────────────────────────────────────
+
+  const getCart = async (id) => {
+    try {
+      const { cart } = await api(`/store/carts/${id}?fields=${encodeURIComponent(CART_FIELDS)}`)
+      return mapCart(cart)
+    } catch (e) {
+      // Un carrito caducado o completado es un caso normal, no un fallo: el
+      // tema debe crear uno nuevo, no enseñar una pantalla de error.
+      if (e.status === 404) return null
+      throw e
+    }
+  }
+
+  const cart = {
+    get: getCart,
+    async create() {
+      const r = await region()
+      const { cart } = await api("/store/carts", { method: "POST", body: r?.id ? { region_id: r.id } : {} })
+      return mapCart(cart)
+    },
+    async addItem(cartId, variantId, quantity) {
+      const { cart } = await api(`/store/carts/${cartId}/line-items`, {
+        method: "POST",
+        body: { variant_id: variantId, quantity },
+      })
+      return mapCart(cart)
+    },
+    async updateItem(cartId, lineId, quantity) {
+      if (quantity <= 0) return cart.removeItem(cartId, lineId)
+      const { cart: c } = await api(`/store/carts/${cartId}/line-items/${lineId}`, {
+        method: "POST",
+        body: { quantity },
+      })
+      return mapCart(c)
+    },
+    async removeItem(cartId, lineId) {
+      await api(`/store/carts/${cartId}/line-items/${lineId}`, { method: "DELETE" })
+      return getCart(cartId)
+    },
+    async applyPromo(cartId, code) {
+      const actual = await getCart(cartId)
+      const { cart } = await api(`/store/carts/${cartId}`, {
+        method: "POST",
+        body: { promo_codes: [...new Set([...(actual?.promoCodes ?? []), code])] },
+      })
+      return mapCart(cart)
+    },
+    async removePromo(cartId, code) {
+      const actual = await getCart(cartId)
+      const { cart } = await api(`/store/carts/${cartId}`, {
+        method: "POST",
+        body: { promo_codes: (actual?.promoCodes ?? []).filter((c) => c !== code) },
+      })
+      return mapCart(cart)
+    },
+  }
+
+  // ── Checkout ────────────────────────────────────────────────────────────
+
+  const checkout = {
+    async setEmail(cartId, email) {
+      const { cart } = await api(`/store/carts/${cartId}`, { method: "POST", body: { email } })
+      return mapCart(cart)
+    },
+    async setAddresses(cartId, shipping, billing) {
+      const { cart } = await api(`/store/carts/${cartId}`, {
+        method: "POST",
+        body: {
+          shipping_address: aDireccionApi(shipping),
+          billing_address: aDireccionApi(billing ?? shipping),
+        },
+      })
+      return mapCart(cart)
+    },
+    async listShippingOptions(cartId) {
+      const { shipping_options = [] } = await api(`/store/shipping-options?cart_id=${cartId}`)
+      return shipping_options.map((o) => ({
+        id: o.id,
+        name: o.name,
+        price: money(o.amount ?? o.calculated_price?.calculated_amount, o.calculated_price?.currency_code ?? "eur", true),
+        priceCalculated: o.price_type === "calculated",
+        description: o.data?.description ?? null,
+      }))
+    },
+    /**
+     * De cuántos sitios sale el carrito.
+     *
+     * Devuelve `null` si el backend no tiene marketplace montado: la ruta no
+     * existe y responde 404. El tema lo interpreta como «una tienda normal» y
+     * sigue con el selector de envío de siempre, sin enterarse de nada.
+     */
+    async listShippingGroups(cartId) {
+      try {
+        return await api(`/tienda/marketplace/envios?cart_id=${cartId}`)
+      } catch {
+        return null
+      }
+    },
+    /**
+     * Los portes de todos los grupos, en UNA llamada.
+     *
+     * Mandarlos de uno en uno no vale: el segundo borra al primero.
+     * Lo impone la ruta del backend, que rechaza un conjunto incompleto en vez
+     * de cobrar de menos calladamente.
+     */
+    async setShippingMethods(cartId, elecciones) {
+      await api("/tienda/marketplace/envios", {
+        method: "POST",
+        body: {
+          cart_id: cartId,
+          elecciones: elecciones.map((e) => ({ grupo: e.grupo, option_id: e.optionId })),
+        },
+      })
+    },
+    async setShippingMethod(cartId, optionId) {
+      const { cart } = await api(`/store/carts/${cartId}/shipping-methods`, {
+        method: "POST",
+        body: { option_id: optionId },
+      })
+      return mapCart(cart)
+    },
+    async listPaymentMethods(cartId) {
+      const c = await getCart(cartId)
+      const r = c?.regionId ?? (await region())?.id
+      if (!r) return []
+      const { payment_providers = [] } = await api(`/store/payment-providers?region_id=${r}`)
+      // El recargo configurado en la tienda, para poder enseñarlo junto al
+      // método. Si la ruta no existe (backend anterior), simplemente no hay.
+      let cfg = {}
+      try {
+        const r2 = await api("/payment-config")
+        cfg = r2?.methods ?? {}
+      } catch {}
+      return payment_providers.map((p) => ({
+        id: p.id,
+        provider: p.id,
+        name: cfg[p.id]?.name || p.id,
+        ...(cfg[p.id]?.surcharge ? { surcharge: Number(cfg[p.id].surcharge) } : {}),
+      }))
+    },
+    async selectPaymentMethod(cartId, provider, datos) {
+      // El recargo de la forma de pago, ANTES de crear el cobro: el importe a
+      // cobrar sale del total del carrito. Al revés, el recargo entraría en el
+      // pedido pero no en lo que se le cobra al cliente.
+      //
+      // Si el backend no tiene la ruta (versión anterior), no hay recargos y se
+      // sigue igual que siempre.
+      try {
+        await api("/tienda/pagos/recargo", {
+          method: "POST",
+          body: { cart_id: cartId, provider_id: provider },
+        })
+      } catch {}
+
+      const { payment_collection } = await api("/store/payment-collections", {
+        method: "POST",
+        body: { cart_id: cartId },
+      })
+      await api(`/store/payment-collections/${payment_collection.id}/payment-sessions`, {
+        method: "POST",
+        // `data` lo lee el proveedor de pago del backend. Sirve para decirle
+        // cosas que solo sabe el escaparate — por ejemplo a qué RUTA debe
+        // volver el comprador, que cambia con el idioma de la página.
+        body: { provider_id: provider, ...(datos ? { data: datos } : {}) },
+      })
+      return getCart(cartId)
+    },
+    async complete(cartId) {
+      const r = await api(`/store/carts/${cartId}/complete`, { method: "POST" })
+      // El backend contesta con el pedido o, si algo falló al cobrar, con el carrito
+      // intacto y el motivo. Las dos son respuestas 200: el tema tiene que
+      // mirar el tipo, no el código HTTP.
+      if (r?.type === "order" && r.order) return { order: mapOrder(r.order) }
+      return { cart: mapCart(r?.cart), error: r?.error?.message ?? "No se pudo completar el pedido" }
+    },
+  }
+
+  // ── Cuenta y contenido ──────────────────────────────────────────────────
+
+  const account = {
+    async login(email, password) {
+      const r = await api("/auth/customer/emailpass", { method: "POST", body: { email, password } })
+      return { token: r.token }
+    },
+    async register({ email, password, firstName, lastName }) {
+      const { token } = await api("/auth/customer/emailpass/register", {
+        method: "POST",
+        body: { email, password },
+      })
+      const { customer } = await api("/store/customers", {
+        method: "POST",
+        token,
+        body: { email, first_name: firstName, last_name: lastName },
+      })
+      return { id: customer.id, email: customer.email, firstName: customer.first_name, lastName: customer.last_name }
+    },
+    async me(token) {
+      try {
+        const { customer } = await api("/store/customers/me", { token })
+        return { id: customer.id, email: customer.email, firstName: customer.first_name, lastName: customer.last_name, phone: customer.phone }
+      } catch (e) {
+        if (e.status === 401) return null
+        throw e
+      }
+    },
+    async orders(token) {
+      const { orders = [] } = await api("/store/orders", { token })
+      return orders.map(mapOrder)
+    },
+  }
+
+  const content = {
+    async listPosts(limit = 10) {
+      try {
+        const { posts = [] } = await api(`/tienda/posts?limit=${limit}`)
+        return posts.map(mapPost)
+      } catch {
+        return []
+      }
+    },
+    async getPost(handle) {
+      try {
+        const { posts = [] } = await api(`/tienda/posts?handle=${encodeURIComponent(handle)}`)
+        return posts[0] ? mapPost(posts[0]) : null
+      } catch {
+        return null
+      }
+    },
+    async listPages() {
+      try {
+        const { paginas = [] } = await api(`/tienda/paginas`)
+        return paginas.map(mapPagina)
+      } catch {
+        // Sin páginas el pie se pinta sin enlaces, que es peor que con ellos y
+        // muchísimo mejor que una tienda que no carga.
+        return []
+      }
+    },
+    async getPage(handle) {
+      try {
+        const { pagina } = await api(`/tienda/paginas/${encodeURIComponent(handle)}`)
+        return pagina ? mapPagina(pagina) : null
+      } catch {
+        // Un borrador o una que no existe dan 404, y eso es «no hay página»,
+        // no un error de la tienda.
+        return null
+      }
+    },
+  }
+
+  const mapPost = (p) => ({
+    id: p.id,
+    handle: p.handle,
+    title: p.title,
+    excerpt: p.excerpt ?? null,
+    content: p.content ?? p.body ?? null,
+    image: p.image ?? p.thumbnail ?? null,
+    publishedAt: p.published_at ?? p.created_at ?? null,
+    tags: p.tags ?? [],
+  })
+
+  const mapPagina = (p) => ({
+    handle: p.handle,
+    title: p.titulo ?? p.title ?? p.handle,
+    content: p.contenido ?? p.content ?? null,
+    order: p.orden ?? p.order ?? 0,
+    seoTitle: p.seo_titulo ?? p.seoTitle ?? null,
+    seoDescription: p.seo_descripcion ?? p.seoDescription ?? null,
+  })
+
+  return {
+    adapter: "pcreative",
+    listProducts,
+    getProduct,
+    getProductsByIds,
+    listCategories,
+    getCategory,
+    search,
+    getOrder,
+    cart,
+    checkout,
+    account,
+    content,
+  }
+}