@hostwebhook/platform-contracts 0.1.0 → 0.2.0

package/README.md

@@ -3,20 +3,80 @@
 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í.
+Cero dependencias de runtime, a propósito — el dashboard lo carga en el
+navegador.
+
+## 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 nada en absoluto. Los dos leen
+de aquí.
 
 ```ts
 import { ADDONS, tieneAddon, normalizarAddons } from '@hostwebhook/platform-contracts';
 
-tieneAddon(user.plan.addons, 'social');   // → boolean, falla cerrado
+tieneAddon(user.plan.addons, 'social');   // → boolean, falla CERRADO
 normalizarAddons(['social', 'social']);   // → ['social']
 ```
 
+⚠️ `tieneAddon` falla **cerrado**: ante una entrada que no entiende, dice que
+no. Es lo contrario que `llevaValor` de abajo, y la diferencia es deliberada —
+lo seguro al conceder acceso es negar; lo seguro al pintar un formulario es
+enseñar el campo.
+
+## Operadores
+
+Las dos listas de operadores, con los tipos derivados de ellas.
+
+```ts
+import {
+  FILTER_OPERATORS,   // 30 — los que evalúa `filter-utils` del node-sdk
+  ROUTER_OPERATORS,   //  9 — los que evalúa `RoutersService` de la api
+  llevaValor,
+  type FilterOperator,
+  type RouterOperator,
+} from '@hostwebhook/platform-contracts';
+
+llevaValor('exists');   // → false: el formulario esconde el campo del valor
+llevaValor('eq');       // → true
+```
+
+⚠️ **`ROUTER_OPERATORS` no es `FILTER_OPERATORS` recortada.** Tiene `in` y
+`not_in`, que `filter-utils` no sabe resolver, y le faltan los otros 23. Son
+dos evaluadores distintos. Darle los 30 al router permitiría guardar reglas que
+su `switch` no resuelve: caerían en el `default: false` y la regla nunca
+casaría — sin dar error, que es lo que lo hace difícil de ver.
+
+### Por qué las listas están aquí y no junto a sus evaluadores
+
+La regla natural sería «la lista vive pegada al `switch` que la resuelve». Pero
+el dashboard también las necesita, para pintar los desplegables, y el evaluador
+de filtros vive en `@hostwebhook/node-sdk`, que arrastra `re2` y medio runtime
+de nodos. Importarlo desde el navegador para leer treinta cadenas sería pagar
+un bundle entero por una constante.
+
+Así que la regla se afina:
+
+> la **definición** vive aquí, donde no hay dependencias de runtime; el **test**
+> que la ata a su evaluador vive con el evaluador.
+
+Quién ata cada una:
+
+| lista | quién la ata | contra qué |
+|---|---|---|
+| `FILTER_OPERATORS` | `node-sdk/__tests__/una-sola-lista-de-operadores` | los `case` de `filter-utils.ts` |
+| `ROUTER_OPERATORS` | `api/src/nodes/una-sola-lista-de-operadores.spec` | los `case` de `routers.service.ts` |
+
+⚠️ Si un evaluador se muda, **su test se muda con él**. Una lista aquí sin
+nadie que la ate al otro lado es una lista que vuelve a divergir — que es
+exactamente de donde se venía: había seis copias de los operadores de filtro y
+ninguna igual a otra.
+
 ## 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.
+- Etiquetas de pantalla: cómo se llama un operador para el usuario es cosa del
+  dashboard (`lib/operadores.ts`). Aquí van las claves, no los textos.
 - Cualquier cosa que sólo lea un servicio.

package/dist/index.d.ts

@@ -10,3 +10,4 @@
  * Stripe, límites por plan).
  */
 export * from './addons';
+export * from './operadores';

package/dist/index.js

@@ -26,3 +26,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Stripe, límites por plan).
  */
 __exportStar(require("./addons"), exports);
+__exportStar(require("./operadores"), exports);

