@hostwebhook/node-sdk 0.1.0

package/dist/swallow.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Catch handlers for work whose failure must not abort the caller.
+ *
+ * `.catch(() => {})` says "this may fail and that is fine". It is almost
+ * never true. What it actually says is "this may fail and nobody will ever
+ * know" — and this codebase has paid for that repeatedly: a TTL index that
+ * was silently discarded and expired nothing for four months, an S3 adapter
+ * built without a bucket whose every delete failed while uploads kept
+ * working, a merge that waited forever because no timeout job was enqueued.
+ * Each one was found by accident, long after it started costing something.
+ *
+ * There is a real category of work that genuinely should not abort a
+ * request: cache writes, `lastUsed` touches, best-effort cleanup. The
+ * problem was never that they are swallowed, it is that they are swallowed
+ * *anonymously*. These helpers keep the non-blocking behaviour and make the
+ * failure land in the log with a name attached.
+ *
+ *   redis.set(k, v).catch(onFailure(this.logger, `cache write ${k}`));
+ *   const limits = await plans.getOrgPlanLimits(orgId)
+ *     .catch(onFailureReturn(this.logger, `plan limits for org ${orgId}`, null));
+ *
+ * NOT for use where the failure changes the answer. If a lookup failing
+ * means the caller returns 404 instead of 500, the fix is to let it throw,
+ * not to log it and carry on.
+ */
+import type { Logger } from '@nestjs/common';
+/**
+ * Log and continue, yielding `undefined`.
+ *
+ * `what` should name the resource, not the operation — "cache write for
+ * workspace 69ab…" beats "redis failed", because the first one can be
+ * searched for and the second cannot.
+ */
+export declare function onFailure(logger: Logger, what: string): (err: unknown) => undefined;
+/**
+ * Log and continue with a fallback value.
+ *
+ * Use when the fallback is a genuine default rather than a disguise for the
+ * error — plan limits falling back to `null` is fine as long as the log says
+ * the tier could not be read, because otherwise a user silently gets the
+ * wrong ceiling and nothing anywhere says why.
+ */
+export declare function onFailureReturn<T>(logger: Logger, what: string, fallback: T): (err: unknown) => T;
+/**
+ * Report the rejections inside an already-settled batch.
+ *
+ * `Promise.allSettled` never rejects, so `await Promise.allSettled(x).catch(…)`
+ * is dead code — three of those existed here, each looking like error
+ * handling while every individual rejection went unread. This awaits the
+ * batch and logs whichever entries failed.
+ */
+export declare function settleAll(promises: Promise<unknown>[], logger: Logger, what: string): Promise<void>;

package/dist/swallow.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onFailure = onFailure;
+exports.onFailureReturn = onFailureReturn;
+exports.settleAll = settleAll;
+function describe(err) {
+    if (err instanceof Error)
+        return err.stack ?? `${err.name}: ${err.message}`;
+    return String(err);
+}
+/**
+ * Log and continue, yielding `undefined`.
+ *
+ * `what` should name the resource, not the operation — "cache write for
+ * workspace 69ab…" beats "redis failed", because the first one can be
+ * searched for and the second cannot.
+ */
+function onFailure(logger, what) {
+    return (err) => {
+        logger.warn(`${what} failed (continuing): ${describe(err)}`);
+        return undefined;
+    };
+}
+/**
+ * Log and continue with a fallback value.
+ *
+ * Use when the fallback is a genuine default rather than a disguise for the
+ * error — plan limits falling back to `null` is fine as long as the log says
+ * the tier could not be read, because otherwise a user silently gets the
+ * wrong ceiling and nothing anywhere says why.
+ */
+function onFailureReturn(logger, what, fallback) {
+    return (err) => {
+        logger.warn(`${what} failed (using fallback): ${describe(err)}`);
+        return fallback;
+    };
+}
+/**
+ * Report the rejections inside an already-settled batch.
+ *
+ * `Promise.allSettled` never rejects, so `await Promise.allSettled(x).catch(…)`
+ * is dead code — three of those existed here, each looking like error
+ * handling while every individual rejection went unread. This awaits the
+ * batch and logs whichever entries failed.
+ */
+async function settleAll(promises, logger, what) {
+    if (promises.length === 0)
+        return;
+    const results = await Promise.allSettled(promises);
+    const failed = results.filter((r) => r.status === 'rejected');
+    if (failed.length > 0) {
+        logger.warn(`${what}: ${failed.length}/${results.length} failed — ` +
+            failed.map((f) => describe(f.reason)).join(' | '));
+    }
+}

