@hostwebhook/platform-contracts 0.1.0

package/README.md

@@ -0,0 +1,22 @@
+# @hostwebhook/platform-contracts
+
+Contratos compartidos entre los servicios de HostWebhook: lo que cruza una
+frontera y no puede estar escrito dos veces.
+
+Hoy contiene el registro de **addons** — los complementos que se venden aparte
+del plan. La api decide si una petición pasa; el dashboard decide si pinta la
+pantalla o el candado. Los dos leen de aquí.
+
+```ts
+import { ADDONS, tieneAddon, normalizarAddons } from '@hostwebhook/platform-contracts';
+
+tieneAddon(user.plan.addons, 'social');   // → boolean, falla cerrado
+normalizarAddons(['social', 'social']);   // → ['social']
+```
+
+## Qué no va aquí
+
+- Precios e ids de Stripe: viven en la configuración de la api, que es la única
+  que habla con Stripe. Cambiarlos no puede obligar a publicar un paquete.
+- Límites por plan: `plan.constants.ts` en la api.
+- Cualquier cosa que sólo lea un servicio.

package/dist/addons.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Los complementos que se venden aparte del plan.
+ *
+ * ## Por qué esto vive en un paquete y no en la api
+ *
+ * Porque lo leen los dos lados. La api decide si una petición pasa; el
+ * dashboard decide si pinta la pantalla o el candado. Si cada uno escribe la
+ * cadena `'social'` por su cuenta, un día uno de los dos la escribe distinta y
+ * el síntoma es una pantalla que se ve pero no carga — o peor, una que no se
+ * ve aunque esté pagada.
+ *
+ * Es el mismo motivo por el que `NODE_REGISTRY` vive en `@hostwebhook/node-types`
+ * y no en cada repo.
+ *
+ * ## Un addon NO es un plan
+ *
+ * `tier` (free / pro / enterprise) y `addons` son ejes distintos y a propósito.
+ * El Asset Manager y el calendario social no se compran subiendo de plan: se
+ * compran aparte, y quien está en `free` puede tenerlos. `plan.constants.ts`
+ * de la api ya lo dice desde que `maxStorageMB` vale lo mismo en los tres
+ * planes.
+ */
+/** La clave de cada complemento. Es la que viaja en `plan.addons`. */
+export declare const ADDON_KEYS: readonly ["social"];
+export type AddonKey = (typeof ADDON_KEYS)[number];
+export interface AddonDef {
+    key: AddonKey;
+    /** Lo que ve quien lo compra. */
+    label: string;
+    /**
+     * Qué desbloquea, en una línea y en el idioma del usuario, no en el del
+     * código. Sale en la pantalla de venta cuando la puerta está cerrada.
+     */
+    descripcion: string;
+}
+/**
+ * El registro. Añadir un complemento es añadir aquí y en `ADDON_KEYS`.
+ *
+ * ⚠️ Lo que NO va aquí es el precio ni el id de Stripe: eso vive en la
+ * configuración de la api, que es la única que habla con Stripe, y cambiarlo no
+ * puede obligar a publicar un paquete y subir la dependencia en dos repos.
+ */
+export declare const ADDONS: Record<AddonKey, AddonDef>;
+/** ¿Es esta cadena un complemento que existe? Guarda de tipo. */
+export declare function esAddonConocido(valor: unknown): valor is AddonKey;
+/**
+ * ¿Esta cuenta tiene el complemento?
+ *
+ * ⚠️ **Falla cerrado a propósito.** Sin lista, o con una lista que no es un
+ * array, la respuesta es `false` y no `true`. La tentación contraria —«si no
+ * puedo leerlo, que pase»— es la que regala el producto cuando una consulta
+ * falla, y es exactamente el fail-open que ya hubo que quitar de
+ * `topeDeSubida`.
+ *
+ * Se acepta `unknown` porque quien llama suele traerlo de un documento de
+ * Mongo o de un JSON de la api, y ahí el tipo es una promesa, no un hecho.
+ */
+export declare function tieneAddon(addons: unknown, cual: AddonKey): boolean;
+/**
+ * Deja una lista de complementos en su forma canónica: sólo claves conocidas,
+ * sin repetidos y en el orden de `ADDON_KEYS`.
+ *
+ * Existe porque la lista se construye desde las líneas de una suscripción de
+ * Stripe, y de ahí puede llegar con duplicados, con una clave que ya se retiró,
+ * o en el orden en que el webhook las mandó. Guardar eso tal cual hace que dos
+ * cuentas con lo mismo comprado se vean distintas en la base de datos.
+ */
+export declare function normalizarAddons(addons: unknown): AddonKey[];

