@hostwebhook/node-sdk 0.1.0

package/dist/filter-utils.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNestedValue = getNestedValue;
+exports.evaluateFilters = evaluateFilters;
+exports.evaluateFiltersIterable = evaluateFiltersIterable;
+const template_engine_1 = require("@hostwebhook/template-engine");
+const regex_de_inquilino_1 = require("./regex-de-inquilino");
+function getNestedValue(obj, path) {
+    return path.split('.').reduce((curr, key) => {
+        if (curr !== null && typeof curr === 'object') {
+            return curr[key];
+        }
+        return undefined;
+    }, obj);
+}
+/** Try to compare as numbers; if either is NaN, try as dates; if still NaN, compare as strings. */
+function smartCompare(a, b) {
+    const numA = Number(a);
+    const numB = Number(b ?? 0);
+    if (!isNaN(numA) && !isNaN(numB))
+        return { left: numA, right: numB };
+    // Try date comparison (ISO strings, date strings)
+    const dA = new Date(String(a)).getTime();
+    const dB = new Date(String(b)).getTime();
+    if (!isNaN(dA) && !isNaN(dB))
+        return { left: dA, right: dB };
+    // Fallback: lexicographic string comparison via charCodeAt sum won't work — use localeCompare
+    const cmp = String(a).localeCompare(String(b));
+    return { left: cmp, right: 0 };
+}
+function matchFilter(f, payload, opts) {
+    // Resolve field: supports {{$now}}, {{payload.field}}, or plain dot notation
+    const fieldStr = String(f.field ?? '');
+    const val = /^\{\{/.test(fieldStr)
+        ? (0, template_engine_1.resolveInput)(fieldStr, payload, opts)
+        : getNestedValue(payload, (0, template_engine_1.resolveFieldPath)(fieldStr));
+    const fv = (0, template_engine_1.resolveInput)(f.value, payload, opts);
+    switch (f.operator) {
+        // String
+        case 'eq':
+            return String(val) === String(fv ?? '');
+        case 'neq':
+            return String(val) !== String(fv ?? '');
+        case 'contains':
+            return typeof val === 'string' && val.includes(String(fv ?? ''));
+        case 'not_contains':
+            return typeof val === 'string' && !val.includes(String(fv ?? ''));
+        case 'starts_with':
+            return typeof val === 'string' && val.startsWith(String(fv ?? ''));
+        case 'not_starts_with':
+            return typeof val === 'string' && !val.startsWith(String(fv ?? ''));
+        case 'ends_with':
+            return typeof val === 'string' && val.endsWith(String(fv ?? ''));
+        case 'not_ends_with':
+            return typeof val === 'string' && !val.endsWith(String(fv ?? ''));
+        case 'is_empty':
+            return val === undefined || val === null || val === '';
+        case 'is_not_empty':
+            return val !== undefined && val !== null && val !== '';
+        case 'matches_regex':
+            /* El patron lo escribe el inquilino y la cadena viene del payload, que
+               entra por el ingress publico: con el motor de JavaScript, `(a+)+$`
+               contra treinta caracteres deja el hilo girando. Ver
+               `regex-de-inquilino.ts`. */
+            return (0, regex_de_inquilino_1.casaRegexDeInquilino)(String(fv ?? ''), val, 'matches_regex');
+        // Number / Date (smart comparison)
+        case 'gt': {
+            const c = smartCompare(val, fv);
+            return c.left > c.right;
+        }
+        case 'gte': {
+            const c = smartCompare(val, fv);
+            return c.left >= c.right;
+        }
+        case 'lt': {
+            const c = smartCompare(val, fv);
+            return c.left < c.right;
+        }
+        case 'lte': {
+            const c = smartCompare(val, fv);
+            return c.left <= c.right;
+        }
+        // Date comparison
+        case 'date_before': {
+            const dA = new Date(String(val)).getTime();
+            const dB = new Date(String(fv)).getTime();
+            return !isNaN(dA) && !isNaN(dB) && dA < dB;
+        }
+        case 'date_after': {
+            const dA = new Date(String(val)).getTime();
+            const dB = new Date(String(fv)).getTime();
+            return !isNaN(dA) && !isNaN(dB) && dA > dB;
+        }
+        case 'date_eq': {
+            const dA = new Date(String(val)).toISOString().slice(0, 10);
+            const dB = new Date(String(fv)).toISOString().slice(0, 10);
+            return dA === dB;
+        }
+        // Boolean
+        case 'is_true':
+            return val === true || val === 'true' || val === 1;
+        case 'is_false':
+            return val === false || val === 'false' || val === 0;
+        // Existence
+        case 'exists':
+            return val !== undefined && val !== null;
+        case 'not_exists':
+            return val === undefined || val === null;
+        // Array
+        case 'array_contains':
+            return (Array.isArray(val) && val.some((v) => String(v) === String(fv ?? '')));
+        case 'array_not_contains':
+            return (Array.isArray(val) && !val.some((v) => String(v) === String(fv ?? '')));
+        case 'array_empty':
+            return Array.isArray(val) && val.length === 0;
+        case 'array_not_empty':
+            return Array.isArray(val) && val.length > 0;
+        case 'array_length_eq':
+            return Array.isArray(val) && val.length === Number(fv ?? 0);
+        case 'array_length_gt':
+            return Array.isArray(val) && val.length > Number(fv ?? 0);
+        case 'array_length_lt':
+            return Array.isArray(val) && val.length < Number(fv ?? 0);
+        // Object
+        case 'has_key':
+            return (val !== null &&
+                typeof val === 'object' &&
+                !Array.isArray(val) &&
+                String(fv ?? '') in val);
+        default:
+            return true;
+    }
+}
+function evaluateFilters(filters, payload, mode = 'and', opts) {
+    const active = (filters ?? []).filter((f) => f.enabled !== false);
+    if (active.length === 0)
+        return true;
+    if (mode === 'and')
+        return active.every((f) => matchFilter(f, payload, opts));
+    return active.some((f) => matchFilter(f, payload, opts));
+}
+/**
+ * Evaluate filters against a payload that may be iterable.
+ * If iterable: filters each item, returns a new iterable payload with only passing items.
+ * If not iterable: returns { passed, payload } with the original payload.
+ */
+function evaluateFiltersIterable(filters, payload, mode = 'and', outputAsSingle = false, opts) {
+    const meta = payload._meta;
+    if (meta?.iterable && meta.iterateField) {
+        const items = payload[meta.iterateField] ?? [];
+        const passing = items.filter((item) => evaluateFilters(filters, item, mode, opts));
+        const resultPayload = outputAsSingle
+            ? { _meta: { iterable: false, count: 1 }, [meta.iterateField]: passing }
+            : {
+                _meta: {
+                    iterable: true,
+                    iterateField: meta.iterateField,
+                    count: passing.length,
+                },
+                [meta.iterateField]: passing,
+            };
+        return {
+            passed: passing.length > 0,
+            resultPayload,
+            totalItems: items.length,
+            passedItems: passing.length,
+        };
+    }
+    // Strip _meta for evaluation, keep it in result
+    const { _meta, ...cleanPayload } = payload;
+    const passed = evaluateFilters(filters, cleanPayload, mode, opts);
+    return {
+        passed,
+        resultPayload: payload,
+        totalItems: 1,
+        passedItems: passed ? 1 : 0,
+    };
+}

package/dist/handler-helpers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared helpers for node handler definitions.
+ * Reusable getOutputPayload, buildLastPayload, and buildDeliveryRecord builders
+ * that most action/processing handlers share.
+ */
+type Result = {
+    statusCode: number;
+    responseBody: string;
+    latencyMs: number;
+    outputPayload?: Record<string, unknown>;
+};
+/** Standard getOutputPayload — parse responseBody, preserve _meta, spread fields */
+export declare function standardGetOutputPayload(_entity: any, result: Result, _input: Record<string, unknown>): Record<string, unknown> | null;
+/** Standard buildLastPayload — wrap output with success/statusCode/latencyMs in _meta */
+export declare function standardBuildLastPayload(_entity: any, result: Result, output: Record<string, unknown>): Record<string, unknown>;
+/** Build a standard action delivery record */
+export declare function buildActionDeliveryRecord(actionIdField: string, entity: any, result: Result, success: boolean, ctx: {
+    event: any;
+    webhook: any;
+}, targetUrl?: string): Record<string, unknown>;
+export {};

package/dist/handler-helpers.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Shared helpers for node handler definitions.
+ * Reusable getOutputPayload, buildLastPayload, and buildDeliveryRecord builders
+ * that most action/processing handlers share.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.standardGetOutputPayload = standardGetOutputPayload;
+exports.standardBuildLastPayload = standardBuildLastPayload;
+exports.buildActionDeliveryRecord = buildActionDeliveryRecord;
+/** Standard getOutputPayload — parse responseBody, preserve _meta, spread fields */
+function standardGetOutputPayload(_entity, result, _input) {
+    try {
+        const parsed = result.responseBody ? JSON.parse(result.responseBody) : {};
+        const meta = parsed?._meta ?? {};
+        return {
+            _meta: { iterable: false, count: 1, ...meta },
+            ...Object.fromEntries(Object.entries(typeof parsed === 'object' && parsed !== null
+                ? parsed
+                : { value: parsed }).filter(([k]) => k !== '_meta')),
+        };
+    }
+    catch {
+        return { _meta: { iterable: false, count: 1 }, raw: result.responseBody };
+    }
+}
+/** Standard buildLastPayload — wrap output with success/statusCode/latencyMs in _meta */
+function standardBuildLastPayload(_entity, result, output) {
+    const meta = output._meta ?? {};
+    return {
+        _meta: {
+            ...meta,
+            success: result.statusCode < 400,
+            statusCode: result.statusCode,
+            latencyMs: result.latencyMs,
+        },
+        ...Object.fromEntries(Object.entries(output).filter(([k]) => k !== '_meta')),
+    };
+}
+/** Build a standard action delivery record */
+function buildActionDeliveryRecord(actionIdField, entity, result, success, ctx, targetUrl) {
+    return {
+        eventId: ctx.event.id,
+        webhookId: ctx.webhook.id,
+        [actionIdField]: entity._id?.toString(),
+        statusCode: result.statusCode || (success ? 200 : 0),
+        success,
+        error: success ? undefined : result.responseBody,
+        targetUrl: targetUrl ?? '',
+        attemptedAt: new Date(),
+        attempt: 1,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @hostwebhook/node-sdk
+ *
+ * Lo que un servicio necesita para EJECUTAR nodos de HostWebhook, sin traerse
+ * la aplicación entera. Sale de `api/src/common/`, donde estos 27 ficheros
+ * convivían con el motor de ejecución y con los servicios de operaciones de
+ * cada integración.
+ *
+ * ## Qué NO está aquí, y por qué
+ *
+ * - **`BaseNodeService`** y el **factory de controladores**. Arrastran 19 y
+ *   37 ficheros de fuera —planes, credenciales, auditoría, decoradores de
+ *   auth— por cinco y cuatro colaboradores concretos. Salen cuando esos se
+ *   inviertan tras una interfaz, no antes.
+ * - **El motor** (`event-pipeline`, `pipeline-run`). Es la aplicación, no
+ *   el SDK: decide QUÉ nodo corre y cuándo. Aquí está sólo el CÓMO corre uno.
+ * - Los **servicios de operaciones** por integración. Se van con los nodos.
+ *
+ * ## Los contratos
+ *
+ * `contratos.ts` declara los siete tipos que antes llegaban de entidades de
+ * la api por `import type`. La dirección se invierte: los define el SDK y la
+ * api los cumple.
+ */
+export * from "./code-runner";
+export * from "./contratos";
+export * from "./ensure-meta";
+export * from "./execute-with-iteration";
+export * from "./filter-utils";
+export * from "./handler-helpers";
+export * from "./log-metadata";
+export * from "./node-dispatch.registry";
+export * from "./node-executors";
+export * from "./node-lifecycle";
+export * from "./normalize-nodes";
+export * from "./output-node-ref.schema";
+export * from "./output-webhook-scope";
+export * from "./payload-preview";
+export * from "./pipeline.constants";
+export * from "./pre-request-pool";
+export * from "./pre-request-runner-source";
+export * from "./regex-de-inquilino";
+export * from "./request-context";
+export { retryOnTransientError, type NodeResult } from "./retry-transient";
+export * from "./retry-utils";
+export * from "./schema-validator-utils";
+export * from "./ssrf-guard";
+export * from "./swallow";
+export * from "./template-render";
+export * from "./try-parse";
+export * from "./workspace-payloads";

package/dist/index.js

@@ -0,0 +1,73 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryOnTransientError = void 0;
+/**
+ * @hostwebhook/node-sdk
+ *
+ * Lo que un servicio necesita para EJECUTAR nodos de HostWebhook, sin traerse
+ * la aplicación entera. Sale de `api/src/common/`, donde estos 27 ficheros
+ * convivían con el motor de ejecución y con los servicios de operaciones de
+ * cada integración.
+ *
+ * ## Qué NO está aquí, y por qué
+ *
+ * - **`BaseNodeService`** y el **factory de controladores**. Arrastran 19 y
+ *   37 ficheros de fuera —planes, credenciales, auditoría, decoradores de
+ *   auth— por cinco y cuatro colaboradores concretos. Salen cuando esos se
+ *   inviertan tras una interfaz, no antes.
+ * - **El motor** (`event-pipeline`, `pipeline-run`). Es la aplicación, no
+ *   el SDK: decide QUÉ nodo corre y cuándo. Aquí está sólo el CÓMO corre uno.
+ * - Los **servicios de operaciones** por integración. Se van con los nodos.
+ *
+ * ## Los contratos
+ *
+ * `contratos.ts` declara los siete tipos que antes llegaban de entidades de
+ * la api por `import type`. La dirección se invierte: los define el SDK y la
+ * api los cumple.
+ */
+__exportStar(require("./code-runner"), exports);
+__exportStar(require("./contratos"), exports);
+__exportStar(require("./ensure-meta"), exports);
+__exportStar(require("./execute-with-iteration"), exports);
+__exportStar(require("./filter-utils"), exports);
+__exportStar(require("./handler-helpers"), exports);
+__exportStar(require("./log-metadata"), exports);
+__exportStar(require("./node-dispatch.registry"), exports);
+__exportStar(require("./node-executors"), exports);
+__exportStar(require("./node-lifecycle"), exports);
+__exportStar(require("./normalize-nodes"), exports);
+__exportStar(require("./output-node-ref.schema"), exports);
+__exportStar(require("./output-webhook-scope"), exports);
+__exportStar(require("./payload-preview"), exports);
+__exportStar(require("./pipeline.constants"), exports);
+__exportStar(require("./pre-request-pool"), exports);
+__exportStar(require("./pre-request-runner-source"), exports);
+__exportStar(require("./regex-de-inquilino"), exports);
+__exportStar(require("./request-context"), exports);
+/* ⚠️ `retry-transient` y `retry-utils` declaran cada uno su `RetryOptions`,
+   y NO son el mismo tipo. El barril reexporta el de `retry-utils` —el
+   general— y del otro saca sólo sus funciones; quien necesite ese tipo lo
+   importa por su módulo. Unificarlos es trabajo de la api, no del paquete. */
+var retry_transient_1 = require("./retry-transient");
+Object.defineProperty(exports, "retryOnTransientError", { enumerable: true, get: function () { return retry_transient_1.retryOnTransientError; } });
+__exportStar(require("./retry-utils"), exports);
+__exportStar(require("./schema-validator-utils"), exports);
+__exportStar(require("./ssrf-guard"), exports);
+__exportStar(require("./swallow"), exports);
+__exportStar(require("./template-render"), exports);
+__exportStar(require("./try-parse"), exports);
+__exportStar(require("./workspace-payloads"), exports);

package/dist/log-metadata.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 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.
+ */
+/** 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. */
+export declare const TOPE_DE_LOG: number;
+/**
+ * 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.
+ */
+export declare function recortarEstructural(value: unknown, tope?: number): unknown;
+/**
+ * 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.
+ */
+export declare const 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.
+ */
+export declare function mismoContenido(a: unknown, b: unknown): boolean;
+/**
+ * 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.
+ */
+export declare function podarLoRepetido(response: unknown, entrada: unknown, 
+/**
+ * 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?: string): unknown;
+/** El response ya parseado, si es que se puede. Nunca revienta. */
+export declare function parsearResponse(responseBody: unknown): unknown;
+/**
+ * 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.
+ */
+export declare function explicarFallo(args: {
+    nodeType?: string;
+    nodeName?: string;
+    statusCode?: number;
+    response?: unknown;
+}): string;
+/**
+ * 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.
+ */
+export declare const LEER_TAMBIEN_LAS_VIEJAS: {
+    readonly payload: readonly ["requestPayload", "payloadPreview"];
+    readonly response: readonly ["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.
+ */
+export declare function construirMetadatosDeLog(args: {
+    nodeType?: string;
+    nodeName?: string;
+    /** Lo que entró al nodo. */
+    payload?: unknown;
+    /** Lo que salió, en crudo o ya parseado. */
+    responseBody?: unknown;
+    statusCode?: number;
+    success: boolean;
+    extra?: Record<string, unknown>;
+    /** Escribir además las claves viejas. Por defecto sí, mientras la pantalla
+     *  desplegada siga siendo la anterior. */
+    conClavesViejas?: boolean;
+}): Record<string, unknown>;