package/dist/template-render.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Centralized template render factory.
+ *
+ * Creates a render function bound to a specific execution context
+ * (payload, headers, meta, workspacePayloads). Ensures $() cross-node
+ * references always resolve when workspacePayloads is available.
+ *
+ * Usage:
+ *   const { render } = createRender({ payload, workspacePayloads, eventMeta });
+ *   const url = render(entity.url);
+ *   const body = render(entity.body);
+ *
+ *   // Async version with _file resolution:
+ *   const { renderAsync } = createRender({ payload, fileResolver });
+ *   const body = await renderAsync(entity.body);
+ */
+import { type TemplateContext, type TemplateOptions, type FileResolver } from '@hostwebhook/template-engine';
+export interface RenderContext {
+    payload: Record<string, unknown>;
+    headers?: Record<string, string>;
+    meta?: Record<string, string>;
+    eventMeta?: Record<string, string>;
+    workspacePayloads?: Record<string, Record<string, unknown>>;
+    /** Async file resolver — generates presigned download URLs for _file references */
+    fileResolver?: FileResolver;
+}
+export declare function createRender(rCtx: RenderContext, extraOpts?: Partial<TemplateOptions>): {
+    ctx: TemplateContext;
+    /** Sync render — does NOT resolve _file downloadUrl (use renderAsync for that) */
+    render: (t: string) => string;
+    /** Async render — pre-resolves _file references with presigned download URLs */
+    renderAsync: (t: string) => Promise<string>;
+};

package/dist/template-render.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Centralized template render factory.
+ *
+ * Creates a render function bound to a specific execution context
+ * (payload, headers, meta, workspacePayloads). Ensures $() cross-node
+ * references always resolve when workspacePayloads is available.
+ *
+ * Usage:
+ *   const { render } = createRender({ payload, workspacePayloads, eventMeta });
+ *   const url = render(entity.url);
+ *   const body = render(entity.body);
+ *
+ *   // Async version with _file resolution:
+ *   const { renderAsync } = createRender({ payload, fileResolver });
+ *   const body = await renderAsync(entity.body);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRender = createRender;
+const template_engine_1 = require("@hostwebhook/template-engine");
+function createRender(rCtx, extraOpts) {
+    const ctx = {
+        payload: rCtx.payload,
+        headers: rCtx.headers ?? {},
+        meta: rCtx.eventMeta ?? rCtx.meta ?? {},
+    };
+    const opts = extraOpts || rCtx.workspacePayloads || rCtx.fileResolver
+        ? {
+            ...extraOpts,
+            ...(rCtx.workspacePayloads
+                ? { workspacePayloads: rCtx.workspacePayloads }
+                : {}),
+            ...(rCtx.fileResolver ? { fileResolver: rCtx.fileResolver } : {}),
+        }
+        : undefined;
+    return {
+        ctx,
+        /** Sync render — does NOT resolve _file downloadUrl (use renderAsync for that) */
+        render: (t) => (0, template_engine_1.renderTemplate)(t, ctx, opts).output,
+        /** Async render — pre-resolves _file references with presigned download URLs */
+        renderAsync: async (t) => (await (0, template_engine_1.renderTemplateAsync)(t, ctx, opts)).output,
+    };
+}

package/dist/try-parse.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Parsers used as tests rather than as conversions.
+ *
+ * `try { JSON.parse(x) } catch {}` is not an error being swallowed — the throw
+ * IS the answer, and the caller wants "is this JSON?" rather than a failure.
+ * That makes it the one shape `common/swallow.ts` deliberately does not cover:
+ * logging it would emit a line per non-JSON payload, which is noise.
+ *
+ * But it was written out longhand 39 times across the codebase, each with its
+ * own comment explaining the same thing, and each leaving an empty `catch` for
+ * a reviewer to classify from scratch. The intent belongs in a name.
+ *
+ *   const parsed = tryParseJson<Shape>(result.responseBody);
+ *   if (parsed?._operationOutput) return parsed.output;
+ *
+ * The distinction that matters, and the reason this is a separate file from
+ * swallow.ts: use these ONLY where a parse failure is an expected, ordinary
+ * branch. If a payload that fails to parse means something is actually wrong —
+ * a webhook that should always be JSON, a config file, an API contract — let
+ * it throw, or catch it and say so. Reaching for `tryParseJson` to make an
+ * error quiet is the same mistake as `.catch(() => {})`, wearing a better name.
+ */
+/**
+ * Parse JSON, or `null` when the input is not JSON.
+ *
+ * Returns `null` for `null`/`undefined`/empty input too, so callers do not
+ * need a separate emptiness check before asking.
+ */
+export declare function tryParseJson<T = unknown>(raw: unknown): T | null;
+/**
+ * Parse JSON expecting an object, or `null`.
+ *
+ * `JSON.parse('4')` and `JSON.parse('"x"')` both succeed, so a bare
+ * `tryParseJson` followed by `parsed.someField` is a silent `undefined` on
+ * perfectly valid JSON that simply is not a record. Most call sites here want
+ * a record; this makes that explicit instead of relying on the field lookup
+ * to fail quietly.
+ */
+export declare function tryParseJsonObject<T extends object = Record<string, unknown>>(raw: unknown): T | null;
+/** Parse a URL, or `null` when the string is not one. */
+export declare function tryParseUrl(raw: unknown): URL | null;

