@hostwebhook/node-sdk 0.1.0

package/dist/normalize-nodes.d.ts

@@ -0,0 +1,18 @@
+import { Types } from 'mongoose';
+/**
+ * Normalizes an array of input/output node DTOs into Mongoose-ready documents.
+ * Extracts the common pattern used in every node service's create() and update().
+ */
+export declare function normalizeNodes(nodes?: Array<{
+    nodeType: string;
+    nodeId: string;
+    port?: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+}>): Array<{
+    nodeType: string;
+    nodeId: Types.ObjectId;
+    port: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+}>;

package/dist/normalize-nodes.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeNodes = normalizeNodes;
+const mongoose_1 = require("mongoose");
+const output_node_dto_1 = require("./dto/output-node.dto");
+const output_node_ref_schema_1 = require("./output-node-ref.schema");
+/**
+ * Normalizes an array of input/output node DTOs into Mongoose-ready documents.
+ * Extracts the common pattern used in every node service's create() and update().
+ */
+function normalizeNodes(nodes) {
+    return (nodes ?? []).map((n) => ({
+        nodeType: (0, output_node_dto_1.normalizeNodeType)(n.nodeType),
+        nodeId: new mongoose_1.Types.ObjectId(n.nodeId),
+        // Rebuilt field by field, so anything not listed here is silently
+        // dropped on save — which is exactly how the port went missing the
+        // first time. Absent means the main port.
+        port: n.port || output_node_ref_schema_1.MAIN_PORT,
+        ...(n.sourceHandle && { sourceHandle: n.sourceHandle }),
+        ...(n.targetHandle && { targetHandle: n.targetHandle }),
+    }));
+}

package/dist/output-node-ref.schema.d.ts

@@ -0,0 +1,82 @@
+import { Schema as MongooseSchema, Types } from 'mongoose';
+/**
+ * The one shape of "this node connects to that node".
+ *
+ * Phase 1 of the standardization plan. Before this, the same literal was
+ * pasted 58 times across 30 entities, and a node that needed a second
+ * outbound port invented a second field name for it — elseOutputNodes,
+ * loopOutputNodes, doneOutputNodes, rejectionOutputNodes, plus containers
+ * that nested their own `outputNodes` (branches[], outputs[],
+ * categories[]) and a router that stored a bare string. Nine names for one
+ * idea, and every consumer had to remember all of them; cascade-cleanup
+ * forgot one and accumulated orphan references for months.
+ *
+ * Now there is one array per node and the port lives on the edge:
+ *
+ *   port: "main"            the default, and what an unported edge means
+ *   port: "else"            conditional fallback
+ *   port: "loop" | "done"   loop
+ *   port: "rejected"        approval
+ *   port: "branch:<id>"     conditional, one per branches[].id
+ *   port: "output:<id>"     split, one per outputs[].id
+ *   port: "category:<id>"   ai classifier, one per categories[].id
+ *   port: "rule:<id>"       router, one per rules[].id
+ *
+ * The containers keep the condition and the label — that part really is
+ * per-node — but they no longer keep the destination.
+ *
+ * `sourceHandle` / `targetHandle` stay and are NOT the port: their values
+ * are canvas geometry ("ro-<id>-right-out" means "leaves from the right
+ * edge"), not semantics. They exist to draw the line.
+ *
+ * `port` is required with a default so an older client that omits it
+ * still saves, and lands on the main port — which is what it meant.
+ */
+export declare const OUTPUT_NODE_REF_SCHEMA: {
+    readonly nodeType: {
+        readonly type: StringConstructor;
+        readonly required: true;
+    };
+    readonly nodeId: {
+        readonly type: typeof MongooseSchema.Types.ObjectId;
+        readonly required: true;
+    };
+    readonly port: {
+        readonly type: StringConstructor;
+        readonly required: true;
+        readonly default: "main";
+    };
+    readonly sourceHandle: StringConstructor;
+    readonly targetHandle: StringConstructor;
+    readonly _id: false;
+};
+/** TS counterpart of the schema above. */
+export interface OutputNodeRef {
+    nodeType: string;
+    nodeId: Types.ObjectId;
+    port: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+}
+export declare const MAIN_PORT = "main";
+/** Ports whose name is fixed, as opposed to the `<kind>:<id>` ones. */
+export declare const FIXED_PORTS: readonly ["main", "else", "loop", "done", "rejected"];
+/** Build the port name for a container-owned edge. */
+export declare const branchPort: (id: string) => string;
+export declare const outputPort: (id: string) => string;
+export declare const categoryPort: (id: string) => string;
+export declare const rulePort: (id: string) => string;
+/** Read the container id back out of a port name, or null if the port is
+ *  a fixed one. */
+export declare function portContainerId(port: string, kind: 'branch' | 'output' | 'category' | 'rule'): string | null;
+/**
+ * The edges leaving `port`, in the shape the dispatcher wants.
+ *
+ * A ref written before Phase 1 has no `port` and means `main` — the same
+ * rule the schema default encodes, applied on read so a document that has
+ * not been touched since still routes correctly.
+ */
+export declare function refsForPort(entity: Record<string, any> | null | undefined, port: string): Array<{
+    nodeType: string;
+    nodeId: string;
+}>;

