@pcreative/commerce-contract 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2026-present Pcreative
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+The rights granted above may only be exercised to develop and distribute
+applications that integrate or interoperate with pcreative Commerce software or
+services.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @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.**
+
+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.
+
+## 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` y `content` son opcionales: un backend puede no tener cuentas de
+cliente ni blog.
+
+## Tests
+
+```bash
+node --test "test/*.test.js"
+```
+
+Los tests inyectan un `fetch` de mentira, así que corren sin backend.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@pcreative/commerce-contract",
+  "version": "1.0.0",
+  "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",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./api": {
+      "types": "./src/adapters/api.d.ts",
+      "default": "./src/adapters/api.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://pcreative.dev",
+  "bugs": {
+    "email": "soporte@pcreative.dev"
+  }
+}

package/src/adapters/api.d.ts

@@ -0,0 +1,36 @@
+import type { CommerceClient } from "../index.js"
+
+export interface OpcionesCommerce {
+  /** URL del backend, sin barra final. */
+  baseUrl: string
+  /** Clave publicable del canal de venta. */
+  publishableKey?: string
+  /**
+   * Leer el catálogo del comercio propio (`/tienda/*`) en vez del motor
+   * anterior (`/store/*`). **Por defecto `true`**, que es lo que sirve
+   * `npm start`.
+   *
+   * Ponerlo a `false` es la vuelta atrás, y va emparejado con
+   * `npm run start:motor` en el backend. Uno sin el otro deja la tienda vacía
+   * sin dar ningún error.
+   *
+   * 🔴 Esto no estaba declarado aquí, y por eso nadie lo encendía: quien
+   * escribía un tema no podía descubrir que existía. Una opción que solo
+   * conoce quien ha leído el código fuente no es una opción.
+   */
+  catalogoPropio?: boolean
+  /** País de la región por defecto, p.ej. "es". Sin él se usa la primera región. */
+  countryCode?: string
+  /**
+   * Idioma del contenido, p.ej. "en-US". Viaja como cabecera en todas las
+   * peticiones: el idioma es del visitante, no de la consulta. Lo que no esté
+   * traducido vuelve en el idioma original.
+   */
+  locale?: string
+  /** `fetch` alternativo: para tests, o el de un framework con su caché. */
+  fetch?: typeof globalThis.fetch
+  /** Opciones extra por petición (`next: { revalidate }`, `cache`…). */
+  requestInit?: RequestInit
+}
+
+export declare function createCommerce(opciones: OpcionesCommerce): CommerceClient