package/dist/try-parse.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Parsers used as tests rather than as conversions.
+ *
+ * `try { JSON.parse(x) } catch {}` is not an error being swallowed — the throw
+ * IS the answer, and the caller wants "is this JSON?" rather than a failure.
+ * That makes it the one shape `common/swallow.ts` deliberately does not cover:
+ * logging it would emit a line per non-JSON payload, which is noise.
+ *
+ * But it was written out longhand 39 times across the codebase, each with its
+ * own comment explaining the same thing, and each leaving an empty `catch` for
+ * a reviewer to classify from scratch. The intent belongs in a name.
+ *
+ *   const parsed = tryParseJson<Shape>(result.responseBody);
+ *   if (parsed?._operationOutput) return parsed.output;
+ *
+ * The distinction that matters, and the reason this is a separate file from
+ * swallow.ts: use these ONLY where a parse failure is an expected, ordinary
+ * branch. If a payload that fails to parse means something is actually wrong —
+ * a webhook that should always be JSON, a config file, an API contract — let
+ * it throw, or catch it and say so. Reaching for `tryParseJson` to make an
+ * error quiet is the same mistake as `.catch(() => {})`, wearing a better name.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryParseJson = tryParseJson;
+exports.tryParseJsonObject = tryParseJsonObject;
+exports.tryParseUrl = tryParseUrl;
+/**
+ * Parse JSON, or `null` when the input is not JSON.
+ *
+ * Returns `null` for `null`/`undefined`/empty input too, so callers do not
+ * need a separate emptiness check before asking.
+ */
+function tryParseJson(raw) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse JSON expecting an object, or `null`.
+ *
+ * `JSON.parse('4')` and `JSON.parse('"x"')` both succeed, so a bare
+ * `tryParseJson` followed by `parsed.someField` is a silent `undefined` on
+ * perfectly valid JSON that simply is not a record. Most call sites here want
+ * a record; this makes that explicit instead of relying on the field lookup
+ * to fail quietly.
+ */
+function tryParseJsonObject(raw) {
+    const parsed = tryParseJson(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    return parsed;
+}
+/** Parse a URL, or `null` when the string is not one. */
+function tryParseUrl(raw) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return null;
+    try {
+        return new URL(raw);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/workspace-payloads.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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
+ */
+import type { Db } from 'mongodb';
+import type { Connection } from 'mongoose';
+/** Get the shared Redis client (or null if not initialized) */
+export declare function getPayloadRedis(): any;
+/** Get or create the shared Redis client for payload caching */
+export declare function initPayloadRedis(redisUrl?: string): void;
+/** Extract node names referenced by $("name") or $('name') in the entity */
+export declare function extractCrossNodeRefs(entity: unknown): Set<string>;
+/** Write a node's payload to Redis cache (fire-and-forget, 5 min TTL) */
+export declare function cacheNodePayload(wsId: string, name: string, payload: Record<string, unknown>): void;
+/**
+ * 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.
+ */
+export declare function deleteNodePayload(connection: Connection, nodeId: string): Promise<void>;
+/** Invalidate canvas-data Redis cache for an org+workspace (fire-and-forget) */
+export declare function invalidateCanvasCache(orgId: string, workspaceId?: string): void;
+/**
+ * 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.
+ */
+export declare function propagateNodeRename(connection: Connection, nodeId: string, previousName: string | undefined, newName: string, workspaceId: string | undefined): Promise<void>;
+/**
+ * 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.
+ */
+export declare function loadWorkspacePayloads(db: Db, workspaceId: string, orgId: string, nodeNames?: Set<string>): Promise<Record<string, Record<string, unknown>>>;