@pcreative/commerce-contract 1.3.6 → 1.3.10

package/README.es.md

@@ -90,6 +90,78 @@ const licencias = await commerce.getLicenses(id, access)             // 403 sin
 const dado = await commerce.requestOrderAccess(id, email)            // { access, days } | null
 ```
 
+**Agotada y reservada no son lo mismo.** Mientras alguien paga, la tienda le
+guarda unos minutos lo que lleva. Esas unidades salen en `Variant.held` y ya
+están descontadas de `stock`; el carrito que paga lleva `holdUntil`. Con `stock`
+0 y `held` mayor que 0 la pieza puede volver en unos minutos.
+
+```js
+import { isVariantHeld, holdSecondsLeft } from "@pcreative/commerce-contract"
+isVariantHeld(variante)    // true: «otra persona la está pagando»
+holdSecondsLeft(carrito)   // segundos que quedan, o null si no retiene
+```
+
+**Lanzamientos.** Un producto con fecha de salida llega `sealed: true` hasta
+entonces, con `available: false` en el producto y en todas sus variantes, así
+que no entra en un carrito (la tienda contesta 400). Trae `releaseAt` (ISO, en
+UTC), `releaseAtLocal` (`AAAA-MM-DDTHH:mm` en la zona de la tienda) y
+`releaseTimeZone`. El precio se sigue viendo. `releases.notify` (que no envía
+nada si `consent.accepted` no es exactamente `true`) pide un aviso
+por correo (del lanzamiento, o de reposición de una variante agotada con
+`variantId`): manda un correo de confirmación y contesta siempre
+`{ status: "pendiente" }`, estuviera o no ya apuntada esa dirección. Falla con
+409 `avisos.ya_a_la_venta` si no hay nada que esperar, con 400 sin
+consentimiento y con 429 (`rate_limited`) al pasar los límites. `consent.info`
+(opcional, hasta 4000 caracteres) es el texto plano de la información básica
+que se vio junto a la casilla; se guarda con la prueba como `consentInfo`. El correo
+enlaza a `/avisos/confirmar?token=` y `/avisos/baja?token=` del escaparate, que
+llaman a `releases.confirm` (`{ confirmed: false }` si el enlace caducó o ya se
+usó) y a `releases.unsubscribe` desde el servidor, tras un clic, nunca con un
+GET que pueda disparar un escáner de enlaces.
+
+```js
+await commerce.releases.notify({ productId, variantId, email, consent: { accepted: true, text, version, info }, locale })
+await commerce.releases.confirm(token)       // { confirmed: boolean }
+await commerce.releases.unsubscribe(token)   // { unsubscribed: true, alreadyWas: boolean }
+```
+
+**Ediciones numeradas.** Una variante que se vende como edición numerada lleva
+`Variant.edition: { size, available }`: cuántos ejemplares hay y cuántos
+números quedan libres (coincide con `stock`). En lo demás es `null`. El
+carrito no lleva número: la tienda los asigna al crear el pedido, empezando por
+el más bajo libre. Cada línea del pedido trae entonces `editionNumber` (el más
+bajo), `editionNumbers` (todos, ordenados) y `editionSize`, todo `null` si la
+línea no es una edición, y `editionLabel`: lo mismo ya escrito en el idioma de
+la petición (también en `account.orders`).
+
+```js
+const v = producto.variants[0]
+if (v.edition) `Edición de ${v.edition.size} · quedan ${v.edition.available}`
+if (linea.editionNumber) `Edición nº ${linea.editionNumbers.join(", ")}/${linea.editionSize}`
+```
+
+**Un tema que llama a la tienda desde su servidor le pasa la IP del
+comprador**, o todos los compradores comparten el límite del tema. El adaptador
+la manda en `X-Forwarded-For` solo en las escrituras y nunca desde el
+navegador, y solo si es una única dirección válida. `clientIpFromHeaders` la
+saca por la derecha de la cabecera que llega, saltándose tus proxies de
+confianza, así que el comprador no la puede elegir. Igual con
+`clientUserAgent`: el navegador del comprador, que va en las escrituras en
+`X-Pcc-Client-User-Agent` (sin caracteres de control, 512 como mucho) como
+prueba del consentimiento; la tienda solo lo acepta de un proxy de confianza.
+
+```js
+const commerce = createCommerce({
+  baseUrl: process.env.COMMERCE_URL,
+  clientIp: async () => clientIpFromHeaders(await headers(), {
+    trustedProxies: process.env.PCC_PROXIES_DE_CONFIANZA,
+  }),
+})
+```
+
+Un 429 trae `err.retryAfter` en segundos, y
+`tooManyAttemptsMessage(err, "es")` da el texto que hay que enseñar.
+
 ## Escribir otro adaptador
 
 Implementa la interfaz `CommerceClient` de [`src/index.d.ts`](src/index.d.ts) y
@@ -100,8 +172,9 @@ import { assertCommerceClient } from "@pcreative/commerce-contract"
 const faltan = assertCommerceClient(miCliente)   // [] si cumple
 ```
 
-`account`, `content`, `getAuthor` y `support` son opcionales: un backend puede
-no tener cuentas de cliente, ni blog, ni mercado de autores.
+`account` (con su libreta `account.addresses`), `wishlist`, `content`,
+`getAuthor` y `support` son opcionales: un backend puede no tener cuentas de
+cliente, ni lista de deseos, ni blog, ni mercado de autores.
 
 ## Idioma de los mensajes
 

package/README.md

