@pcreative/commerce-contract 1.3.0 → 1.3.2

package/README.md

@@ -44,6 +44,31 @@ 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
+```
+
 ## Escribir otro adaptador
 
 Implementa la interfaz `CommerceClient` de [`src/index.d.ts`](src/index.d.ts) y
@@ -54,8 +79,8 @@ import { assertCommerceClient } from "@pcreative/commerce-contract"
 const faltan = assertCommerceClient(miCliente)   // [] si cumple
 ```
 
-`account` y `content` son opcionales: un backend puede no tener cuentas de
-cliente ni blog.
+`account`, `content`, `getAuthor` y `support` son opcionales: un backend puede
+no tener cuentas de cliente, ni blog, ni mercado de autores.
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pcreative/commerce-contract",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Contrato de datos de commerce: los tipos que consume un tema y los adaptadores que los resuelven. Sin dependencias ni SDK del backend.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/adapters/api.js

@@ -6,6 +6,26 @@ const ORDEN_DEL_CONTRATO = {
   price_desc: "precio_desc",
 }
 
+const DE_QUIEN = { comprador: "buyer", autor: "author", tienda: "store" }
+
+function aHilo(h) {
+  return {
+    id: h.id,
+    subject: h.asunto,
+    item: h.pieza,
+    status: h.estado,
+    covered: h.con_soporte !== false,
+    solved: h.resuelto ?? null,
+    messages: (h.mensajes ?? []).map((m) => ({
+      from: DE_QUIEN[m.de] ?? "store",
+      text: m.texto,
+      createdAt: m.creado_en,
+    })),
+    createdAt: h.creado_en,
+    updatedAt: h.movido_en,
+  }
+}
+
 export function createCommerce({
   baseUrl,
   publishableKey,
@@ -108,11 +128,13 @@ export function createCommerce({
         tiers: v.tiers ?? [],
         digital: Boolean(v.digital),
         requiresShipping: v.requiresShipping ?? !v.digital,
+        code: v.code ?? null,
         bundle: v.bundle ?? null,
         bundleGroups: v.bundleGroups ?? null,
         measure: v.measure ?? null,
         unitPrice: v.unitPrice ?? null,
       })),
+      market: p.market ?? null,
       categories: p.categories ?? [],
       quantityRules: p.quantityRules ?? null,
       customization: p.customization ?? [],
@@ -359,6 +381,11 @@ export function createCommerce({
       })
       return mapCart(c)
     },