package/dist/output-node-ref.schema.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rulePort = exports.categoryPort = exports.outputPort = exports.branchPort = exports.FIXED_PORTS = exports.MAIN_PORT = exports.OUTPUT_NODE_REF_SCHEMA = void 0;
+exports.portContainerId = portContainerId;
+exports.refsForPort = refsForPort;
+const mongoose_1 = require("mongoose");
+/**
+ * The one shape of "this node connects to that node".
+ *
+ * Phase 1 of the standardization plan. Before this, the same literal was
+ * pasted 58 times across 30 entities, and a node that needed a second
+ * outbound port invented a second field name for it — elseOutputNodes,
+ * loopOutputNodes, doneOutputNodes, rejectionOutputNodes, plus containers
+ * that nested their own `outputNodes` (branches[], outputs[],
+ * categories[]) and a router that stored a bare string. Nine names for one
+ * idea, and every consumer had to remember all of them; cascade-cleanup
+ * forgot one and accumulated orphan references for months.
+ *
+ * Now there is one array per node and the port lives on the edge:
+ *
+ *   port: "main"            the default, and what an unported edge means
+ *   port: "else"            conditional fallback
+ *   port: "loop" | "done"   loop
+ *   port: "rejected"        approval
+ *   port: "branch:<id>"     conditional, one per branches[].id
+ *   port: "output:<id>"     split, one per outputs[].id
+ *   port: "category:<id>"   ai classifier, one per categories[].id
+ *   port: "rule:<id>"       router, one per rules[].id
+ *
+ * The containers keep the condition and the label — that part really is
+ * per-node — but they no longer keep the destination.
+ *
+ * `sourceHandle` / `targetHandle` stay and are NOT the port: their values
+ * are canvas geometry ("ro-<id>-right-out" means "leaves from the right
+ * edge"), not semantics. They exist to draw the line.
+ *
+ * `port` is required with a default so an older client that omits it
+ * still saves, and lands on the main port — which is what it meant.
+ */
+exports.OUTPUT_NODE_REF_SCHEMA = {
+    nodeType: { type: String, required: true },
+    nodeId: { type: mongoose_1.Schema.Types.ObjectId, required: true },
+    port: { type: String, required: true, default: 'main' },
+    sourceHandle: String,
+    targetHandle: String,
+    _id: false,
+};
+exports.MAIN_PORT = 'main';
+/** Ports whose name is fixed, as opposed to the `<kind>:<id>` ones. */
+exports.FIXED_PORTS = [
+    'main',
+    'else',
+    'loop',
+    'done',
+    'rejected',
+];
+/** Build the port name for a container-owned edge. */
+const branchPort = (id) => `branch:${id}`;
+exports.branchPort = branchPort;
+const outputPort = (id) => `output:${id}`;
+exports.outputPort = outputPort;
+const categoryPort = (id) => `category:${id}`;
+exports.categoryPort = categoryPort;
+const rulePort = (id) => `rule:${id}`;
+exports.rulePort = rulePort;
+/** Read the container id back out of a port name, or null if the port is
+ *  a fixed one. */
+function portContainerId(port, kind) {
+    const prefix = `${kind}:`;
+    return port.startsWith(prefix) ? port.slice(prefix.length) : null;
+}
+/**
+ * The edges leaving `port`, in the shape the dispatcher wants.
+ *
+ * A ref written before Phase 1 has no `port` and means `main` — the same
+ * rule the schema default encodes, applied on read so a document that has
+ * not been touched since still routes correctly.
+ */
+/* Deliberately loose in what it accepts: callers pass a hydrated Mongoose
+ * document, a raw driver `WithId<Document>`, or a plain object from a test,
+ * and all three carry the same field. */
+function refsForPort(entity, port) {
+    const refs = (entity?.outputNodes ?? []);
+    return refs
+        .filter((n) => (n.port ?? exports.MAIN_PORT) === port)
+        .map((n) => ({
+        nodeType: n.nodeType,
+        nodeId: n.nodeId?.toString?.() ?? String(n.nodeId),
+    }));
+}