package/dist/operadores.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Los operadores de filtro y de router.
+ *
+ * ## Por qué están AQUÍ y no donde vive el evaluador
+ *
+ * La regla natural sería «la lista vive pegada al `switch` que la resuelve»,
+ * y durante un rato lo estuvo. Pero el dashboard también necesita las listas
+ * —para pintar los desplegables— y el evaluador de filtros vive en
+ * `@hostwebhook/node-sdk`, que arrastra `re2` y medio runtime de nodos.
+ * Importarlo desde el navegador para leer treinta cadenas sería pagar un
+ * bundle entero por una constante.
+ *
+ * Así que la regla se afina: **la definición vive aquí, en el paquete que no
+ * tiene dependencias de runtime; el test que la ata a su evaluador vive con
+ * el evaluador.** La garantía es la misma —la lista no puede separarse de lo
+ * que la resuelve— y quien sólo necesita leerla no se trae el motor.
+ *
+ * Quién ata cada una:
+ *
+ *   `FILTER_OPERATORS` → `node-sdk/__tests__/una-sola-lista-de-operadores`
+ *                        contra los `case` de `filter-utils.ts`
+ *   `ROUTER_OPERATORS` → `api/src/nodes/una-sola-lista-de-operadores.spec`
+ *                        contra los `case` de `routers.service.ts`
+ *
+ * ⚠️ Si alguna de esas dos casas se muda, el test se muda con ella. Una lista
+ * aquí sin nadie que la ate al otro lado es una lista que vuelve a divergir.
+ */
+/**
+ * Lo que `filter-utils` sabe evaluar. Treinta.
+ *
+ * ⚠️ No incluye `in` ni `not_in`: esos son del router, que tiene otro
+ * evaluador. Ver `ROUTER_OPERATORS` abajo.
+ */
+export declare const FILTER_OPERATORS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "contains", "not_contains", "starts_with", "not_starts_with", "ends_with", "not_ends_with", "matches_regex", "is_empty", "is_not_empty", "exists", "not_exists", "has_key", "is_true", "is_false", "array_contains", "array_not_contains", "array_empty", "array_not_empty", "array_length_eq", "array_length_gt", "array_length_lt", "date_eq", "date_before", "date_after"];
+export type FilterOperator = (typeof FILTER_OPERATORS)[number];
+/**
+ * Lo que `RoutersService.evaluateRule` sabe resolver. Nueve.
+ *
+ * ⚠️ **Parece la lista de arriba recortada y no lo es.** Tiene dos que allí no
+ * existen —`in` y `not_in`, que parten el valor por comas y miran si el del
+ * campo está dentro— y le faltan los otros veintitrés.
+ *
+ * Por eso no se unifican. Si el router heredara los treinta, se podrían
+ * guardar reglas que su `switch` no resuelve: caerían en el `default: false`
+ * y la regla nunca casaría. No daría error — sencillamente no enrutaría, que
+ * es más difícil de ver que un fallo.
+ *
+ * Quien quiera unificarlas de verdad tiene que escribir los `case` primero.
+ */
+export declare const ROUTER_OPERATORS: readonly ["eq", "neq", "contains", "gt", "lt", "exists", "not_exists", "in", "not_in"];
+export type RouterOperator = (typeof ROUTER_OPERATORS)[number];
+/**
+ * Los operadores que no llevan valor.
+ *
+ * Sirve a los dos lados: el formulario esconde el campo del valor y el
+ * resumen de un vistazo no escribe «existe undefined». Es una propiedad del
+ * operador, no de la pantalla, así que se declara una vez.
+ */
+export declare const OPERADORES_SIN_VALOR: readonly ["exists", "not_exists", "is_empty", "is_not_empty", "is_true", "is_false", "array_empty", "array_not_empty"];
+export declare function llevaValor(operador: string): boolean;

