@hostwebhook/platform-contracts 0.1.0 → 0.3.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,5 @@
  * Stripe, límites por plan).
  */
 export * from './addons';
+export * from './operadores';
+export * from './servicios';

package/dist/index.js

@@ -26,3 +26,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Stripe, límites por plan).
  */
 __exportStar(require("./addons"), exports);
+__exportStar(require("./operadores"), exports);
+__exportStar(require("./servicios"), 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/dist/servicios/almacenes-vectoriales.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Lo que un nodo le pide a un almacén vectorial.
+ *
+ * Costura de la Fase 2, del lote de las pequeñas. `VectorStoresService`
+ * arrastra tres colecciones, los backends de vectores —Atlas, pgvector,
+ * Pinecone—, el cifrado de credenciales y el registro de accesos. El nodo
+ * sólo consulta, inserta y borra.
+ *
+ * ## ⚠️ Lo que NO puede perderse: la marca de quién
+ *
+ * Los tres métodos que TOCAN datos llevan `userId`, `sourceIp` y
+ * `relatedEntity`, y no son telemetría de adorno: son lo que el registro de
+ * accesos del almacén guarda para poder decir quién consultó qué. Hay un
+ * guardián dedicado a eso (`el-nodo-se-firma-en-el-registro.spec.ts`) porque
+ * un nodo que se cuela sin firmar deja el registro mintiendo.
+ *
+ * ⚠️ Y `relatedEntity` es lo que distingue a un nodo de su DUEÑO: un nodo
+ * corre con el `userId` del usuario que lo creó, así que sin la entidad
+ * relacionada la fila del registro dice «lo consultó Ariel» cuando lo
+ * consultó un flujo. Ver `project_el_registro_dice_quien`.
+ */
+/** Quién —o qué— está detrás de una operación sobre el almacén. */
+export interface EntidadRelacionada {
+    type: string;
+    id: string;
+    name?: string;
+}
+/** Un trozo devuelto por una consulta. */
+export interface TrozoEncontrado {
+    chunkId: string;
+    content: string;
+    score: number;
+    sourceDocId?: string;
+    sourceDocName?: string;
+    sourceDocType?: string;
+    metadata?: Record<string, unknown>;
+    createdAt?: Date;
+}
+import type { ChunkingStrategy } from './formas-compartidas';
+/**
+ * El troceo que el almacén trae de fábrica.
+ *
+ * ⚠️ `chunkSize` y `chunkOverlap` son en CARACTERES, no en tokens. Está en el
+ * contrato porque es justo lo que se malinterpreta al leerlo de fuera; ver
+ * `project_vector_store_troceo`.
+ */
+export interface TroceoPorDefecto {
+    strategy: ChunkingStrategy;
+    chunkSize: number;
+    chunkOverlap: number;
+    separators?: string[] | null;
+}
+export interface ConsultaAlAlmacen {
+    query: string;
+    topK?: number;
+    filter?: Record<string, unknown>;
+    minScore?: number;
+}
+export interface BorradoDeTrozos {
+    chunkIds?: string[];
+    sourceDocId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AlmacenesVectoriales {
+    query(storeId: string, orgId: string, dto: ConsultaAlAlmacen, userId: string, sourceIp: string, relatedEntity?: EntidadRelacionada): Promise<{
+        matches: TrozoEncontrado[];
+        tookMs: number;
+        storeName: string;
+        storeId: string;
+    }>;
+    /**
+     * El almacén, para leerle la configuración de troceo por defecto.
+     *
+     * ⚠️ Devuelve SÓLO `chunking`, que es lo único que su llamante lee — se
+     * comprobó campo por campo. El documento entero trae además el backend, sus
+     * credenciales cifradas y el recuento de vectores; nada de eso tiene por
+     * qué cruzar.
+     *
+     * ⚠️ Y lanza si el almacén no es de esa organización. Eso hay que
+     * conservarlo: es la comprobación de propiedad, no un detalle.
+     */
+    getStore(id: string, orgId: string): Promise<{
+        chunking: TroceoPorDefecto;
+    }>;
+    findExistingHashes(storeId: string, orgId: string, hashes: string[]): Promise<string[]>;
+    deleteChunks(storeId: string, orgId: string, dto: BorradoDeTrozos, userId: string, sourceIp: string, relatedEntity?: EntidadRelacionada): Promise<{
+        deletedCount: number;
+    }>;
+    ingestPreChunked(storeId: string, orgId: string, opts: {
+        chunks: Array<{
+            content: string;
+            metadata?: Record<string, unknown>;
+        }>;
+        sourceDocId?: string;
+        sourceDocName?: string;
+        sourceDocType?: string;
+        baseMetadata?: Record<string, unknown>;
+    }, userId: string, sourceIp: string, relatedEntity?: EntidadRelacionada): Promise<{
+        chunksInserted: number;
+        skipped: number;
+        bytes: number;
+    }>;
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+export declare const ALMACENES_VECTORIALES = "ALMACENES_VECTORIALES";

package/dist/servicios/almacenes-vectoriales.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Lo que un nodo le pide a un almacén vectorial.
+ *
+ * Costura de la Fase 2, del lote de las pequeñas. `VectorStoresService`
+ * arrastra tres colecciones, los backends de vectores —Atlas, pgvector,
+ * Pinecone—, el cifrado de credenciales y el registro de accesos. El nodo
+ * sólo consulta, inserta y borra.
+ *
+ * ## ⚠️ Lo que NO puede perderse: la marca de quién
+ *
+ * Los tres métodos que TOCAN datos llevan `userId`, `sourceIp` y
+ * `relatedEntity`, y no son telemetría de adorno: son lo que el registro de
+ * accesos del almacén guarda para poder decir quién consultó qué. Hay un
+ * guardián dedicado a eso (`el-nodo-se-firma-en-el-registro.spec.ts`) porque
+ * un nodo que se cuela sin firmar deja el registro mintiendo.
+ *
+ * ⚠️ Y `relatedEntity` es lo que distingue a un nodo de su DUEÑO: un nodo
+ * corre con el `userId` del usuario que lo creó, así que sin la entidad
+ * relacionada la fila del registro dice «lo consultó Ariel» cuando lo
+ * consultó un flujo. Ver `project_el_registro_dice_quien`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALMACENES_VECTORIALES = void 0;
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+exports.ALMACENES_VECTORIALES = 'ALMACENES_VECTORIALES';

package/dist/servicios/aprobaciones-pendientes.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Lo que una PUERTA del gateway necesita de las aprobaciones pendientes.
+ *
+ * ## Por qué existe
+ *
+ * `source-nodes/triggers` —el trigger de Telegram— y `social-posts` viven en el
+ * gateway; `approval-nodes` se muda a hw-nodes. Entre los dos había cuatro
+ * llamadas directas a `ApprovalNodesService`, y una de ellas pasaba un
+ * **documento de Mongoose vivo** al motor.
+ *
+ * ## 🔥 Por qué el contrato NO es «los mismos cuatro métodos»
+ *
+ * El código de hoy hace esto:
+ *
+ *     const fila = await pendingService.resolvePendingByToken({…});
+ *     await eventPipeline.resumeAfterSendAndWait(fila, {…});
+ *
+ * O sea: la puerta resuelve la fila y le pasa el DOCUMENTO al motor, que le lee
+ * seis campos más (`eventId`, `organizationId`, `webhookId`, `payload`,
+ * `eventHeaders`, `id`). Un documento de Mongoose no cruza una red, así que
+ * copiar esos métodos tal cual obligaría a serializar la fila entera y a
+ * mantener las dos formas en paralelo.
+ *
+ * Pero es que no hace falta: **el motor y las aprobaciones están del MISMO
+ * lado**. Los dos se van a hw-nodes. Lo único que cruza es la decisión —quién
+ * pulsó, cuándo, qué escribió—, y el documento se queda donde vive.
+ *
+ * Por eso hay un solo método para las dos cosas, `resolverYReanudar`.
+ *
+ * ## ⚠️ La distinción que hay que conservar
+ *
+ * Hoy los dos fallos NO se tratan igual, y eso es visible para el usuario:
+ *
+ *   - si no se puede RESOLVER la fila, a Telegram le vuelve «No pude registrar
+ *     tu respuesta. Inténtalo de nuevo»;
+ *   - si falla el REANUDADO, se registra y ya: la fila está resuelta, el
+ *     usuario ve su confirmación, y volver a lanzar aguas abajo necesitaría a
+ *     un operador de todas formas.
+ *
+ * Por eso `resolverYReanudar` devuelve un booleano que habla SÓLO de la
+ * resolución. Fundir los dos fallos en uno cambiaría lo que ve el usuario sin
+ * tocar una línea de la UI.
+ */
+/** La fila pendiente, en lo que la puerta lee de ella. Seis campos, medidos. */
+export interface AprobacionPendiente {
+    /** El `id` virtual de Mongoose, ya en cadena. */
+    id: string;
+    /** `pending` | `approved` | `rejected` | `expired`. */
+    status: string;
+    /** De dónde salió: `telegramSendAndWait`, `approval`, `socialMedia`… */
+    source: string;
+    /** El contexto con el que se creó. La puerta lo lee entero y opaco. */
+    pipelineContext: Record<string, unknown>;
+    /** El nodo que la pidió, o `null` si no hubo uno. */
+    sourceNodeId: string | null;
+    /** El token con el que se resuelve. */
+    resolveToken: string;
+    /** De quién es. Las puertas públicas lo necesitan para acotar sus lecturas. */
+    organizationId: string;
+    /** El evento que la creó, si lo hubo. */
+    eventId: string | null;
+    /** El webhook que lo trajo, si lo hubo. */
+    webhookId: string | null;
+    /** Cuándo se pidió y cuándo caduca — la página se lo dice a quien llega
+     *  tarde. */
+    requestedAt: Date | null;
+    expiresAt: Date | null;
+}
+/** Quién decidió, cuándo y qué dijo. Es lo único que cruza. */
+export interface DecisionSobrePendiente {
+    token: string;
+    aprobada: boolean;
+    decidedAt: Date;
+    /** Etiqueta legible: `telegram:ariel`, `telegram-callback`… */
+    decidedBy: string;
+    /** De dónde vino la decisión, para la auditoría. */
+    ipAddress: string;
+    comment?: string;
+    /**
+     * La respuesta escrita a mano, cuando la hay.
+     *
+     * ⚠️ Sólo el camino de texto libre de Telegram la trae; un botón no. Sale en
+     * `_waitResponse.responseText` para que un Conditional o un nodo de IA de
+     * abajo puedan leerla.
+     */
+    responseText?: string;
+}
+export interface AprobacionesPendientes {
+    /** La fila de ese token, o `null` si no existe. */
+    porToken(token: string): Promise<AprobacionPendiente | null>;
+    /**
+     * La pendiente MÁS ANTIGUA de ese chat de Telegram que admita texto libre.
+     *
+     * ⚠️ Primero en llegar, primero en resolverse: si un chat tiene dos
+     * esperando, la respuesta escrita resuelve la de arriba. Y la comparación va
+     * por tipo exacto —`telegramChatId` se guarda como NÚMERO y `allowFreeText`
+     * como BOOLEANO—, o una coerción de cadena a número deja de encontrar la
+     * fila sin decir nada.
+     */
+    deTelegram(orgId: string, chatId: number | string): Promise<AprobacionPendiente | null>;
+    /**
+     * Resuelve la fila y reanuda el flujo, del otro lado y en proceso.
+     *
+     * ⚠️ El booleano habla SÓLO de la resolución. Un fallo al reanudar se
+     * registra y devuelve `true`, porque la fila ya está resuelta y el usuario ya
+     * tiene su confirmación. Ver la cabecera.
+     */
+    resolverYReanudar(decision: DecisionSobrePendiente): Promise<boolean>;
+    /**
+     * Resuelve por ID y reanuda. Hermana de `resolverYReanudar`.
+     *
+     * ⚠️ Son DOS y no una porque abajo hay dos métodos distintos, no dos
+     * nombres del mismo: `resolvePendingByToken` empareja por token, y `resolve`
+     * empareja por id Y comprueba `allowedApproverIds` cuando hay un usuario
+     * detrás. Fundirlas aquí escondería esa comprobación —una aprobación
+     * restringida al director la resolvía cualquier empleado hasta que se
+     * arregló—, así que cada puerta llama a la suya.
+     *
+     * El enlace de un clic no trae identidad: resuelve con una etiqueta, así que
+     * la comprobación de aprobador no le aplica. Pero el método sí es el otro.
+     */
+    resolverPorIdYReanudar(decision: {
+        pendingId: string;
+        orgId: string;
+        aprobada: boolean;
+        decidedAt: Date;
+        /** Etiqueta, no identidad: en un enlace de un clic sólo hay una IP. */
+        decidedBy: string;
+        ipAddress?: string;
+        comment?: string;
+    }): Promise<boolean>;
+    /**
+     * Resuelve y NO encadena nada. Devuelve la fila resuelta, aplanada.
+     *
+     * ⚠️ Es la tercera resolución del contrato, y las tres existen porque lo que
+     * SIGUE a una resolución es distinto en cada puerta:
+     *
+     *   `resolverYReanudar`         resuelve por token  → reanuda el flujo
+     *   `resolverPorIdYReanudar`    resuelve por id     → reanuda el flujo
+     *   `resolverAprobacionDeRedes` resuelve por token  → nada, el que llama decide
+     *
+     * La de redes se bifurca DESPUÉS: un post del calendario se publica por su
+     * camino, que es del gateway, y el plan de un nodo por el suyo, que es del
+     * ejecutor. Fundir eso aquí obligaría al contrato a saber de calendarios.
+     *
+     * ⚠️ Devuelve la fila porque quien llama necesita su `pipelineContext` para
+     * elegir la rama — y `null` cuando no ganó la reclamación, que es lo que
+     * distingue «resuelta por mí» de «alguien se me adelantó».
+     */
+    resolverAprobacionDeRedes(decision: {
+        token: string;
+        aprobada: boolean;
+        decidedBy: string;
+        comment?: string | null;
+    }): Promise<AprobacionPendiente | null>;
+    /**
+     * Publica el plan de una fila que QUIEN LLAMA acaba de reclamar.
+     *
+     * ⚠️ El nombre lo dice a propósito: la garantía de una sola publicación no la
+     * da el estado de la fila, la da haber ganado la reclamación. Llamar a esto
+     * sin haberla ganado es un error, y del otro lado se rechaza.
+     */
+    publicarPlanReclamado(pendingId: string, orgId: string): Promise<{
+        statusCode: number;
+        responseBody: string;
+    }>;
+    /**
+     * ¿La página de rechazo tiene que pedir un comentario?
+     *
+     * ⚠️ Sale de `operationConfig.requireDisapproveComment` del nodo que creó la
+     * pendiente —Gmail primero, Email de respaldo, porque `sendAndWaitForResponse`
+     * pasó al nodo de Gmail al repartirse y los pendientes de antes apuntan a la
+     * fila vieja—. Es UN booleano, así que se pide en vez de traerse el nodo: el
+     * gateway sólo tiene que pintar la página.
+     *
+     * ⚠️ Y va en su propio método, no en `AprobacionPendiente`: sólo hace falta
+     * en el camino de rechazo, y meterlo en la fila obligaría a dos búsquedas
+     * extra en CADA lectura.
+     */
+    pideComentarioAlRechazar(pendingId: string): Promise<{
+        /** Si es `false`, el rechazo sigue siendo de un clic. */
+        pide: boolean;
+        /** Los dos textos de la página, tal y como los configuró quien monta el
+         *  flujo. `undefined` deja el de por defecto. */
+        label?: string;
+        placeholder?: string;
+    }>;
+    /** Da de alta la aprobación de una publicación en redes. */
+    crearParaAprobacionDeRedes(params: {
+        sourceNodeId: string;
+        eventId: string;
+        webhookId: string;
+        orgId: string;
+        payload: Record<string, unknown>;
+        headers: Record<string, unknown>;
+        plan: Record<string, unknown>;
+        timeoutMinutes: number;
+    }): Promise<{
+        id: string;
+        resolveToken: string;
+    }>;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que los otros tokens de esta fase: un
+ * `Symbol` no sobrevive a una frontera de módulo duplicada.
+ */
+export declare const APROBACIONES_PENDIENTES = "APROBACIONES_PENDIENTES";

package/dist/servicios/aprobaciones-pendientes.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Lo que una PUERTA del gateway necesita de las aprobaciones pendientes.
+ *
+ * ## Por qué existe
+ *
+ * `source-nodes/triggers` —el trigger de Telegram— y `social-posts` viven en el
+ * gateway; `approval-nodes` se muda a hw-nodes. Entre los dos había cuatro
+ * llamadas directas a `ApprovalNodesService`, y una de ellas pasaba un
+ * **documento de Mongoose vivo** al motor.
+ *
+ * ## 🔥 Por qué el contrato NO es «los mismos cuatro métodos»
+ *
+ * El código de hoy hace esto:
+ *
+ *     const fila = await pendingService.resolvePendingByToken({…});
+ *     await eventPipeline.resumeAfterSendAndWait(fila, {…});
+ *
+ * O sea: la puerta resuelve la fila y le pasa el DOCUMENTO al motor, que le lee
+ * seis campos más (`eventId`, `organizationId`, `webhookId`, `payload`,
+ * `eventHeaders`, `id`). Un documento de Mongoose no cruza una red, así que
+ * copiar esos métodos tal cual obligaría a serializar la fila entera y a
+ * mantener las dos formas en paralelo.
+ *
+ * Pero es que no hace falta: **el motor y las aprobaciones están del MISMO
+ * lado**. Los dos se van a hw-nodes. Lo único que cruza es la decisión —quién
+ * pulsó, cuándo, qué escribió—, y el documento se queda donde vive.
+ *
+ * Por eso hay un solo método para las dos cosas, `resolverYReanudar`.
+ *
+ * ## ⚠️ La distinción que hay que conservar
+ *
+ * Hoy los dos fallos NO se tratan igual, y eso es visible para el usuario:
+ *
+ *   - si no se puede RESOLVER la fila, a Telegram le vuelve «No pude registrar
+ *     tu respuesta. Inténtalo de nuevo»;
+ *   - si falla el REANUDADO, se registra y ya: la fila está resuelta, el
+ *     usuario ve su confirmación, y volver a lanzar aguas abajo necesitaría a
+ *     un operador de todas formas.
+ *
+ * Por eso `resolverYReanudar` devuelve un booleano que habla SÓLO de la
+ * resolución. Fundir los dos fallos en uno cambiaría lo que ve el usuario sin
+ * tocar una línea de la UI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APROBACIONES_PENDIENTES = void 0;
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que los otros tokens de esta fase: un
+ * `Symbol` no sobrevive a una frontera de módulo duplicada.
+ */
+exports.APROBACIONES_PENDIENTES = 'APROBACIONES_PENDIENTES';