package/dist/output-webhook-scope.d.ts

@@ -0,0 +1,36 @@
+/** The two fields ownership is read from, in that order (`_id` only labels the log line). */
+interface OwnedDoc {
+    organizationId?: unknown;
+    userId?: unknown;
+    _id?: unknown;
+}
+/**
+ * Does this webhook belong to the organization whose pipeline is running?
+ *
+ * Every other node type reaches the pipeline through its service's
+ * `findOne(id, orgId)`, which filters by `organizationId` and so cannot return
+ * another tenant's node. Webhook-typed outputs were the one exception: they are
+ * resolved with a bare `webhookModel.findById(nodeId)` and were gated only on
+ * `isActive`. That `nodeId` comes from the tenant-written `outputNodes` array,
+ * whose only write-time constraint is `@IsMongoId()`, so naming a webhook in
+ * another organization made the pipeline create a child event on it — POSTed to
+ * the victim's `targetUrl`, signed with the victim's signing secret, written to
+ * their event history and pushed to their dashboard.
+ *
+ * Ownership is read as `(doc.organizationId ?? doc.userId)`, the same formula
+ * `WebhooksService.findOne` and `ingress.service.ts` use: `WebhooksService.create`
+ * stores the userId as organizationId when there is no org, so plain equality on
+ * that formula also matches rows written before that field existed.
+ *
+ * Callers skip rather than throw — a foreign target is dropped exactly like a
+ * deleted or paused one, so one bad edge cannot abort the sibling outputs of a
+ * pipeline that is otherwise the tenant's own.
+ *
+ * `orgId` is never attacker-supplied: every production caller derives it
+ * server-side from the source document. When it is missing we cannot establish
+ * ownership, so the answer is false — the only context that leaves it empty
+ * (`test-node.ts`) deliberately wires no `eventModel`/`webhookModel`/
+ * `onEventCreated` and so never reaches a dispatch site.
+ */
+export declare function belongsToOrg(doc: OwnedDoc, orgId: unknown): boolean;
+export {};

package/dist/output-webhook-scope.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.belongsToOrg = belongsToOrg;
+const common_1 = require("@nestjs/common");
+const logger = new common_1.Logger('OutputWebhookScope');
+/**
+ * Does this webhook belong to the organization whose pipeline is running?
+ *
+ * Every other node type reaches the pipeline through its service's
+ * `findOne(id, orgId)`, which filters by `organizationId` and so cannot return
+ * another tenant's node. Webhook-typed outputs were the one exception: they are
+ * resolved with a bare `webhookModel.findById(nodeId)` and were gated only on
+ * `isActive`. That `nodeId` comes from the tenant-written `outputNodes` array,
+ * whose only write-time constraint is `@IsMongoId()`, so naming a webhook in
+ * another organization made the pipeline create a child event on it — POSTed to
+ * the victim's `targetUrl`, signed with the victim's signing secret, written to
+ * their event history and pushed to their dashboard.
+ *
+ * Ownership is read as `(doc.organizationId ?? doc.userId)`, the same formula
+ * `WebhooksService.findOne` and `ingress.service.ts` use: `WebhooksService.create`
+ * stores the userId as organizationId when there is no org, so plain equality on
+ * that formula also matches rows written before that field existed.
+ *
+ * Callers skip rather than throw — a foreign target is dropped exactly like a
+ * deleted or paused one, so one bad edge cannot abort the sibling outputs of a
+ * pipeline that is otherwise the tenant's own.
+ *
+ * `orgId` is never attacker-supplied: every production caller derives it
+ * server-side from the source document. When it is missing we cannot establish
+ * ownership, so the answer is false — the only context that leaves it empty
+ * (`test-node.ts`) deliberately wires no `eventModel`/`webhookModel`/
+ * `onEventCreated` and so never reaches a dispatch site.
+ */
+function belongsToOrg(doc, orgId) {
+    const caller = orgId?.toString();
+    const owner = (doc.organizationId ?? doc.userId)?.toString();
+    if (caller && owner && owner === caller)
+        return true;
+    logger.warn(`[Tenancy] Output webhook ${doc._id?.toString() ?? '(unknown)'} belongs to ` +
+        `${owner ?? '(unknown)'}, not to ${caller ?? '(unknown)'} — skipped`);
+    return false;
+}