package/dist/operadores.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Los operadores de filtro y de router.
+ *
+ * ## Por qué están AQUÍ y no donde vive el evaluador
+ *
+ * La regla natural sería «la lista vive pegada al `switch` que la resuelve»,
+ * y durante un rato lo estuvo. Pero el dashboard también necesita las listas
+ * —para pintar los desplegables— y el evaluador de filtros vive en
+ * `@hostwebhook/node-sdk`, que arrastra `re2` y medio runtime de nodos.
+ * Importarlo desde el navegador para leer treinta cadenas sería pagar un
+ * bundle entero por una constante.
+ *
+ * Así que la regla se afina: **la definición vive aquí, en el paquete que no
+ * tiene dependencias de runtime; el test que la ata a su evaluador vive con
+ * el evaluador.** La garantía es la misma —la lista no puede separarse de lo
+ * que la resuelve— y quien sólo necesita leerla no se trae el motor.
+ *
+ * Quién ata cada una:
+ *
+ *   `FILTER_OPERATORS` → `node-sdk/__tests__/una-sola-lista-de-operadores`
+ *                        contra los `case` de `filter-utils.ts`
+ *   `ROUTER_OPERATORS` → `api/src/nodes/una-sola-lista-de-operadores.spec`
+ *                        contra los `case` de `routers.service.ts`
+ *
+ * ⚠️ Si alguna de esas dos casas se muda, el test se muda con ella. Una lista
+ * aquí sin nadie que la ate al otro lado es una lista que vuelve a divergir.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPERADORES_SIN_VALOR = exports.ROUTER_OPERATORS = exports.FILTER_OPERATORS = void 0;
+exports.llevaValor = llevaValor;
+/* ── Filtros ─────────────────────────────────────────────────────── */
+/**
+ * Lo que `filter-utils` sabe evaluar. Treinta.
+ *
+ * ⚠️ No incluye `in` ni `not_in`: esos son del router, que tiene otro
+ * evaluador. Ver `ROUTER_OPERATORS` abajo.
+ */
+exports.FILTER_OPERATORS = [
+    /* Comparación */
+    'eq',
+    'neq',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    /* Texto */
+    'contains',
+    'not_contains',
+    'starts_with',
+    'not_starts_with',
+    'ends_with',
+    'not_ends_with',
+    'matches_regex',
+    'is_empty',
+    'is_not_empty',
+    /* Presencia */
+    'exists',
+    'not_exists',
+    'has_key',
+    /* Booleanos */
+    'is_true',
+    'is_false',
+    /* Listas */
+    'array_contains',
+    'array_not_contains',
+    'array_empty',
+    'array_not_empty',
+    'array_length_eq',
+    'array_length_gt',
+    'array_length_lt',
+    /* Fechas */
+    'date_eq',
+    'date_before',
+    'date_after',
+];
+/* ── Router ──────────────────────────────────────────────────────── */
+/**
+ * Lo que `RoutersService.evaluateRule` sabe resolver. Nueve.
+ *
+ * ⚠️ **Parece la lista de arriba recortada y no lo es.** Tiene dos que allí no
+ * existen —`in` y `not_in`, que parten el valor por comas y miran si el del
+ * campo está dentro— y le faltan los otros veintitrés.
+ *
+ * Por eso no se unifican. Si el router heredara los treinta, se podrían
+ * guardar reglas que su `switch` no resuelve: caerían en el `default: false`
+ * y la regla nunca casaría. No daría error — sencillamente no enrutaría, que
+ * es más difícil de ver que un fallo.
+ *
+ * Quien quiera unificarlas de verdad tiene que escribir los `case` primero.
+ */
+exports.ROUTER_OPERATORS = [
+    'eq',
+    'neq',
+    'contains',
+    'gt',
+    'lt',
+    'exists',
+    'not_exists',
+    'in',
+    'not_in',
+];
+/* ── Lo que tienen en común ──────────────────────────────────────── */
+/**
+ * Los operadores que no llevan valor.
+ *
+ * Sirve a los dos lados: el formulario esconde el campo del valor y el
+ * resumen de un vistazo no escribe «existe undefined». Es una propiedad del
+ * operador, no de la pantalla, así que se declara una vez.
+ */
+exports.OPERADORES_SIN_VALOR = [
+    'exists',
+    'not_exists',
+    'is_empty',
+    'is_not_empty',
+    'is_true',
+    'is_false',
+    'array_empty',
+    'array_not_empty',
+];
+function llevaValor(operador) {
+    return !exports.OPERADORES_SIN_VALOR.includes(operador);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/platform-contracts",
-  "version": "0.1.0",
+  "version": "0.2.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",