@hostwebhook/node-sdk 0.1.0

package/dist/log-metadata.js

@@ -0,0 +1,375 @@
+"use strict";
+/**
+ * Lo que un log de un nodo guarda, y con qué nombre.
+ *
+ * ## El desorden que esto viene a cerrar
+ *
+ * Auditado el 2026-08-27 sobre los cinco sitios que escriben `metadata`:
+ *
+ * | camino                | entrada             | salida               | error                          |
+ * |-----------------------|---------------------|----------------------|--------------------------------|
+ * | producción (C1)       | **ninguna**         | `responseBody` ≤4096 | `error` = COPIA del response   |
+ * | Run Test (C3)         | `payloadPreview`    | **ninguna**          | `error` = el response          |
+ * | Run Pipeline (C2)     | **ninguna**         | `responseBody` ≤1024 | `error` = el response, entero  |
+ * | entrega ok            | `requestPayload`    | `responseBody` ≤2048 | —                              |
+ * | entrega fallida       | `requestPayload`    | `responseBody` ≤1024 | `error` = mensaje de verdad    |
+ *
+ * Tres defectos, y los tres se ven en pantalla:
+ *
+ * 1. **«Error» casi nunca es un error.** En tres de los cinco sitios es el
+ *    response copiado tal cual. La pantalla pinta dos paneles con el mismo
+ *    contenido y titula uno «ERROR», así que el usuario busca ahí la causa y
+ *    encuentra otra vez la salida.
+ * 2. **La entrada no se guarda donde más se necesita.** En producción no se
+ *    guarda ninguna: con un nodo que falló, el log no dice con qué datos
+ *    falló.
+ * 3. **El recorte rompe el JSON.** `truncatePreview` devuelve un OBJETO si
+ *    cabe y una CADENA CORTADA si no. El mismo campo cambia de tipo según el
+ *    tamaño, así que el visor pinta un árbol o un churro de texto sin que
+ *    nada lo anuncie. Medido con un caso real: un response de 1270 caracteres
+ *    pasaba entero por el `error` (sin límite) y cortado por el
+ *    `responseBody` (límite 1024) — los dos paneles, el mismo dato, uno
+ *    legible y el otro no.
+ *
+ * ## Lo que se guarda ahora
+ *
+ * Dos campos con el mismo significado en todos los caminos, más una frase:
+ *
+ *   - `payload`  — lo que ENTRÓ al nodo.
+ *   - `response` — lo que SALIÓ. Al fallar lleva dentro un `error` con la
+ *                  frase que lo explica, en el hueco que deja el payload
+ *                  repetido.
+ *
+ * La frase estuvo un rato en un campo aparte (`errorSummary`) que la pantalla
+ * pintaba en una caja roja encima del panel. Se metió dentro porque lo que se
+ * quiere leer de un log que falló es «qué contestó el nodo», y eso son el
+ * veredicto y el motivo juntos — no uno arriba y otro dentro.
+ *
+ * Las claves viejas se siguen escribiendo un tiempo (`responseBody`,
+ * `payloadPreview`, `requestPayload`) porque los logs ya guardados las llevan
+ * y la pantalla tiene que poder pintar el historial. Ver
+ * `LEER_TAMBIEN_LAS_VIEJAS` abajo.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEER_TAMBIEN_LAS_VIEJAS = exports.IGUAL_QUE_LA_ENTRADA = exports.TOPE_DE_LOG = void 0;
+exports.recortarEstructural = recortarEstructural;
+exports.mismoContenido = mismoContenido;
+exports.podarLoRepetido = podarLoRepetido;
+exports.parsearResponse = parsearResponse;
+exports.explicarFallo = explicarFallo;
+exports.construirMetadatosDeLog = construirMetadatosDeLog;
+/** Tope por defecto. 16 KB: 16 veces el peor límite de antes, y de sobra para
+ *  cualquier payload real —el caso que destapó esto medía 1,2 KB—. Existe un
+ *  tope porque un documento de Mongo no pasa de 16 MB, no por ahorrar. */
+exports.TOPE_DE_LOG = 16 * 1024;
+/**
+ * Recorta SIN romper la forma.
+ *
+ * `truncatePreview` corta la cadena serializada por la mitad y le pega
+ * `...[truncated]`. Eso deja un JSON inválido, y el panel que lo recibe deja
+ * de poder plegarlo, colorearlo o buscar dentro: pasa a ser texto.
+ *
+ * Aquí se recorta por DENTRO: se sustituye el valor grande por una nota que
+ * dice qué había, y lo que sale sigue siendo un objeto válido. Un campo que
+ * no cabe se lee como «aquí había 40 KB de texto» en vez de dejar el
+ * documento entero ilegible por culpa de ese campo.
+ */
+function recortarEstructural(value, tope = exports.TOPE_DE_LOG) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    const cabe = (v) => {
+        try {
+            return JSON.stringify(v)?.length ?? 0;
+        }
+        catch {
+            return Infinity;
+        }
+    };
+    if (cabe(value) <= tope)
+        return value;
+    /* Una cadena suelta demasiado grande sí se corta —no tiene estructura que
+       preservar— pero se dice cuánto se dejó fuera, que es lo que `[truncated]`
+       a secas no decía. */
+    if (typeof value === 'string') {
+        return `${value.slice(0, tope)}\n\n[+${value.length - tope} caracteres más — recortado para el log]`;
+    }
+    if (typeof value !== 'object')
+        return value;
+    /* Se poda de mayor a menor hasta que quepa: así lo que se pierde es el
+       campo gordo que causó el problema, no los treinta pequeños que sí
+       interesan. */
+    const podar = (v, profundidad) => {
+        if (v === null || typeof v !== 'object')
+            return v;
+        if (Array.isArray(v)) {
+            if (profundidad <= 0)
+                return `[array de ${v.length} elementos — recortado]`;
+            return v.map((x) => podar(x, profundidad - 1));
+        }
+        if (profundidad <= 0) {
+            return `[objeto con ${Object.keys(v).length} campos — recortado]`;
+        }
+        const entradas = Object.entries(v);
+        const salida = {};
+        for (const [k, val] of entradas) {
+            const tam = cabe(val);
+            salida[k] =
+                typeof val === 'string' && tam > tope / 4
+                    ? `[${val.length} caracteres — recortado para el log]`
+                    : podar(val, profundidad - 1);
+        }
+        return salida;
+    };
+    for (const profundidad of [6, 4, 3, 2, 1]) {
+        const intento = podar(value, profundidad);
+        if (cabe(intento) <= tope)
+            return intento;
+    }
+    return `[${cabe(value)} caracteres — demasiado grande para el log]`;
+}
+/**
+ * Lo que se pinta en lugar del dato repetido. En inglés: acaba en pantalla.
+ *
+ * ⚠️ NO empieza por `[` ni por `{`, y no es un capricho: cuando lo que se
+ * sustituye es el response ENTERO, esta cadena llega sola al panel, y el
+ * dashboard decide si pintar el visor de JSON mirando si el texto empieza por
+ * `[` o `{` (`looksLikeJson` en `app/dashboard/logs/page.tsx`). Con corchetes
+ * intentaría parsear «[identical to…]» como JSON y no es JSON.
+ */
+exports.IGUAL_QUE_LA_ENTRADA = 'Same as the payload below';
+/**
+ * ¿Estos dos llevan el mismo contenido?
+ *
+ * `_meta` se ignora a propósito: es contabilidad que el pipeline añade
+ * (`iterable`, `count`), no dato del usuario. Un filtro que deja pasar el
+ * payload tal cual devuelve el MISMO objeto pero con `_meta` puesto, así que
+ * comparar en crudo diría «distintos» justo en el caso que esto viene a
+ * detectar.
+ *
+ * Comparar por JSON con las claves ordenadas y no con `===`: el response viaja
+ * serializado y vuelve parseado, así que nunca es el mismo objeto en memoria
+ * aunque sea el mismo dato.
+ */
+function mismoContenido(a, b) {
+    if (a == null || b == null)
+        return false;
+    if (typeof a !== 'object' || typeof b !== 'object')
+        return false;
+    const normaliza = (v) => {
+        const sinMeta = Object.fromEntries(Object.entries(v).filter(([k]) => k !== '_meta'));
+        const ordenar = (x) => {
+            if (Array.isArray(x))
+                return x.map(ordenar);
+            if (x && typeof x === 'object') {
+                return Object.fromEntries(Object.entries(x)
+                    .sort(([p], [q]) => p.localeCompare(q))
+                    .map(([k, val]) => [k, ordenar(val)]));
+            }
+            return x;
+        };
+        try {
+            return JSON.stringify(ordenar(sinMeta));
+        }
+        catch {
+            return '';
+        }
+    };
+    const ja = normaliza(a);
+    return ja !== '' && ja === normaliza(b);
+}
+/**
+ * Quita del response lo que YA se guarda como entrada.
+ *
+ * ## Por qué
+ *
+ * Un log pinta el response arriba y el payload abajo, y en los nodos que
+ * dejan pasar los datos eso es el MISMO objeto dos veces. En un filtro no
+ * iterable es literal: `evaluateFiltersIterable` devuelve `resultPayload:
+ * payload`, el propio objeto de entrada. Reportado mirando un log: «si arriba
+ * está la response y abajo el payload, estaríamos repitiendo data».
+ *
+ * ## Por qué no se arregla en el ejecutor
+ *
+ * Porque `responseBody` **no es un campo de log**: se lee en 140 sitios de 46
+ * ficheros y una veintena lo parsean para DECIDIR. `standardGetOutputPayload`
+ * —que usan 23 handlers— construye parseándolo el payload que va aguas abajo;
+ * `pipeline-run` y `test-node` caen a `JSON.parse(responseBody)` cuando el
+ * handler no transforma; `cache` lee `.action`, `conditional` `.matchedId`,
+ * `schemaValidator` `.valid`. Vaciar el response ahí es cambiar la ejecución.
+ *
+ * El log, en cambio, es una hoja: nadie lee hacia atrás desde él. Así que la
+ * poda vive aquí.
+ *
+ * ## La regla
+ *
+ * Sólo se quita lo que está DEMOSTRADO repetido, comparando contenido:
+ *
+ *   - el response entero igual a la entrada  → se sustituye por la nota;
+ *   - `response.payload` igual a la entrada  → se sustituye ese campo y el
+ *     veredicto (`passed`, `totalItems`…) se queda;
+ *   - distintos                              → intacto.
+ *
+ * Ese último caso no es teórico: con un payload iterable el filtro devuelve un
+ * objeto NUEVO con sólo los items que pasaron. Ahí `response.payload` no es la
+ * entrada, es el resultado del filtrado, y borrarlo perdería el dato que más
+ * interesa.
+ *
+ * Y se sustituye en vez de borrar: un campo que desaparece se lee como «el
+ * nodo no devolvió nada», que es otra cosa.
+ */
+function podarLoRepetido(response, entrada, 
+/**
+ * La frase del fallo, si el nodo falló.
+ *
+ * Va DENTRO del response, en el hueco que deja el payload repetido, en vez
+ * de aparte y en rojo encima del panel. Así el panel de arriba se lee
+ * entero como «qué contestó el nodo»: el veredicto y por qué, juntos, que
+ * es lo que se quiere saber al abrir un log que falló.
+ */
+fallo) {
+    if (response == null)
+        return fallo ? { error: fallo } : response;
+    const conFallo = (r) => fallo ? { ...r, error: fallo } : r;
+    if (entrada == null) {
+        return typeof response === 'object' && !Array.isArray(response)
+            ? conFallo(response)
+            : response;
+    }
+    /* El response ENTERO era la entrada. Al fallar no se pierde nada por
+       sustituirlo: lo que aporta es la frase, y el dato está justo debajo. */
+    if (mismoContenido(response, entrada)) {
+        return fallo ? { error: fallo } : exports.IGUAL_QUE_LA_ENTRADA;
+    }
+    if (typeof response !== 'object' || Array.isArray(response))
+        return response;
+    const r = response;
+    if (!('payload' in r) || !mismoContenido(r.payload, entrada)) {
+        return conFallo(r);
+    }
+    /* El payload repetido se va, y en su sitio queda la frase. Sin fallo —un
+       nodo que fue bien— no hay frase que poner, así que se queda la nota
+       diciendo dónde está el dato. */
+    if (fallo) {
+        const { payload: _repetido, ...resto } = r;
+        return { ...resto, error: fallo };
+    }
+    return { ...r, payload: exports.IGUAL_QUE_LA_ENTRADA };
+}
+/** El response ya parseado, si es que se puede. Nunca revienta. */
+function parsearResponse(responseBody) {
+    if (responseBody == null)
+        return undefined;
+    if (typeof responseBody !== 'string')
+        return responseBody;
+    try {
+        return JSON.parse(responseBody);
+    }
+    catch {
+        return responseBody;
+    }
+}
+/**
+ * Qué falló, en una frase.
+ *
+ * En inglés porque es texto de pantalla, y la pantalla está en inglés — hay
+ * un guardián en el dashboard (`check-spanish-ui`) que lo exige.
+ *
+ * El objetivo NO es reemplazar al response: es que la primera línea diga qué
+ * pasó sin tener que leer JSON. El response sigue guardado al lado.
+ */
+function explicarFallo(args) {
+    const { nodeType, statusCode } = args;
+    const r = (args.response ?? {});
+    const nombre = args.nodeName ? `"${args.nodeName}"` : 'This node';
+    /* Un filtro que bloquea NO es una avería, y decirlo importa: su 403 se lee
+       como un problema de permisos. Es el caso que destapó la auditoría. */
+    if (nodeType === 'filter' && r.passed === false) {
+        const total = Number(r.totalItems ?? 0);
+        const pasaron = Number(r.passedItems ?? 0);
+        return total > 1
+            ? `${nombre} blocked the event: ${pasaron} of ${total} items matched the rules, so nothing continued downstream. This is the filter doing its job, not a failure.`
+            : `${nombre} blocked the event: the payload did not match the rules, so nothing continued downstream. This is the filter doing its job, not a failure.`;
+    }
+    /* Un mensaje que el propio nodo escribió gana a cualquier frase nuestra:
+       lo puso quien sabía qué pasaba. */
+    const propio = (typeof r.error === 'string' && r.error) ||
+        (typeof r.message === 'string' && r.message) ||
+        null;
+    if (propio)
+        return propio;
+    if (nodeType === 'schemaValidator') {
+        return `${nombre} rejected the payload: it does not match the schema.`;
+    }
+    if (typeof statusCode === 'number' && statusCode > 0) {
+        if (statusCode === 401 || statusCode === 403) {
+            return `${nombre} was refused by the service (${statusCode}). The credential is usually the cause: expired, revoked, or missing the scope this operation needs.`;
+        }
+        if (statusCode === 404) {
+            return `${nombre} asked for something the service could not find (404). Check the ids in the configuration.`;
+        }
+        if (statusCode === 429) {
+            return `${nombre} was rate-limited by the service (429). It ran too often for the plan or quota in use.`;
+        }
+        if (statusCode >= 500) {
+            return `${nombre} failed on the service's side (${statusCode}). Nothing is wrong with the configuration; retrying later usually works.`;
+        }
+        if (statusCode >= 400) {
+            return `${nombre} was rejected by the service (${statusCode}). The request was built from the configuration, so that is where to look.`;
+        }
+    }
+    return `${nombre} did not finish successfully.`;
+}
+/**
+ * Las claves de antes, que la PANTALLA sigue teniendo que leer.
+ *
+ * No se borran de los logs ya escritos, así que el dashboard mira primero la
+ * nueva y luego estas. Se listan aquí para que el día que se dejen de
+ * escribir haya un sitio donde mirar cuáles eran.
+ */
+exports.LEER_TAMBIEN_LAS_VIEJAS = {
+    payload: ['requestPayload', 'payloadPreview'],
+    response: ['responseBody'],
+};
+/**
+ * Los metadatos de un log de nodo, iguales vengan del camino que vengan.
+ *
+ * `extra` es lo que aporta cada nodo (`filterMode`, `attempt`, `targetUrl`…)
+ * y va primero, para que no pueda pisar a los tres campos que esta función
+ * garantiza.
+ */
+function construirMetadatosDeLog(args) {
+    const response = parsearResponse(args.responseBody);
+    /* La frase se calcula ANTES de podar, porque entra DENTRO del response.
+       Antes salía aparte, en `errorSummary`, y la pantalla la pintaba en una
+       caja roja encima del panel. Se junta con el veredicto a propósito: lo
+       que se quiere leer de un log que falló es «qué contestó el nodo», y eso
+       son las dos cosas a la vez, no una arriba y otra dentro. */
+    const fallo = args.success
+        ? undefined
+        : explicarFallo({
+            nodeType: args.nodeType,
+            nodeName: args.nodeName,
+            statusCode: args.statusCode,
+            response,
+        });
+    /* La poda compara los ORIGINALES, antes de recortar: si se comparara
+       después, dos recortes distintos del mismo dato parecerían datos
+       distintos y la repetición se colaría justo en los payloads grandes. */
+    const responsePodado = podarLoRepetido(response, args.payload, fallo);
+    const payload = recortarEstructural(args.payload);
+    const responseRecortado = recortarEstructural(responsePodado);
+    const viejas = args.conClavesViejas !== false;
+    return {
+        ...(args.extra ?? {}),
+        ...(payload !== undefined ? { payload } : {}),
+        ...(responseRecortado !== undefined ? { response: responseRecortado } : {}),
+        /* Compatibilidad con la pantalla ya desplegada. Se quitan cuando el
+           dashboard que lee `payload`/`response` esté en prod. */
+        ...(viejas && responseRecortado !== undefined
+            ? { responseBody: responseRecortado }
+            : {}),
+        ...(viejas && payload !== undefined ? { requestPayload: payload } : {}),
+    };
+}

