@pcreative/commerce-contract 1.3.4 → 1.3.5

package/README.es.md

@@ -0,0 +1,118 @@
+# @pcreative/commerce-contract
+
+[English](README.md) · **Español**
+
+Contrato de datos de commerce (v1.0): las entidades que consume un tema y los
+adaptadores que las resuelven. **Sin dependencias y sin el SDK del backend.**
+
+Un tema no importa ningún SDK de nadie: consume este contrato.
+De ahí salen las dos propiedades que sostienen el producto — el mismo tema sirve
+para otro backend mañana, y el backend no queda casado con temas de un solo
+framework.
+
+## Uso
+
+```js
+import { createCommerce } from "@pcreative/commerce-contract/api"
+
+const commerce = createCommerce({
+  baseUrl: process.env.NEXT_PUBLIC_COMMERCE_URL,
+  publishableKey: process.env.NEXT_PUBLIC_COMMERCE_KEY,
+  countryCode: "es",
+  // El framework aporta su caché sin que el adaptador sepa de frameworks:
+  requestInit: { next: { revalidate: 300 } },
+})
+
+const { items, count } = await commerce.listProducts({ category: "iluminacion", limit: 24 })
+const carrito = await commerce.cart.addItem(cartId, variantId, 1)
+```
+
+## Reglas del contrato
+
+**Los importes son decimales en unidades mayores** (`19.99`, no `1999`) y llevan
+su moneda al lado. Ningún tema tiene que adivinar la escala, que es de donde sale
+la mitad de los errores de precio en una tienda.
+
+```js
+import { formatMoney, sumMoney } from "@pcreative/commerce-contract"
+formatMoney({ amount: 19.99, currency: "eur" })   // "19,99 €"
+sumMoney(a, b)                                     // lanza si mezclas monedas
+```
+
+**Los errores llevan el código HTTP dentro** (`err.status`), porque un 404 de
+carrito caducado y un 401 por clave publicable mal puesta piden cosas distintas
+al tema. Un carrito que ya no existe devuelve `null`, no una excepción.
+
+**`checkout.complete()` puede devolver `{ order }` o `{ cart, error }`** — las
+dos con HTTP 200. Si el cobro falla, el carrito vuelve intacto y con el motivo.
+
+**El autor de una pieza y su soporte van juntos.** `getAuthor(handle)` trae la
+ficha pública de quien vende en el mercado, con sus piezas y con lo que calcula
+la plataforma: cuántas consultas resuelve y cuánto tarda en contestar. Lo que
+todavía no tiene dato viene en `null` —nunca en cero— para que el tema pueda
+enseñar «autor nuevo» en vez de un 0 % que espanta.
+
+```js
+const autor = await commerce.getAuthor("estudio-demo")
+autor.support?.resolvedPct   // 80, o null si aún no hay tres valoraciones
+autor.sales                  // 12, o null si todavía no ha vendido
+```
+
+**Para escribir al autor hace falta la clave de licencia**: solo da soporte a
+quien ha comprado. El hilo es privado y el correo del comprador viaja siempre en
+el cuerpo, nunca en la dirección.
+
+```js
+const { id, covered } = await commerce.support.open({
+  licenseKey, subject: "No instala", message: "Me da un error", email,
+})
+// covered === false: su soporte incluido ya caducó. Se avisa, no se bloquea.
+await commerce.support.get(id, email)
+await commerce.support.rate(id, email, true)   // una sola pregunta al cerrar
+```
+
+**El id de un pedido no es una contraseña.** El pedido de quien compró sin
+cuenta solo vuelve entero con la prueba de que es suyo. Sin ella, `getOrder`
+devuelve el pedido marcado con `partial: true` y sin correo ni dirección, y las
+licencias, los códigos y las descargas contestan 403. La prueba le llega al tema
+en el enlace que llevan los correos (`?acceso=`), en la respuesta de
+`checkout.complete`, o pidiéndola con el correo de la compra: y viaja en una
+cabecera, nunca en la dirección.
+
+```js
+const { order, access } = await commerce.checkout.complete(cartId)   // guarda `access`
+const pedido = await commerce.getOrder(id, access)                   // entero
+const licencias = await commerce.getLicenses(id, access)             // 403 sin ella
+
+// ¿Sin prueba? Se pide. Devuelve null cuando el correo no es el del pedido:
+// exactamente lo mismo que devuelve un pedido que no existe, para que la
+// respuesta no pueda decir cuál de las dos cosas ha pasado.
+const dado = await commerce.requestOrderAccess(id, email)            // { access, days } | null
+```
+
+## Escribir otro adaptador
+
+Implementa la interfaz `CommerceClient` de [`src/index.d.ts`](src/index.d.ts) y
+compruébalo:
+
+```js
+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.
+
+## Idioma de los mensajes
+
+Los errores que lanza el paquete salen en inglés. Salen en español cuando
+`LC_ALL`, `LC_MESSAGES` o `LANG` empiezan por `es` (por ejemplo
+`LANG=es_ES.UTF-8`). Donde no hay entorno (un navegador), en inglés.
+
+## Tests
+
+```bash
+node --test "test/*.test.js"
+```
+
+Los tests inyectan un `fetch` de mentira, así que corren sin backend.

package/README.md

@@ -1,14 +1,16 @@
 # @pcreative/commerce-contract
 
-Contrato de datos de commerce (v1.0): las entidades que consume un tema y los
-adaptadores que las resuelven. **Sin dependencias y sin el SDK del backend.**
+**English** · [Español](README.es.md)
 
-Un tema no importa ningún SDK de nadie: consume este contrato.
-De ahí salen las dos propiedades que sostienen el producto — el mismo tema sirve
-para otro backend mañana, y el backend no queda casado con temas de un solo
+Commerce data contract (v1.0): the entities a theme consumes and the adapters
+that resolve them. **No dependencies and no backend SDK.**
+
+A theme does not import anybody's SDK: it consumes this contract. That gives
+the two properties the product stands on — the same theme can serve another
+backend tomorrow, and the backend is not married to themes from a single
 framework.
 
-## Uso
+## Usage
 
 ```js
 import { createCommerce } from "@pcreative/commerce-contract/api"
