@hostwebhook/platform-contracts 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -11,3 +11,4 @@
  */
 export * from './addons';
 export * from './operadores';
+export * from './servicios';

package/dist/index.js

@@ -27,3 +27,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 __exportStar(require("./addons"), exports);
 __exportStar(require("./operadores"), exports);
+__exportStar(require("./servicios"), exports);

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';

package/dist/servicios/avisos-en-vivo.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Lo que un nodo le manda decir al panel. Nada más.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. `nodes/` y `common/` importaban `ingress/` 18 veces, y
+ * las 18 apuntaban a la MISMA clase:
+ *
+ *   10  `WebhookGateway`         el gateway de Socket.IO
+ *    8  `WebhookGatewayModule`   cableado, desaparece con la mudanza
+ *
+ * `WebhookGateway` es un `@WebSocketGateway` de 2000 líneas: mantiene el
+ * servidor de sockets, las salas por organización, la autenticación de cada
+ * conexión —con sus modelos de `Token`, `User` y `ApiKey`—, el túnel de
+ * desarrollo y las peticiones HTTP en espera. Nada de eso puede vivir en
+ * `hw-nodes`: quien tiene abiertos los sockets del panel es el gateway.
+ *
+ * Lo que el nodo necesita es mucho menos: **decir que algo ha pasado**.
+ *
+ * ## Lo que ya estaba bien
+ *
+ * Los diez métodos reciben datos planos, y no por casualidad: los llamantes
+ * ya hacen `.toJSON()` o pasan por `comoObjetoPlano(...)` antes de emitir.
+ * Aquí no hay ningún documento de Mongoose que aplanar — algo que en la
+ * costura de ficheros costó un adaptador entero.
+ *
+ * ⚠️ Por eso las cargas se declaran `object` y NO `Record<string, unknown>`,
+ * que fue lo primero que escribí. Una firma de índice hace el contrato MÁS
+ * ESTRICTO que la realidad: rechaza lo que devuelve `.toJSON()` de Mongoose
+ * —que no la tiene— y también una interfaz declarada como `PipelineStep`.
+ * Trece errores de compilación que no señalaban ningún dato mal formado,
+ * sólo un contrato mal escrito. Es la segunda vez en esta fase.
+ *
+ * ⚠️ Y una que el inventario evitó: un `grep` de `gateway.<algo>` sacaba
+ * `subscribe` y `unsubscribe` de más. Son de `DiscordGatewayService`, otra
+ * clase que en `discord.provider` también se llama `gateway`. Medir por el
+ * TIPO inyectado y no por el nombre de la propiedad es lo que los descarta.
+ *
+ * ## ⚠️ Nueve avisan, uno CONTESTA
+ *
+ * Nueve de los diez son difusión a la sala `org:<id>`: se mandan y no se
+ * espera nada. Si se pierde uno, el panel enseña un dato viejo hasta que
+ * alguien recargue — molesto y nada más.
+ *
+ * `resolveSyncWaiter` no. Ése completa una **petición HTTP que el gateway
+ * tiene retenida** (el modo síncrono de un webhook): al otro lado hay alguien
+ * esperando una respuesta. Si ese mensaje se pierde, el que llamó se queda
+ * colgado hasta que salte el 408 de `waitForSync`.
+ *
+ * Va en el mismo contrato porque hoy es la misma inyección y su único
+ * llamante es el motor, pero quien implemente esto por red tiene que tratarlo
+ * distinto: los nueve pueden ser «dispara y olvida», éste no.
+ */
+/** Un aviso en vivo al panel de la organización. */
+export interface AvisosEnVivo {
+    emitNewEvent(webhookId: string, orgId: string, evento: object): void;
+    emitEventUpdate(webhookId: string, orgId: string, evento: object): void;
+    emitWebhookUpdate(webhookId: string, orgId: string, webhook: object): void;
+    /** Un paso de pipeline terminó. */
+    emitPipelineStep(orgId: string, paso: object): void;
+    /**
+     * Un nodo FUENTE recibió algo.
+     *
+     * Evento propio y no `pipeline:step` porque un webhook recibiendo tráfico
+     * no ejecuta un paso, y fabricarle uno falso ensucia a quien escucha pasos
+     * de verdad.
+     */
+    emitNodePayload(orgId: string, data: {
+        nodeType: string;
+        nodeId: string;
+        lastPayload: unknown;
+        /** Datos de ejemplo adoptados a mano; viaja aparte del payload. */
+        example?: boolean;
+    }): void;
+    /** Un trigger acaba de recibir algo de su proveedor. */
+    emitTriggerActivity(orgId: string, data: {
+        nodeId: string;
+        lastPushAt: string;
+    }): void;
+    emitApprovalUpdate(orgId: string, data: {
+        type: 'created' | 'resolved';
+        pendingApproval: object;
+    }): void;
+    emitSwRunComplete(orgId: string, swId: string, run: object): void;
+    /**
+     * Un contador de uso cambió. Sin payload: quien escucha vuelve a pedir
+     * `GET /auth/me/usage`.
+     */
+    emitUsageInvalidate(orgId: string): void;
+    /**
+     * ⚠️ Contesta una petición HTTP que el gateway tiene RETENIDA.
+     *
+     * No es difusión. Al otro lado hay un cliente esperando la respuesta de un
+     * webhook en modo síncrono; perder este mensaje lo deja colgado hasta el
+     * 408 de `waitForSync`. Los otros nueve pueden ser «dispara y olvida»; éste
+     * necesita entrega, y por eso está escrito aparte y no mezclado arriba.
+     */
+    resolveSyncWaiter(eventId: string, resultado: {
+        status: number;
+        body: Record<string, unknown>;
+    }): void;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+export declare const AVISOS_EN_VIVO = "AVISOS_EN_VIVO";

package/dist/servicios/avisos-en-vivo.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Lo que un nodo le manda decir al panel. Nada más.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. `nodes/` y `common/` importaban `ingress/` 18 veces, y
+ * las 18 apuntaban a la MISMA clase:
+ *
+ *   10  `WebhookGateway`         el gateway de Socket.IO
+ *    8  `WebhookGatewayModule`   cableado, desaparece con la mudanza
+ *
+ * `WebhookGateway` es un `@WebSocketGateway` de 2000 líneas: mantiene el
+ * servidor de sockets, las salas por organización, la autenticación de cada
+ * conexión —con sus modelos de `Token`, `User` y `ApiKey`—, el túnel de
+ * desarrollo y las peticiones HTTP en espera. Nada de eso puede vivir en
+ * `hw-nodes`: quien tiene abiertos los sockets del panel es el gateway.
+ *
+ * Lo que el nodo necesita es mucho menos: **decir que algo ha pasado**.
+ *
+ * ## Lo que ya estaba bien
+ *
+ * Los diez métodos reciben datos planos, y no por casualidad: los llamantes
+ * ya hacen `.toJSON()` o pasan por `comoObjetoPlano(...)` antes de emitir.
+ * Aquí no hay ningún documento de Mongoose que aplanar — algo que en la
+ * costura de ficheros costó un adaptador entero.
+ *
+ * ⚠️ Por eso las cargas se declaran `object` y NO `Record<string, unknown>`,
+ * que fue lo primero que escribí. Una firma de índice hace el contrato MÁS
+ * ESTRICTO que la realidad: rechaza lo que devuelve `.toJSON()` de Mongoose
+ * —que no la tiene— y también una interfaz declarada como `PipelineStep`.
+ * Trece errores de compilación que no señalaban ningún dato mal formado,
+ * sólo un contrato mal escrito. Es la segunda vez en esta fase.
+ *
+ * ⚠️ Y una que el inventario evitó: un `grep` de `gateway.<algo>` sacaba
+ * `subscribe` y `unsubscribe` de más. Son de `DiscordGatewayService`, otra
+ * clase que en `discord.provider` también se llama `gateway`. Medir por el
+ * TIPO inyectado y no por el nombre de la propiedad es lo que los descarta.
+ *
+ * ## ⚠️ Nueve avisan, uno CONTESTA
+ *
+ * Nueve de los diez son difusión a la sala `org:<id>`: se mandan y no se
+ * espera nada. Si se pierde uno, el panel enseña un dato viejo hasta que
+ * alguien recargue — molesto y nada más.
+ *
+ * `resolveSyncWaiter` no. Ése completa una **petición HTTP que el gateway
+ * tiene retenida** (el modo síncrono de un webhook): al otro lado hay alguien
+ * esperando una respuesta. Si ese mensaje se pierde, el que llamó se queda
+ * colgado hasta que salte el 408 de `waitForSync`.
+ *
+ * Va en el mismo contrato porque hoy es la misma inyección y su único
+ * llamante es el motor, pero quien implemente esto por red tiene que tratarlo
+ * distinto: los nueve pueden ser «dispara y olvida», éste no.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AVISOS_EN_VIVO = void 0;
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+exports.AVISOS_EN_VIVO = 'AVISOS_EN_VIVO';

package/dist/servicios/canal-de-stream.d.ts

@@ -0,0 +1,78 @@
+/**
+ * El canal por el que el ejecutor le va dando trozos a una respuesta que el
+ * gateway tiene RETENIDA.
+ *
+ * ## De dónde sale la forma
+ *
+ * No es difusión. Es el mismo gesto que `resolveSyncWaiter` en
+ * `avisos-en-vivo.ts`, y su comentario lo dice mejor que yo:
+ *
+ *   «Contesta una petición HTTP que el gateway tiene RETENIDA. No es difusión.
+ *    Al otro lado hay un cliente esperando la respuesta.»
+ *
+ * Aquí es un SSE en vez de una respuesta única: el widget de chat mantiene
+ * abierta una conexión y el nodo de IA le manda tokens según los produce.
+ *
+ * ## ⚠️ Por qué NO se reusa `AVISOS_EN_VIVO`
+ *
+ * Porque ese contrato es «un aviso en vivo **al panel de la organización**» y
+ * todo lo suyo va con `orgId`. El visitante de un chat NO es el panel: es
+ * alguien anónimo en la web de un cliente. Mandar sus tokens por una sala de
+ * organización sería una fuga.
+ *
+ * La clave aquí es el STREAM, no la organización.
+ *
+ * ## ⚠️ Y por qué el gateway se queda el SSE
+ *
+ * Se valoró que el widget conectara directo al ejecutor. Se descartó: la puerta
+ * del chat es `@Public()` —sin sesión, porque es un widget en la web de un
+ * cliente—, así que eso le pondría una puerta pública y sin autenticar al
+ * servicio que corre el Code Node con código del usuario. Y habría que
+ * duplicar el control de orígenes, que ya avisa de que «un cliente que no sea
+ * un navegador ignora las cabeceras».
+ *
+ * Una sola puerta pública. El coste es un salto por trozo sobre conexión
+ * persistente, y el ritmo lo pone el modelo, no la red.
+ */
+/**
+ * Lo que viaja por el stream.
+ *
+ * ⚠️ Se declara AQUÍ y no se importa de `ai-nodes`: es lo que cruza la
+ * frontera, así que su forma es parte del contrato y no del ejecutor. Y son
+ * datos planos —cadenas, números, un booleano—, que es lo que hace que pueda
+ * cruzar.
+ */
+export type EventoDeStream = {
+    event: 'token';
+    data: {
+        text: string;
+    };
+} | {
+    event: 'tool_start';
+    data: {
+        name: string;
+        input: Record<string, unknown>;
+    };
+} | {
+    event: 'tool_end';
+    data: {
+        name: string;
+        output: string;
+        success: boolean;
+        durationMs: number;
+    };
+};
+/**
+ * Lo que escribe un trozo en el SSE. Es un callback y por eso NO viaja: quien
+ * lo tiene es el gateway, que sostiene la respuesta.
+ */
+export type EmisorDeStream = (evento: EventoDeStream) => void | Promise<void>;
+export interface CanalDeStream {
+    /**
+     * Un trozo para ese stream. Si nadie lo escucha, se tira sin ruido: quien
+     * cerró la pestaña no es un error.
+     */
+    emitir(streamId: string, evento: EventoDeStream): void;
+}
+/** ⚠️ Cadena y no `Symbol`. */
+export declare const CANAL_DE_STREAM = "CANAL_DE_STREAM";

package/dist/servicios/canal-de-stream.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANAL_DE_STREAM = void 0;
+/** ⚠️ Cadena y no `Symbol`. */
+exports.CANAL_DE_STREAM = 'CANAL_DE_STREAM';