@hostwebhook/node-sdk 0.1.0

package/dist/node-lifecycle.d.ts

@@ -0,0 +1,399 @@
+/**
+ * Unified Node Lifecycle — single dispatch function for all 3 execution paths.
+ *
+ * Each node type registers a NodeHandler. dispatchSingleNode() runs the
+ * standard lifecycle: fetch → validate → filter → execute → save → delivery → telemetry → downstream.
+ * Only the execute step is node-specific.
+ */
+import { Types } from 'mongoose';
+import type { PasoEjecutado, RunStepStatus } from './contratos';
+import { type NodeExecutionResult, type NodeExecutorServices, type ExecutorContext } from './node-executors';
+import type { EmisorDeTelemetria as TelemetryService, LogSource } from './contratos';
+/**
+ * ⚠️ Extiende `ContextoDelHistorial` a propósito, y no lo repite: son el mismo
+ * `orgId`, el mismo `event` y el mismo `webhook`, y dos declaraciones paralelas
+ * se separan en cuanto una crezca. Así el compilador garantiza que todo
+ * contexto del pipeline sirve para anotar un paso.
+ */
+export interface NodeLifecycleContext extends ContextoDelHistorial {
+    mode: 'prod' | 'pipeline-run' | 'test';
+    orgId: string;
+    event: {
+        id: string;
+        headers: Record<string, unknown>;
+        sourceIp?: string;
+        eventType?: string;
+        correlationId?: string;
+        createdAt?: Date;
+    };
+    webhook: {
+        id: string;
+        name: string;
+    };
+    depth: number;
+    services: NodeExecutorServices;
+    executorContext: ExecutorContext;
+    /** Telemetry service (prod + pipeline-run) */
+    telemetry?: TelemetryService;
+    /**
+     * El historial de corridas. CONVIVE con la telemetría: durante un
+     * tiempo cada paso se escribe en los dos sitios, que es lo que permite
+     * comprobar que el historial no pierde nada antes de retirar el otro.
+     *
+     * Opcional por lo mismo que `telemetry`: los modos que no lo traen
+     * —tests, ejecuciones sueltas— siguen funcionando sin él.
+     */
+    historial?: {
+        registrarPaso(paso: PasoEjecutado): void;
+    };
+    /** WebSocket gateway for emitting real-time node payload updates */
+    gateway?: {
+        emitPipelineStep(orgId: string, step: object): void;
+        emitNodePayload(orgId: string, data: {
+            nodeType: string;
+            nodeId: string;
+            lastPayload: unknown;
+        }): void;
+        resolveSyncWaiter(eventId: string, result: {
+            status: number;
+            body: Record<string, unknown>;
+        }): void;
+    };
+    /** Delivery model for creating delivery records (prod only) */
+    deliveryModel?: any;
+    /** Dispatch downstream outputs — provided by the caller (event-pipeline or pipeline-run) */
+    dispatchOutputNodes?: (outputs: Array<{
+        nodeType: string;
+        nodeId: Types.ObjectId;
+    }>, payload: Record<string, unknown>, event: any, webhook: any, ctx: any, depth: number) => Promise<void>;
+    /** Raw event/webhook documents for downstream dispatch */
+    rawEvent?: any;
+    rawWebhook?: any;
+    rawCtx?: any;
+    /** Event model for creating child events (webhook outputs) */
+    eventModel?: any;
+    /** Callback for child events created for webhook outputs */
+    onEventCreated?: (childEvent: any, outEp: any, ctx: any) => Promise<void>;
+    /** Webhook model for looking up webhook outputs */
+    webhookModel?: any;
+    /** Handle loop iteration (loop-back signal) — provided by event-pipeline */
+    handleLoopIteration?: (event: any, webhook: any, loopNode: any, payload: any, ctx: any, depth: number) => Promise<void>;
+    /** Loop state ID — when set, nodes write checkpoints for crash recovery */
+    loopStateId?: string;
+    /** Called when a node fails inside a loop — triggers skip/retry/stop policy */
+    onLoopIterationError?: (loopStateId: string, error: string, retriedTransient: boolean) => Promise<void>;
+    /** Loop checkpoint writer — saves lastCompletedNode for crash recovery */
+    updateLoopCheckpoint?: (stateId: string, node: {
+        nodeType: string;
+        nodeId: string;
+        outputPayload: Record<string, unknown>;
+    }) => Promise<void>;
+    /** Raw MongoDB connection for direct queries */
+    connection?: any;
+    /** In-memory workspace payload overrides — used by loops to inject current iteration payload */
+    wsPayloadOverrides?: Record<string, Record<string, unknown>>;
+    /**
+     * Cross-workspace dispatch hook — called after a node's local downstream
+     * dispatch completes. The implementation queries FlowLinks where source
+     * matches and invokes each target trigger in another workspace. Optional;
+     * paths that don't wire it (test mode, replay) silently skip flow links.
+     */
+    dispatchFlowLinksFor?: (sourceNodeType: string, sourceNodeId: string, payload: Record<string, unknown>, callStack?: string[]) => Promise<void>;
+}
+export interface DeliveryData {
+    eventId: string;
+    webhookId: string;
+    statusCode: number;
+    success: boolean;
+    error?: string;
+    targetUrl: string;
+    /** Dynamic action ID field (e.g. httpActionId, emailActionId) */
+    [key: string]: unknown;
+}
+export interface NodeHandler {
+    /** Node type key */
+    nodeType: string;
+    /**
+     * Qué versión del tipo atiende este handler.
+     *
+     * Sin declarar —el caso de los 43 tipos hoy— significa "la única que
+     * hay". Se declara el día que un proveedor deprecia sus endpoints y hay
+     * que servir dos versiones a la vez; entonces cada una registra el suyo
+     * y el despacho las separa por la clave. Ver `docs/ADR-0002`.
+     */
+    version?: number;
+    /** Telemetry source label */
+    telemetrySource: LogSource;
+    /**
+     * Fetch the entity from DB via the node's service.
+     */
+    fetchEntity(id: string, orgId: string): Promise<any>;
+    /**
+     * Save lastPayload via the node's service.
+     */
+    /** El resultado se ignora aquí. Se tipa `unknown` y no `void` porque
+     *  `BaseNodeService.saveLastPayload` devuelve el `organizationId` para
+     *  quien quiera avisar por socket, y `Promise<X>` no es asignable a
+     *  `Promise<void>` — cada servicio que lo pasa como callback fallaría. */
+    saveLastPayload(id: string, payload: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Execute the node. Returns NodeExecutionResult.
+     */
+    execute(entity: any, payload: Record<string, unknown>, ctx: NodeLifecycleContext): Promise<NodeExecutionResult>;
+    /**
+     * Pre-execution filter check.
+     * Return a reason string to block, or null to proceed.
+     * Default: check entity.filters via evaluateFilters (if the node has filters).
+     */
+    preFilter?(entity: any, payload: Record<string, unknown>): string | null;
+    /**
+     * Extract the output payload from the execution result.
+     * Return null to block downstream dispatch (e.g. code node returns null).
+     * Default: result.outputPayload ?? inputPayload
+     */
+    getOutputPayload?(entity: any, result: NodeExecutionResult, inputPayload: Record<string, unknown>): Record<string, unknown> | null;
+    /**
+     * Build the lastPayload to save (with _meta diagnostics).
+     * Default: wrap in { _meta: { iterable: false, count: 1 }, ...outputPayload }
+     */
+    buildLastPayload?(entity: any, result: NodeExecutionResult, outputPayload: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Build delivery record data (action nodes only).
+     * Return null to skip delivery creation.
+     */
+    buildDeliveryRecord?(entity: any, result: NodeExecutionResult, success: boolean, ctx: NodeLifecycleContext): DeliveryData | null;
+    /**
+     * Get node-specific telemetry metadata.
+     */
+    getTelemetryMetadata?(entity: any, result: NodeExecutionResult): Record<string, unknown>;
+    /**
+     * Override telemetry emission entirely. If provided, the lifecycle skips its generic emit.
+     * Use this for nodes with custom telemetry (e.g. filter emits 'warn' when blocked, not 'error').
+     * May return a Promise — the lifecycle awaits it. Async variants matter for handlers that
+     * call `telemetry.emitAndWait` themselves for SIGTERM-safe recovery.
+     */
+    emitTelemetry?(entity: any, result: NodeExecutionResult, success: boolean, outputPayload: Record<string, unknown> | null, ctx: NodeLifecycleContext, 
+    /** Lo que ENTRÓ al nodo. Va también aquí para que un emisor propio pueda
+     *  guardar los mismos dos campos que el unificado: sin esto, el único
+     *  handler que se emite aparte se quedaba sin la entrada. */
+    inputPayload?: Record<string, unknown>): void | Promise<void>;
+    /**
+     * When true, the lifecycle awaits the success telemetry write before
+     * returning from `dispatchSingleNode`. Use for nodes whose re-execution
+     * is costly or non-idempotent — primarily LLM-calling nodes (AI Node)
+     * where a SIGTERM between handler completion and a fire-and-forget
+     * telemetry write would make `hasRecentSuccess` return false on
+     * recovery, triggering a re-run and double-charging the provider.
+     * Default false (fire-and-forget — the right choice for cheap idempotent ops).
+     */
+    awaitTelemetry?: boolean;
+    /**
+     * Return a sync result to resolve the ingress sync waiter.
+     * Called after execution — return non-null to resolve immediately (e.g. schema validator invalid).
+     * Return null to let delivery resolve the sync waiter later.
+     */
+    getSyncResult?(entity: any, result: NodeExecutionResult, outputPayload: Record<string, unknown> | null, ctx: NodeLifecycleContext): {
+        status: number;
+        body: Record<string, unknown>;
+    } | null;
+    /**
+     * Whether to propagate to downstream on success.
+     * Default: true
+     */
+    propagateDownstream?: boolean;
+    /**
+     * Which payload to propagate downstream: the execution result or the original input.
+     * Default: 'result' (use output payload)
+     */
+    downstreamPayload?: 'result' | 'original';
+    /**
+     * Override which nodes to dispatch downstream.
+     * If not defined, uses getAllOutputs(entity) which reads outputNodes + elseOutputNodes + branches etc.
+     * Use this for nodes with conditional routing (e.g. conditional dispatches only the matched branch).
+     */
+    getOutputNodes?(entity: any, result: NodeExecutionResult): Array<{
+        nodeType: string;
+        nodeId: string;
+    }>;
+}
+export declare function registerNodeHandler(handler: NodeHandler): void;
+/**
+ * El handler de un tipo, opcionalmente el de una versión concreta.
+ *
+ * Sin `version` devuelve el de la versión vigente, que es exactamente lo
+ * que hacía antes de que existieran las versiones. Con una versión que
+ * nadie registró cae al vigente en vez de devolver nada: un nodo apuntando
+ * a una versión que ya se retiró debe seguir corriendo, no dejar de
+ * dispararse en silencio.
+ */
+export declare function getNodeHandler(nodeType: string, version?: number): NodeHandler | undefined;
+/**
+ * Telemetry log source for a node type.
+ *
+ * This used to be a 33-entry `NODE_TYPE_TO_SOURCE` map maintained by hand in
+ * pipeline-run.service.ts — a fourth place to remember when adding a node,
+ * and one that had already grown duplicate aliases (`approval` /
+ * `approvalNode`, `delay` / `delayNode`, `merge` / `mergeNode`,
+ * `conditional` / `conditionalNode`) because nobody could tell which key the
+ * callers passed. Every handler already declares `telemetrySource`, so the
+ * map was a copy of information the registry owned.
+ *
+ * Types with no handler declare their source next to the reason they have no
+ * handler, in HANDLERLESS_NODE_TYPES. Anything else — the non-node sources
+ * the pipeline logs under, like 'delivery', 'replay' and 'chain' — passes
+ * through as-is, which is what the old map's `?? nodeType` fallback did.
+ */
+export declare function getTelemetrySource(nodeType: string): LogSource;
+export interface DispatchResult {
+    executed: boolean;
+    result?: NodeExecutionResult;
+    /**
+     * El mensaje del fallo cuando el nodo REVENTÓ.
+     *
+     * ⚠️ `executed: false` no quiere decir «no llegó a correr». `ejecutarNodo`
+     * lo devuelve por seis caminos y tres de ellos son fallos: no se pudo traer
+     * la entidad, el handler lanzó (o se le acabó el tiempo), o falló dentro de
+     * un loop. Los otros tres sí son «no corrió»: no hay handler, el nodo está
+     * inactivo, lo descartó el pre-filtro.
+     *
+     * Sin este campo los seis se leen igual desde fuera, y el historial no
+     * puede distinguir un nodo que explotó de uno que nadie llamó — que era
+     * exactamente el bug: un nodo caído se guardaba como `skipped`.
+     *
+     * Vacío = no hubo fallo. Nadie más que el historial lo mira, así que
+     * añadirlo no cambia a ningún llamador.
+     */
+    error?: string;
+}
+/**
+ * Lo poco del contexto que hace falta para anotar un paso.
+ *
+ * Es un subconjunto de `NodeLifecycleContext` a propósito. Quien ejecuta un
+ * nodo fuera del pipeline —el Chat Trigger, un tool del nodo AI, uno de MCP—
+ * no tiene un contexto de ciclo de vida, y obligarle a fabricar uno a base de
+ * `{} as never` para poder anotar es cómo se acaba con `services` vacíos
+ * paseándose por sitios donde alguien va a leerlos.
+ *
+ * `NodeLifecycleContext` lo satisface tal cual, así que el pipeline no cambia.
+ */
+export interface ContextoDelHistorial {
+    orgId: string;
+    event: {
+        id: string;
+        correlationId?: string;
+    };
+    /** El ORIGEN de la corrida: el trigger, el chat, el servidor MCP. */
+    webhook: {
+        id: string;
+        name: string;
+    };
+    historial?: {
+        registrarPaso(paso: PasoEjecutado): void;
+    };
+    /**
+     * Cómo se disparó la corrida. Ausente = producción. Ver `Run.modo`.
+     *
+     * No sale de `NodeLifecycleContext.mode`, que también vale
+     * `'pipeline-run'`, porque son dos cosas distintas: aquél dice cómo se
+     * ejecuta un nodo —y los tools del agente y los de MCP lo ponen en
+     * `'pipeline-run'` estando en producción—, éste dice de dónde salió la
+     * corrida. Confundirlos marcaría como prueba todo lo que hace un agente.
+     */
+    modoDeCorrida?: 'pipeline';
+}
+/**
+ * Lo que hay que saber de un paso para poder anotarlo.
+ *
+ * `nodeName` y `workspaceId` van sueltos y se rellenan DURANTE la ejecución,
+ * no antes: viven en la entidad, y la entidad la carga quien corre el paso.
+ * Ver `FichaDelNodo`, que es la mitad que `ejecutarNodo` rellena.
+ */
+export interface FichaDelPaso {
+    nodeType: string;
+    nodeId: string;
+    nodeName?: string;
+    workspaceId?: string;
+    entrada: unknown;
+}
+/** Cómo acabó un paso, visto desde fuera de quien lo ejecutó. */
+export interface VeredictoDelPaso {
+    status: RunStepStatus;
+    salida?: unknown;
+    error?: string;
+}
+/**
+ * Saca del resultado la frase que explica el fallo.
+ *
+ * Los handlers devuelven el cuerpo como texto, y casi siempre es un JSON con
+ * `error` dentro — una frase ya escrita para leerse. Enseñar el JSON crudo en
+ * la línea de tiempo es enseñar llaves y comillas donde cabía la explicación.
+ * Si no es JSON, o no trae `error`, se enseña el cuerpo recortado; y si no hay
+ * cuerpo, el código HTTP, que al menos dice algo.
+ */
+export declare function mensajeDeFallo(result?: NodeExecutionResult): string;
+/**
+ * Cómo le fue al paso, a partir de lo que devolvió el despacho.
+ *
+ * ⚠️ El veredicto sale del `statusCode`, NO de si el nodo llegó a correr. Eso
+ * era el bug: `anotar(r.executed ? 'success' : 'skipped')` daba `success` a
+ * todo nodo que corriera, devolviese lo que devolviese. Un Email Action que
+ * lleva cinco días contestando 500 tenía cinco corridas en verde, con el
+ * `{"statusCode":500}` guardado dentro de su propio payload. La telemetría de
+ * este mismo fichero ya lo miraba bien (`result.statusCode < 400`): eran dos
+ * criterios distintos sobre el mismo resultado.
+ *
+ * Los tres estados, y por qué son tres y no dos:
+ *
+ * - `failed`  — corrió y salió mal, o reventó. Es lo que cuenta `failures` y
+ *               lo que hace que la corrida entera sea `failed` o `partial`.
+ * - `skipped` — no llegó a correr: inactivo, filtrado, sin handler. Un paso
+ *               que no existe y uno que se saltó no se leen igual.
+ * - `success` — corrió y salió bien.
+ */
+export declare function veredictoDelDespacho(r: DispatchResult): VeredictoDelPaso;
+/**
+ * El veredicto de un nodo que SÍ corrió, sacado de lo que devolvió.
+ *
+ * Aparte de `veredictoDelDespacho` porque las rutas que no pasan por el
+ * pipeline —el Chat Trigger, los tools del nodo AI, los de MCP— no tienen un
+ * `DispatchResult`: tienen el `NodeExecutionResult` a secas. El criterio de
+ * qué es un fallo tiene que ser UNO, o vuelven a ser dos.
+ *
+ * Sin `statusCode` numérico se da por bueno a propósito: un handler que no lo
+ * declara no está diciendo que falló, y pintar de rojo lo que no se sabe es
+ * peor que dejarlo verde — el rojo se mira.
+ */
+export declare function veredictoDeResultado(result?: NodeExecutionResult): VeredictoDelPaso;
+/**
+ * Corre algo y lo deja escrito en el historial como un paso.
+ *
+ * Es una envoltura, y no un puñado de llamadas repartidas por dentro, a
+ * propósito: `ejecutarNodo` tiene seis salidas —no hay handler, no se pudo
+ * traer la entidad, está inactiva, la filtró el pre-filtro, reventó, salió
+ * bien— y anotar el paso en cada una es la clase de lista que se olvida en la
+ * séptima. Desde fuera se ven todas a la vez, con su duración de verdad.
+ *
+ * Vive fuera de `dispatchSingleNode` porque el pipeline de producción NO es la
+ * única forma de ejecutar un nodo. El Chat Trigger, los tools del nodo AI, los
+ * de MCP, Run Pipeline y Run Test llegan al nodo por su cuenta, y sin una
+ * función a la que llamar cada uno tendría que copiar este bloque — que es
+ * como se llega a seis copias que se desincronizan.
+ *
+ * `ficha` se lee DESPUÉS de correr, no antes: `correr` puede rellenarle el
+ * `nodeName` y el `workspaceId` en cuanto cargue la entidad. Son opcionales en
+ * `PasoEjecutado`, así que olvidarlos no rompe nada y sólo se nota en pantalla
+ * —sin `nodeName` la línea de tiempo enseña el tipo dos veces; sin
+ * `workspaceId` la corrida sale sin foto y diciendo que es anterior al sellado
+ * de versiones—.
+ *
+ * Nunca estorba: si no hay `historial` en el contexto —tests, modos que no lo
+ * montan— esto es una llamada directa y ya está.
+ */
+export declare function conPasoRegistrado<T>(ctx: ContextoDelHistorial, ficha: FichaDelPaso, correr: () => Promise<T>, veredicto: (r: T) => VeredictoDelPaso): Promise<T>;
+/**
+ * Ejecuta un nodo y, de paso, lo deja escrito en el historial.
+ *
+ * El payload de entrada es un argumento, así que entra gratis. El de salida y
+ * el veredicto salen del resultado, en `veredictoDelDespacho`.
+ */
+export declare function dispatchSingleNode(nodeType: string, id: string, payload: Record<string, unknown>, ctx: NodeLifecycleContext): Promise<DispatchResult>;