@hostwebhook/node-sdk 0.1.0

package/dist/workspace-payloads.js

@@ -0,0 +1,496 @@
+"use strict";
+/**
+ * Load lastPayload for referenced nodes in a workspace.
+ *
+ * Used by $("node name") in templates — provides synchronous
+ * lookup of any node's output within the same workspace.
+ *
+ * Optimized with Redis caching:
+ * - Extract $() refs from entity → only load referenced nodes
+ * - Redis MGET first (~1ms) → MongoDB fallback only for cache misses
+ * - cacheNodePayload warms the cache → subsequent lookups are instant
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPayloadRedis = getPayloadRedis;
+exports.initPayloadRedis = initPayloadRedis;
+exports.extractCrossNodeRefs = extractCrossNodeRefs;
+exports.cacheNodePayload = cacheNodePayload;
+exports.deleteNodePayload = deleteNodePayload;
+exports.invalidateCanvasCache = invalidateCanvasCache;
+exports.propagateNodeRename = propagateNodeRename;
+exports.loadWorkspacePayloads = loadWorkspacePayloads;
+const mongodb_1 = require("mongodb");
+const common_1 = require("@nestjs/common");
+const swallow_1 = require("./swallow");
+const try_parse_1 = require("./try-parse");
+const workspacePayloadsLogger = new common_1.Logger('workspace-payloads');
+// ── Singleton Redis client (lazy, shared across all calls) ──
+let redisClient = null;
+let redisInitAttempted = false;
+/** Get the shared Redis client (or null if not initialized) */
+function getPayloadRedis() {
+    return redisClient;
+}
+/** Get or create the shared Redis client for payload caching */
+function initPayloadRedis(redisUrl) {
+    if (redisClient || redisInitAttempted)
+        return;
+    redisInitAttempted = true;
+    const url = redisUrl ?? process.env.REDIS_URL;
+    if (!url)
+        return;
+    try {
+        // Dynamic require — ioredis is a transitive dep of @nestjs/bullmq, not always directly installed
+        const IoRedis = require('ioredis');
+        redisClient = new IoRedis(url, {
+            maxRetriesPerRequest: 1,
+            lazyConnect: true,
+        });
+        redisClient.connect().catch(() => {
+            redisClient = null;
+        });
+    }
+    catch {
+        redisClient = null;
+    }
+}
+// ── Helpers ──
+/** Extract node names referenced by $("name") or $('name') in the entity */
+function extractCrossNodeRefs(entity) {
+    const refs = new Set();
+    // Match $("name"), $('name'), $(\"name\"), and $(\'name\') — handles JSON-escaped strings
+    const re = /\$\(\\?["']([^"'\\]+)\\?["']\)/g;
+    const visited = new WeakSet();
+    function scan(val) {
+        if (typeof val === 'string') {
+            let m;
+            while ((m = re.exec(val)) !== null)
+                refs.add(m[1]);
+            re.lastIndex = 0;
+        }
+        else if (val && typeof val === 'object') {
+            if (visited.has(val))
+                return;
+            visited.add(val);
+            // Mongoose document → use toObject() to get plain data without circular refs
+            const plain = typeof val.toObject === 'function'
+                ? val.toObject()
+                : val;
+            if (Array.isArray(plain)) {
+                for (const item of plain)
+                    scan(item);
+            }
+            else {
+                for (const v of Object.values(plain))
+                    scan(v);
+            }
+        }
+    }
+    scan(entity);
+    return refs;
+}
+function payloadKey(wsId, name) {
+    return `ws:${wsId}:payload:${name}`;
+}
+/** Write a node's payload to Redis cache (fire-and-forget, 5 min TTL) */
+function cacheNodePayload(wsId, name, payload) {
+    if (!redisClient)
+        return;
+    redisClient
+        .set(payloadKey(wsId, name), JSON.stringify(payload), 'EX', 300)
+        .catch((0, swallow_1.onFailure)(workspacePayloadsLogger, `workspace payload cache write ${wsId}/${name}`));
+}
+/**
+ * Drop a deleted node's payload row and its Redis mirror.
+ *
+ * `saveLastPayload` creates the row and nothing ever removed it. Since the
+ * payload moved out of the entity and into `nodepayloads`, deleting a node
+ * left its output behind permanently: measured on production 2026-08-05,
+ * 25 of 192 rows (13%) belonged to nodes that no longer existed, spread
+ * across 13 node types, the oldest from 2026-07-31.
+ *
+ * The stale Redis key is the sharper edge. `$("node name")` resolves by
+ * NAME, not by id, so a new node reusing a deleted one's name would read the
+ * dead payload until the 5-minute TTL expired.
+ *
+ * Best-effort: the entity delete has already happened and a leftover row is
+ * inert, so failures are logged rather than thrown back at the caller.
+ */
+async function deleteNodePayload(connection, nodeId) {
+    const db = connection.db;
+    if (!db)
+        return;
+    const oid = new mongodb_1.ObjectId(nodeId);
+    const rows = db.collection('nodepayloads');
+    // Read before deleting. The row is the only place carrying the workspace
+    // and name needed to evict the Redis key — once it is gone there is
+    // nothing left to derive them from, which is how the row and its cache
+    // entry would drift apart.
+    const row = await rows
+        .findOne({ nodeId: oid }, { projection: { name: 1, workspaceId: 1 } })
+        .catch((0, swallow_1.onFailureReturn)(workspacePayloadsLogger, `nodepayloads lookup before delete for node ${nodeId}`, null));
+    await rows
+        .deleteOne({ nodeId: oid })
+        .catch((0, swallow_1.onFailure)(workspacePayloadsLogger, `nodepayloads delete for node ${nodeId}`));
+    if (redisClient && row?.workspaceId && row?.name) {
+        redisClient
+            .del(payloadKey(String(row.workspaceId), String(row.name)))
+            .catch((0, swallow_1.onFailure)(workspacePayloadsLogger, `payload cache purge for deleted node ${nodeId} (${String(row.name)})`));
+    }
+}
+/** Invalidate canvas-data Redis cache for an org+workspace (fire-and-forget) */
+function invalidateCanvasCache(orgId, workspaceId) {
+    /* El cliente se creaba sólo al ejecutar un nodo, correr un pipeline o probar
+       uno — nunca al arrancar. Así que en un proceso recién desplegado, o que
+       todavía no haya despachado nada, `redisClient` era null y esta función se
+       iba por el `return` de abajo sin borrar nada... mientras CanvasService, que
+       sí crea el suyo en el constructor, seguía sirviendo el lienzo cacheado 30 s.
+       El efecto para quien usa: creas un nodo, recargas, y el lienzo aparece sin
+       él; borras uno, recargas, y vuelve. Inicializar aquí ata la invalidación al
+       mismo arranque perezoso que el caché en vez de a que alguien haya disparado
+       un nodo antes. */
+    initPayloadRedis();
+    if (!redisClient)
+        return;
+    const keys = [`canvas:${orgId}:all`];
+    if (workspaceId)
+        keys.push(`canvas:${orgId}:${workspaceId}`);
+    redisClient
+        .del(...keys)
+        .catch((0, swallow_1.onFailure)(workspacePayloadsLogger, `workspace payload cache purge (${keys.length} key(s))`));
+}
+/**
+ * Propagate a node rename to the `nodepayloads` collection and the
+ * Redis hot cache. Without this, cross-node `$("name")` lookups break
+ * silently after a rename: the template engine resolves $() by NAME
+ * (the data-picker emits names, not ObjectIds), but the persisted
+ * nodepayloads row keeps the old auto-generated name until the next
+ * dispatch overwrites it. The user-visible bug is "node fired, payload
+ * shows in the detail page, but downstream `$()` references render
+ * empty" — which produces hours of debugging chasing ghost workspace
+ * mismatches.
+ *
+ * Also wipes the old Redis cache key so a stale read doesn't shadow
+ * the new name, and re-warms under the new name when the row has a
+ * payload (so the very next $() lookup hits Redis, not Mongo).
+ *
+ * Fire-and-forget on individual failures — caller already returned
+ * the updated entity. Best-effort: the nodepayloads row is overwritten
+ * on the next dispatch anyway, so a one-off failure is recoverable.
+ */
+async function propagateNodeRename(connection, nodeId, previousName, newName, workspaceId) {
+    if (!previousName || previousName === newName)
+        return;
+    const ObjectIdCtor = (await Promise.resolve().then(() => __importStar(require('mongoose')))).Types.ObjectId;
+    try {
+        await connection.db
+            ?.collection('nodepayloads')
+            .updateOne({ nodeId: new ObjectIdCtor(nodeId) }, { $set: { name: newName } });
+    }
+    catch (err) {
+        workspacePayloadsLogger.warn(`propagateNodeRename — nodepayloads update failed for ${nodeId}: ${err.message}`);
+        return;
+    }
+    if (!workspaceId || !redisClient)
+        return;
+    try {
+        redisClient
+            .del(payloadKey(workspaceId, previousName))
+            .catch((0, swallow_1.onFailure)(workspacePayloadsLogger, `workspace payload cache rename purge ${workspaceId}/${previousName}`));
+        const fresh = await connection.db
+            ?.collection('nodepayloads')
+            .findOne({ nodeId: new ObjectIdCtor(nodeId) }, { projection: { payload: 1 } });
+        if (fresh?.payload) {
+            cacheNodePayload(workspaceId, newName, fresh.payload);
+        }
+    }
+    catch (err) {
+        // Redis is best-effort here, but this is the rename path: failing leaves
+        // the payload cached under the OLD node name, so `$("New Name")` resolves
+        // to nothing while `$("Old Name")` still works. Confusing enough to be
+        // worth a line.
+        workspacePayloadsLogger.warn(`workspace payload cache re-key ${workspaceId}: ${previousName} → ${newName} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// ── Main loader ──
+/**
+ * Load workspace payloads for the given node names.
+ * Redis first (MGET, ~1ms), MongoDB fallback only for cache misses.
+ * If nodeNames is empty or undefined, returns {} instantly.
+ */
+async function loadWorkspacePayloads(db, workspaceId, orgId, nodeNames) {
+    if (!nodeNames || nodeNames.size === 0)
+        return {};
+    const names = Array.from(nodeNames);
+    const result = {};
+    // 1. Try Redis MGET (single round-trip, ~1ms)
+    if (redisClient) {
+        const keys = names.map((n) => payloadKey(workspaceId, n));
+        // A per-entry parse failure is an ordinary miss — the entry is stale or
+        // truncated and Mongo answers instead. The MGET itself failing is not: it
+        // means every lookup in this workspace is going to Mongo from now on, which
+        // is a performance cliff nobody would connect to Redis without a line here.
+        const values = await redisClient
+            .mget(...keys)
+            .catch((0, swallow_1.onFailureReturn)(workspacePayloadsLogger, `workspace payload cache read ${workspaceId} (${names.length} nodes)`, null));
+        if (values) {
+            const misses = [];
+            for (let i = 0; i < names.length; i++) {
+                const parsed = (0, try_parse_1.tryParseJsonObject)(values[i]);
+                if (parsed)
+                    result[names[i]] = parsed;
+                else
+                    misses.push(names[i]);
+            }
+            if (misses.length === 0)
+                return result;
+            names.length = 0;
+            names.push(...misses);
+        }
+    }
+    // 2. MongoDB fallback — single query to node_payloads collection (not 30 collection scan)
+    const docs = await db
+        .collection('nodepayloads')
+        .find({
+        workspaceId: new mongodb_1.ObjectId(workspaceId),
+        organizationId: new mongodb_1.ObjectId(orgId),
+        name: { $in: names },
+    }, { projection: { name: 1, payload: 1 } })
+        .toArray();
+    for (const doc of docs) {
+        if (doc.name && doc.payload) {
+            result[doc.name] = doc.payload;
+            cacheNodePayload(workspaceId, doc.name, doc.payload);
+        }
+    }
+    // Rename-recovery fallback — when nodepayloads has the OLD name but
+    // the entity has been renamed in the dashboard. The on-disk row
+    // gets its `name` field updated only at next dispatch (or now
+    // synchronously via propagateNodeRename on entity update), but
+    // existing rows from before that fix are still stuck on the old
+    // name. We scan the entity collections by the CURRENT (requested)
+    // name, get the nodeId, then re-resolve nodepayloads by nodeId.
+    // That bridges the gap without requiring users to re-fire every
+    // upstream trigger or run a manual migration.
+    //
+    // Also serves as the legacy fallback for triggers whose
+    // dashboard Output panel reads entity.lastPayload directly — if
+    // an entity carries lastPayload but its nodepayloads row is
+    // missing entirely, we surface entity.lastPayload too.
+    const initiallyRequested = Array.from(nodeNames);
+    let resolved = new Set(Object.keys(result));
+    let stillMissing = initiallyRequested.filter((n) => !resolved.has(n));
+    const initialMissingCount = stillMissing.length;
+    if (stillMissing.length > 0) {
+        const FALLBACK_COLLECTIONS = [
+            'triggers',
+            'chattriggers',
+            'scheduledworkflows',
+            'webhooks',
+        ];
+        const collectedNodeIds = [];
+        const nodeIdToName = new Map();
+        for (const coll of FALLBACK_COLLECTIONS) {
+            if (stillMissing.length === 0)
+                break;
+            try {
+                const entities = await db
+                    .collection(coll)
+                    .find({
+                    organizationId: new mongodb_1.ObjectId(orgId),
+                    workspaceId: new mongodb_1.ObjectId(workspaceId),
+                    name: { $in: stillMissing },
+                }, { projection: { name: 1, _id: 1, lastPayload: 1 } })
+                    .toArray();
+                for (const ent of entities) {
+                    const name = ent.name;
+                    if (!name)
+                        continue;
+                    collectedNodeIds.push(ent._id);
+                    nodeIdToName.set(ent._id.toString(), name);
+                    // Direct hit via legacy entity.lastPayload (rare but still valid)
+                    const payload = ent.lastPayload;
+                    if (payload && !(name in result)) {
+                        result[name] = payload;
+                        cacheNodePayload(workspaceId, name, payload);
+                    }
+                }
+                stillMissing = stillMissing.filter((n) => !(n in result));
+            }
+            catch {
+                /* collection doesn't exist or query failed — try next */
+            }
+        }
+        // Re-resolve via nodepayloads by nodeId (catches renamed rows
+        // whose `name` field is still stuck on the previous value).
+        if (stillMissing.length > 0 && collectedNodeIds.length > 0) {
+            try {
+                const docs = await db
+                    .collection('nodepayloads')
+                    .find({ nodeId: { $in: collectedNodeIds } }, { projection: { nodeId: 1, payload: 1 } })
+                    .toArray();
+                for (const doc of docs) {
+                    const nid = doc.nodeId.toString();
+                    const wantedName = nodeIdToName.get(nid);
+                    const payload = doc.payload;
+                    if (wantedName && payload && !(wantedName in result)) {
+                        result[wantedName] = payload;
+                        // Repair the stale name on the row so the next lookup
+                        // hits the fast path. Best-effort — log on failure
+                        // but don't fail the read.
+                        db.collection('nodepayloads')
+                            .updateOne({ _id: doc._id }, { $set: { name: wantedName } })
+                            .catch((err) => workspacePayloadsLogger.warn(`lazy rename repair failed for nodeId=${nid}: ${err.message}`));
+                        cacheNodePayload(workspaceId, wantedName, payload);
+                    }
+                }
+                stillMissing = stillMissing.filter((n) => !(n in result));
+            }
+            catch (err) {
+                workspacePayloadsLogger.warn(`loadWorkspacePayloads — nodeId re-resolve failed: ${err.message}`);
+            }
+        }
+        if (initialMissingCount > stillMissing.length) {
+            workspacePayloadsLogger.log(`loadWorkspacePayloads — fallback resolved ${initialMissingCount - stillMissing.length} name(s) (rename-recovery path) in ws=${workspaceId}`);
+        }
+        resolved = new Set(Object.keys(result));
+    }
+    // Diagnostic: every requested name that didn't land in the result
+    // got resolved as `undefined` by the template engine. Surface the
+    // mismatch so users can debug name-spelling / case / whitespace
+    // without having to inspect the database. Also dump the names that
+    // DO exist in the workspace so the diff is obvious — most "no
+    // resolve" cases turn out to be silent casing / whitespace drift.
+    const missing = initiallyRequested.filter((n) => !resolved.has(n));
+    if (missing.length > 0) {
+        try {
+            // Cross-workspace probe — find the missing names ANYWHERE in
+            // the org's nodepayloads. If they live under a different
+            // workspaceId (or null), that's the diagnosis.
+            const crossWs = await db
+                .collection('nodepayloads')
+                .find({
+                organizationId: new mongodb_1.ObjectId(orgId),
+                name: { $in: missing },
+            }, { projection: { name: 1, workspaceId: 1, nodeType: 1, nodeId: 1 } })
+                .limit(20)
+                .toArray();
+            const crossInfo = crossWs.length > 0
+                ? crossWs
+                    .map((d) => {
+                    const wsRaw = d.workspaceId;
+                    const wsId = wsRaw ? wsRaw.toString() : 'null';
+                    const wsLabel = wsId === workspaceId
+                        ? `${wsId} (SAME — name match failed for unknown reason)`
+                        : wsId === 'null'
+                            ? 'NULL (legacy node — never assigned a workspace)'
+                            : `${wsId} (DIFFERENT — workspaceId MISMATCH)`;
+                    return `"${d.name}" (${d.nodeType ?? '?'}) → ws=${wsLabel} node=${d.nodeId?.toString() ?? '?'}`;
+                })
+                    .join('; ')
+                : '(not found in any workspace of this org — node never fired)';
+            // Deeper probe — also scan ENTITY collections cross-workspace.
+            // The dashboard's OutputSection reads `entity.lastPayload`
+            // directly, so a user can see data in the UI even when both
+            // nodepayloads AND the same-workspace entity scan come up
+            // empty (means the entity lives in a different workspace
+            // entirely). Surface ALL matches across orgs so the workspace
+            // mismatch is unambiguous.
+            const entityFindings = [];
+            for (const coll of [
+                'triggers',
+                'chattriggers',
+                'scheduledworkflows',
+                'webhooks',
+            ]) {
+                try {
+                    const hits = await db
+                        .collection(coll)
+                        .find({
+                        organizationId: new mongodb_1.ObjectId(orgId),
+                        name: { $in: missing },
+                    }, {
+                        projection: {
+                            name: 1,
+                            workspaceId: 1,
+                            lastPayload: 1,
+                            isActive: 1,
+                        },
+                    })
+                        .limit(10)
+                        .toArray();
+                    for (const ent of hits) {
+                        const wsRaw = ent.workspaceId;
+                        const wsId = wsRaw ? wsRaw.toString() : 'null';
+                        const wsLabel = wsId === workspaceId ? 'SAME ws' : `DIFFERENT ws (${wsId})`;
+                        const hasLp = ent.lastPayload != null &&
+                            Object.keys(ent.lastPayload).length > 0;
+                        entityFindings.push(`"${ent.name}" in ${coll} → ${wsLabel}, lastPayload=${hasLp ? 'YES' : 'EMPTY'}, isActive=${ent.isActive ?? '?'}`);
+                    }
+                }
+                catch {
+                    /* collection doesn't exist — skip */
+                }
+            }
+            const entityInfo = entityFindings.length > 0
+                ? entityFindings.join('; ')
+                : '(no matching entity anywhere in the org)';
+            const all = await db
+                .collection('nodepayloads')
+                .find({
+                workspaceId: new mongodb_1.ObjectId(workspaceId),
+                organizationId: new mongodb_1.ObjectId(orgId),
+            }, { projection: { name: 1, nodeType: 1 } })
+                .limit(50)
+                .toArray();
+            const availableNames = all
+                .map((d) => {
+                const name = d.name ?? '(no name)';
+                const nodeType = d.nodeType ?? '?';
+                return `"${name}" (${nodeType})`;
+            })
+                .join(', ');
+            workspacePayloadsLogger.warn(`loadWorkspacePayloads — ${missing.length}/${initiallyRequested.length} unresolved in ws=${workspaceId}: missing=[${missing.map((m) => `"${m}"`).join(', ')}]. ` +
+                `\n  → nodepayloads cross-org: ${crossInfo}.` +
+                `\n  → entity collections cross-org: ${entityInfo}.` +
+                `\n  → Available payloads in THIS workspace (${all.length}): [${availableNames || 'none'}].`);
+        }
+        catch (err) {
+            workspacePayloadsLogger.warn(`loadWorkspacePayloads — ${missing.length} unresolved in ws=${workspaceId}: [${missing.join(', ')}] (diagnostic query failed: ${err.message})`);
+        }
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@hostwebhook/node-sdk",
+  "version": "0.1.0",
+  "description": "El SDK de un nodo de HostWebhook: ciclo de vida, ejecución con iteración, reintentos, filtros y validación de esquema — lo que comparten la api y el futuro servicio de nodos",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm --prefix ../node-types run build && npm --prefix ../template-engine run build && tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "hostwebhook",
+    "nodes",
+    "sdk"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hostwebhook/node-types": ">=1.67.0",
+    "@hostwebhook/template-engine": ">=2.0.0",
+    "@nestjs/common": ">=11.0.0",
+    "class-transformer": ">=0.5.0",
+    "express": ">=5.0.0",
+    "mongodb": ">=6.0.0",
+    "mongoose": ">=8.0.0",
+    "re2": ">=1.20.0",
+    "undici": ">=7.0.0",
+    "class-validator": ">=0.14.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}