package/dist/node-dispatch.registry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Node Dispatch Registry — re-exports from @hostwebhook/node-types shared package.
+ * Adds backward-compatible array form and getAllOutputs runtime helper.
+ */
+export type { NodeDispatchConfig } from '@hostwebhook/node-types';
+export { NODE_DISPATCH, getAllNodeCollections, getNodeDispatchConfig, } from '@hostwebhook/node-types';
+/** Array form for backward compat (event-pipeline uses .find()) */
+export declare const NODE_DISPATCH_REGISTRY: {
+    service: string;
+    collection: string;
+    hasFilters: boolean;
+    outputFields: string[];
+    customDispatch: boolean;
+    pipelineDispatch: import("@hostwebhook/node-types/dist/types").PipelineDispatchKind;
+    type: string;
+}[];
+/**
+ * Unconditional downstream targets — the edges that fire whenever the node
+ * succeeds, with no branch decision involved.
+ *
+ * A named port (`branch:…`, `output:…`, `category:…`, `rule:…`, `else`,
+ * `loop`, `done`, `rejected`) is NOT unconditional: its owner decides
+ * whether it fires, via the handler's own `getOutputNodes`. Including one
+ * here would fan a payload down every branch at once. That is why the
+ * `main` filter below is load-bearing and not a tidy-up — Phase 1 moved
+ * every edge into `outputNodes`, so without it this function would return
+ * branches it never saw before.
+ */
+export declare function getAllOutputs(node: any): Array<{
+    nodeType: string;
+    nodeId: string;
+}>;

