@hostwebhook/node-sdk 0.1.0

package/dist/node-executors.d.ts

@@ -0,0 +1,299 @@
+/**
+ * Shared node execution functions.
+ *
+ * Both pipeline-run.service.ts (Run Pipeline / test) and event-pipeline.service.ts
+ * (real events) call these functions so that "how to execute node type X" lives in
+ * exactly ONE place.  Callers still own Delivery records, child events, telemetry,
+ * and output-routing — only core execution logic is here.
+ */
+export interface NodeExecutionResult {
+    statusCode: number;
+    responseBody: string;
+    latencyMs: number;
+    /** Parsed output payload for downstream nodes (avoids callers re-parsing responseBody) */
+    outputPayload?: Record<string, unknown>;
+}
+export interface ITransformService {
+    executeSingle(entity: any, payload: Record<string, unknown>, context?: {
+        headers?: Record<string, string>;
+        meta?: Record<string, string>;
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+    }): Promise<NodeExecutionResult>;
+}
+export interface IHttpActionService {
+    executeSingle(entity: any, payload: Record<string, unknown>, opts?: {
+        eventMeta?: Record<string, string>;
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+    }): Promise<NodeExecutionResult>;
+}
+export interface IEmailActionService {
+    executeSingle(entity: any, payload: Record<string, unknown>): Promise<NodeExecutionResult>;
+}
+export interface ISheetsActionService {
+    executeForEvent(entity: any, payload: Record<string, unknown>, opts?: {
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+    }): Promise<any>;
+}
+export interface ICalendarActionService {
+    executeForEvent(entity: any, payload: Record<string, unknown>, opts?: {
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+    }): Promise<any>;
+}
+export interface IDocsActionService {
+    executeForEvent(entity: any, payload: Record<string, unknown>, opts?: {
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+    }): Promise<any>;
+}
+export interface IFirecrawlActionService {
+    executeSingle(entity: any, payload: Record<string, unknown>, opts?: {
+        eventMeta?: Record<string, string>;
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+    }): Promise<any>;
+}
+export interface IMarkdownNodeService {
+    executeForEvent(entity: any, payload: Record<string, unknown>, opts?: {
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+    }): Promise<any>;
+}
+export interface IAiNodeService {
+    executeForEvent(entity: any, payload: Record<string, unknown>, opts?: {
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+        eventMeta?: Record<string, string>;
+    }): Promise<any>;
+}
+export interface IMongoActionService {
+    executeForEvent(entity: any, ctx: {
+        payload: Record<string, unknown>;
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+    }): Promise<{
+        result?: any;
+        latencyMs: number;
+    }>;
+}
+export interface IAggregatorService {
+    processBatchPayload(entity: any, payload: Record<string, unknown>): NodeExecutionResult | Promise<NodeExecutionResult>;
+}
+export interface ILimitNodeService {
+    executeForEvent(entity: any, payload: Record<string, unknown>): {
+        statusCode: number;
+        responseBody: string;
+        latencyMs: number;
+    };
+}
+export interface ICacheService {
+    processEvent(entity: any, payload: Record<string, unknown>): {
+        action: string;
+        outputPayload: Record<string, unknown> | null;
+    };
+}
+export interface IRateLimiterService {
+    checkRate(entity: any): {
+        allowed: boolean;
+        delayMs: number;
+    };
+}
+export interface IDriveActionService {
+    executeForEvent(entity: any, payload: Record<string, unknown>, opts?: {
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+        eventMeta?: Record<string, string>;
+    }): Promise<any>;
+}
+export interface IVectorStoreNodeService {
+    executeForEvent(entity: any, payload: Record<string, unknown> & {
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+        eventMeta?: Record<string, string>;
+    }): Promise<any>;
+}
+export interface IFileTransformNodeService {
+    executeForEvent(entity: any, payload: Record<string, unknown>, opts?: {
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+    }): Promise<any>;
+}
+export interface IPostgresActionService {
+    executeForEvent(entity: any, payload: Record<string, unknown> & {
+        workspacePayloads?: Record<string, Record<string, unknown>>;
+        eventMeta?: Record<string, string>;
+    }): Promise<any>;
+}
+export interface INotificationActionService {
+    sendForEvent(entity: any, ctx: any, payload: Record<string, unknown>): Promise<{
+        success: boolean;
+        error?: string;
+        statusCode?: number;
+    }>;
+}
+export interface NodeExecutorServices {
+    transform?: ITransformService;
+    httpAction?: IHttpActionService;
+    emailAction?: IEmailActionService;
+    sheetsAction?: ISheetsActionService;
+    calendarAction?: ICalendarActionService;
+    docsAction?: IDocsActionService;
+    firecrawlAction?: IFirecrawlActionService;
+    mongoAction?: IMongoActionService;
+    aggregator?: IAggregatorService;
+    cache?: ICacheService;
+    rateLimiter?: IRateLimiterService;
+    notificationAction?: INotificationActionService;
+    markdown?: IMarkdownNodeService;
+    ai?: IAiNodeService;
+    driveAction?: IDriveActionService;
+    vectorStore?: IVectorStoreNodeService;
+    fileTransform?: IFileTransformNodeService;
+    postgresAction?: IPostgresActionService;
+    limit?: ILimitNodeService;
+}
+export interface FilterExecutionResult extends Omit<NodeExecutionResult, 'outputPayload'> {
+    outputPayload: Record<string, unknown>;
+    passed: boolean;
+    totalItems: number;
+    passedItems: number;
+}
+export declare function executeFilter(entity: any, payload: Record<string, unknown>, context?: ExecutorContext): FilterExecutionResult;
+export declare function executeTransform(svc: ITransformService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executeHttpAction(svc: IHttpActionService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executeEmailAction(svc: IEmailActionService, entity: any, payload: Record<string, unknown>): Promise<NodeExecutionResult>;
+export declare function executeSheetsAction(svc: ISheetsActionService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executeDriveAction(svc: IDriveActionService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executeVectorStoreNode(svc: IVectorStoreNodeService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executeFileTransformNode(svc: IFileTransformNodeService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executePostgresAction(svc: IPostgresActionService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executeCalendarAction(svc: ICalendarActionService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executeDocsAction(svc: IDocsActionService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executeMarkdownNode(svc: IMarkdownNodeService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executeAiNode(svc: IAiNodeService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executeMongoAction(svc: IMongoActionService, entity: any, payload: Record<string, unknown>, context?: ExecutorContext): Promise<NodeExecutionResult>;
+export declare function executeAggregator(svc: IAggregatorService, entity: any, payload: Record<string, unknown>): Promise<NodeExecutionResult>;
+export declare function executeCache(svc: ICacheService, entity: any, payload: Record<string, unknown>): NodeExecutionResult;
+export declare function executeRateLimiter(svc: IRateLimiterService, entity: any): NodeExecutionResult;
+export declare function executeConditional(entity: any, payload: Record<string, unknown>, context?: ExecutorContext): NodeExecutionResult & {
+    matchedBranch: any | null;
+};
+export declare function executeSchemaValidator(entity: any, payload: Record<string, unknown>): NodeExecutionResult;
+export declare function executeNotificationAction(svc: INotificationActionService, entity: any, payload: Record<string, unknown>, notifCtx?: any): Promise<NodeExecutionResult>;
+export interface SplitExecutionResult extends NodeExecutionResult {
+    splitOutputs: Array<{
+        name: string;
+        field: string;
+        payload: unknown;
+    }>;
+    remainder: Record<string, unknown> | null;
+}
+export declare function executeSplit(entity: any, payload: Record<string, unknown>): SplitExecutionResult;
+export interface CodeExecutionResult extends NodeExecutionResult {
+    logs: string[];
+}
+/**
+ * Ejecutar el nodo de código.
+ *
+ * ## Por qué esto ya no corre aquí dentro
+ *
+ * Antes iba a `renderTemplate(..., { mode: 'code' })`, o sea a `node:vm` con
+ * una lista negra sobre el texto fuente. `vm` no es una frontera y una lista
+ * de expresiones regulares sobre el fuente no es un control: la concatenación
+ * de cadenas la cruza sin despeinarse, y el contexto se sembraba con los
+ * intrínsecos del propio realm, así que `Math.constructor.constructor` era el
+ * `Function` de la casa.
+ *
+ * Con eso, un `return Math["constr"+"uctor"]…("return this")()["proc"+"ess"].env`
+ * devolvía `process.env` — es decir `MONGO_URI` y `API_SECRET`, que es la
+ * entrada del PBKDF2 con el que se descifran las credenciales guardadas de
+ * TODOS los inquilinos. Y cambiando la pieza final, ejecución de comandos.
+ *
+ * Ahora corre en el mismo hijo desechable que los scripts pre-request: entorno
+ * vacío, sin ficheros ni spawn donde el runtime lo soporte, muerto tras cada
+ * ejecución. Salirse del vm sigue siendo fácil; lo que cambia es que ya no
+ * lleva a ningún sitio.
+ *
+ * El contrato hacia fuera no cambia — mismos códigos, mismo `outputPayload`,
+ * mismos logs— salvo que ahora es asíncrono, que es lo que cuesta un proceso.
+ */
+export declare function executeCode(entity: any, payload: Record<string, unknown>, workspacePayloads?: Record<string, Record<string, unknown>>): Promise<CodeExecutionResult>;
+/**
+ * Execute any node type.  Used by pipeline-run.service.ts.
+ * event-pipeline.service.ts calls the individual functions directly
+ * because it needs more control over pre/post processing.
+ *
+ * Handles _meta iteration: if the incoming payload has
+ * _meta.iterable + _meta.iterateField, each item is executed
+ * individually and results are aggregated — matching the behaviour
+ * of executeWithIteration used by individual test webhooks.
+ *
+ * filter and aggregator handle _meta internally and receive the
+ * full payload (with _meta) — they are excluded from iteration.
+ */
+export interface ExecutorContext {
+    workspacePayloads?: Record<string, Record<string, unknown>>;
+    /** Event headers — used by transform's applyTransform for {{headers.x}} interpolation */
+    headers?: Record<string, string>;
+    /** Event-level metadata (eventId, webhookId, receivedAt) — used by transform */
+    eventMeta?: Record<string, string>;
+    /** Notification context — used by notification action */
+    notifCtx?: any;
+}
+/**
+ * Loop fan-out: turn the iterable field into one payload per item, each
+ * stamped with its position. The loop node owns its own iteration and
+ * LoopState, which is why it has no registered handler — the caller drives
+ * the iterations from this list.
+ */
+export declare function executeLoopFanOut(entity: any, payload: Record<string, unknown>): NodeExecutionResult;
+/**
+ * The seven node types that do NOT call `registerNodeHandler`, and what
+ * Run Pipeline does for each. Everything else executes through its
+ * registered handler — the same object prod runs — so the two cycles
+ * cannot drift.
+ *
+ * This list is deliberately explicit rather than a `default:` arm. A
+ * `default` silently absorbs any node type nobody wired up, which is
+ * exactly how the Limit node came to return 15 of 15 items in Run
+ * Pipeline while prod limited correctly. A missing entry here is a
+ * loud `undefined`, and `architecture.spec.ts` asserts the set matches
+ * the types that actually lack a handler.
+ */
+export declare const HANDLERLESS_NODE_TYPES: {
+    /** Annotation — never executes. */
+    readonly stickyNote: {
+        readonly run: "passthrough";
+        readonly telemetrySource: "sticky_note";
+    };
+    readonly webhook: {
+        readonly run: "passthrough";
+        readonly telemetrySource: "entry_webhook";
+    };
+    readonly scheduledWorkflow: {
+        readonly run: "passthrough";
+        readonly telemetrySource: "scheduled_webhook";
+    };
+    readonly voiceAgent: {
+        readonly run: "passthrough";
+        readonly telemetrySource: "voice_agent";
+    };
+    /** Queue-based: prod enqueues, Run Pipeline has nothing to wait on. */
+    readonly delay: {
+        readonly run: "passthrough";
+        readonly telemetrySource: "delay_node";
+    };
+    /** Waits on a human. Run Pipeline cannot block on a click. */
+    readonly approval: {
+        readonly run: "passthrough";
+        readonly telemetrySource: "approval_node";
+    };
+    /** pipeline-run.service collects the inputs itself and merges them. */
+    readonly merge: {
+        readonly run: "passthrough";
+        readonly telemetrySource: "merge_node";
+    };
+    /** Owns its own iteration + LoopState; pipeline-run drives it directly. */
+    readonly loop: {
+        readonly run: "custom";
+        readonly telemetrySource: "loop_node";
+    };
+    /** Counter lives in Redis; prod dispatches it from event-pipeline. */
+    readonly rateLimiter: {
+        readonly run: "custom";
+        readonly telemetrySource: "rate_limiter_node";
+    };
+};
+export type HandlerlessNodeType = keyof typeof HANDLERLESS_NODE_TYPES;
+export declare function isHandlerless(nodeType: string): nodeType is HandlerlessNodeType;