@@ -89,6 +89,76 @@ const licencias = await commerce.getLicenses(id, access)             // 403 with
 const dado = await commerce.requestOrderAccess(id, email)            // { access, days } | null
 ```
 
+**Sold out and held are not the same.** While someone pays, the store holds
+what their cart carries for a few minutes. Those units come in `Variant.held`
+and are already taken out of `stock`; the cart that is paying carries
+`holdUntil`. With `stock` 0 and `held` above 0 the item may come back soon.
+
+```js
+import { isVariantHeld, holdSecondsLeft } from "@pcreative/commerce-contract"
+isVariantHeld(variant)     // true: "someone else is paying for it"
+holdSecondsLeft(cart)      // seconds left, or null if it holds nothing
+```
+
+**Releases.** A product with a release date comes `sealed: true` until then,
+with `available: false` on the product and on every variant, so it cannot be
+added to a cart (the store answers 400). It carries `releaseAt` (ISO, UTC),
+`releaseAtLocal` (`YYYY-MM-DDTHH:mm` in the store's time zone) and
+`releaseTimeZone`. The price stays visible. `releases.notify` (which sends
+nothing unless `consent.accepted` is literally `true`) asks for an email alert (launch, or back in stock for a sold-out variant with
+`variantId`): it sends a confirmation email and always answers
+`{ status: "pendiente" }`, whether or not the address was already there. It
+fails with 409 `avisos.ya_a_la_venta` when there is nothing to wait for, 400
+without consent and 429 (`rate_limited`) when the limits kick in. `consent.info`
+(optional, up to 4000 characters) is the plain text of the privacy notice shown
+next to the box; it is stored with the proof as `consentInfo`. The email
+links to `/avisos/confirmar?token=` and `/avisos/baja?token=` on the
+storefront, which call `releases.confirm` (`{ confirmed: false }` for an
+expired or used link) and `releases.unsubscribe` from the server, after a
+click, never on a plain GET a link scanner could trigger.
+
+```js
+await commerce.releases.notify({ productId, variantId, email, consent: { accepted: true, text, version, info }, locale })
+await commerce.releases.confirm(token)       // { confirmed: boolean }
+await commerce.releases.unsubscribe(token)   // { unsubscribed: true, alreadyWas: boolean }
+```
+
+**Numbered editions.** A variant sold as a numbered edition carries
+`Variant.edition: { size, available }`: how many copies there are and how many
+numbers are still free (it matches `stock`). It is `null` for anything else.
+The cart carries no number: the store assigns them when the order is created,
+lowest free first. Each order line then carries `editionNumber` (the lowest),
+`editionNumbers` (all of them, sorted) and `editionSize`, all `null` when the
+line is not an edition, plus `editionLabel`: the same, already written in the
+language of the request (also in `account.orders`).
+
+```js
+const v = product.variants[0]
+if (v.edition) `Edition of ${v.edition.size} · ${v.edition.available} left`
+if (line.editionNumber) `Edition no. ${line.editionNumbers.join(", ")}/${line.editionSize}`
+```
+
+**A theme that calls the store from its server passes the buyer's IP**, or
+every buyer shares the theme's rate limit. The adapter sends it in
+`X-Forwarded-For` only on writes and never from the browser, and only if it is
+a single valid address. `clientIpFromHeaders` picks it from the right of the
+incoming header, skipping your trusted proxies, so the buyer cannot choose it.
+The same goes for `clientUserAgent`: the buyer's browser, sent on writes in
+`X-Pcc-Client-User-Agent` (no control characters, 512 at most) as proof of
+consent; the store only accepts it from a trusted proxy.
+
+```js
+const commerce = createCommerce({
+  baseUrl: process.env.COMMERCE_URL,
+  clientIp: async () => clientIpFromHeaders(await headers(), {
+    trustedProxies: process.env.PCC_PROXIES_DE_CONFIANZA,
+  }),
+})
+```
+
+A 429 comes with `err.retryAfter` in seconds, and
+`tooManyAttemptsMessage(err, "en")` gives the text to show.
+
 ## Writing another adapter
 
 Implement the `CommerceClient` interface from [`src/index.d.ts`](src/index.d.ts)
@@ -99,8 +169,9 @@ import { assertCommerceClient } from "@pcreative/commerce-contract"
 const faltan = assertCommerceClient(miCliente)   // [] if it complies
 ```
 
-`account`, `content`, `getAuthor` and `support` are optional: a backend may have
-no customer accounts, no blog and no author marketplace.
+`account` (with its `account.addresses` book), `wishlist`, `content`,
+`getAuthor` and `support` are optional: a backend may have no customer
+accounts, no wishlist, no blog and no author marketplace.
 
 ## Language of the messages
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pcreative/commerce-contract",
-  "version": "1.3.6",
+  "version": "1.3.10",
   "description": "Commerce data contract: the types a theme consumes and the adapters that resolve them. No dependencies and no backend SDK.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/adapters/api.d.ts

@@ -7,6 +7,14 @@ export interface OpcionesCommerce {
   locale?: string
   fetch?: typeof globalThis.fetch
   requestInit?: RequestInit
+  /**
+   * La IP del comprador, para un tema que llama al comercio desde su servidor.
+   * Va en `X-Forwarded-For` solo en las escrituras y solo fuera del navegador,
+   * y tiene que ser una única dirección válida: cualquier otra cosa se descarta.
+   * Sácala con `clientIpFromHeaders`, nunca copiando la cabecera que llega.
+   */
+  clientIp?: string | null | (() => string | null | undefined | Promise<string | null | undefined>)
+  clientUserAgent?: string | null | (() => string | null | undefined | Promise<string | null | undefined>)
 }
 
 export declare function createCommerce(opciones: OpcionesCommerce): CommerceClient

package/src/adapters/api.js

@@ -1,4 +1,5 @@
-import { money } from "../index.js"
+import { money, parseRetryAfter } from "../index.js"
+import { normalizeIp } from "../ip.js"
 import { msg } from "../mensajes.js"
 
 /** La cabecera con la que se demuestra que un pedido de invitado es tuyo. */
