@hostwebhook/platform-contracts 0.1.0 → 0.3.0

package/dist/servicios/posts-sociales.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Lo que el nodo de redes le pide al calendario de publicaciones.
+ *
+ * Costura de la Fase 2, del lote de las pequeñas. `SocialPostsService`
+ * arrastra la colección de posts, el planificador por zona horaria y el
+ * publicador con sus siete proveedores. El nodo publica y deja constancia.
+ *
+ * ## Cómo viaja
+ *
+ * ⚠️ `publicarDesdeNodo` devolvía un documento de Mongoose. Su llamante lee
+ * TRES campos —`id`, `status` y `results`— y nada más; se comprobó llamante
+ * por llamante. El contrato devuelve esos tres, planos.
+ *
+ * ⚠️ `publishApproved` devuelve `null` cuando el post sigue esperando su hora,
+ * y eso NO es un error: el llamante lo distingue en el log («sigue esperando
+ * su hora»). Un contrato que lanzara en vez de devolver `null` convertiría un
+ * caso normal en un fallo.
+ */
+/** Una fila por (red × cuenta): de aquí sale el `3/7` del parcial. */
+export interface ResultadoDePublicacion {
+    platform: string;
+    credentialId: string;
+    success: boolean;
+    url?: string;
+    error?: string;
+}
+/** Lo que el nodo lee de un post recién creado. Tres campos. */
+export interface PostCreado {
+    id: string;
+    status: string;
+    results: ResultadoDePublicacion[];
+}
+export interface PostsSociales {
+    publicarDesdeNodo(params: {
+        orgId: string;
+        workspaceId: string;
+        ownerUserId: string;
+        sourceNodeId?: string;
+        entityName?: string;
+        platforms: string[];
+        credentialIds: Record<string, string[]>;
+        text: string;
+        media?: Array<Record<string, unknown>>;
+        perNetwork?: Record<string, {
+            text?: string;
+            media?: unknown[];
+        }>;
+    }): Promise<PostCreado>;
+    /** Deja constancia de lo que ya publicó el flujo por su cuenta. */
+    recordFlowPost(params: {
+        orgId: string;
+        workspaceId: string;
+        sourceNodeId?: string;
+        text?: string;
+        media?: Array<Record<string, unknown>>;
+        results: Array<{
+            platform: string;
+            credentialId: string;
+            success: boolean;
+            url?: string;
+            error?: string;
+        }>;
+    }): Promise<void>;
+    /** ⚠️ `null` = aprobado pero aún no le toca. No es un error. */
+    publishApproved(postId: string, porQuien?: string): Promise<string | null>;
+    rejectApproval(postId: string, porQuien?: string): Promise<void>;
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+export declare const POSTS_SOCIALES = "POSTS_SOCIALES";

package/dist/servicios/posts-sociales.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Lo que el nodo de redes le pide al calendario de publicaciones.
+ *
+ * Costura de la Fase 2, del lote de las pequeñas. `SocialPostsService`
+ * arrastra la colección de posts, el planificador por zona horaria y el
+ * publicador con sus siete proveedores. El nodo publica y deja constancia.
+ *
+ * ## Cómo viaja
+ *
+ * ⚠️ `publicarDesdeNodo` devolvía un documento de Mongoose. Su llamante lee
+ * TRES campos —`id`, `status` y `results`— y nada más; se comprobó llamante
+ * por llamante. El contrato devuelve esos tres, planos.
+ *
+ * ⚠️ `publishApproved` devuelve `null` cuando el post sigue esperando su hora,
+ * y eso NO es un error: el llamante lo distingue en el log («sigue esperando
+ * su hora»). Un contrato que lanzara en vez de devolver `null` convertiría un
+ * caso normal en un fallo.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POSTS_SOCIALES = void 0;
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+exports.POSTS_SOCIALES = 'POSTS_SOCIALES';

package/dist/servicios/registro-de-entregas.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Lo que el motor apunta y consulta sobre las entregas.
+ *
+ * ## Por qué esta costura es distinta de las trece anteriores
+ *
+ * Las otras invertían un SERVICIO. Ésta invierte el acceso directo a una
+ * COLECCIÓN: `nodes/` y el motor inyectaban `Model<DeliveryDocument>` y
+ * consultaban `deliveries` a mano.
+ *
+ * Por eso se dejó fuera del lote del #468: cerrarla obliga a decidir de quién
+ * es la colección. La respuesta, mirando lo que se hace con ella, es que es
+ * del gateway — `deliveries` es lo que el panel enseña como historial de
+ * entregas, tiene su propia política de retención en `plans/` y su controlador
+ * de reintentos. El motor sólo escribe filas y pregunta si ya escribió una.
+ *
+ * ## Las tres operaciones, medidas
+ *
+ *   3  `exists`      la comprobación de IDEMPOTENCIA de email, sheets y
+ *                    notificaciones
+ *   3  `create`      la fila de cada entrega, con la misma forma las tres
+ *   2  `deleteMany`  las dos cascadas: por webhook y por evento
+ *
+ * ## ⚠️ Lo que no se puede perder
+ *
+ * **`soloSiTuvoExito`.** El chequeo de notificaciones añade `success: true` al
+ * filtro cuando `triggerOn` NO es `'always'`. Perder esa condición tiene dos
+ * caras y las dos son malas: sin ella, una notificación que falló cuenta como
+ * entregada y no se reintenta nunca; con ella siempre puesta, una que sí se
+ * mandó se manda otra vez en cada reintento del evento.
+ *
+ * **`refIdIn` en el borrado.** `webhookId` se guarda como cadena en unas filas
+ * y como `ObjectId` en otras. Filtrar por una sola forma deja la mitad de las
+ * entregas huérfanas — que es justo lo que la cascada existe para evitar. El
+ * contrato recibe los ids en crudo y la conversión se queda en el gateway,
+ * donde vive el problema.
+ *
+ * ## Cómo viaja
+ *
+ * Bien: entran y salen datos planos, y `anotar` es «dispara y olvida» —el SDK
+ * ya la llama con `.catch()` colgado, sin esperarla—.
+ */
+/** Una fila del historial de entregas. */
+export interface EntregaAnotada {
+    eventId: string;
+    webhookId?: string;
+    emailActionId?: string;
+    sheetsActionId?: string;
+    notificationActionId?: string;
+    targetUrl?: string;
+    attempt?: number;
+    statusCode?: number;
+    responseBody?: string;
+    latencyMs?: number;
+    success?: boolean;
+    error?: string | null;
+}
+export interface RegistroDeEntregas {
+    /**
+     * ¿Ya se entregó esto para este evento?
+     *
+     * ⚠️ `soloSiTuvoExito` NO es opcional en el sentido de «da igual»: cambia
+     * qué cuenta como entregado. Ver la cabecera.
+     */
+    yaSeEntrego(filtro: {
+        eventId: string;
+        emailActionId?: string;
+        sheetsActionId?: string;
+        notificationActionId?: string;
+        soloSiTuvoExito?: boolean;
+    }): Promise<boolean>;
+    /** ⚠️ No se espera. El SDK la llama con un `.catch()` colgado. */
+    anotar(entrega: EntregaAnotada): Promise<void>;
+    /**
+     * La cascada al borrar webhooks.
+     *
+     * ⚠️ Recibe los ids en crudo a propósito: la conversión a las dos formas en
+     * que se guardan —cadena y `ObjectId`— se queda en el gateway. Ver la
+     * cabecera.
+     */
+    borrarDeWebhooks(webhookIds: ReadonlyArray<string>): Promise<void>;
+    /**
+     * La otra cascada: al borrar un trigger, sus entregas.
+     *
+     * ⚠️ Va por `eventId` y NO por `webhookId`, y ésa es toda la razón de que
+     * sean dos métodos. Las entregas se indexan por el evento; el llamante tiene
+     * que recoger los ids de evento ANTES de borrar los eventos, porque después
+     * no queda nada por lo que resolverlos y se quedan huérfanas en silencio.
+     * Ver `cascade-trigger-events.ts`, que existe justo por eso.
+     */
+    borrarDeEventos(eventIds: ReadonlyArray<string>): Promise<void>;
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+export declare const REGISTRO_DE_ENTREGAS = "REGISTRO_DE_ENTREGAS";

package/dist/servicios/registro-de-entregas.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Lo que el motor apunta y consulta sobre las entregas.
+ *
+ * ## Por qué esta costura es distinta de las trece anteriores
+ *
+ * Las otras invertían un SERVICIO. Ésta invierte el acceso directo a una
+ * COLECCIÓN: `nodes/` y el motor inyectaban `Model<DeliveryDocument>` y
+ * consultaban `deliveries` a mano.
+ *
+ * Por eso se dejó fuera del lote del #468: cerrarla obliga a decidir de quién
+ * es la colección. La respuesta, mirando lo que se hace con ella, es que es
+ * del gateway — `deliveries` es lo que el panel enseña como historial de
+ * entregas, tiene su propia política de retención en `plans/` y su controlador
+ * de reintentos. El motor sólo escribe filas y pregunta si ya escribió una.
+ *
+ * ## Las tres operaciones, medidas
+ *
+ *   3  `exists`      la comprobación de IDEMPOTENCIA de email, sheets y
+ *                    notificaciones
+ *   3  `create`      la fila de cada entrega, con la misma forma las tres
+ *   2  `deleteMany`  las dos cascadas: por webhook y por evento
+ *
+ * ## ⚠️ Lo que no se puede perder
+ *
+ * **`soloSiTuvoExito`.** El chequeo de notificaciones añade `success: true` al
+ * filtro cuando `triggerOn` NO es `'always'`. Perder esa condición tiene dos
+ * caras y las dos son malas: sin ella, una notificación que falló cuenta como
+ * entregada y no se reintenta nunca; con ella siempre puesta, una que sí se
+ * mandó se manda otra vez en cada reintento del evento.
+ *
+ * **`refIdIn` en el borrado.** `webhookId` se guarda como cadena en unas filas
+ * y como `ObjectId` en otras. Filtrar por una sola forma deja la mitad de las
+ * entregas huérfanas — que es justo lo que la cascada existe para evitar. El
+ * contrato recibe los ids en crudo y la conversión se queda en el gateway,
+ * donde vive el problema.
+ *
+ * ## Cómo viaja
+ *
+ * Bien: entran y salen datos planos, y `anotar` es «dispara y olvida» —el SDK
+ * ya la llama con `.catch()` colgado, sin esperarla—.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGISTRO_DE_ENTREGAS = void 0;
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+exports.REGISTRO_DE_ENTREGAS = 'REGISTRO_DE_ENTREGAS';

package/dist/servicios/registro-de-eventos.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Lo que un nodo apunta y pregunta sobre eventos.
+ *
+ * ## ⚠️ Esta costura es MUCHO más pequeña de lo que el conteo decía
+ *
+ * `nodes/` y `common/` tocan el modelo de eventos en seis ficheros y con una
+ * superficie grande —`create` ×10, `findById` ×5, `findByIdAndUpdate` ×5,
+ * `hydrate`, `aggregate`, incluso `db.db` en crudo—. Con ese número, esto
+ * parecía la costura más cara de la fase.
+ *
+ * Lo es sólo si uno olvida leer el plan. `event-pipeline` y `pipeline-run`
+ * **se quedan en el gateway**: este servicio ejecuta nodos, no orquesta
+ * corridas. Y `agent-context` también es del gateway. O sea que casi toda esa
+ * superficie es del motor consultando SU PROPIA colección de trabajo, y no
+ * hay nada que invertir ahí.
+ *
+ * Lo que de verdad viaja son tres ficheros y tres operaciones:
+ *
+ *   `triggers.service`               crea el evento de un empujón externo
+ *   `scheduled-workflows.processor`  crea el de un cron
+ *   `webhooks.service`               cuenta para las estadísticas y borra en
+ *                                    cascada
+ *
+ * ⚠️ Y `common/node-handlers.ts` lo inyectaba sin usarlo NUNCA. Fuera.
+ *
+ * ## Cómo viaja
+ *
+ * Bien: entra un objeto plano y sale lo que el llamante lee. De los tres
+ * `create`, dos DESCARTAN el resultado y sólo el del cron le lee dos campos.
+ */
+/**
+ * En qué estado está un evento.
+ *
+ * ⚠️ Vivía en `events/event.entity.ts`, junto al esquema de Mongoose. Es un
+ * enum puro y los nodos lo necesitan, así que se muda aquí y allí queda el
+ * reenvío — mismo reparto que `Audited` o `PasoEjecutado`.
+ */
+export declare enum EstadoDeEvento {
+    PENDING = "pending",
+    DELIVERED = "delivered",
+    FAILED = "failed",
+    RETRYING = "retrying",
+    FILTERED = "filtered",
+    SCHEMA_INVALID = "schema_invalid",
+    AWAITING_APPROVAL = "awaiting_approval",
+    DELAYED = "delayed",
+    DEDUPLICATED = "deduplicated",
+    RATE_LIMITED = "rate_limited",
+    IP_BLOCKED = "ip_blocked",
+    SIGNATURE_INVALID = "signature_invalid",
+    /** Payload contained a `_file` ref that the malware scanner flagged
+     *  as infected or scan_failed. Distinct from FAILED so dashboards
+     *  and stats can highlight security blocks separately from
+     *  delivery errors. */
+    MALICIOUS_FILE = "malicious_file"
+}
+/** Un evento que entra al sistema. */
+export interface EventoEntrante {
+    /** El nodo fuente que lo produjo: webhook, trigger o programado. */
+    webhookId: string;
+    payload: unknown;
+    rawBody: string;
+    headers: Record<string, string>;
+    sourceIp: string;
+    status: string;
+    /** ⚠️ Opcional: el trigger no lo pone y el esquema tiene su valor por
+     *  defecto. Exigirlo aquí obligaría a inventárselo en el llamante. */
+    eventType?: string;
+    attemptCount?: number;
+    /**
+     * La corrida a la que pertenece.
+     *
+     * ⚠️ Ausente significa «este evento ABRE una corrida», y entonces la abre
+     * con su propio id. No es lo mismo que ponerlo a `null`.
+     */
+    correlationId?: string;
+    /**
+     * La llave con que se reconoce un empujón repetido del proveedor.
+     *
+     * ⚠️ Gmail, Drive y compañía reenvían la misma notificación más de una vez.
+     * Sin esto, un cambio se despacha dos veces.
+     */
+    idempotencyKey?: string;
+}
+/** Lo que el llamante lee de un evento recién creado. Dos campos. */
+export interface EventoCreado {
+    id: string;
+    correlationId?: string;
+}
+export interface RegistroDeEventos {
+    /**
+     * ⚠️ Devuelve datos planos, no el documento. Se comprobó llamante por
+     * llamante: dos de los tres tiran el resultado y el tercero lee `id` y
+     * `correlationId` para enhebrar la corrida.
+     */
+    crear(evento: EventoEntrante): Promise<EventoCreado>;
+    /**
+     * Cuántos eventos tiene un webhook, para el `successRate` del panel.
+     *
+     * ⚠️ `soloEntregados` cambia la pregunta, no la afina: sin él es el
+     * denominador y con él el numerador. Y las pruebas NO cuentan —`isTest`
+     * queda fuera siempre—, porque un webhook que se probó diez veces tendría
+     * un porcentaje que no describe su tráfico real.
+     */
+    contarDeWebhook(webhookId: string, opts?: {
+        soloEntregados?: boolean;
+    }): Promise<number>;
+    /**
+     * La cascada al borrar webhooks.
+     *
+     * ⚠️ Los ids van en crudo: `webhookId` se guarda como cadena en unas filas
+     * y como `ObjectId` en otras, y esa conversión se queda en el gateway,
+     * donde vive el problema. Mismo reparto que el registro de entregas.
+     */
+    borrarDeWebhooks(webhookIds: ReadonlyArray<string>): Promise<void>;
+    /**
+     * ¿Ya se despachó este empujón?
+     *
+     * ⚠️ Falla ABIERTO y hay que conservarlo: si la consulta revienta devuelve
+     * `false` —«no lo he visto»— y el evento se despacha igual. El peor caso es
+     * un duplicado aguas abajo; el otro camino es tragarse un cambio real en
+     * silencio, que es mucho peor y no deja rastro.
+     */
+    yaSeDespacho(webhookId: string, idempotencyKey: string): Promise<boolean>;
+    /**
+     * Los ids de los eventos de un nodo fuente.
+     *
+     * ⚠️ Se recogen ANTES de borrarlos: las entregas se indexan por `eventId`,
+     * y una vez borrados los eventos no queda nada por lo que resolverlas.
+     * Ver `cascade-trigger-events.ts`.
+     */
+    idsDeWebhook(webhookId: string): Promise<string[]>;
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+export declare const REGISTRO_DE_EVENTOS = "REGISTRO_DE_EVENTOS";

package/dist/servicios/registro-de-eventos.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Lo que un nodo apunta y pregunta sobre eventos.
+ *
+ * ## ⚠️ Esta costura es MUCHO más pequeña de lo que el conteo decía
+ *
+ * `nodes/` y `common/` tocan el modelo de eventos en seis ficheros y con una
+ * superficie grande —`create` ×10, `findById` ×5, `findByIdAndUpdate` ×5,
+ * `hydrate`, `aggregate`, incluso `db.db` en crudo—. Con ese número, esto
+ * parecía la costura más cara de la fase.
+ *
+ * Lo es sólo si uno olvida leer el plan. `event-pipeline` y `pipeline-run`
+ * **se quedan en el gateway**: este servicio ejecuta nodos, no orquesta
+ * corridas. Y `agent-context` también es del gateway. O sea que casi toda esa
+ * superficie es del motor consultando SU PROPIA colección de trabajo, y no
+ * hay nada que invertir ahí.
+ *
+ * Lo que de verdad viaja son tres ficheros y tres operaciones:
+ *
+ *   `triggers.service`               crea el evento de un empujón externo
+ *   `scheduled-workflows.processor`  crea el de un cron
+ *   `webhooks.service`               cuenta para las estadísticas y borra en
+ *                                    cascada
+ *
+ * ⚠️ Y `common/node-handlers.ts` lo inyectaba sin usarlo NUNCA. Fuera.
+ *
+ * ## Cómo viaja
+ *
+ * Bien: entra un objeto plano y sale lo que el llamante lee. De los tres
+ * `create`, dos DESCARTAN el resultado y sólo el del cron le lee dos campos.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGISTRO_DE_EVENTOS = exports.EstadoDeEvento = void 0;
+/**
+ * En qué estado está un evento.
+ *
+ * ⚠️ Vivía en `events/event.entity.ts`, junto al esquema de Mongoose. Es un
+ * enum puro y los nodos lo necesitan, así que se muda aquí y allí queda el
+ * reenvío — mismo reparto que `Audited` o `PasoEjecutado`.
+ */
+var EstadoDeEvento;
+(function (EstadoDeEvento) {
+    EstadoDeEvento["PENDING"] = "pending";
+    EstadoDeEvento["DELIVERED"] = "delivered";
+    EstadoDeEvento["FAILED"] = "failed";
+    EstadoDeEvento["RETRYING"] = "retrying";
+    EstadoDeEvento["FILTERED"] = "filtered";
+    EstadoDeEvento["SCHEMA_INVALID"] = "schema_invalid";
+    EstadoDeEvento["AWAITING_APPROVAL"] = "awaiting_approval";
+    EstadoDeEvento["DELAYED"] = "delayed";
+    EstadoDeEvento["DEDUPLICATED"] = "deduplicated";
+    EstadoDeEvento["RATE_LIMITED"] = "rate_limited";
+    EstadoDeEvento["IP_BLOCKED"] = "ip_blocked";
+    EstadoDeEvento["SIGNATURE_INVALID"] = "signature_invalid";
+    /** Payload contained a `_file` ref that the malware scanner flagged
+     *  as infected or scan_failed. Distinct from FAILED so dashboards
+     *  and stats can highlight security blocks separately from
+     *  delivery errors. */
+    EstadoDeEvento["MALICIOUS_FILE"] = "malicious_file";
+})(EstadoDeEvento || (exports.EstadoDeEvento = EstadoDeEvento = {}));
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+exports.REGISTRO_DE_EVENTOS = 'REGISTRO_DE_EVENTOS';

package/dist/servicios/restauracion-de-nodos.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Restaurar las entidades de nodo de un snapshot del lienzo.
+ *
+ * ## Por qué esto es un contrato y no una lectura cruda
+ *
+ * `agent-context` dejó de necesitar las entidades leyendo las colecciones a
+ * pelo (api#555). Aquí no vale, y la diferencia es de una palabra: **aquí se
+ * escribe**.
+ *
+ * `model.create` aplica los `default`, el casteo y las validaciones del
+ * esquema. Un `insertOne` crudo no aplica ninguno, así que un snapshot viejo
+ * restaurado contra un esquema nuevo saldría sin los campos que el esquema
+ * habría rellenado — y eso no falla al escribir, falla mucho más tarde, en
+ * quien lee. La escritura tiene que ocurrir donde vive el esquema.
+ *
+ * ## Y por eso la restauración es de los dos lados
+ *
+ * Un lienzo mezcla nodos de origen —del gateway— con nodos de acción, que se
+ * van a hw-nodes. De las cuarenta y nueve claves que un snapshot puede traer, **cinco
+ * son del gateway** —los cinco nodos de ORIGEN, que es exactamente la frontera
+ * del corte— y **cuarenta y cuatro se van**.
+ *
+ * Así que los dos lados reciben el snapshot ENTERO y cada uno escribe su
+ * parte: el bucle vive en `@hostwebhook/node-sdk` y a cada lado se le pasan sus
+ * modelos. Una clave que un lado no posee se salta sin contarla.
+ *
+ * ⚠️ La caché del lienzo se tira UNA vez, cuando han terminado los dos. Por eso
+ * el contrato devuelve los workspaces tocados en vez de invalidar por su
+ * cuenta: invalidar antes de que el otro lado haya escrito devuelve el grafo
+ * viejo durante 30 s, que es justo el momento en el que nadie se cree que la
+ * restauración haya funcionado.
+ */
+export interface RestauracionDeNodos {
+    /**
+     * Las claves del snapshot que este lado sabe escribir.
+     *
+     * ⚠️ Se pregunta, no se escribe a mano en el gateway: un segundo mapa que se
+     * queda viejo es exactamente cómo se perdió `mailchimpAction` del registro de
+     * conexiones. El que sabe qué nodos tiene es quien los tiene.
+     */
+    clavesQueRestaura(): string[];
+    restaurar(peticion: {
+        /** El `entities` del snapshot, entero — el otro lado ignora lo que no es suyo. */
+        entidades: Record<string, unknown[]>;
+        orgId: string;
+        /** Quien restaura. La identidad del nodo se rederiva de aquí, no del snapshot. */
+        userId: string;
+    }): Promise<{
+        contadores: Record<string, number>;
+        workspacesTocados: string[];
+    }>;
+}
+export declare const RESTAURACION_DE_NODOS = "RESTAURACION_DE_NODOS";

package/dist/servicios/restauracion-de-nodos.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESTAURACION_DE_NODOS = void 0;
+exports.RESTAURACION_DE_NODOS = 'RESTAURACION_DE_NODOS';

package/dist/servicios/salud-del-webhook.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Lo que el motor necesita del comprobador de salud del webhook. UN método.
+ *
+ * ## Por qué
+ *
+ * `event-pipeline` llama a `HealthCheckerService.startRecovery(webhookId)`
+ * cuando un webhook pasa a `down` y tiene la recuperación automática puesta.
+ * Es la ÚNICA llamada: medido, `startRecovery` y nada más.
+ *
+ * El motor viaja a hw-nodes; `webhooks` es uno de los cinco nodos de origen que
+ * se quedan en el gateway. Sin esto, el motor arrastra un servicio del gateway
+ * entero por un método de cuatro líneas.
+ *
+ * ## Lo que cruza
+ *
+ * Un id y nada más. No hay respuesta que esperar: quien llama lo lanza con
+ * `void`, porque arrancar la recuperación no puede retrasar el despacho del
+ * evento que la disparó.
+ */
+export interface SaludDelWebhook {
+    /** Marca el webhook como «recuperándose». No devuelve nada. */
+    arrancarRecuperacion(webhookId: string): Promise<void>;
+}
+/** ⚠️ Cadena y no `Symbol`: un `Symbol` no sobrevive a una frontera de módulo
+ *  duplicada. */
+export declare const SALUD_DEL_WEBHOOK = "SALUD_DEL_WEBHOOK";

package/dist/servicios/salud-del-webhook.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SALUD_DEL_WEBHOOK = void 0;
+/** ⚠️ Cadena y no `Symbol`: un `Symbol` no sobrevive a una frontera de módulo
+ *  duplicada. */
+exports.SALUD_DEL_WEBHOOK = 'SALUD_DEL_WEBHOOK';

package/dist/servicios/secretos-de-firma.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Si un secreto de firma es de esta organización. Una pregunta.
+ *
+ * Costura de la Fase 2, del lote de las pequeñas. `webhooks.service` hacía
+ * `connection.model(SigningSecret.name).collection.findOne(...)` — o sea,
+ * consultaba una colección de OTRO dominio a través de la conexión, sólo para
+ * comprobar que el id que llega en el cuerpo es suyo.
+ *
+ * ⚠️ Importaba la clase de la entidad para usar su `.name` como cadena. Eso
+ * arrastra el fichero de la entidad entero —con sus decoradores de Mongoose—
+ * para leerle una palabra.
+ *
+ * ## Lo que hay que conservar
+ *
+ * ⚠️ La comprobación existe porque `signingSecretId` llega del CUERPO de la
+ * petición y sólo se validaba con `@IsMongoId()`: sin esto, un id de otra
+ * organización pasaba el DTO. Devolver `true` cuando no se sabe abriría justo
+ * esa puerta, así que quien lo implemente por red tiene que fallar hacia
+ * `false` — al revés que la mayoría de fallbacks de esta fase.
+ */
+export interface SecretosDeFirma {
+    /** ⚠️ Ante la duda, `false`. Ver la cabecera. */
+    esDeLaOrganizacion(secretoId: string, orgId: string): Promise<boolean>;
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+export declare const SECRETOS_DE_FIRMA = "SECRETOS_DE_FIRMA";

package/dist/servicios/secretos-de-firma.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECRETOS_DE_FIRMA = void 0;
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+exports.SECRETOS_DE_FIRMA = 'SECRETOS_DE_FIRMA';

package/dist/servicios/telemetria.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Lo que un nodo apunta en el registro. Una sola operación.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. Después del #459 quedaban 16 ficheros de `nodes/`
+ * importando `TelemetryService`, más tres del motor en `common/` —que viaja
+ * con ellos—. Los 19 lo usan para **lo mismo**: `emit`.
+ *
+ * `TelemetryService` arrastra la colección de logs, su conexión de Mongo
+ * propia y el gateway de sockets que empuja la fila al panel en vivo. Nada de
+ * eso puede vivir en `hw-nodes`: el registro es del gateway, y lo que el nodo
+ * necesita es poder DECIR lo que ha pasado.
+ *
+ * ## Tres métodos, y medidos
+ *
+ * En `nodes/` el inventario dio **uno solo** —`emit`— en 15 de los 16
+ * ficheros. El que sobraba (`ai-nodes.controller`) no lo llamaba: se lo
+ * pasaba al probador, y para eso ya existe la bandera `conTelemetria` desde
+ * el #458.
+ *
+ * ⚠️ Pero el inventario iba apuntado sólo a `nodes/`, y el motor vive en
+ * `common/`, que viaja con ellos. Al compilar salieron dos métodos más:
+ * `hasRecentSuccess` y `emitAndWait`. Los dos son de la recuperación de
+ * caídas, no del registro: sin ellos un nodo caro se re-ejecuta. Lo cazó tsc,
+ * no yo — la lección de siempre, con el barrido mal apuntado.
+ *
+ * ⚠️ Y ahí apareció una regresión MÍA. El #459 le quitó a
+ * `code-nodes.controller` el parámetro `telemetry` y su `super()`, pero dejó
+ * en pie un `this.telemetry` en la ruta `:id/test` escrita a mano. Desde
+ * entonces valía `undefined`, así que un paso de Run Pipeline sobre un Code
+ * node **no anotaba nada** — justo el comportamiento que el #459 decía haber
+ * conservado. No lo vio tsc porque la clase base del factory está tipada como
+ * `=> any`: dentro de una subclase, `this.loquesea` compila.
+ *
+ * ## Los campos son los que se usan
+ *
+ * El esquema `TelemetryLog` tiene ~20 campos. Se contaron los que aparecen de
+ * verdad en las 67 llamadas de `nodes/` y las 53 de `common/`: son quince.
+ * Fuera quedan `timestamp` —lo pone el gateway si falta—, `correlationId` y
+ * los dos de voz, que nadie de este lado escribe.
+ *
+ * ## Cómo viaja
+ *
+ * Bien: sólo datos planos. `TelemetryLog` es una clase con decoradores pero
+ * sin métodos, así que no hay documento vivo que aplanar; aun así el contrato
+ * lo declara aparte para no arrastrar `@nestjs/mongoose` a `hw-nodes`.
+ *
+ * ⚠️ `emit` devuelve `void` y no espera: por dentro hace `create(...).catch()`.
+ * Eso es deliberado y hay que conservarlo cuando esto sea una llamada de red —
+ * un nodo no puede quedarse esperando a que se escriba una fila de log, y
+ * menos aún fallar porque no se pudo escribir.
+ */
+/** Nivel de la fila. Los mismos cuatro del esquema. */
+export type NivelDeRegistro = 'info' | 'warn' | 'error' | 'debug';
+/**
+ * Una fila del registro.
+ *
+ * ⚠️ Los quince campos MEDIDOS, ni uno más. Si hace falta otro, se añade
+ * aquí: tsc rechaza una clave desconocida en un literal, así que no se puede
+ * colar por accidente.
+ */
+export interface EntradaDeTelemetria {
+    organizationId: string;
+    level: NivelDeRegistro;
+    /** Cadena abierta, no un enum: un tipo de nodo nuevo funciona solo. */
+    source: string;
+    message: string;
+    /** `pipeline_test` distingue una corrida de una prueba suelta. */
+    trigger?: 'event' | 'pipeline_test';
+    eventId?: string;
+    webhookId?: string;
+    webhookName?: string;
+    nodeId?: string;
+    nodeName?: string;
+    scheduledWorkflowId?: string;
+    durationMs?: number;
+    statusCode?: number;
+    success?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Apuntar en el registro, y preguntarle a la recuperación de caídas. */
+export interface Telemetria {
+    /**
+     * ⚠️ `void`, y no espera. Ver la nota de arriba: una implementación por red
+     * tiene que seguir sin bloquear y sin propagar su propio fallo.
+     */
+    emit(entrada: EntradaDeTelemetria): void;
+    /**
+     * Lo mismo, pero espera a que la fila esté escrita.
+     *
+     * ⚠️ No es un capricho de consistencia: lo usan los handlers que declaran
+     * `awaitTelemetry: true`, que son los caros (llamadas a un LLM). Si un
+     * SIGTERM cae entre el handler y la escritura, al recuperar
+     * `hasRecentSuccess` dice que no y la operación **se repite** — y al
+     * usuario se la cobran dos veces. Una implementación por red tiene que
+     * seguir esperando de verdad aquí.
+     */
+    emitAndWait(entrada: EntradaDeTelemetria): Promise<void>;
+    /**
+     * ¿Ya corrió con éxito este nodo para este evento hace poco?
+     *
+     * ⚠️ Falla ABIERTO: si la consulta revienta devuelve `false`, o sea «no
+     * corrió», y el nodo se re-ejecuta. Es lo correcto —repetir es más seguro
+     * que saltarse un paso— pero hay que conservarlo: una implementación por
+     * red que devolviera `true` al fallar dejaría pasos sin ejecutar en
+     * silencio, que es el fallo que no se ve.
+     */
+    hasRecentSuccess(eventId: string, nodeId: string, withinMs?: number): Promise<boolean>;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+export declare const TELEMETRIA = "TELEMETRIA";