@pcreative/commerce-contract 1.3.1 → 1.3.3

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.1",
+  "version": "1.3.3",
   "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 ?? [],
@@ -203,6 +225,7 @@ export function createCommerce({
     if (params.q) qs.set("q", String(params.q))
     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)
     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}`)
@@ -571,6 +594,148 @@ export function createCommerce({
         throw e
       }
     },
+    async getLicenses(orderId) {
+      try {
+        const { licencias } = await api(`/tienda/pedidos/${encodeURIComponent(orderId)}/licencias`)
+        return (licencias ?? []).map((l) => ({
+          key: l.key,
+          status: l.status,
+          title: l.title ?? null,
+          sites: Number(l.sites ?? 0),
+          limit: Number(l.limit ?? 1),
+          supportedUntil: l.supportedUntil ? String(l.supportedUntil).slice(0, 10) : null,
+        }))
+      } catch (e) {
+        if (e.status === 404) return []
+        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
+    },
+    newsletter: {
+      async subscribe(email, consent = {}) {
+        await api("/tienda/boletin", {
+          method: "POST",
+          body: {
+            email,
+            texto: consent.text,
+            version: consent.version,
+            idioma: consent.locale,
+            origen: consent.source,
+            ip: consent.ip,
+            navegador: consent.userAgent,
+          },
+        })
+        return { status: "pendiente" }
+      },
+      async confirm(token) {
+        try {
+          await api("/tienda/boletin/confirmar", { method: "POST", body: { token } })
+          return true
+        } catch (e) {
+          if (e.status === 400) return false
+          throw e
+        }
+      },
+      async unsubscribe(token) {
+        await api("/tienda/boletin/baja", { method: "POST", body: { token } })
+        return true
+      },
+    },
+    async applyAsAuthor(a) {
+      const vende = [...new Set((a.sells ?? []).filter((x) => x === "tema" || x === "extension"))]
+      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,
+          slug: a.handle,
+          pais: a.country,
+          web: a.website,
+          stacks: a.stacks,
+          experiencia: a.experience,
+        },
+      })
+      return { id: r.id }
+    },
+    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,

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,73 @@ 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.
+ */
+/**
+ * La licencia de una pieza del mercado comprada en un pedido. La clave es la
+ * credencial con la que el comprador activa el tema o la extensión en su sitio
+ * y con la que abre soporte con el autor: por eso se enseña entera.
+ */
+export interface License {
+  key: string
+  status: "activa" | "caducada" | "anulada"
+  /** Nombre del producto al que da derecho. */
+  title: string | null
+  /** Sitios donde está activada ahora mismo. */
+  sites: number
+  /** Cuántos sitios admite. */
+  limit: number
+  /** Hasta cuándo incluye soporte y versiones nuevas (AAAA-MM-DD). null: sin fecha. */
+  supportedUntil: string | null
+}
+
+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.
+ *
+ * En los listados llega un resumen: `screenshots` y `changelog` vienen vacíos
+ * y se rellenan en `getProduct`, que es donde se enseñan.
+ */
+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 }[]
+  /**
+   * Meses de soporte del autor que incluye la compra (0: sin soporte). Las
+   * versiones nuevas no tienen fecha: le llegan al comprador siempre.
+   */
+  supportMonths?: number
+}
+
 export interface Download {
   id: string
   lineId: string
@@ -149,6 +222,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
@@ -430,6 +505,11 @@ export interface ListProductsParams {
   categoryId?: string
   ids?: string[]
   tags?: string[]
+  /**
+   * 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"
   limit?: number
   offset?: number
   sort?: SortProductos
@@ -445,6 +525,87 @@ 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
+}
+
+/** Lo que manda quien quiere vender en el mercado. Lo revisa una persona. */
+export interface AuthorApplication {
+  /** Nombre con el que publicará. */
+  name: string
+  email: string
+  /** Enlace a algo que haya hecho: sin eso no hay nada que revisar. */
+  portfolio: string
+  sells: ("tema" | "extension")[]
+  /** Identificador público; si falta, sale del nombre. */
+  handle?: string
+  /** Código de dos letras. */
+  country?: string
+  website?: string
+  stacks?: string[]
+  experience?: string
+}
+
+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
@@ -461,10 +622,61 @@ 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[]>
+  /** Opcional: las licencias de las piezas del mercado compradas en un pedido. */
+  getLicenses?(orderId: string): Promise<License[]>
+  /** 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: 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
+   * `err.status` 400 y el motivo en `err.detalle`.
+   */
+  applyAsAuthor?(application: AuthorApplication): Promise<{ id: 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.
+   * Contesta siempre lo mismo para que no sirva para averiguar quién está.
+   */
+  newsletter?: {
+    subscribe(
+      email: string,
+      consent: {
+        /** El texto EXACTO que vio la persona junto a la casilla. Es la prueba. */
+        text: string
+        /** Versión de ese texto: cambia cuando cambia el texto. */
+        version: string
+        locale?: string
+        source?: string
+        ip?: string
+        userAgent?: string
+      },
+    ): Promise<{ status: "pendiente" }>
+    confirm(token: string): Promise<boolean>
+    unsubscribe(token: string): Promise<boolean>
+  }
+  /** 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>