@@ -20,6 +21,9 @@ function aHilo(h) {
     status: h.estado,
     covered: h.con_soporte !== false,
     solved: h.resuelto ?? null,
+    mediation: h.mediacion_en
+      ? { requestedAt: h.mediacion_en, resolvedAt: h.mediacion_resuelta_en ?? null }
+      : null,
     messages: (h.mensajes ?? []).map((m) => ({
       from: DE_QUIEN[m.de] ?? "store",
       text: m.texto,
@@ -30,6 +34,34 @@ function aHilo(h) {
   }
 }
 
+const CODIGOS_DE_SALDO = new Set([
+  "balance.invalid",
+  "balance.expired",
+  "balance.disabled",
+  "balance.currency",
+  "balance.empty",
+  "rate_limited",
+])
+
+const CLAVES_DE_SALDO = {
+  "saldo.no_existe": "balance.invalid",
+  "saldo.caducado": "balance.expired",
+  "saldo.desactivado": "balance.disabled",
+  "saldo.otra_moneda": "balance.currency",
+  "saldo.sin_saldo": "balance.empty",
+}
+
+function codigoDeSaldo(motivo, codigo) {
+  if (typeof codigo === "string") {
+    if (CODIGOS_DE_SALDO.has(codigo)) return codigo
+    if (CLAVES_DE_SALDO[codigo]) return CLAVES_DE_SALDO[codigo]
+  }
+  const texto = String(motivo ?? "")
+  if (/caduc|expir/i.test(texto)) return "balance.expired"
+  if (/saldo|balance|vac[ií]a|empty/i.test(texto)) return "balance.empty"
+  return "balance.invalid"
+}
+
 export function createCommerce({
   baseUrl,
   publishableKey,
@@ -37,10 +69,27 @@ export function createCommerce({
   locale,
   fetch: fetchImpl,
   requestInit = {},
+  clientIp,
+  clientUserAgent,
 } = {}) {
   if (!baseUrl) throw new Error(msg("faltaBaseUrl"))
   const f = fetchImpl ?? globalThis.fetch
   const raiz = String(baseUrl).replace(/\/$/, "")
+  const enNavegador = typeof window !== "undefined" && typeof document !== "undefined"
+
+  async function ipDelComprador(method) {
+    if (!clientIp || enNavegador || method === "GET" || method === "HEAD") return null
+    const valor = typeof clientIp === "function" ? await clientIp() : clientIp
+    return normalizeIp(valor)
+  }
+
+  async function navegadorDelComprador(method) {
+    if (!clientUserAgent || enNavegador || method === "GET" || method === "HEAD") return null
+    const valor = typeof clientUserAgent === "function" ? await clientUserAgent() : clientUserAgent
+    if (typeof valor !== "string") return null
+    const limpio = valor.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim().slice(0, 512)
+    return limpio || null
+  }
 
   async function api(ruta, { method = "GET", body, token, acceso, ...extra } = {}) {
     const cabeceras = { accept: "application/json", ...(extra.headers ?? {}) }
@@ -52,6 +101,10 @@ export function createCommerce({
     // nunca en la direccion: una direccion acaba en el historial, en los
     // registros del servidor y en el `Referer` de cualquier enlace que se pulse.
     if (acceso) cabeceras[CABECERA_DE_ACCESO] = acceso
+    const ip = await ipDelComprador(method)
+    if (ip) cabeceras["x-forwarded-for"] = ip
+    const navegador = await navegadorDelComprador(method)
+    if (navegador) cabeceras["x-pcc-client-user-agent"] = navegador
 
     const res = await f(`${raiz}${ruta}`, {
       method,
@@ -63,14 +116,22 @@ export function createCommerce({
 
     if (!res.ok) {
       let detalle = ""
+      let codigoDelCuerpo = ""
       try {
-        detalle = (await res.json())?.message ?? ""
+        const cuerpo = await res.json()
+        detalle = cuerpo?.message ?? ""
+        codigoDelCuerpo = typeof cuerpo?.code === "string" ? cuerpo.code : typeof cuerpo?.codigo === "string" ? cuerpo.codigo : ""
       } catch {
         detalle = ""
       }
       const err = new Error(`${method} ${ruta} → ${res.status}${detalle ? `: ${detalle}` : ""}`)
       err.status = res.status
       err.detalle = detalle
+      if (codigoDelCuerpo) err.code = codigoDelCuerpo
+      if (res.status === 429) {
+        err.code = codigoDelCuerpo || "rate_limited"
+        err.retryAfter = parseRetryAfter(res.headers?.get?.("retry-after"))
+      }
       throw err
     }
     return res.status === 204 ? null : res.json()
@@ -105,6 +166,22 @@ export function createCommerce({
     }
   }
 
+  function mapEdicion(e) {
+    const size = Number(e?.size)
+    const available = Number(e?.available)
+    if (!Number.isInteger(size) || size <= 0 || !Number.isInteger(available) || available < 0) return null
+    return { size, available: Math.min(available, size) }
+  }
+
+  function lineaDePedido(l) {
+    const numeros = Array.isArray(l?.editionNumbers) ? l.editionNumbers.map(Number).filter((n) => Number.isInteger(n) && n > 0).sort((a, b) => a - b) : null
+    const suelto = Number.isInteger(Number(l?.editionNumber)) && Number(l.editionNumber) > 0 ? Number(l.editionNumber) : null
+    const numero = numeros?.length ? numeros[0] : suelto
+    const tamano = Number.isInteger(Number(l?.editionSize)) && Number(l.editionSize) > 0 ? Number(l.editionSize) : null
+    const etiqueta = typeof l?.editionLabel === "string" && l.editionLabel.trim() ? l.editionLabel.trim() : null
+    return { ...l, editionNumber: numero, editionNumbers: numeros?.length ? numeros : null, editionSize: tamano, editionLabel: etiqueta }
+  }
+
   function mapProducto(p) {
     return {
       id: p.id,
@@ -128,6 +205,8 @@ export function createCommerce({
         price: v.price,
         compareAt: v.compareAt ?? null,
         stock: v.stock ?? null,
+        held: v.held ?? null,
+        edition: mapEdicion(v.edition),
         available: v.available,
         options: v.options ?? [],
         weight: v.weight ?? null,
@@ -147,6 +226,10 @@ export function createCommerce({
       quantityRules: p.quantityRules ?? null,
       customization: p.customization ?? [],
       available: p.available,
+      releaseAt: typeof p.releaseAt === "string" ? p.releaseAt : null,
+      releaseAtLocal: typeof p.releaseAtLocal === "string" ? p.releaseAtLocal : null,
+      releaseTimeZone: typeof p.releaseTimeZone === "string" ? p.releaseTimeZone : null,
+      sealed: p.sealed === true,
       metadata: p.metadata ?? {},
     }
   }
@@ -217,15 +300,61 @@ export function createCommerce({
       billingAddress: mapAddress(c.billingAddress),
       shippingMethods: c.shippingMethods ?? [],
       regionId: c.regionId,
+      balanceApplied: c.balanceApplied ?? money(0, c.total?.currency ?? c.currency ?? "eur", c.total?.taxIncluded),
+      amountDue: c.amountDue ?? c.total,
+      balances: Array.isArray(c.balances) ? c.balances.map(mapSaldo).filter(Boolean) : [],
+      ...(c.includedTax && typeof c.includedTax === "object" ? { includedTax: c.includedTax } : {}),
+      ...(typeof c.pricesIncludeTax === "boolean" ? { pricesIncludeTax: c.pricesIncludeTax } : {}),
       promoCodes: c.promoCodes ?? [],
       hasDigital: Boolean(c.hasDigital),
       digitalConsent: c.digitalConsent ?? null,
       pago: c.pago ?? null,
       vatNumber: c.vatNumber ?? null,
       taxExempt: c.taxExempt ?? null,
+      holdUntil: c.holdUntil ?? null,
     }
   }
 
+  function mapSaldo(s) {
+    if (!s || typeof s !== "object" || !s.id) return null
+    const final = s.last4 ?? s.final ?? null
+    const disponible = s.available ?? (s.disponible != null ? money(s.disponible, s.moneda ?? "eur") : null)
+    return {
+      id: String(s.id),
+      last4: final ? String(final).slice(-4) : null,
+      applied: s.applied && typeof s.applied === "object" ? s.applied : null,
+      available: disponible && typeof disponible === "object" ? disponible : null,
+    }
+  }
+
+  function conSaldos(cart, ids, nuevo) {
+    if (!cart) return cart
+    const porId = new Map(cart.balances.map((b) => [b.id, b]))
+    if (nuevo) porId.set(nuevo.id, { ...nuevo, ...(porId.get(nuevo.id) ?? {}), last4: porId.get(nuevo.id)?.last4 ?? nuevo.last4 })
+    const orden = Array.isArray(ids) && ids.length ? ids.map(String) : [...porId.keys()]
+    const balances = orden.map((id) => porId.get(id) ?? { id, last4: null, applied: null, available: null })
+    return { ...cart, balances }
+  }
+
+  function mapSavedAddress(a) {
+    return {
+      ...mapAddress(a),
+      id: a.id,
+      name: a.address_name ?? a.name ?? null,
+      isDefaultShipping: Boolean(a.is_default_shipping ?? a.isDefaultShipping),
+      isDefaultBilling: Boolean(a.is_default_billing ?? a.isDefaultBilling),
+    }
+  }
+
+  const aDireccionGuardadaApi = (a = {}) => ({
+    ...aDireccionApi(a),
+    ...(a.name !== undefined ? { address_name: a.name } : {}),
+    ...(a.isDefaultShipping !== undefined ? { is_default_shipping: Boolean(a.isDefaultShipping) } : {}),
+    ...(a.isDefaultBilling !== undefined ? { is_default_billing: Boolean(a.isDefaultBilling) } : {}),
+  })
+
+  const listaDeDeseos = (r) => (Array.isArray(r?.wishlist) ? r.wishlist.filter((x) => typeof x === "string") : [])
+
   async function listProducts(params = {}) {
     const limit = params.limit ?? 24
     const offset = params.offset ?? 0
@@ -234,6 +363,10 @@ export function createCommerce({
     if (params.category) qs.set("categoria_handle", params.category)
     if (params.categoryId) qs.set("categoria", params.categoryId)
     if (params.type) qs.set("tipo", params.type)
+    for (const [clave, valores] of Object.entries(params.attributes ?? {})) {
+      const lista = (Array.isArray(valores) ? valores : [valores]).map(String).filter(Boolean)
+      if (lista.length) qs.set(`attr.${clave}`, lista.join(","))
+    }
     if (params.ids?.length) qs.set("ids", params.ids.join(","))
     if (ORDEN_DEL_CONTRATO[params.sort]) qs.set("orden", ORDEN_DEL_CONTRATO[params.sort])
     const r = await api(`/tienda/productos?${qs}`)
@@ -271,6 +404,7 @@ export function createCommerce({
     try {
       const { order, acceso_requerido } = await api(`/tienda/pedidos/${encodeURIComponent(id)}`, { acceso })
       if (!order) return null
+      if (Array.isArray(order.items)) order.items = order.items.map(lineaDePedido)
       // Sin prueba, el comercio contesta el pedido recortado: sin correo ni
       // direccion. `partial` es lo que le dice al tema que pida el correo en vez
       // de pintar huecos vacios como si el pedido no tuviera datos.
@@ -385,6 +519,29 @@ export function createCommerce({
       const { cart: c } = await api(rutaCarrito(cartId, `/cupon/${encodeURIComponent(code)}`), { method: "DELETE" })
       return mapCart(c)
     },
+    async applyBalance(cartId, code) {
+      let r
+      try {
+        r = await api(rutaCarrito(cartId, "/saldo"), { method: "POST", body: { codigo: code } })
+      } catch (e) {
+        if (e?.status === 400 && !e.code) e.code = codigoDeSaldo(e.detalle)
+        throw e
+      }
+      if (!r?.aplicado) {
+        const motivo = r?.motivo ?? ""
+        const err = new Error(motivo || msg("codigoNoValido"))
+        err.status = 400
+        err.detalle = motivo
+        err.code = codigoDeSaldo(motivo, r?.code ?? r?.codigo)
+        throw err
+      }
+      return conSaldos(mapCart(r.cart), r.saldos, mapSaldo(r.saldo))
+    },
+    async removeBalance(cartId, balanceId) {
+      const { cart: c } = await api(rutaCarrito(cartId, `/saldo/${encodeURIComponent(balanceId)}`), { method: "DELETE" })
+      const carrito = mapCart(c)
+      return carrito ? { ...carrito, balances: carrito.balances.filter((b) => b.id !== balanceId) } : carrito
+    },
   }
 
   const checkout = {
@@ -530,7 +687,7 @@ export function createCommerce({
     },
     async orders(token) {
       const { orders = [] } = await api("/tienda/cuenta/pedidos", { token })
-      return orders
+      return orders.map((o) => (Array.isArray(o?.items) ? { ...o, items: o.items.map(lineaDePedido) } : o))
     },
     async licenses(token) {
       const { licencias = [] } = await api("/tienda/cuenta/licencias", { token })
@@ -553,6 +710,52 @@ export function createCommerce({
         throw e
       }
     },
+    addresses: {
+      async list(token) {
+        try {
+          const { direcciones = [] } = await api("/tienda/cuenta/direcciones", { token })
+          return direcciones.map(mapSavedAddress)
+        } catch (e) {
+          if (e.status === 404) return []
+          throw e
+        }
+      },
+      async create(token, direccion) {
+        const { direccion: d } = await api("/tienda/cuenta/direcciones", {
+          method: "POST",
+          token,
+          body: aDireccionGuardadaApi(direccion),
+        })
+        return mapSavedAddress(d)
+      },
+      async update(token, id, direccion) {
+        const { direccion: d } = await api(`/tienda/cuenta/direcciones/${encodeURIComponent(id)}`, {
+          method: "POST",
+          token,
+          body: aDireccionGuardadaApi(direccion),
+        })
+        return mapSavedAddress(d)
+      },
+      async remove(token, id) {
+        await api(`/tienda/cuenta/direcciones/${encodeURIComponent(id)}`, { method: "DELETE", token })
+      },
+    },
+  }
+
+  const wishlist = {
+    async list(token) {
+      return listaDeDeseos(await api("/tienda/wishlist", { token }))
+    },
+    async add(token, productIds) {
+      const ids = [...new Set((Array.isArray(productIds) ? productIds : [productIds]).map(String).filter(Boolean))]
+      if (!ids.length) return wishlist.list(token)
+      const body = ids.length === 1 ? { product_id: ids[0] } : { wishlist: ids }
+      return listaDeDeseos(await api("/tienda/wishlist", { method: "POST", token, body }))
+    },
+    async remove(token, productId) {
+      const qs = new URLSearchParams({ product_id: String(productId) })
+      return listaDeDeseos(await api(`/tienda/wishlist?${qs}`, { method: "DELETE", token }))
+    },
   }
 
   const mapPost = (p) => ({
@@ -678,6 +881,44 @@ export function createCommerce({
       )
       return codigo ?? null
     },
+    releases: {
+      async notify({ productId, variantId = null, email, consent, locale } = {}) {
+        if (consent?.accepted !== true || !consent?.text || !consent?.version) {
+          const err = new Error("POST /tienda/avisos: sin consentimiento expreso no se envía")
+          err.status = 400
+          err.code = "avisos.falta_consentimiento"
+          err.detalle = ""
+          throw err
+        }
+        await api("/tienda/avisos", {
+          method: "POST",
+          body: {
+            producto_id: productId,
+            variante_id: variantId ?? null,
+            email,
+            consentimiento: true,
+            texto: consent?.text,
+            version: consent?.version,
+            ...(typeof consent?.info === "string" && consent.info.trim() ? { consentInfo: consent.info.trim().slice(0, 4000) } : {}),
+            ...(locale ? { idioma: locale } : {}),
+          },
+        })
+        return { status: "pendiente" }
+      },
+      async confirm(token) {
+        try {
+          await api("/tienda/avisos/confirmar", { method: "POST", body: { token } })
+          return { confirmed: true }
+        } catch (e) {
+          if (e.status === 400) return { confirmed: false }
+          throw e
+        }
+      },
+      async unsubscribe(token) {
+        const r = await api("/tienda/avisos/baja", { method: "POST", body: { token } })
+        return { unsubscribed: true, alreadyWas: Boolean(r?.yaEstaba) }
+      },
+    },
     newsletter: {
       async subscribe(email, consent = {}) {
         await api("/tienda/boletin", {
@@ -709,14 +950,14 @@ export function createCommerce({
       },
     },
     async applyAsAuthor(a) {
-      const vende = [...new Set((a.sells ?? []).filter((x) => x === "tema" || x === "extension"))]
+      const vende = [...new Set((a.sells ?? []).map(String).filter(Boolean))]
       const r = await api("/tienda/autores/solicitudes", {
         method: "POST",
         body: {
           nombre: a.name,
           email: a.email,
           portafolio: a.portfolio,
-          vende: vende.length === 2 ? ["los-dos"] : vende,
+          vende,
           slug: a.handle,
           pais: a.country,
           web: a.website,
@@ -726,6 +967,56 @@ export function createCommerce({
       })
       return { id: r.id }
     },
+    forum: {
+      async get() {
+        const { forum } = await api("/tienda/foro")
+        return forum?.url ? { url: forum.url } : null
+      },
+      async signIn(token, sso, sig) {
+        const { url } = await api("/tienda/foro/entrar", { method: "POST", token, body: { sso, sig } })
+        return { url }
+      },
+    },
+    async listReviews(productId, params = {}) {
+      const q = new URLSearchParams({ product_id: productId })
+      if (params.limit != null) q.set("limit", String(params.limit))
+      if (params.offset != null) q.set("offset", String(params.offset))
+      const r = await api(`/tienda/reviews?${q}`)
+      return {
+        reviews: r.reviews ?? [],
+        count: r.count ?? 0,
+        average: r.average ?? null,
+        ...(r.histogram ? { histogram: r.histogram } : {}),
+      }
+    },
+    async submitReview(productId, review, token) {
+      const { review: r } = await api("/tienda/reviews", {
+        method: "POST",
+        token,
+        body: { product_id: productId, rating: review.rating, title: review.title, content: review.content },
+      })
+      return { id: r.id, status: r.status }
+    },
+    async getFounders() {
+      const { founders } = await api("/tienda/mercado/fundadores")
+      return founders ?? null
+    },
+    async listMarketTypes() {
+      const { tipos } = await api("/tienda/mercado/tipos")
+      return (tipos ?? []).map((t) => ({
+        key: t.clave,
+        name: t.nombre ?? {},
+        description: t.descripcion ?? {},
+        order: t.orden ?? 0,
+        attributes: (t.atributos ?? []).map((a) => ({
+          key: a.clave,
+          name: a.nombre ?? {},
+          multiple: a.multiple === true,
+          required: a.obligatorio === true,
+          options: (a.opciones ?? []).map((o) => ({ value: o.valor, name: o.nombre ?? {} })),
+        })),
+      }))
+    },
     async getAuthor(handle) {
       try {
         const { autor } = await api(`/tienda/autores/${encodeURIComponent(handle)}`)
@@ -781,6 +1072,9 @@ export function createCommerce({
       async reply(id, email, message) {
         await api(`/tienda/soporte/${encodeURIComponent(id)}`, { method: "POST", body: { email, texto: message } })
       },
+      async requestMediation(id, email, reason) {
+        await api(`/tienda/soporte/${encodeURIComponent(id)}`, { method: "POST", body: { email, mediacion: reason } })
+      },
       async rate(id, email, solved) {
         await api(`/tienda/soporte/${encodeURIComponent(id)}`, {
           method: "POST",
@@ -791,6 +1085,7 @@ export function createCommerce({
     cart,
     checkout,
     account,
+    wishlist,
     content,
     async getStore() {
       try {

package/src/index.d.ts

@@ -45,6 +45,8 @@ export interface Variant {
   compareAt?: Money | null
   /** null = el backend no lleva stock de esta variante. */
   stock: number | null
+  held?: number | null
+  edition?: { size: number; available: number } | null
   available: boolean
   options: OptionValue[]
   weight?: number | null
@@ -174,8 +176,10 @@ export interface ProductCode {
  * y se rellenan en `getProduct`, que es donde se enseñan.
  */
 export interface MarketInfo {
-  type: "tema" | "extension"
+  type: string
+  attributes?: Record<string, string[]>
   author: { name: string; handle: string }
+  contributors?: { name: string; handle: string }[]
   version: string | null
   updatedAt: string | null
   stack: string | null
@@ -189,6 +193,40 @@ export interface MarketInfo {
    * versiones nuevas no tienen fecha: le llegan al comprador siempre.
    */
   supportMonths?: number
+  sales?: number
+  downloads?: number
+}
+
+export interface ReviewReply {
+  content: string
+  created_at: string | null
+}
+
+export interface Review {
+  id: string
+  product_id: string
+  rating: number
+  title: string | null
+  content: string
+  author_name: string
+  created_at: string
+  updated_at?: string
+  version?: string | null
+  verified?: boolean
+  reply?: ReviewReply | null
+}
+
+export interface ReviewList {
+  reviews: Review[]
+  count: number
+  average: number | null
+  histogram?: Record<"1" | "2" | "3" | "4" | "5", number>
+}
+
+export interface ReviewDraft {
+  rating: number
+  content: string
+  title?: string
 }
 
 export interface Download {
@@ -261,6 +299,10 @@ export interface Product {
   rating?: number | null
   reviewCount?: number
   available: boolean
+  releaseAt?: string | null
+  releaseAtLocal?: string | null
+  releaseTimeZone?: string | null
+  sealed?: boolean
   quantityRules?: QuantityRules | null
   customization?: CustomField[]
   metadata?: Record<string, unknown>
@@ -293,6 +335,19 @@ export interface Address {
   phone?: string
 }
 
+export interface SavedAddress extends Address {
+  id: string
+  name?: string | null
+  isDefaultShipping: boolean
+  isDefaultBilling: boolean
+}
+
+export interface SavedAddressInput extends Address {
+  name?: string | null
+  isDefaultShipping?: boolean
+  isDefaultBilling?: boolean
+}
+
 export interface LineItem {
   id: string
   productId: string
@@ -318,6 +373,10 @@ export interface LineItem {
   personalized?: boolean
   digital?: boolean
   bundle?: { title: string; quantity: number }[] | null
+  editionNumber?: number | null
+  editionNumbers?: number[] | null
+  editionSize?: number | null
+  editionLabel?: string | null
 }
 
 /** Un sitio del que sale mercancía: un paquete, un porte. */
@@ -446,6 +505,51 @@ export type SiguientePago =
       proveedor?: string
     }
 
+/**
+ * Una tarjeta regalo o un saldo puesto en el carrito.
+ *
+ * El código entero no vuelve nunca: con los cuatro últimos caracteres el
+ * comprador reconoce su tarjeta, y quien mire la pantalla no se la lleva.
+ */
+export interface AppliedBalance {
+  id: string
+  /** Los cuatro últimos caracteres del código; `null` en un saldo de cuenta sin código. */
+  last4: string | null
+  /** Lo que esta tarjeta paga de este carrito. `null` si no se sabe. */
+  applied: Money | null
+  /** Lo que le queda a la tarjeta. `null` si no se sabe. */
+  available: Money | null
+}
+
+/**
+ * Por qué no se ha podido poner un saldo. Llega en `err.code`; el texto del
+ * backend sigue en `err.detalle` por si el tema quiere enseñarlo tal cual.
+ */
+export type BalanceErrorCode =
+  /** El código no existe, está desactivado o es de otra persona. */
+  | "balance.invalid"
+  /** El código existió pero ya ha caducado. */
+  | "balance.expired"
+  /** La tienda ha desactivado la tarjeta. */
+  | "balance.disabled"
+  /** La tarjeta es de otra moneda que el carrito. */
+  | "balance.currency"
+  /** La tarjeta existe pero no le queda nada. */
+  | "balance.empty"
+  /** Demasiados intentos: `err.retryAfter` dice cuántos segundos esperar. */
+  | "rate_limited"
+
+/** El error que lanza el cliente cuando el comercio contesta con un fallo. */
+export interface CommerceError extends Error {
+  status: number
+  /** Código estable para elegir el texto; sin definir si el comercio no da ninguno. */
+  code?: BalanceErrorCode | (string & {})
+  /** El motivo tal y como lo escribió el backend, ya en el idioma de la petición. */
+  detalle: string
+  /** Segundos que pide esperar un 429, si los dice. */
+  retryAfter?: number | null
+}
+
 export interface Cart {
   id: string
   items: LineItem[]
@@ -454,6 +558,33 @@ export interface Cart {
   discount: Money
   tax: Money
   total: Money
+  /**
+   * Lo que pagan las tarjetas regalo y el saldo puestos en el carrito. Ya está
+   * dentro de `total`: el pedido se factura por `total` y el saldo es una forma
+   * de pago, no un descuento.
+   */
+  balanceApplied: Money
+  /**
+   * Lo que queda por pagar con una pasarela: `total` menos `balanceApplied`.
+   * Con 0, la caja cierra con `checkout.complete` sin elegir forma de pago.
+   */
+  amountDue: Money
+  /**
+   * Las tarjetas y saldos puestos, para enseñarlos y poder quitarlos con
+   * `removeBalance`. El código entero no viene nunca.
+   */
+  balances?: AppliedBalance[]
+  /**
+   * El impuesto que ya va DENTRO de los precios. La cuenta cuadra siempre:
+   * `subtotal - discount + shipping + (tax - includedTax) = total`.
+   */
+  includedTax?: Money
+  /**
+   * `true` si los precios de las líneas llevan el impuesto dentro. El total lo
+   * lleva siempre: bajo el total se pinta «IVA incluido (tax)». Sin definir si
+   * el backend no lo dice.
+   */
+  pricesIncludeTax?: boolean
   itemCount: number
   email?: string | null
   shippingAddress?: Address | null
@@ -470,6 +601,7 @@ export interface Cart {
    * métodos sin pasarela: ahí pagar es confirmar el pedido y ya está.
    */
   pago?: SiguientePago | null
+  holdUntil?: string | null
 }
 
 export interface Order {
@@ -477,11 +609,36 @@ export interface Order {
   displayId?: number
   email?: string
   status: string
+  paymentStatus?: "not_paid" | "authorized" | "partially_authorized" | "captured" | "partially_captured" | "refunded" | "partially_refunded" | "canceled"
   items: LineItem[]
   subtotal: Money
   shipping: Money
+  /** El descuento APLICADO al pedido, no el que prometía el cupón. */
   discount: Money
   tax: Money
+  /**
+   * El impuesto que ya va DENTRO de los precios. La cuenta cuadra siempre:
+   * `subtotal - discount + shipping + (tax - includedTax) = total`.
+   */
+  includedTax?: Money
+  /**
+   * `true` si los precios de las líneas llevan el impuesto dentro. El total lo
+   * lleva siempre: bajo el total se pinta «IVA incluido (tax)». Sin definir si
+   * el backend no lo dice.
+   */
+  pricesIncludeTax?: boolean
+  /**
+   * Lo que se pagó con tarjetas regalo o saldo. Ya está dentro de `total`: lo
+   * cobrado por la pasarela es `total - balanceApplied`. Sin definir si la
+   * tienda no lo dice o no se usó saldo.
+   */
+  balanceApplied?: Money
+  /**
+   * La forma de pago del resto, tal y como la llama la tienda: `pp_offline_transfer`,
+   * `pp_offline_bizum`, `pp_offline_cod` o la de una pasarela. Sin definir si la
+   * tienda no lo dice: el tema no debe adivinarla.
+   */
+  paymentProvider?: string | null
   total: Money
   shippingAddress?: Address | null
   createdAt?: string
@@ -548,7 +705,8 @@ export interface ListProductsParams {
    * Solo piezas del mercado de ese tipo. Sin él salen todos los productos,
    * sean o no del mercado. Un adaptador sin mercado lo ignora.
    */
-  type?: "tema" | "extension"
+  type?: string
+  attributes?: Record<string, string[]>
   limit?: number
   offset?: number
   sort?: SortProductos
@@ -565,11 +723,37 @@ export interface Page<T> {
 // ── El cliente ────────────────────────────────────────────────────────────
 
 
+export type LocalizedText = Record<string, string>
+
+export interface MarketTypeAttribute {
+  key: string
+  name: LocalizedText
+  multiple: boolean
+  required: boolean
+  options: { value: string; name: LocalizedText }[]
+}
+
+export interface FounderProgram {
+  slots: number
+  taken: number
+  left: number
+  commissionPct: number
+  months: number
+}
+
+export interface MarketType {
+  key: string
+  name: LocalizedText
+  description: LocalizedText
+  attributes: MarketTypeAttribute[]
+  order: number
+}
+
 /** Una pieza del autor tal y como se lista en su ficha. */
 export interface AuthorItem {
   handle: string
   title: string
-  type: "tema" | "extension"
+  type: string
   summary: string | null
   price: Money
   cover: string | null
@@ -615,7 +799,7 @@ export interface AuthorApplication {
   email: string
   /** Enlace a algo que haya hecho: sin eso no hay nada que revisar. */
   portfolio: string
-  sells: ("tema" | "extension")[]
+  sells: string[]
   /** Identificador público; si falta, sale del nombre. */
   handle?: string
   /** Código de dos letras. */
@@ -640,11 +824,27 @@ export interface SupportThread {
   covered: boolean
   /** Lo que contestó al cerrar. null mientras no se le ha preguntado. */
   solved: boolean | null
+  mediation?: { requestedAt: string; resolvedAt: string | null } | null
   messages: SupportMessage[]
   createdAt: string
   updatedAt: string
 }
 
+export interface ReleaseNotifyInput {
+  productId: string
+  variantId?: string | null
+  email: string
+  consent: { accepted: true; text: string; version: string; info?: string }
+  locale?: string
+}
+
+export type ReleaseErrorCode =
+  | "avisos.ya_a_la_venta"
+  | "avisos.correo_no_valido"
+  | "avisos.falta_consentimiento"
+  | "avisos.producto_no_existe"
+  | "rate_limited"
+
 export interface CommerceClient {
   /** Identificador del adaptador: "pcreative", "static"… */
   readonly adapter: string
@@ -702,6 +902,14 @@ export interface CommerceClient {
    * `err.status` 400 y el motivo en `err.detalle`.
    */
   applyAsAuthor?(application: AuthorApplication): Promise<{ id: string }>
+  listMarketTypes?(): Promise<MarketType[]>
+  getFounders?(): Promise<FounderProgram | null>
+  forum?: {
+    get(): Promise<{ url: string } | null>
+    signIn(token: string, sso: string, sig: string): Promise<{ url: string }>
+  }
+  listReviews?(productId: string, params?: { limit?: number; offset?: number }): Promise<ReviewList>
+  submitReview?(productId: string, review: ReviewDraft, token?: string): Promise<{ id: string; status: string }>
   /**
    * Opcional: el boletín, con doble confirmación. `subscribe` NO apunta a nadie:
    * manda un correo con un enlace, y solo al pulsarlo (`confirm`) queda dentro.
@@ -724,6 +932,11 @@ export interface CommerceClient {
     confirm(token: string): Promise<boolean>
     unsubscribe(token: string): Promise<boolean>
   }
+  releases?: {
+    notify(input: ReleaseNotifyInput): Promise<{ status: "pendiente" }>
+    confirm(token: string): Promise<{ confirmed: boolean }>
+    unsubscribe(token: string): Promise<{ unsubscribed: true; alreadyWas: boolean }>
+  }
   /** Opcional: la ficha pública de un autor del mercado. */
   getAuthor?(handle: string): Promise<Author | null>
 
@@ -740,6 +953,7 @@ export interface CommerceClient {
     reply(id: string, email: string, message: string): Promise<void>
     /** Una sola pregunta al cerrar: si le sirvió. Alimenta el dato público del autor. */
     rate(id: string, email: string, solved: boolean): Promise<void>
+    requestMediation?(id: string, email: string, reason: string): Promise<void>
   }
 
   cart: {
@@ -758,6 +972,17 @@ export interface CommerceClient {
     consentirDigital?(cartId: string, aceptado: boolean): Promise<Cart>
     applyPromo(cartId: string, code: string): Promise<Cart>
     removePromo(cartId: string, code: string): Promise<Cart>
+    /**
+     * Opcional: pone una tarjeta regalo o un saldo por su código. El carrito
+     * vuelve con `balanceApplied`, `amountDue` y la tarjeta en `balances`.
+     *
+     * Si no se puede, rechaza con un `CommerceError` cuyo `code` es un
+     * `BalanceErrorCode`: `status` 400 para los códigos que no sirven y 429
+     * para demasiados intentos.
+     */
+    applyBalance?(cartId: string, code: string): Promise<Cart>
+    /** Opcional: quita del carrito la tarjeta o el saldo con ese `id`. */
+    removeBalance?(cartId: string, balanceId: string): Promise<Cart>
   }
 
   checkout: {
@@ -825,6 +1050,18 @@ export interface CommerceClient {
      * licencia no es suya, y 429 si se ha pasado del tope.
      */
     releaseSite?(token: string, licenseKey: string, instance: string): Promise<{ released: boolean; site: string }>
+    addresses?: {
+      list(token: string): Promise<SavedAddress[]>
+      create(token: string, address: SavedAddressInput): Promise<SavedAddress>
+      update(token: string, id: string, address: SavedAddressInput): Promise<SavedAddress>
+      remove(token: string, id: string): Promise<void>
+    }
+  }
+
+  wishlist?: {
+    list(token: string): Promise<string[]>
+    add(token: string, productIds: string | string[]): Promise<string[]>
+    remove(token: string, productId: string): Promise<string[]>
   }
 
   /** Opcional: nombre y datos legales de la tienda, tal y como los tiene el panel. */
@@ -864,5 +1101,51 @@ 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
 
+export declare function isVariantHeld(variant: Pick<Variant, "stock" | "held"> | null | undefined): boolean
+
+export declare function holdSecondsLeft(cart: Pick<Cart, "holdUntil"> | null | undefined, now?: number | Date): number | null
+
+/**
+ * `true` si las tarjetas y el saldo cubren el carrito entero: no queda nada
+ * que cobrar y la caja se cierra con `checkout.complete` sin pasarela.
+ */
+export declare function isCoveredByBalance(cart: Pick<Cart, "balanceApplied" | "amountDue"> | null | undefined): boolean
+
 /** Comprueba que un objeto implementa el contrato; devuelve lo que falta. */
 export declare function assertCommerceClient(cliente: unknown): string[]
+
+/** Una dirección IPv4 o IPv6 en su forma limpia, o `null` si no lo es. */
+export declare function normalizeIp(valor: unknown): string | null
+
+export interface TrustedNetwork {
+  bytes: number[]
+  prefijo: number
+}
+
+/** Lee una lista de proxies de confianza: `"127.0.0.1, 10.0.0.0/8, ::1"`. */
+export declare function parseTrustedProxies(lista: string | string[] | null | undefined): TrustedNetwork[]
+
+export declare function isTrustedProxy(ip: string, redes: TrustedNetwork[]): boolean
+
+/**
+ * La IP del comprador según `X-Forwarded-For`, leída de derecha a izquierda y
+ * saltando los proxies de confianza: la primera que no lo es la añadió un proxy
+ * propio y no el navegador. Lo que el comprador escriba a la izquierda no se
+ * usa nunca.
+ */
+export declare function clientIpFromHeaders(
+  cabeceras: Headers | Record<string, string | string[] | undefined> | null | undefined,
+  opciones?: { trustedProxies?: string | string[] | TrustedNetwork[] | null }
+): string | null
+
+/** Segundos de `Retry-After`, venga en segundos o como fecha HTTP. */
+export declare function parseRetryAfter(valor: string | null | undefined, now?: number | Date): number | null
+
+/** `true` si el error es un 429 del comercio. */
+export declare function isRateLimited(err: unknown): boolean
+
+/** «Demasiados intentos…», con la espera si se sabe. Acepta el error o los segundos. */
+export declare function tooManyAttemptsMessage(
+  espera: number | null | undefined | { retryAfter?: number | null },
+  locale?: string
+): string

package/src/index.js

@@ -37,6 +37,24 @@ export function sumMoney(...importes) {
   )
 }
 
+export function isVariantHeld(variant) {
+  if (!variant) return false
+  return variant.stock === 0 && Number(variant.held ?? 0) > 0
+}
+
+export function holdSecondsLeft(cart, now = Date.now()) {
+  const hasta = cart?.holdUntil ? Date.parse(cart.holdUntil) : NaN
+  if (!Number.isFinite(hasta)) return null
+  const ahora = now instanceof Date ? now.getTime() : Number(now)
+  return Math.max(0, Math.ceil((hasta - ahora) / 1000))
+}
+
+export function isCoveredByBalance(cart) {
+  const aplicado = Math.round(Number(cart?.balanceApplied?.amount ?? 0) * 100)
+  const queda = Math.round(Number(cart?.amountDue?.amount ?? NaN) * 100)
+  return aplicado > 0 && queda === 0
+}
+
 const REQUERIDO = {
   raiz: ["listProducts", "getProduct", "getProductsByIds", "listCategories", "getCategory", "search", "getOrder"],
   cart: ["get", "create", "addItem", "updateItem", "removeItem"],
@@ -60,3 +78,40 @@ export function assertCommerceClient(cliente) {
   }
   return faltan
 }
+
+export { clientIpFromHeaders, isTrustedProxy, normalizeIp, parseTrustedProxies } from "./ip.js"
+
+export function parseRetryAfter(valor, now = Date.now()) {
+  const texto = String(valor ?? "").trim()
+  if (!texto) return null
+  if (/^\d+$/.test(texto)) return Number(texto)
+  const fecha = Date.parse(texto)
+  if (Number.isNaN(fecha)) return null
+  return Math.max(0, Math.ceil((fecha - (now instanceof Date ? now.getTime() : now)) / 1000))
+}
+
+export function isRateLimited(err) {
+  return Number(err?.status) === 429
+}
+
+const TEXTOS_DEMASIADOS = {
+  en: {
+    sin: "Too many attempts. Wait a moment and try again.",
+    segundos: (n) => `Too many attempts. Wait ${n} ${n === 1 ? "second" : "seconds"} and try again.`,
+    minutos: (n) => `Too many attempts. Wait ${n} ${n === 1 ? "minute" : "minutes"} and try again.`,
+  },
+  es: {
+    sin: "Demasiados intentos. Espera un momento y vuelve a probar.",
+    segundos: (n) => `Demasiados intentos. Espera ${n} ${n === 1 ? "segundo" : "segundos"} y vuelve a probar.`,
+    minutos: (n) => `Demasiados intentos. Espera ${n} ${n === 1 ? "minuto" : "minutos"} y vuelve a probar.`,
+  },
+}
+
+export function tooManyAttemptsMessage(espera, locale = "en") {
+  const textos = TEXTOS_DEMASIADOS[String(locale).toLowerCase().startsWith("es") ? "es" : "en"]
+  const segundos = typeof espera === "object" && espera !== null ? espera.retryAfter : espera
+  const n = Number(segundos)
+  if (!Number.isFinite(n) || n <= 0) return textos.sin
+  if (n < 90) return textos.segundos(Math.ceil(n))
+  return textos.minutos(Math.ceil(n / 60))
+}

package/src/ip.js

@@ -0,0 +1,106 @@
+const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/
+
+function bytesV4(texto) {
+  if (!IPV4.test(texto)) return null
+  return texto.split(".").map(Number)
+}
+
+function bytesV6(texto) {
+  if (!/^[0-9a-fA-F:.]+$/.test(texto) || texto.length > 45) return null
+  let cola = []
+  let cuerpo = texto
+  const ultimo = texto.lastIndexOf(":")
+  if (texto.includes(".")) {
+    const v4 = bytesV4(texto.slice(ultimo + 1))
+    if (!v4) return null
+    cola = v4
+    cuerpo = texto.slice(0, ultimo + 1) + "0:0"
+  }
+  const partes = cuerpo.split("::")
+  if (partes.length > 2) return null
+  const trozos = (s) => (s === "" ? [] : s.split(":"))
+  const izquierda = trozos(partes[0])
+  const derecha = partes.length === 2 ? trozos(partes[1]) : []
+  const faltan = 8 - izquierda.length - derecha.length
+  if (partes.length === 1 ? faltan !== 0 : faltan < 1) return null
+  const grupos = [...izquierda, ...Array(partes.length === 2 ? faltan : 0).fill("0"), ...derecha]
+  if (grupos.length !== 8 || grupos.some((g) => !/^[0-9a-fA-F]{1,4}$/.test(g))) return null
+  const bytes = grupos.flatMap((g) => {
+    const n = parseInt(g, 16)
+    return [n >> 8, n & 255]
+  })
+  if (cola.length) bytes.splice(12, 4, ...cola)
+  return bytes
+}
+
+export function normalizeIp(valor) {
+  let texto = String(valor ?? "").trim()
+  if (texto.startsWith("[") && texto.endsWith("]")) texto = texto.slice(1, -1)
+  if (/^::ffff:/i.test(texto) && bytesV4(texto.slice(7))) texto = texto.slice(7)
+  if (bytesV4(texto)) return texto
+  if (bytesV6(texto)) return texto.toLowerCase()
+  return null
+}
+
+function bytesDe(ip) {
+  return bytesV4(ip) ?? bytesV6(ip)
+}
+
+function dentro(bytes, red, prefijo) {
+  if (bytes.length !== red.length) return false
+  let resto = prefijo
+  for (let i = 0; i < bytes.length && resto > 0; i++) {
+    const bits = Math.min(8, resto)
+    const mascara = (0xff << (8 - bits)) & 0xff
+    if ((bytes[i] & mascara) !== (red[i] & mascara)) return false
+    resto -= bits
+  }
+  return true
+}
+
+export function parseTrustedProxies(lista) {
+  const trozos = Array.isArray(lista) ? lista : String(lista ?? "").split(",")
+  const redes = []
+  for (const trozo of trozos.map((t) => String(t).trim()).filter(Boolean)) {
+    const [direccion, prefijoTexto] = trozo.split("/")
+    const ip = normalizeIp(direccion)
+    if (!ip) continue
+    const bytes = bytesDe(ip)
+    const maximo = bytes.length * 8
+    const prefijo = prefijoTexto === undefined ? maximo : Number(prefijoTexto)
+    if (!Number.isInteger(prefijo) || prefijo < 0 || prefijo > maximo) continue
+    redes.push({ bytes, prefijo })
+  }
+  return redes
+}
+
+export function isTrustedProxy(ip, redes) {
+  const limpia = normalizeIp(ip)
+  if (!limpia) return false
+  const bytes = bytesDe(limpia)
+  return redes.some((r) => dentro(bytes, r.bytes, r.prefijo))
+}
+
+function leerCabecera(cabeceras, nombre) {
+  if (!cabeceras) return ""
+  if (typeof cabeceras.get === "function") return cabeceras.get(nombre) ?? ""
+  const encontrada = Object.keys(cabeceras).find((k) => k.toLowerCase() === nombre)
+  const valor = encontrada ? cabeceras[encontrada] : ""
+  return Array.isArray(valor) ? valor.join(",") : String(valor ?? "")
+}
+
+export function clientIpFromHeaders(cabeceras, { trustedProxies } = {}) {
+  const redes = Array.isArray(trustedProxies) && trustedProxies[0]?.bytes ? trustedProxies : parseTrustedProxies(trustedProxies)
+  const saltos = leerCabecera(cabeceras, "x-forwarded-for")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+  let ultimaDeConfianza = null
+  for (let i = saltos.length - 1; i >= 0; i--) {
+    const ip = normalizeIp(saltos[i])
+    if (!ip) return ultimaDeConfianza
+    if (!isTrustedProxy(ip, redes)) return ip
+    ultimaDeConfianza ??= ip
+  }
+  return ultimaDeConfianza
+}