package/dist/node-dispatch.registry.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Node Dispatch Registry — re-exports from @hostwebhook/node-types shared package.
+ * Adds backward-compatible array form and getAllOutputs runtime helper.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODE_DISPATCH_REGISTRY = exports.getNodeDispatchConfig = exports.getAllNodeCollections = exports.NODE_DISPATCH = void 0;
+exports.getAllOutputs = getAllOutputs;
+const node_types_1 = require("@hostwebhook/node-types");
+var node_types_2 = require("@hostwebhook/node-types");
+Object.defineProperty(exports, "NODE_DISPATCH", { enumerable: true, get: function () { return node_types_2.NODE_DISPATCH; } });
+Object.defineProperty(exports, "getAllNodeCollections", { enumerable: true, get: function () { return node_types_2.getAllNodeCollections; } });
+Object.defineProperty(exports, "getNodeDispatchConfig", { enumerable: true, get: function () { return node_types_2.getNodeDispatchConfig; } });
+/** Array form for backward compat (event-pipeline uses .find()) */
+exports.NODE_DISPATCH_REGISTRY = Object.entries(node_types_1.NODE_DISPATCH).map(([type, config]) => ({ type, ...config }));
+/**
+ * Unconditional downstream targets — the edges that fire whenever the node
+ * succeeds, with no branch decision involved.
+ *
+ * A named port (`branch:…`, `output:…`, `category:…`, `rule:…`, `else`,
+ * `loop`, `done`, `rejected`) is NOT unconditional: its owner decides
+ * whether it fires, via the handler's own `getOutputNodes`. Including one
+ * here would fan a payload down every branch at once. That is why the
+ * `main` filter below is load-bearing and not a tidy-up — Phase 1 moved
+ * every edge into `outputNodes`, so without it this function would return
+ * branches it never saw before.
+ */
+function getAllOutputs(node) {
+    const seen = new Set();
+    const result = [];
+    const add = (nodeType, nodeId) => {
+        const id = nodeId?.toString?.() ?? String(nodeId);
+        const key = `${nodeType}:${id}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push({ nodeType, nodeId: id });
+        }
+    };
+    for (const n of node.outputNodes ?? []) {
+        if ((n.port ?? 'main') !== 'main')
+            continue;
+        add(n.nodeType, n.nodeId);
+    }
+    return result;
+}