+    async listProvinces(country) {
+      if (!country) return []
+      const { provincias = [] } = await api(`/tienda/provincias?pais=${encodeURIComponent(country)}`)
+      return provincias.map((p) => ({ code: p.codigo, name: p.nombre }))
+    },
     async listShippingOptions(cartId) {
       const { moneda = "eur", opciones = [] } = await api(rutaCarrito(cartId, "/envios"))
       return opciones.map((o) => ({
@@ -566,13 +593,91 @@ export function createCommerce({
         throw e
       }
     },
+    async getCodes(orderId) {
+      try {
+        const { codigos } = await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/codigos`)
+        return codigos ?? []
+      } catch (e) {
+        if (e.status === 404) return []
+        throw e
+      }
+    },
+    async revealCode(orderId, codeId) {
+      const { codigo } = await api(
+        `/tienda/pedidos/${encodeURIComponent(orderId)}/codigos/${encodeURIComponent(codeId)}/revelar`,
+        { method: "POST", body: {} },
+      )
+      return codigo ?? null
+    },
+    async getAuthor(handle) {
+      try {
+        const { autor } = await api(`/tienda/autores/${encodeURIComponent(handle)}`)
+        if (!autor) return null
+        return {
+          handle: autor.handle,
+          name: autor.name,
+          bio: autor.bio ?? null,
+          website: autor.website ?? null,
+          country: autor.country ?? null,
+          links: autor.links ?? {},
+          logo: autor.logo ?? null,
+          since: autor.since,
+          items: (autor.items ?? []).map((i) => ({
+            handle: i.handle,
+            title: i.title,
+            type: i.type,
+            summary: i.summary ?? null,
+            cover: i.cover ?? null,
+            price: money(i.price?.amount ?? 0, i.price?.currency ?? "eur"),
+          })),
+          sales: autor.sales ?? null,
+          support: autor.soporte
+            ? {
+                resolvedPct: autor.soporte.porcentaje ?? null,
+                firstReplyHours: autor.soporte.horasPrimeraRespuesta ?? null,
+                ratings: autor.soporte.valorados ?? 0,
+              }
+            : null,
+        }
+      } catch (e) {
+        if (e.status === 404) return null
+        throw e
+      }
+    },
+    support: {
+      async open({ licenseKey, subject, message, email }) {
+        const r = await api("/tienda/soporte", {
+          method: "POST",
+          body: { clave: licenseKey, asunto: subject, texto: message, email },
+        })
+        return { id: r.id, covered: r.conSoporte !== false }
+      },
+      async get(id, email) {
+        try {
+          const { hilo } = await api(`/tienda/soporte/${encodeURIComponent(id)}`, { method: "POST", body: { email } })
+          return hilo ? aHilo(hilo) : null
+        } catch (e) {
+          if (e.status === 404 || e.status === 400) return null
+          throw e
+        }
+      },
+      async reply(id, email, message) {
+        await api(`/tienda/soporte/${encodeURIComponent(id)}`, { method: "POST", body: { email, texto: message } })
+      },
+      async rate(id, email, solved) {
+        await api(`/tienda/soporte/${encodeURIComponent(id)}`, {
+          method: "POST",
+          body: { email, resuelto: !!solved },
+        })
+      },
+    },
     cart,
     checkout,
     account,
     content,
     async getStore() {
       try {
-        const { tienda, legal } = await api("/tienda/tienda")
+        const { tienda, legal, precios } = await api("/tienda/tienda")
         if (!tienda) return null
         return {
           name: tienda.nombre ?? null,
@@ -582,6 +687,14 @@ export function createCommerce({
           email: tienda.correo ?? null,
           phone: tienda.telefono ?? null,
           country: tienda.pais ?? null,
+          priceDisplay: precios
+            ? {
+                show: precios.muestra === 'sin' ? 'without' : precios.muestra === 'ambos' ? 'both' : 'with',
+                storedWithTax: !!precios.guardadosConImpuesto,
+                defaultRate: Number(precios.tasaPorDefecto ?? 0),
+                country: precios.pais ?? null,
+              }
+            : null,
           legal: legal ?? null,
         }
       } catch {

package/src/index.d.ts

@@ -53,6 +53,12 @@ export interface Variant {
   tiers?: PriceTier[]
   digital?: boolean
   requiresShipping?: boolean
+  /**
+   * Cuando la variante se vende como codigo: donde se canjea, para que region
+   * vale y en que idiomas viene. Se ensena ANTES de pagar; una clave de la
+   * region equivocada no sirve y acaba en devolucion.
+   */
+  code?: { platform: string | null; region: string | null; languages: string[]; instructions: string | null } | null
   bundle?: BundleComponent[] | null
   bundleGroups?: BundleGroup[] | null
   measure?: { quantity: number; unit: string } | null
@@ -86,6 +92,47 @@ export interface BundleComponent {
   image?: string | null
 }
 
+/**
+ * Un codigo que se vende y se entrega: clave de juego, tarjeta, licencia.
+ * `code` solo llega cuando el comprador pide destaparlo; hasta entonces se
+ * ensena `hint` (los ultimos caracteres) y `revealed` dice si ya se destapo,
+ * que es lo que cuenta como entregado.
+ */
+export interface ProductCode {
+  id: string
+  lineId: string
+  title: string
+  status: "libre" | "reservado" | "entregado" | "revocado" | "retirado"
+  hint: string
+  code: string | null
+  revealed: boolean
+  revealedAt: string | null
+  deliveredAt: string | null
+  reason: string | null
+  platform: string | null
+  region: string | null
+  languages: string[]
+  instructions: string | null
+}
+
+/**
+ * Lo que anade un producto que viene del mercado de temas y extensiones:
+ * version, cuando se actualizo, demo y changelog. Es lo que mira quien compra
+ * software y lo que un producto normal no tiene.
+ */
+export interface MarketInfo {
+  type: "tema" | "extension"
+  author: { name: string; handle: string }
+  version: string | null
+  updatedAt: string | null
+  stack: string | null
+  niche: string[]
+  license: string | null
+  demoUrl: string | null
+  screenshots: string[]
+  changelog: { version: string; date: string | null; notes: string | null }[]
+}
+
 export interface Download {
   id: string
   lineId: string
@@ -149,6 +196,8 @@ export interface Product {
   /** Precio mínimo entre las variantes: el «desde X €» de la tarjeta. */
   price: Money
   variants: Variant[]
+  /** Solo cuando el producto es una pieza del mercado de temas y extensiones. */
+  market?: MarketInfo | null
   categories: CategoryRef[]
   tags?: string[]
   rating?: number | null
@@ -244,6 +293,20 @@ export interface StoreInfo {
   email: string | null
   phone: string | null
   country?: string | null
+  /**
+   * Como quiere la tienda que se vean los precios en el escaparate.
+   * `show: 'with'` es lo que exige la ley europea para consumidores;
+   * `'without'` y `'both'` son para tiendas que venden a empresas.
+   * `storedWithTax` dice si el precio que llega ya lleva el impuesto dentro,
+   * y `defaultRate` es la tasa del pais de la tienda, para poder calcular el
+   * otro importe antes de que el cliente diga donde vive.
+   */
+  priceDisplay?: {
+    show: 'with' | 'without' | 'both'
+    storedWithTax: boolean
+    defaultRate: number
+    country: string | null
+  }
   legal?: {
     digital?: {
       pais: string
@@ -431,6 +494,70 @@ export interface Page<T> {
 
 // ── El cliente ────────────────────────────────────────────────────────────
 
+
+/** Una pieza del autor tal y como se lista en su ficha. */
+export interface AuthorItem {
+  handle: string
+  title: string
+  type: "tema" | "extension"
+  summary: string | null
+  price: Money
+  cover: string | null
+}
+
+/**
+ * Lo que la plataforma calcula del soporte de un autor. Es lo que le da valor:
+ * no lo escribe él. Cuando todavía no hay datos suficientes viene en null, que
+ * se enseña como «autor nuevo» y nunca como un cero.
+ */
+export interface AuthorSupport {
+  /** Porcentaje de consultas que sus compradores dieron por resueltas. */
+  resolvedPct: number | null
+  /** Mediana de horas hasta su primera respuesta. */
+  firstReplyHours: number | null
+  /** Cuántas valoraciones sostienen el porcentaje. */
+  ratings: number
+}
+
+/** La ficha pública de quien vende una pieza en el mercado. */
+export interface Author {
+  handle: string
+  name: string
+  bio: string | null
+  website: string | null
+  /** Código de dos letras, en minúsculas. */
+  country: string | null
+  /** Redes y sitios del autor, siempre https. */
+  links: Record<string, string>
+  logo: string | null
+  /** Desde cuándo publica. */
+  since: string
+  items: AuthorItem[]
+  /** Solo cuando hay ventas: un cero espanta y no se enseña. */
+  sales: number | null
+  support: AuthorSupport | null
+}
+
+export interface SupportMessage {
+  from: "buyer" | "author" | "store"
+  text: string
+  createdAt: string
+}
+
+export interface SupportThread {
+  id: string
+  subject: string
+  item: string
+  status: "abierto" | "contestado" | "esperando" | "cerrado"
+  /** Si su soporte incluido sigue vigente. Caducado no cierra la puerta: avisa. */
+  covered: boolean
+  /** Lo que contestó al cerrar. null mientras no se le ha preguntado. */
+  solved: boolean | null
+  messages: SupportMessage[]
+  createdAt: string
+  updatedAt: string
+}
+
 export interface CommerceClient {
   /** Identificador del adaptador: "pcreative", "static"… */
   readonly adapter: string
@@ -447,10 +574,31 @@ export interface CommerceClient {
   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[]>
+  /** Los codigos de un pedido, tapados. */
+  getCodes?(orderId: string): Promise<ProductCode[]>
+  /** Destapa uno y devuelve el codigo entero. Queda apuntado quien y cuando. */
+  revealCode?(orderId: string, codeId: string): Promise<string>
   /** Opcional: estado del derecho de desistimiento de un pedido. */
   getWithdrawal?(orderId: string): Promise<WithdrawalState | null>
   /** Opcional: solicita el desistimiento de un pedido (botón obligatorio en la UE). */
   requestWithdrawal?(orderId: string, datos?: { lineas?: string[]; motivo?: string }): Promise<{ solicitud: string; aceptadas: number }>
+  /** Opcional: la ficha pública de un autor del mercado. */
+  getAuthor?(handle: string): Promise<Author | null>
+
+  /**
+   * Opcional: hablar con el autor de una pieza. Es privado y hace falta la
+   * clave de licencia, así que solo escribe quien ha comprado.
+   *
+   * El correo va en el cuerpo y nunca en la dirección: identifica a una
+   * persona y una dirección acaba en registros y en el historial del navegador.
+   */
+  support?: {
+    open(datos: { licenseKey: string; subject: string; message: string; email?: string }): Promise<{ id: string; covered: boolean }>
+    get(id: string, email: string): Promise<SupportThread | null>
+    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>
+  }
 
   cart: {
     get(id: string): Promise<Cart | null>
@@ -472,6 +620,12 @@ export interface CommerceClient {
 
   checkout: {
     listCountries?(): Promise<string[]>
+    /**
+     * Provincias, estados o departamentos de un pais, en el nivel que pide su
+     * caja (Espana pide provincia, Alemania Land, Malta nada). Lista vacia =
+     * ese pais no usa provincia y el tema debe dejar el campo libre.
+     */
+    listProvinces?(country: string): Promise<Array<{ code: string; name: string }>>
     setVatNumber?(cartId: string, vatNumber: string | null): Promise<Cart>
     setEmail(cartId: string, email: string): Promise<Cart>
     setAddresses(cartId: string, shipping: Address, billing?: Address): Promise<Cart>