@@ -17,7 +19,7 @@ const commerce = createCommerce({
   baseUrl: process.env.NEXT_PUBLIC_COMMERCE_URL,
   publishableKey: process.env.NEXT_PUBLIC_COMMERCE_KEY,
   countryCode: "es",
-  // El framework aporta su caché sin que el adaptador sepa de frameworks:
+  // The framework brings its own cache without the adapter knowing about frameworks:
   requestInit: { next: { revalidate: 300 } },
 })
 
@@ -25,62 +27,87 @@ const { items, count } = await commerce.listProducts({ category: "iluminacion",
 const carrito = await commerce.cart.addItem(cartId, variantId, 1)
 ```
 
-## Reglas del contrato
+## Contract rules
 
-**Los importes son decimales en unidades mayores** (`19.99`, no `1999`) y llevan
-su moneda al lado. Ningún tema tiene que adivinar la escala, que es de donde sale
-la mitad de los errores de precio en una tienda.
+**Amounts are decimals in major units** (`19.99`, not `1999`) and carry their
+currency next to them. No theme has to guess the scale, which is where half of
+the price bugs in a store come from.
 
 ```js
 import { formatMoney, sumMoney } from "@pcreative/commerce-contract"
 formatMoney({ amount: 19.99, currency: "eur" })   // "19,99 €"
-sumMoney(a, b)                                     // lanza si mezclas monedas
+sumMoney(a, b)                                     // throws if you mix currencies
 ```
 
-**Los errores llevan el código HTTP dentro** (`err.status`), porque un 404 de
-carrito caducado y un 401 por clave publicable mal puesta piden cosas distintas
-al tema. Un carrito que ya no existe devuelve `null`, no una excepción.
+**Errors carry the HTTP status inside** (`err.status`), because a 404 for an
+expired cart and a 401 for a misconfigured publishable key ask different things
+of the theme. A cart that no longer exists returns `null`, not an exception.
 
-**`checkout.complete()` puede devolver `{ order }` o `{ cart, error }`** — las
-dos con HTTP 200. Si el cobro falla, el carrito vuelve intacto y con el motivo.
+**`checkout.complete()` can return `{ order }` or `{ cart, error }`** — both
+with HTTP 200. If the charge fails, the cart comes back intact with the reason.
 
-**El autor de una pieza y su soporte van juntos.** `getAuthor(handle)` trae la
-ficha pública de quien vende en el mercado, con sus piezas y con lo que calcula
-la plataforma: cuántas consultas resuelve y cuánto tarda en contestar. Lo que
-todavía no tiene dato viene en `null` —nunca en cero— para que el tema pueda
-enseñar «autor nuevo» en vez de un 0 % que espanta.
+**An item's author and its support go together.** `getAuthor(handle)` returns
+the public profile of whoever sells on the marketplace, with their items and
+what the platform computes: how many requests they resolve and how long they
+take to answer. Anything without data yet comes as `null` — never zero — so the
+theme can show "new author" instead of a 0 % that scares people away.
 
 ```js
 const autor = await commerce.getAuthor("estudio-demo")
-autor.support?.resolvedPct   // 80, o null si aún no hay tres valoraciones
-autor.sales                  // 12, o null si todavía no ha vendido
+autor.support?.resolvedPct   // 80, or null until there are three ratings
+autor.sales                  // 12, or null if they have not sold yet
 ```
 
-**Para escribir al autor hace falta la clave de licencia**: solo da soporte a
-quien ha comprado. El hilo es privado y el correo del comprador viaja siempre en
-el cuerpo, nunca en la dirección.
+**Writing to the author requires the license key**: support is only for those
+who bought. The thread is private and the buyer's email always travels in the
+body, never in the URL.
 
 ```js
 const { id, covered } = await commerce.support.open({
-  licenseKey, subject: "No instala", message: "Me da un error", email,
+  licenseKey, subject: "Will not install", message: "I get an error", email,
 })
-// covered === false: su soporte incluido ya caducó. Se avisa, no se bloquea.
+// covered === false: the included support has expired. It warns, it does not block.
 await commerce.support.get(id, email)
-await commerce.support.rate(id, email, true)   // una sola pregunta al cerrar
+await commerce.support.rate(id, email, true)   // a single question when closing
 ```
 
-## Escribir otro adaptador
+**An order id is not a password.** A guest order only comes back whole with
+proof that it belongs to whoever is asking. Without it, `getOrder` returns the
+order marked `partial: true` and with no email or address, and licences, codes
+and downloads answer 403. The proof reaches the theme in the link the emails
+carry (`?acceso=`), in the answer to `checkout.complete`, or by asking for it
+with the email of the purchase — and it travels in a header, never in the URL.
+
+```js
+const { order, access } = await commerce.checkout.complete(cartId)   // keep `access`
+const pedido = await commerce.getOrder(id, access)                   // whole
+const licencias = await commerce.getLicenses(id, access)             // 403 without it
+
+// No proof? Ask for it. null when the email is not the one on the order —
+// exactly what an order that does not exist returns, so the answer cannot say
+// which of the two happened.
+const dado = await commerce.requestOrderAccess(id, email)            // { access, days } | null
+```
 
-Implementa la interfaz `CommerceClient` de [`src/index.d.ts`](src/index.d.ts) y
-compruébalo:
+## Writing another adapter
+
+Implement the `CommerceClient` interface from [`src/index.d.ts`](src/index.d.ts)
+and check it:
 
 ```js
 import { assertCommerceClient } from "@pcreative/commerce-contract"
-const faltan = assertCommerceClient(miCliente)   // [] si cumple
+const faltan = assertCommerceClient(miCliente)   // [] if it complies
 ```
 
-`account`, `content`, `getAuthor` y `support` son opcionales: un backend puede
-no tener cuentas de cliente, ni blog, ni mercado de autores.
+`account`, `content`, `getAuthor` and `support` are optional: a backend may have
+no customer accounts, no blog and no author marketplace.
+
+## Language of the messages
+
+Errors thrown by the package are in English. They come out in Spanish when
+`LC_ALL`, `LC_MESSAGES` or `LANG` starts with `es` (for example
+`LANG=es_ES.UTF-8`). Where there is no environment (a browser), English is
+used.
 
 ## Tests
 
@@ -88,4 +115,4 @@ no tener cuentas de cliente, ni blog, ni mercado de autores.
 node --test "test/*.test.js"
 ```
 
-Los tests inyectan un `fetch` de mentira, así que corren sin backend.
+The tests inject a fake `fetch`, so they run without a backend.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pcreative/commerce-contract",
-  "version": "1.3.4",
-  "description": "Contrato de datos de commerce: los tipos que consume un tema y los adaptadores que los resuelven. Sin dependencias ni SDK del backend.",
+  "version": "1.3.5",
+  "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",
   "main": "./src/index.js",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "README.md",
+    "README.es.md",
     "LICENSE"
   ],
   "engines": {

package/src/adapters/api.js

@@ -1,4 +1,8 @@
 import { money } from "../index.js"
+import { msg } from "../mensajes.js"
+
+/** La cabecera con la que se demuestra que un pedido de invitado es tuyo. */
+const CABECERA_DE_ACCESO = "x-pcc-pedido"
 
 const ORDEN_DEL_CONTRATO = {
   newest: "novedades",
@@ -34,16 +38,20 @@ export function createCommerce({
   fetch: fetchImpl,
   requestInit = {},
 } = {}) {
-  if (!baseUrl) throw new Error("createCommerce: falta baseUrl")
+  if (!baseUrl) throw new Error(msg("faltaBaseUrl"))
   const f = fetchImpl ?? globalThis.fetch
   const raiz = String(baseUrl).replace(/\/$/, "")
 
-  async function api(ruta, { method = "GET", body, token, ...extra } = {}) {
+  async function api(ruta, { method = "GET", body, token, acceso, ...extra } = {}) {
     const cabeceras = { accept: "application/json", ...(extra.headers ?? {}) }
     if (publishableKey) cabeceras["x-pcc-clave"] = publishableKey
     if (locale) cabeceras["x-pcc-locale"] = locale
     if (body !== undefined) cabeceras["content-type"] = "application/json"
     if (token) cabeceras.authorization = `Bearer ${token}`
+    // La prueba de que el pedido es de quien pregunta va SIEMPRE en cabecera y
+    // 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 res = await f(`${raiz}${ruta}`, {
       method,
@@ -259,16 +267,39 @@ export function createCommerce({
     return product_categories[0] ? mapCategory(product_categories[0]) : null
   }
 
-  async function getOrder(id) {
+  async function getOrder(id, acceso) {
     try {
-      const { order } = await api(`/tienda/pedidos/${encodeURIComponent(id)}`)
-      return order ?? null
+      const { order, acceso_requerido } = await api(`/tienda/pedidos/${encodeURIComponent(id)}`, { acceso })
+      if (!order) return null
+      // 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.
+      return acceso_requerido ? { ...order, partial: true } : order
     } catch (e) {
       if (e.status === 404 || e.status === 401) return null
       throw e
     }
   }
 
+  /**
+   * La segunda puerta: quien llega a `/pedido/<id>` sin la prueba del correo la
+   * pide con el correo de la compra. Devuelve null cuando no coincide, que es
+   * la MISMA respuesta que da un pedido que no existe: si no, la respuesta
+   * diria si ese pedido existe.
+   */
+  async function requestOrderAccess(orderId, email) {
+    try {
+      const r = await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/acceso`, {
+        method: "POST",
+        body: { email },
+      })
+      return r?.acceso ? { access: r.acceso, days: Number(r.dias ?? 0) } : null
+    } catch (e) {
+      if (e.status === 404 || e.status === 400) return null
+      throw e
+    }
+  }
+
   async function search(q, limit = 24) {
     const { items } = await listProducts({ q, limit })
     return items
@@ -295,7 +326,7 @@ export function createCommerce({
       body: cuerpo,
     })
     const datos = await r.json().catch(() => ({}))
-    if (!r.ok) throw new Error(datos?.message || "No se pudo subir el fichero.")
+    if (!r.ok) throw new Error(datos?.message || msg("ficheroNoSubido"))
     return datos.fichero
   }
 
@@ -343,7 +374,7 @@ export function createCommerce({
     async applyPromo(cartId, code) {
       const r = await api(rutaCarrito(cartId, "/cupon"), { method: "POST", body: { codigo: code } })
       if (!r.aplicado) {
-        const err = new Error(r.motivo ?? "Ese código no se puede usar.")
+        const err = new Error(r.motivo ?? msg("codigoNoValido"))
         err.status = 400
         err.detalle = r.motivo ?? ""
         throw err
@@ -443,7 +474,11 @@ export function createCommerce({
     async complete(cartId) {
       try {
         const r = await api(rutaCarrito(cartId, "/completar"), { method: "POST", body: {} })
-        const pedido = (await getOrder(r.order.id)) ?? {
+        // La prueba de acceso vuelve con el pedido recién cerrado: la página de
+        // gracias enseña claves y descargas sin pedirle el correo a quien acaba
+        // de escribirlo dos pantallas antes.
+        const acceso = r.acceso ?? undefined
+        const pedido = (await getOrder(r.order.id, acceso)) ?? {
           id: r.order.id,
           status: "pending",
           items: [],
@@ -453,7 +488,7 @@ export function createCommerce({
           tax: money(0, r.order.currency_code ?? "eur", true),
           total: money(r.order.total, r.order.currency_code ?? "eur", true),
         }
-        return { order: pedido }
+        return acceso ? { order: pedido, access: acceso } : { order: pedido }
       } catch (e) {
         if (e.status !== 409 && e.status !== 400) throw e
         return { cart: await getCart(cartId), error: e.detalle || "No se pudo completar el pedido" }
@@ -572,31 +607,36 @@ export function createCommerce({
     getCategory,
     search,
     getOrder,
+    requestOrderAccess,
     subirFichero: subirFicheroCliente,
-    async getWithdrawal(orderId) {
+    async getWithdrawal(orderId, acceso) {
       try {
-        const { desistimiento } = await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/desistimiento`)
+        const { desistimiento } = await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/desistimiento`, { acceso })
         return desistimiento ?? null
       } catch (e) {
         if (e.status === 404) return null
         throw e
       }
     },
-    async requestWithdrawal(orderId, datos = {}) {
-      return await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/desistimiento`, { method: "POST", body: datos })
+    async requestWithdrawal(orderId, datos = {}, acceso) {
+      return await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/desistimiento`, {
+        method: "POST",
+        body: datos,
+        acceso,
+      })
     },
-    async getDownloads(orderId) {
+    async getDownloads(orderId, acceso) {
       try {
-        const { descargas } = await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/descargas`)
+        const { descargas } = await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/descargas`, { acceso })
         return (descargas ?? []).map((d) => ({ ...d, url: d.url ? `${raiz}${d.url}` : null }))
       } catch (e) {
         if (e.status === 404) return []
         throw e
       }
     },
-    async getLicenses(orderId) {
+    async getLicenses(orderId, acceso) {
       try {
-        const { licencias } = await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/licencias`)
+        const { licencias } = await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/licencias`, { acceso })
         return (licencias ?? []).map((l) => ({
           key: l.key,
           status: l.status,
@@ -610,19 +650,19 @@ export function createCommerce({
         throw e
       }
     },
-    async getCodes(orderId) {
+    async getCodes(orderId, acceso) {
       try {
-        const { codigos } = await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/codigos`)
+        const { codigos } = await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/codigos`, { acceso })
         return codigos ?? []
       } catch (e) {
         if (e.status === 404) return []
         throw e
       }
     },
-    async revealCode(orderId, codeId) {
+    async revealCode(orderId, codeId, acceso) {
       const { codigo } = await api(
         `/tienda/pedidos/${encodeURIComponent(orderId)}/codigos/${encodeURIComponent(codeId)}/revelar`,
-        { method: "POST", body: {} },
+        { method: "POST", body: {}, acceso },
       )
       return codigo ?? null
     },

package/src/index.d.ts

@@ -458,6 +458,13 @@ export interface Order {
   total: Money
   shippingAddress?: Address | null
   createdAt?: string
+  /**
+   * El pedido llega RECORTADO: sin correo ni dirección, porque quien lo pide no
+   * ha demostrado todavía que es suyo. Un tema que lo ignore pinta huecos
+   * vacíos como si el pedido no tuviera esos datos; lo que toca es pedir el
+   * correo con `requestOrderAccess`.
+   */
+  partial?: boolean
 }
 
 export interface Customer {
@@ -621,22 +628,47 @@ export interface CommerceClient {
   listCategories(): Promise<Category[]>
   getCategory(handle: string): Promise<Category | null>
   search(q: string, limit?: number): Promise<Product[]>
-  /** Pedido por id, para la página de confirmación tras el checkout. */
-  getOrder(id: string): Promise<Order | null>
+  /**
+   * Pedido por id, para la página de confirmación tras el checkout.
+   *
+   * Un id NO es una credencial: el pedido de quien compró sin cuenta solo sale
+   * entero con la prueba de `access`, que llega en el enlace del correo
+   * (`?acceso=`), la devuelve `checkout.complete` o la da `requestOrderAccess`.
+   * Sin ella vuelve con `partial: true` y sin datos personales.
+   */
+  getOrder(id: string, access?: string): Promise<Order | null>
+  /**
+   * Opcional: pedir la prueba de acceso a un pedido con el correo de la compra.
+   * Devuelve null si no coincide, que es exactamente lo mismo que devuelve un
+   * pedido que no existe: la respuesta no puede decir cuál de las dos cosas
+   * pasó. Está limitada por número de intentos, así que el tema tiene que
+   * contar con un fallo por exceso.
+   */
+  requestOrderAccess?(orderId: string, email: string): Promise<{ access: string; days: number } | 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: las descargas de un pedido con contenido digital.
+   *
+   * Estas cuatro NO tienen versión recortada: sin `access` el comercio contesta
+   * 403, porque un fichero, una clave de licencia y un código son la compra
+   * misma. El tema las llama con la prueba o no las llama.
+   */
+  getDownloads?(orderId: string, access?: string): Promise<Download[]>
   /** Opcional: las licencias de las piezas del mercado compradas en un pedido. */
-  getLicenses?(orderId: string): Promise<License[]>
+  getLicenses?(orderId: string, access?: string): Promise<License[]>
   /** Los codigos de un pedido, tapados. */
-  getCodes?(orderId: string): Promise<ProductCode[]>
+  getCodes?(orderId: string, access?: string): Promise<ProductCode[]>
   /** Destapa uno y devuelve el codigo entero. Queda apuntado quien y cuando. */
-  revealCode?(orderId: string, codeId: string): Promise<string>
+  revealCode?(orderId: string, codeId: string, access?: string): Promise<string>
   /** Opcional: estado del derecho de desistimiento de un pedido. */
-  getWithdrawal?(orderId: string): Promise<WithdrawalState | null>
+  getWithdrawal?(orderId: string, access?: 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 }>
+  requestWithdrawal?(
+    orderId: string,
+    datos?: { lineas?: string[]; motivo?: string },
+    access?: string,
+  ): Promise<{ solicitud: string; aceptadas: number }>
   /**
    * Opcional: pedir vender en el mercado. Devuelve el id de la solicitud; la
    * cuenta se crea cuando alguien la acepta. Si el correo ya pidió, falla con
@@ -740,7 +772,12 @@ export interface CommerceClient {
      * backend. Se usa para la ruta de vuelta, que depende del idioma.
      */
     selectPaymentMethod(cartId: string, provider: string, datos?: Record<string, unknown>): Promise<Cart>
-    complete(cartId: string): Promise<{ order: Order } | { cart: Cart; error: string }>
+    /**
+     * `access` es la prueba de que ese pedido es de quien acaba de pagarlo: la
+     * página de gracias enseña claves y descargas sin volver a pedirle el
+     * correo a quien lo escribió dos pantallas antes. Guárdala.
+     */
+    complete(cartId: string): Promise<{ order: Order; access?: string } | { cart: Cart; error: string }>
   }
 
   /** Opcional: un adaptador puede no soportar cuentas de cliente. */

package/src/index.js

@@ -1,4 +1,6 @@
 
+import { msg } from "./mensajes.js"
+
 export const CONTRACT_VERSION = "1.0"
 
 export function money(amount, currency, taxIncluded) {
@@ -25,7 +27,7 @@ export function sumMoney(...importes) {
   const currency = validos[0].currency
   for (const m of validos) {
     if (m.currency !== currency) {
-      throw new Error(`no se pueden sumar importes en ${currency} y en ${m.currency}`)
+      throw new Error(msg("monedasDistintas", currency, m.currency))
     }
   }
   return money(
@@ -43,7 +45,7 @@ const REQUERIDO = {
 
 export function assertCommerceClient(cliente) {
   const faltan = []
-  if (!cliente || typeof cliente !== "object") return ["el cliente no es un objeto"]
+  if (!cliente || typeof cliente !== "object") return [msg("clienteNoObjeto")]
   for (const m of REQUERIDO.raiz) {
     if (typeof cliente[m] !== "function") faltan.push(m)
   }

package/src/mensajes.js

@@ -0,0 +1,31 @@
+export function idioma(entorno) {
+  const env = entorno ?? (typeof process !== "undefined" && process?.env ? process.env : {})
+  for (const v of [env.LC_ALL, env.LC_MESSAGES, env.LANG]) {
+    if (v) return /^es([_.@-]|$)/i.test(String(v)) ? "es" : "en"
+  }
+  return "en"
+}
+
+const en = {
+  monedasDistintas: (a, b) => `cannot add amounts in ${a} and in ${b}`,
+  clienteNoObjeto: () => "the client is not an object",
+  faltaBaseUrl: () => "createCommerce: baseUrl is missing",
+  ficheroNoSubido: () => "The file could not be uploaded.",
+  codigoNoValido: () => "That code cannot be used.",
+}
+
+const es = {
+  monedasDistintas: (a, b) => `no se pueden sumar importes en ${a} y en ${b}`,
+  clienteNoObjeto: () => "el cliente no es un objeto",
+  faltaBaseUrl: () => "createCommerce: falta baseUrl",
+  ficheroNoSubido: () => "No se pudo subir el fichero.",
+  codigoNoValido: () => "Ese código no se puede usar.",
+}
+
+export const MENSAJES = { en, es }
+
+export function msg(clave, ...args) {
+  const f = MENSAJES[idioma()][clave] ?? en[clave]
+  if (typeof f !== "function") throw new Error(`message without text: ${clave}`)
+  return f(...args)
+}