package/dist/addons.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Los complementos que se venden aparte del plan.
+ *
+ * ## Por qué esto vive en un paquete y no en la api
+ *
+ * Porque lo leen los dos lados. La api decide si una petición pasa; el
+ * dashboard decide si pinta la pantalla o el candado. Si cada uno escribe la
+ * cadena `'social'` por su cuenta, un día uno de los dos la escribe distinta y
+ * el síntoma es una pantalla que se ve pero no carga — o peor, una que no se
+ * ve aunque esté pagada.
+ *
+ * Es el mismo motivo por el que `NODE_REGISTRY` vive en `@hostwebhook/node-types`
+ * y no en cada repo.
+ *
+ * ## Un addon NO es un plan
+ *
+ * `tier` (free / pro / enterprise) y `addons` son ejes distintos y a propósito.
+ * El Asset Manager y el calendario social no se compran subiendo de plan: se
+ * compran aparte, y quien está en `free` puede tenerlos. `plan.constants.ts`
+ * de la api ya lo dice desde que `maxStorageMB` vale lo mismo en los tres
+ * planes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADDONS = exports.ADDON_KEYS = void 0;
+exports.esAddonConocido = esAddonConocido;
+exports.tieneAddon = tieneAddon;
+exports.normalizarAddons = normalizarAddons;
+/** La clave de cada complemento. Es la que viaja en `plan.addons`. */
+exports.ADDON_KEYS = ['social'];
+/**
+ * El registro. Añadir un complemento es añadir aquí y en `ADDON_KEYS`.
+ *
+ * ⚠️ Lo que NO va aquí es el precio ni el id de Stripe: eso vive en la
+ * configuración de la api, que es la única que habla con Stripe, y cambiarlo no
+ * puede obligar a publicar un paquete y subir la dependencia en dos repos.
+ */
+exports.ADDONS = {
+    social: {
+        key: 'social',
+        label: 'Social',
+        descripcion: 'Publishing calendar, media library, and the Calendar tab inside the Social node.',
+    },
+};
+/** ¿Es esta cadena un complemento que existe? Guarda de tipo. */
+function esAddonConocido(valor) {
+    return typeof valor === 'string' && exports.ADDON_KEYS.includes(valor);
+}
+/**
+ * ¿Esta cuenta tiene el complemento?
+ *
+ * ⚠️ **Falla cerrado a propósito.** Sin lista, o con una lista que no es un
+ * array, la respuesta es `false` y no `true`. La tentación contraria —«si no
+ * puedo leerlo, que pase»— es la que regala el producto cuando una consulta
+ * falla, y es exactamente el fail-open que ya hubo que quitar de
+ * `topeDeSubida`.
+ *
+ * Se acepta `unknown` porque quien llama suele traerlo de un documento de
+ * Mongo o de un JSON de la api, y ahí el tipo es una promesa, no un hecho.
+ */
+function tieneAddon(addons, cual) {
+    return Array.isArray(addons) && addons.includes(cual);
+}
+/**
+ * Deja una lista de complementos en su forma canónica: sólo claves conocidas,
+ * sin repetidos y en el orden de `ADDON_KEYS`.
+ *
+ * Existe porque la lista se construye desde las líneas de una suscripción de
+ * Stripe, y de ahí puede llegar con duplicados, con una clave que ya se retiró,
+ * o en el orden en que el webhook las mandó. Guardar eso tal cual hace que dos
+ * cuentas con lo mismo comprado se vean distintas en la base de datos.
+ */
+function normalizarAddons(addons) {
+    if (!Array.isArray(addons))
+        return [];
+    const vistos = new Set();
+    for (const a of addons)
+        if (esAddonConocido(a))
+            vistos.add(a);
+    return exports.ADDON_KEYS.filter((k) => vistos.has(k));
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Contratos compartidos entre los servicios de HostWebhook.
+ *
+ * Lo que entra aquí es lo que **cruza una frontera** —entre la api y el
+ * dashboard hoy, y entre servicios cuando se parta el monolito— y que si se
+ * escribe dos veces, un día se escribe distinto.
+ *
+ * Lo que NO entra: nada específico de un servicio, nada con secretos, y nada
+ * cuyo cambio deba poder desplegarse sin publicar un paquete (precios, ids de
+ * Stripe, límites por plan).
+ */
+export * from './addons';

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Contratos compartidos entre los servicios de HostWebhook.
+ *
+ * Lo que entra aquí es lo que **cruza una frontera** —entre la api y el
+ * dashboard hoy, y entre servicios cuando se parta el monolito— y que si se
+ * escribe dos veces, un día se escribe distinto.
+ *
+ * Lo que NO entra: nada específico de un servicio, nada con secretos, y nada
+ * cuyo cambio deba poder desplegarse sin publicar un paquete (precios, ids de
+ * Stripe, límites por plan).
+ */
+__exportStar(require("./addons"), exports);

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hostwebhook/platform-contracts",
+  "version": "0.1.0",
+  "description": "Contratos compartidos entre los servicios de HostWebhook: addons del plan, identidad interna, y las formas que cruzan una frontera de red",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "hostwebhook",
+    "contracts",
+    "addons"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  }
+}