package/dist/payload-preview.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Truncate any value to fit within maxBytes when serialized.
+ * Used for telemetry metadata, notification payloadPreview, email preview, etc.
+ */
+export declare function truncatePreview(value: unknown, maxBytes?: number): unknown;
+/**
+ * Pretty-print payload as formatted JSON string, truncated to maxChars.
+ * Useful for {{payloadPreview}} in email/notification templates.
+ */
+export declare function payloadPreview(payload: unknown, maxChars?: number): string;

package/dist/payload-preview.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.truncatePreview = truncatePreview;
+exports.payloadPreview = payloadPreview;
+/**
+ * Truncate any value to fit within maxBytes when serialized.
+ * Used for telemetry metadata, notification payloadPreview, email preview, etc.
+ */
+function truncatePreview(value, maxBytes = 2048) {
+    if (value == null)
+        return undefined;
+    try {
+        const str = typeof value === 'string' ? value : JSON.stringify(value);
+        if (str.length <= maxBytes) {
+            return typeof value === 'string' ? value : JSON.parse(str);
+        }
+        return str.slice(0, maxBytes) + '...[truncated]';
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * Pretty-print payload as formatted JSON string, truncated to maxChars.
+ * Useful for {{payloadPreview}} in email/notification templates.
+ */
+function payloadPreview(payload, maxChars = 2500) {
+    if (payload == null)
+        return '(no payload)';
+    try {
+        const str = JSON.stringify(payload, null, 2);
+        return str.length > maxChars
+            ? str.slice(0, maxChars) + '\n...[truncated]'
+            : str;
+    }
+    catch {
+        return '[unserializable]';
+    }
+}

package/dist/pipeline.constants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pipeline-level constants — magic numbers extracted for maintainability.
+ * Plan-level constants (SYNC_TIMEOUT_SECONDS, RESPONSE_MAX_BYTES) live in plans/plan.constants.ts.
+ */
+/** Maximum recursion depth for dispatchOutputNodes — prevents infinite loops */
+export declare const MAX_PROPAGATION_DEPTH = 200;
+/** Default max node cycles per event when no org/workspace/plan override */
+export declare const DEFAULT_MAX_NODE_CYCLES = 50;
+/**
+ * Techo de elementos de un bucle cuando el plan no dice nada.
+ *
+ * Igual que `DEFAULT_MAX_NODE_CYCLES`: existe para que un límite ausente no
+ * signifique «sin límite». `maxLoopIterations` estuvo declarado en los planes
+ * y sin aplicar, y los tiers de pago valían `-1`; el resultado era que dentro
+ * de un bucle no había ningún techo y el tamaño de la lista lo elegía quien
+ * mandaba el evento.
+ *
+ * Se pone en el valor del plan más bajo a propósito: si un día se añade un
+ * tier y se olvida el campo, el respaldo aprieta en vez de abrir.
+ */
+export declare const MAX_LOOP_ITERATIONS_POR_DEFECTO = 50;
+/** Delay (ms) before re-dispatching recovered loops on startup — lets the app fully boot */
+export declare const RECOVERY_BOOT_DELAY_MS = 5000;
+/** Window (ms) for detecting stuck loops on startup — only loops older than this are recovered */
+export declare const RECOVERY_WINDOW_MS: number;
+/** Default per-node execution timeout (seconds) — used when NODE_TIMEOUT_DEFAULTS has no entry */
+export declare const DEFAULT_NODE_TIMEOUT_SEC = 60;
+/** Per-node-type execution timeouts (seconds). Nodes can override via entity.timeoutSeconds. */
+export declare const NODE_TIMEOUT_DEFAULTS: Record<string, number>;

package/dist/pipeline.constants.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Pipeline-level constants — magic numbers extracted for maintainability.
+ * Plan-level constants (SYNC_TIMEOUT_SECONDS, RESPONSE_MAX_BYTES) live in plans/plan.constants.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODE_TIMEOUT_DEFAULTS = exports.DEFAULT_NODE_TIMEOUT_SEC = exports.RECOVERY_WINDOW_MS = exports.RECOVERY_BOOT_DELAY_MS = exports.MAX_LOOP_ITERATIONS_POR_DEFECTO = exports.DEFAULT_MAX_NODE_CYCLES = exports.MAX_PROPAGATION_DEPTH = void 0;
+/** Maximum recursion depth for dispatchOutputNodes — prevents infinite loops */
+exports.MAX_PROPAGATION_DEPTH = 200;
+/** Default max node cycles per event when no org/workspace/plan override */
+exports.DEFAULT_MAX_NODE_CYCLES = 50;
+/**
+ * Techo de elementos de un bucle cuando el plan no dice nada.
+ *
+ * Igual que `DEFAULT_MAX_NODE_CYCLES`: existe para que un límite ausente no
+ * signifique «sin límite». `maxLoopIterations` estuvo declarado en los planes
+ * y sin aplicar, y los tiers de pago valían `-1`; el resultado era que dentro
+ * de un bucle no había ningún techo y el tamaño de la lista lo elegía quien
+ * mandaba el evento.
+ *
+ * Se pone en el valor del plan más bajo a propósito: si un día se añade un
+ * tier y se olvida el campo, el respaldo aprieta en vez de abrir.
+ */
+exports.MAX_LOOP_ITERATIONS_POR_DEFECTO = 50;
+/** Delay (ms) before re-dispatching recovered loops on startup — lets the app fully boot */
+exports.RECOVERY_BOOT_DELAY_MS = 5_000;
+/** Window (ms) for detecting stuck loops on startup — only loops older than this are recovered */
+exports.RECOVERY_WINDOW_MS = 5 * 60 * 1000;
+/** Default per-node execution timeout (seconds) — used when NODE_TIMEOUT_DEFAULTS has no entry */
+exports.DEFAULT_NODE_TIMEOUT_SEC = 60;
+/** Per-node-type execution timeouts (seconds). Nodes can override via entity.timeoutSeconds. */
+exports.NODE_TIMEOUT_DEFAULTS = {
+    httpAction: 30,
+    firecrawlAction: 120,
+    sheetsAction: 60,
+    calendarAction: 60,
+    docsAction: 60,
+    mongoAction: 30,
+    emailAction: 15,
+    notificationAction: 15,
+    ai: 300,
+    transform: 30,
+    filter: 10,
+    code: 30,
+    markdown: 30,
+    cache: 10,
+    schemaValidator: 10,
+    split: 120,
+    conditional: 10,
+    aggregator: 30,
+};

package/dist/pre-request-pool.d.ts

@@ -0,0 +1,58 @@
+export interface RunnerContext {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: string | undefined;
+    payload: unknown;
+}
+export interface RunnerResult {
+    url: unknown;
+    headers: unknown;
+    body: unknown;
+}
+/** Which isolation tier the probe settled on, for logging and tests. */
+export declare function permissionTier(): string;
+/** Top the spare pool back up, in the background. Failures are not fatal: the next run starts one itself. */
+export declare function refillPool(): void;
+/**
+ * Run one script in one throwaway child.
+ *
+ * `ctx.payload` must already be a plain, cloneable value — the caller does the
+ * same JSON round-trip the in-process sandbox always did, which both preserves
+ * that behaviour and guarantees the context can cross.
+ */
+export declare function runInChild(code: string, ctx: RunnerContext, timeoutMs: number): Promise<RunnerResult>;
+export interface CodeRunnerContext {
+    payload: unknown;
+    headers?: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+    workspacePayloads?: Record<string, Record<string, unknown>>;
+}
+export interface CodeRunnerResult {
+    /** Lo que devolvió el código del inquilino. `null` cuando no devolvió nada. */
+    output: unknown;
+    logs: string[];
+}
+/**
+ * Ejecutar el código de un nodo de código en un hijo.
+ *
+ * Mismo pool y mismas garantías que el script pre-request: hijo desechable con
+ * entorno vacío, sin ficheros ni spawn donde el runtime lo soporte, y muerto
+ * después. Lo que cambia respecto a correrlo en proceso es dónde aterriza
+ * quien se salga del vm — y salirse del vm es fácil, nunca fue una frontera.
+ * Dentro del proceso de la API eso daba `process.env`, o sea `MONGO_URI` y el
+ * `API_SECRET` con el que se descifran las credenciales de todos los
+ * inquilinos. Aquí no da nada.
+ *
+ * Un fallo del propio código —una excepción, un timeout— vuelve como `Error`,
+ * con los logs que alcanzó a emitir enganchados en `logs`, porque el usuario
+ * los necesita justamente cuando algo revienta.
+ */
+export declare function runCodeNodeInChild(code: string, ctx: CodeRunnerContext, timeoutMs: number): Promise<CodeRunnerResult>;
+/**
+ * Stop every child, including the ones still starting, and refuse to start
+ * more. Registered on exit, and used by tests so jest sees no stray handles —
+ * a spare that finished starting after the last test would otherwise keep its
+ * IPC channel open.
+ */
+export declare function shutdownPreRequestPool(): void;