@hostwebhook/template-engine 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,85 @@
+type TemplateMode = 'json' | 'text' | 'html' | 'code' | 'auto';
+interface TemplateOptions {
+    /** Template processing mode. Default: 'auto' (json if starts with {/[, else text). */
+    mode?: TemplateMode;
+    /** Enable JS expression evaluation within {{...}} (json/text/html modes). Default: false. */
+    allowJs?: boolean;
+    /** Workspace payloads for $() cross-node references. */
+    workspacePayloads?: Record<string, Record<string, unknown>>;
+    /** Timeout for JS execution in ms. Default: 1000 for template modes, 5000 for code mode. */
+    timeout?: number;
+    /** Code mode only: receive full iterable array as payload instead of per-item. */
+    batchMode?: boolean;
+}
+interface TemplateContext {
+    payload: unknown;
+    headers: Record<string, string>;
+    meta: Record<string, string>;
+    [key: string]: unknown;
+}
+interface TemplateResult {
+    /** The interpolated output string. */
+    output: string;
+    /** Type-preserved value when a single {{expr}} resolves to a non-string (json mode). */
+    rawValue?: unknown;
+}
+interface CodeResult {
+    /** The return value from the executed code. */
+    output: unknown;
+    /** 200 on success, 500 on error. */
+    statusCode: number;
+    /** Captured console.log/warn/error output. */
+    logs: string[];
+    /** Error message if statusCode is 500. */
+    error?: string;
+}
+
+/**
+ * Render a template with the specified mode.
+ *
+ * @example
+ * // JSON mode — type-preserving interpolation
+ * renderTemplate('{"name": "{{payload.name}}"}', ctx, { mode: 'json' });
+ *
+ * // Text mode — plain string replacement
+ * renderTemplate('Hello {{payload.name}}!', ctx, { mode: 'text' });
+ *
+ * // HTML mode — entity-encoded output
+ * renderTemplate('<p>{{payload.html}}</p>', ctx, { mode: 'html' });
+ *
+ * // Code mode — sandboxed JS execution
+ * renderTemplate('return payload.items.length;', ctx, { mode: 'code' });
+ *
+ * // Auto mode — detects json vs text (legacy behavior)
+ * renderTemplate(template, ctx); // default
+ */
+declare function renderTemplate(template: string, ctx: TemplateContext, opts?: TemplateOptions): TemplateResult | CodeResult;
+
+/**
+ * Resolve a dot-notation path against a TemplateContext.
+ * Supports bracket notation for array indexing: `payload.items[0].name`
+ */
+declare function resolvePath(path: string, ctx: TemplateContext): unknown;
+/** Convert a value to string. null/undefined → '', objects → JSON.stringify. */
+declare function valueToString(val: unknown): string;
+
+/**
+ * Try null-coalescing: path ?? "fallback"
+ * Returns null if expression is not a null-coalesce.
+ */
+declare function tryNullCoalesce(expr: string, ctx: TemplateContext): string | null;
+/**
+ * Parse and evaluate a ternary expression.
+ * Returns null if the expression is not a ternary.
+ */
+declare function tryTernary(expr: string, ctx: TemplateContext): string | null;
+/**
+ * Apply a pipe transform: | json, | upper, | lower, | trim
+ */
+declare function applyPipe(pipe: string, val: unknown): string;
+/**
+ * Evaluate a single {{...}} expression and return a string.
+ */
+declare function evaluate(expr: string, ctx: TemplateContext, opts?: TemplateOptions): string;
+
+export { type CodeResult, type TemplateContext, type TemplateMode, type TemplateOptions, type TemplateResult, applyPipe, evaluate, renderTemplate, resolvePath, tryNullCoalesce, tryTernary, valueToString };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+type TemplateMode = 'json' | 'text' | 'html' | 'code' | 'auto';
+interface TemplateOptions {
+    /** Template processing mode. Default: 'auto' (json if starts with {/[, else text). */
+    mode?: TemplateMode;
+    /** Enable JS expression evaluation within {{...}} (json/text/html modes). Default: false. */
+    allowJs?: boolean;
+    /** Workspace payloads for $() cross-node references. */
+    workspacePayloads?: Record<string, Record<string, unknown>>;
+    /** Timeout for JS execution in ms. Default: 1000 for template modes, 5000 for code mode. */
+    timeout?: number;
+    /** Code mode only: receive full iterable array as payload instead of per-item. */
+    batchMode?: boolean;
+}
+interface TemplateContext {
+    payload: unknown;
+    headers: Record<string, string>;
+    meta: Record<string, string>;
+    [key: string]: unknown;
+}
+interface TemplateResult {
+    /** The interpolated output string. */
+    output: string;
+    /** Type-preserved value when a single {{expr}} resolves to a non-string (json mode). */
+    rawValue?: unknown;
+}
+interface CodeResult {
+    /** The return value from the executed code. */
+    output: unknown;
+    /** 200 on success, 500 on error. */
+    statusCode: number;
+    /** Captured console.log/warn/error output. */
+    logs: string[];
+    /** Error message if statusCode is 500. */
+    error?: string;
+}
+
+/**
+ * Render a template with the specified mode.
+ *
+ * @example
+ * // JSON mode — type-preserving interpolation
+ * renderTemplate('{"name": "{{payload.name}}"}', ctx, { mode: 'json' });
+ *
+ * // Text mode — plain string replacement
+ * renderTemplate('Hello {{payload.name}}!', ctx, { mode: 'text' });
+ *
+ * // HTML mode — entity-encoded output
+ * renderTemplate('<p>{{payload.html}}</p>', ctx, { mode: 'html' });
+ *
+ * // Code mode — sandboxed JS execution
+ * renderTemplate('return payload.items.length;', ctx, { mode: 'code' });
+ *
+ * // Auto mode — detects json vs text (legacy behavior)
+ * renderTemplate(template, ctx); // default
+ */
+declare function renderTemplate(template: string, ctx: TemplateContext, opts?: TemplateOptions): TemplateResult | CodeResult;
+
+/**
+ * Resolve a dot-notation path against a TemplateContext.
+ * Supports bracket notation for array indexing: `payload.items[0].name`
+ */
+declare function resolvePath(path: string, ctx: TemplateContext): unknown;
+/** Convert a value to string. null/undefined → '', objects → JSON.stringify. */
+declare function valueToString(val: unknown): string;
+
+/**
+ * Try null-coalescing: path ?? "fallback"
+ * Returns null if expression is not a null-coalesce.
+ */
+declare function tryNullCoalesce(expr: string, ctx: TemplateContext): string | null;
+/**
+ * Parse and evaluate a ternary expression.
+ * Returns null if the expression is not a ternary.
+ */
+declare function tryTernary(expr: string, ctx: TemplateContext): string | null;
+/**
+ * Apply a pipe transform: | json, | upper, | lower, | trim
+ */
+declare function applyPipe(pipe: string, val: unknown): string;
+/**
+ * Evaluate a single {{...}} expression and return a string.
+ */
+declare function evaluate(expr: string, ctx: TemplateContext, opts?: TemplateOptions): string;
+
+export { type CodeResult, type TemplateContext, type TemplateMode, type TemplateOptions, type TemplateResult, applyPipe, evaluate, renderTemplate, resolvePath, tryNullCoalesce, tryTernary, valueToString };

package/dist/index.js

@@ -0,0 +1,476 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  applyPipe: () => applyPipe,
+  evaluate: () => evaluate,
+  renderTemplate: () => renderTemplate,
+  resolvePath: () => resolvePath,
+  tryNullCoalesce: () => tryNullCoalesce,
+  tryTernary: () => tryTernary,
+  valueToString: () => valueToString
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/resolve-path.ts
+function resolvePath(path, ctx) {
+  const [prefix, ...rest] = path.split(".");
+  const key = rest.join(".");
+  let source;
+  switch (prefix) {
+    case "payload":
+      source = ctx.payload;
+      break;
+    case "headers":
+      source = ctx.headers;
+      break;
+    case "meta":
+      source = ctx.meta;
+      break;
+    default:
+      source = ctx[prefix];
+      break;
+  }
+  if (!key) return source;
+  return key.split(".").reduce((curr, k) => {
+    if (curr === null || curr === void 0) return void 0;
+    const bracketMatch = k.match(/^([^[]*)\[(\d+)\]$/);
+    if (bracketMatch) {
+      const [, prop, indexStr] = bracketMatch;
+      let obj = curr;
+      if (prop && typeof obj === "object") {
+        obj = obj[prop];
+      }
+      if (Array.isArray(obj)) {
+        return obj[Number(indexStr)];
+      }
+      return void 0;
+    }
+    if (typeof curr === "object") {
+      return curr[k];
+    }
+    return void 0;
+  }, source);
+}
+function valueToString(val) {
+  if (val === void 0 || val === null) return "";
+  if (typeof val === "object") return JSON.stringify(val);
+  return String(val);
+}
+
+// src/sandbox.ts
+var vm = __toESM(require("vm"));
+function buildNodeLookup(workspacePayloads) {
+  return (nodeName) => {
+    if (!workspacePayloads) throw new Error("$() requires workspace context");
+    const p = workspacePayloads[nodeName];
+    if (!p) throw new Error(`Node "${nodeName}" not found`);
+    let cloned;
+    try {
+      cloned = structuredClone(p);
+    } catch {
+      cloned = JSON.parse(JSON.stringify(p));
+    }
+    const m = cloned._meta;
+    if (m?.iterable && m.iterateField) return cloned[m.iterateField] ?? [];
+    const { _meta, ...clean } = cloned;
+    return clean;
+  };
+}
+function buildSandbox(ctx, opts, logs) {
+  const stringify = (v) => {
+    if (v === void 0) return "undefined";
+    if (v === null) return "null";
+    if (typeof v === "object") {
+      try {
+        return JSON.stringify(v, null, 2);
+      } catch {
+        return String(v);
+      }
+    }
+    return String(v);
+  };
+  const sandbox = {
+    payload: ctx.payload,
+    $: buildNodeLookup(opts.workspacePayloads),
+    headers: ctx.headers,
+    meta: ctx.meta,
+    JSON,
+    Math,
+    Date,
+    Array,
+    Object,
+    String,
+    Number,
+    Boolean,
+    RegExp,
+    parseInt,
+    parseFloat,
+    isNaN,
+    isFinite,
+    encodeURIComponent,
+    decodeURIComponent,
+    Map,
+    Set
+  };
+  if (opts.mode === "code" && logs) {
+    sandbox.console = {
+      log: (...args) => logs.push(args.map(stringify).join(" ")),
+      warn: (...args) => logs.push(`[warn] ${args.map(stringify).join(" ")}`),
+      error: (...args) => logs.push(`[error] ${args.map(stringify).join(" ")}`)
+    };
+  }
+  return vm.createContext(sandbox);
+}
+function evalJsExpression(expr, ctx, opts) {
+  const context = buildSandbox(ctx, { ...opts, mode: "text" });
+  try {
+    const script = new vm.Script(`(${expr})`, { filename: "template-expr.js" });
+    return script.runInContext(context, { timeout: opts.timeout ?? 1e3 });
+  } catch (err) {
+    console.error(
+      `[template-engine] JS eval failed "${expr.slice(0, 80)}": ${err instanceof Error ? err.message : err}`
+    );
+    return void 0;
+  }
+}
+
+// src/expressions.ts
+function resolveBranch(raw, ctx) {
+  const t = raw.trim();
+  if (t.startsWith('"') && t.endsWith('"') || t.startsWith("'") && t.endsWith("'")) {
+    return t.slice(1, -1);
+  }
+  if (t !== "" && !isNaN(Number(t))) {
+    return t;
+  }
+  return valueToString(resolvePath(t, ctx));
+}
+function parseComparand(raw) {
+  const t = raw.trim();
+  if (t === "null") return null;
+  if (t === "undefined") return void 0;
+  if (t === "true") return true;
+  if (t === "false") return false;
+  if (t.startsWith('"') && t.endsWith('"') || t.startsWith("'") && t.endsWith("'")) {
+    return t.slice(1, -1);
+  }
+  if (t !== "" && !isNaN(Number(t))) return Number(t);
+  return t;
+}
+function applyOperator(left, op, right) {
+  switch (op) {
+    case "===":
+      return left === right;
+    case "!==":
+      return left !== right;
+    // eslint-disable-next-line eqeqeq
+    case "==":
+      return left == right;
+    // eslint-disable-next-line eqeqeq
+    case "!=":
+      return left != right;
+    case ">":
+      return Number(left) > Number(right);
+    case "<":
+      return Number(left) < Number(right);
+    case ">=":
+      return Number(left) >= Number(right);
+    case "<=":
+      return Number(left) <= Number(right);
+    default:
+      return false;
+  }
+}
+var BRANCH = `(?:"[^"]*"|'[^']*'|\\S+)`;
+var CMP_RE = new RegExp(
+  `^(.+?)\\s*(===|!==|==|!=|>=|<=|>|<)\\s*(.+?)\\s*\\?\\s*(${BRANCH})\\s*:\\s*(${BRANCH})$`
+);
+var TRUTHY_RE = new RegExp(
+  `^(!?)(.+?)\\s*\\?\\s*(${BRANCH})\\s*:\\s*(${BRANCH})$`
+);
+var NULL_COALESCE_RE = /^(.+?)\s*\?\?\s*("(?:[^"]*)"$|'(?:[^']*)'$|\S+$)/;
+var PIPE_RE = /^(.+?)\s*\|\s*(json|upper|lower|trim)$/;
+function tryNullCoalesce(expr, ctx) {
+  const m = expr.match(NULL_COALESCE_RE);
+  if (!m) return null;
+  const [, path, fallbackRaw] = m;
+  const val = resolvePath(path.trim(), ctx);
+  if (val === null || val === void 0 || val === "") {
+    return resolveBranch(fallbackRaw.trim(), ctx);
+  }
+  return valueToString(val);
+}
+function tryTernary(expr, ctx) {
+  const cmpM = expr.match(CMP_RE);
+  if (cmpM) {
+    const [, path2, op, comparand, trueRaw2, falseRaw2] = cmpM;
+    const left = resolvePath(path2.trim(), ctx);
+    const right = parseComparand(comparand.trim());
+    return applyOperator(left, op, right) ? resolveBranch(trueRaw2, ctx) : resolveBranch(falseRaw2, ctx);
+  }
+  const m = expr.match(TRUTHY_RE);
+  if (!m) return null;
+  const [, negate, path, trueRaw, falseRaw] = m;
+  const resolved = resolvePath(path.trim(), ctx);
+  let truthy = resolved !== void 0 && resolved !== null && resolved !== "" && resolved !== false && resolved !== 0;
+  if (negate === "!") truthy = !truthy;
+  return truthy ? resolveBranch(trueRaw, ctx) : resolveBranch(falseRaw, ctx);
+}
+function applyPipe(pipe, val) {
+  switch (pipe) {
+    case "json":
+      return JSON.stringify(val, null, 2);
+    case "upper":
+      return String(val ?? "").toUpperCase();
+    case "lower":
+      return String(val ?? "").toLowerCase();
+    case "trim":
+      return String(val ?? "").trim();
+    default:
+      return valueToString(val);
+  }
+}
+function evaluate(expr, ctx, opts) {
+  const trimmed = expr.trim();
+  if (trimmed.startsWith("!!")) {
+    const val = resolvePath(trimmed.slice(2).trim(), ctx);
+    return String(!!val);
+  }
+  if (trimmed.startsWith("!") && !trimmed.includes("?") && !trimmed.includes("=")) {
+    const val = resolvePath(trimmed.slice(1).trim(), ctx);
+    return String(!val);
+  }
+  const pipeM = trimmed.match(PIPE_RE);
+  if (pipeM) {
+    const [, path, pipe] = pipeM;
+    const val = resolvePath(path.trim(), ctx);
+    return applyPipe(pipe, val);
+  }
+  const ncResult = tryNullCoalesce(trimmed, ctx);
+  if (ncResult !== null) return ncResult;
+  const ternaryResult = tryTernary(trimmed, ctx);
+  if (ternaryResult !== null) return ternaryResult;
+  const resolved = resolvePath(trimmed, ctx);
+  if (resolved !== void 0) return valueToString(resolved);
+  if (opts?.allowJs) {
+    const jsResult = evalJsExpression(trimmed, ctx, opts);
+    if (jsResult !== void 0) return valueToString(jsResult);
+  }
+  return "";
+}
+
+// src/json-mode.ts
+function resolveJsonValue(value, ctx, opts) {
+  if (typeof value === "string") {
+    const singleExpr = value.match(/^\{\{((?:(?!\}\}).)*)\}\}$/);
+    if (singleExpr) {
+      const expr = singleExpr[1].trim();
+      const ncResult = tryNullCoalesce(expr, ctx);
+      if (ncResult !== null) return ncResult;
+      const ternaryResult = tryTernary(expr, ctx);
+      if (ternaryResult !== null) {
+        if (ternaryResult !== "" && !isNaN(Number(ternaryResult))) return Number(ternaryResult);
+        return ternaryResult;
+      }
+      if (expr.startsWith("!!")) {
+        const val = resolvePath(expr.slice(2).trim(), ctx);
+        return !!val;
+      }
+      if (expr.startsWith("!") && !expr.includes("?") && !expr.includes("=")) {
+        const val = resolvePath(expr.slice(1).trim(), ctx);
+        return !val;
+      }
+      if (/\|\s*(json|upper|lower|trim)$/.test(expr)) {
+        return evaluate(expr, ctx, opts);
+      }
+      const resolved = resolvePath(expr, ctx);
+      if (resolved !== void 0) return resolved;
+      if (opts?.allowJs) {
+        const jsResult = evalJsExpression(expr, ctx, opts);
+        if (jsResult !== void 0) return jsResult;
+      }
+      return "";
+    }
+    return value.replace(
+      /\{\{(.*?)\}\}/g,
+      (_, expr) => evaluate(expr, ctx, opts)
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveJsonValue(item, ctx, opts));
+  }
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = resolveJsonValue(v, ctx, opts);
+    }
+    return result;
+  }
+  return value;
+}
+function resolveJsonTemplate(template, ctx, opts) {
+  const jsonReady = template.replace(/\{\{([\s\S]*?)\}\}/g, (_, inner) => {
+    const escaped = inner.replace(/(?<!\\)"/g, '\\"');
+    return `{{${escaped}}}`;
+  });
+  try {
+    const parsed = JSON.parse(jsonReady);
+    const resolved = resolveJsonValue(parsed, ctx, opts);
+    return {
+      output: JSON.stringify(resolved),
+      rawValue: resolved
+    };
+  } catch {
+    const output = template.replace(/\{\{([\s\S]*?)\}\}/g, (_, expr) => {
+      const val = evaluate(expr, ctx, opts);
+      return val.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+    });
+    return { output };
+  }
+}
+
+// src/html-mode.ts
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}
+function resolveHtmlTemplate(template, ctx, opts) {
+  const output = template.replace(/\{\{([\s\S]*?)\}\}/g, (_, expr) => {
+    const val = evaluate(expr, ctx, opts);
+    return escapeHtml(val);
+  });
+  return { output };
+}
+
+// src/code-mode.ts
+var vm2 = __toESM(require("vm"));
+function executeCodeTemplate(code, ctx, opts) {
+  const logs = [];
+  const timeout = opts.timeout ?? 5e3;
+  let sandboxPayload = ctx.payload;
+  if (opts.batchMode) {
+    const meta = ctx.payload?._meta;
+    if (meta?.iterable && meta.iterateField) {
+      try {
+        sandboxPayload = structuredClone(
+          ctx.payload[meta.iterateField] ?? []
+        );
+      } catch {
+        sandboxPayload = JSON.parse(
+          JSON.stringify(ctx.payload[meta.iterateField] ?? [])
+        );
+      }
+    } else {
+      try {
+        sandboxPayload = structuredClone(ctx.payload);
+      } catch {
+        sandboxPayload = JSON.parse(JSON.stringify(ctx.payload));
+      }
+    }
+  } else {
+    try {
+      sandboxPayload = structuredClone(ctx.payload);
+    } catch {
+      sandboxPayload = JSON.parse(JSON.stringify(ctx.payload));
+    }
+  }
+  const context = buildSandbox(
+    { ...ctx, payload: sandboxPayload },
+    { ...opts, mode: "code" },
+    logs
+  );
+  try {
+    const script = new vm2.Script(`(function() {
+${code}
+})()`, {
+      filename: "code-node.js"
+    });
+    const result = script.runInContext(context, { timeout });
+    if (result == null) {
+      return { output: null, statusCode: 200, logs };
+    }
+    return { output: result, statusCode: 200, logs };
+  } catch (err) {
+    let message;
+    if (err instanceof Error) {
+      message = err.message;
+    } else if (typeof err === "string") {
+      message = err;
+    } else {
+      message = String(err);
+    }
+    return { output: null, statusCode: 500, logs, error: message };
+  }
+}
+
+// src/render.ts
+function resolveTextTemplate(template, ctx, opts) {
+  const output = template.replace(
+    /\{\{([\s\S]*?)\}\}/g,
+    (_, expr) => evaluate(expr, ctx, opts)
+  );
+  return { output };
+}
+function detectMode(template) {
+  return /^\s*[\[{]/.test(template) ? "json" : "text";
+}
+function renderTemplate(template, ctx, opts) {
+  const mode = opts?.mode ?? "auto";
+  switch (mode) {
+    case "code":
+      return executeCodeTemplate(template, ctx, opts ?? {});
+    case "json":
+      return resolveJsonTemplate(template, ctx, opts);
+    case "html":
+      return resolveHtmlTemplate(template, ctx, opts);
+    case "text":
+      return resolveTextTemplate(template, ctx, opts);
+    case "auto": {
+      const detected = detectMode(template);
+      if (detected === "json") {
+        return resolveJsonTemplate(template, ctx, opts);
+      }
+      return resolveTextTemplate(template, ctx, opts);
+    }
+    default:
+      return resolveTextTemplate(template, ctx, opts);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  applyPipe,
+  evaluate,
+  renderTemplate,
+  resolvePath,
+  tryNullCoalesce,
+  tryTernary,
+  valueToString
+});

package/dist/index.mjs

@@ -0,0 +1,433 @@
+// src/resolve-path.ts
+function resolvePath(path, ctx) {
+  const [prefix, ...rest] = path.split(".");
+  const key = rest.join(".");
+  let source;
+  switch (prefix) {
+    case "payload":
+      source = ctx.payload;
+      break;
+    case "headers":
+      source = ctx.headers;
+      break;
+    case "meta":
+      source = ctx.meta;
+      break;
+    default:
+      source = ctx[prefix];
+      break;
+  }
+  if (!key) return source;
+  return key.split(".").reduce((curr, k) => {
+    if (curr === null || curr === void 0) return void 0;
+    const bracketMatch = k.match(/^([^[]*)\[(\d+)\]$/);
+    if (bracketMatch) {
+      const [, prop, indexStr] = bracketMatch;
+      let obj = curr;
+      if (prop && typeof obj === "object") {
+        obj = obj[prop];
+      }
+      if (Array.isArray(obj)) {
+        return obj[Number(indexStr)];
+      }
+      return void 0;
+    }
+    if (typeof curr === "object") {
+      return curr[k];
+    }
+    return void 0;
+  }, source);
+}
+function valueToString(val) {
+  if (val === void 0 || val === null) return "";
+  if (typeof val === "object") return JSON.stringify(val);
+  return String(val);
+}
+
+// src/sandbox.ts
+import * as vm from "vm";
+function buildNodeLookup(workspacePayloads) {
+  return (nodeName) => {
+    if (!workspacePayloads) throw new Error("$() requires workspace context");
+    const p = workspacePayloads[nodeName];
+    if (!p) throw new Error(`Node "${nodeName}" not found`);
+    let cloned;
+    try {
+      cloned = structuredClone(p);
+    } catch {
+      cloned = JSON.parse(JSON.stringify(p));
+    }
+    const m = cloned._meta;
+    if (m?.iterable && m.iterateField) return cloned[m.iterateField] ?? [];
+    const { _meta, ...clean } = cloned;
+    return clean;
+  };
+}
+function buildSandbox(ctx, opts, logs) {
+  const stringify = (v) => {
+    if (v === void 0) return "undefined";
+    if (v === null) return "null";
+    if (typeof v === "object") {
+      try {
+        return JSON.stringify(v, null, 2);
+      } catch {
+        return String(v);
+      }
+    }
+    return String(v);
+  };
+  const sandbox = {
+    payload: ctx.payload,
+    $: buildNodeLookup(opts.workspacePayloads),
+    headers: ctx.headers,
+    meta: ctx.meta,
+    JSON,
+    Math,
+    Date,
+    Array,
+    Object,
+    String,
+    Number,
+    Boolean,
+    RegExp,
+    parseInt,
+    parseFloat,
+    isNaN,
+    isFinite,
+    encodeURIComponent,
+    decodeURIComponent,
+    Map,
+    Set
+  };
+  if (opts.mode === "code" && logs) {
+    sandbox.console = {
+      log: (...args) => logs.push(args.map(stringify).join(" ")),
+      warn: (...args) => logs.push(`[warn] ${args.map(stringify).join(" ")}`),
+      error: (...args) => logs.push(`[error] ${args.map(stringify).join(" ")}`)
+    };
+  }
+  return vm.createContext(sandbox);
+}
+function evalJsExpression(expr, ctx, opts) {
+  const context = buildSandbox(ctx, { ...opts, mode: "text" });
+  try {
+    const script = new vm.Script(`(${expr})`, { filename: "template-expr.js" });
+    return script.runInContext(context, { timeout: opts.timeout ?? 1e3 });
+  } catch (err) {
+    console.error(
+      `[template-engine] JS eval failed "${expr.slice(0, 80)}": ${err instanceof Error ? err.message : err}`
+    );
+    return void 0;
+  }
+}
+
+// src/expressions.ts
+function resolveBranch(raw, ctx) {
+  const t = raw.trim();
+  if (t.startsWith('"') && t.endsWith('"') || t.startsWith("'") && t.endsWith("'")) {
+    return t.slice(1, -1);
+  }
+  if (t !== "" && !isNaN(Number(t))) {
+    return t;
+  }
+  return valueToString(resolvePath(t, ctx));
+}
+function parseComparand(raw) {
+  const t = raw.trim();
+  if (t === "null") return null;
+  if (t === "undefined") return void 0;
+  if (t === "true") return true;
+  if (t === "false") return false;
+  if (t.startsWith('"') && t.endsWith('"') || t.startsWith("'") && t.endsWith("'")) {
+    return t.slice(1, -1);
+  }
+  if (t !== "" && !isNaN(Number(t))) return Number(t);
+  return t;
+}
+function applyOperator(left, op, right) {
+  switch (op) {
+    case "===":
+      return left === right;
+    case "!==":
+      return left !== right;
+    // eslint-disable-next-line eqeqeq
+    case "==":
+      return left == right;
+    // eslint-disable-next-line eqeqeq
+    case "!=":
+      return left != right;
+    case ">":
+      return Number(left) > Number(right);
+    case "<":
+      return Number(left) < Number(right);
+    case ">=":
+      return Number(left) >= Number(right);
+    case "<=":
+      return Number(left) <= Number(right);
+    default:
+      return false;
+  }
+}
+var BRANCH = `(?:"[^"]*"|'[^']*'|\\S+)`;
+var CMP_RE = new RegExp(
+  `^(.+?)\\s*(===|!==|==|!=|>=|<=|>|<)\\s*(.+?)\\s*\\?\\s*(${BRANCH})\\s*:\\s*(${BRANCH})$`
+);
+var TRUTHY_RE = new RegExp(
+  `^(!?)(.+?)\\s*\\?\\s*(${BRANCH})\\s*:\\s*(${BRANCH})$`
+);
+var NULL_COALESCE_RE = /^(.+?)\s*\?\?\s*("(?:[^"]*)"$|'(?:[^']*)'$|\S+$)/;
+var PIPE_RE = /^(.+?)\s*\|\s*(json|upper|lower|trim)$/;
+function tryNullCoalesce(expr, ctx) {
+  const m = expr.match(NULL_COALESCE_RE);
+  if (!m) return null;
+  const [, path, fallbackRaw] = m;
+  const val = resolvePath(path.trim(), ctx);
+  if (val === null || val === void 0 || val === "") {
+    return resolveBranch(fallbackRaw.trim(), ctx);
+  }
+  return valueToString(val);
+}
+function tryTernary(expr, ctx) {
+  const cmpM = expr.match(CMP_RE);
+  if (cmpM) {
+    const [, path2, op, comparand, trueRaw2, falseRaw2] = cmpM;
+    const left = resolvePath(path2.trim(), ctx);
+    const right = parseComparand(comparand.trim());
+    return applyOperator(left, op, right) ? resolveBranch(trueRaw2, ctx) : resolveBranch(falseRaw2, ctx);
+  }
+  const m = expr.match(TRUTHY_RE);
+  if (!m) return null;
+  const [, negate, path, trueRaw, falseRaw] = m;
+  const resolved = resolvePath(path.trim(), ctx);
+  let truthy = resolved !== void 0 && resolved !== null && resolved !== "" && resolved !== false && resolved !== 0;
+  if (negate === "!") truthy = !truthy;
+  return truthy ? resolveBranch(trueRaw, ctx) : resolveBranch(falseRaw, ctx);
+}
+function applyPipe(pipe, val) {
+  switch (pipe) {
+    case "json":
+      return JSON.stringify(val, null, 2);
+    case "upper":
+      return String(val ?? "").toUpperCase();
+    case "lower":
+      return String(val ?? "").toLowerCase();
+    case "trim":
+      return String(val ?? "").trim();
+    default:
+      return valueToString(val);
+  }
+}
+function evaluate(expr, ctx, opts) {
+  const trimmed = expr.trim();
+  if (trimmed.startsWith("!!")) {
+    const val = resolvePath(trimmed.slice(2).trim(), ctx);
+    return String(!!val);
+  }
+  if (trimmed.startsWith("!") && !trimmed.includes("?") && !trimmed.includes("=")) {
+    const val = resolvePath(trimmed.slice(1).trim(), ctx);
+    return String(!val);
+  }
+  const pipeM = trimmed.match(PIPE_RE);
+  if (pipeM) {
+    const [, path, pipe] = pipeM;
+    const val = resolvePath(path.trim(), ctx);
+    return applyPipe(pipe, val);
+  }
+  const ncResult = tryNullCoalesce(trimmed, ctx);
+  if (ncResult !== null) return ncResult;
+  const ternaryResult = tryTernary(trimmed, ctx);
+  if (ternaryResult !== null) return ternaryResult;
+  const resolved = resolvePath(trimmed, ctx);
+  if (resolved !== void 0) return valueToString(resolved);
+  if (opts?.allowJs) {
+    const jsResult = evalJsExpression(trimmed, ctx, opts);
+    if (jsResult !== void 0) return valueToString(jsResult);
+  }
+  return "";
+}
+
+// src/json-mode.ts
+function resolveJsonValue(value, ctx, opts) {
+  if (typeof value === "string") {
+    const singleExpr = value.match(/^\{\{((?:(?!\}\}).)*)\}\}$/);
+    if (singleExpr) {
+      const expr = singleExpr[1].trim();
+      const ncResult = tryNullCoalesce(expr, ctx);
+      if (ncResult !== null) return ncResult;
+      const ternaryResult = tryTernary(expr, ctx);
+      if (ternaryResult !== null) {
+        if (ternaryResult !== "" && !isNaN(Number(ternaryResult))) return Number(ternaryResult);
+        return ternaryResult;
+      }
+      if (expr.startsWith("!!")) {
+        const val = resolvePath(expr.slice(2).trim(), ctx);
+        return !!val;
+      }
+      if (expr.startsWith("!") && !expr.includes("?") && !expr.includes("=")) {
+        const val = resolvePath(expr.slice(1).trim(), ctx);
+        return !val;
+      }
+      if (/\|\s*(json|upper|lower|trim)$/.test(expr)) {
+        return evaluate(expr, ctx, opts);
+      }
+      const resolved = resolvePath(expr, ctx);
+      if (resolved !== void 0) return resolved;
+      if (opts?.allowJs) {
+        const jsResult = evalJsExpression(expr, ctx, opts);
+        if (jsResult !== void 0) return jsResult;
+      }
+      return "";
+    }
+    return value.replace(
+      /\{\{(.*?)\}\}/g,
+      (_, expr) => evaluate(expr, ctx, opts)
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveJsonValue(item, ctx, opts));
+  }
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = resolveJsonValue(v, ctx, opts);
+    }
+    return result;
+  }
+  return value;
+}
+function resolveJsonTemplate(template, ctx, opts) {
+  const jsonReady = template.replace(/\{\{([\s\S]*?)\}\}/g, (_, inner) => {
+    const escaped = inner.replace(/(?<!\\)"/g, '\\"');
+    return `{{${escaped}}}`;
+  });
+  try {
+    const parsed = JSON.parse(jsonReady);
+    const resolved = resolveJsonValue(parsed, ctx, opts);
+    return {
+      output: JSON.stringify(resolved),
+      rawValue: resolved
+    };
+  } catch {
+    const output = template.replace(/\{\{([\s\S]*?)\}\}/g, (_, expr) => {
+      const val = evaluate(expr, ctx, opts);
+      return val.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+    });
+    return { output };
+  }
+}
+
+// src/html-mode.ts
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}
+function resolveHtmlTemplate(template, ctx, opts) {
+  const output = template.replace(/\{\{([\s\S]*?)\}\}/g, (_, expr) => {
+    const val = evaluate(expr, ctx, opts);
+    return escapeHtml(val);
+  });
+  return { output };
+}
+
+// src/code-mode.ts
+import * as vm2 from "vm";
+function executeCodeTemplate(code, ctx, opts) {
+  const logs = [];
+  const timeout = opts.timeout ?? 5e3;
+  let sandboxPayload = ctx.payload;
+  if (opts.batchMode) {
+    const meta = ctx.payload?._meta;
+    if (meta?.iterable && meta.iterateField) {
+      try {
+        sandboxPayload = structuredClone(
+          ctx.payload[meta.iterateField] ?? []
+        );
+      } catch {
+        sandboxPayload = JSON.parse(
+          JSON.stringify(ctx.payload[meta.iterateField] ?? [])
+        );
+      }
+    } else {
+      try {
+        sandboxPayload = structuredClone(ctx.payload);
+      } catch {
+        sandboxPayload = JSON.parse(JSON.stringify(ctx.payload));
+      }
+    }
+  } else {
+    try {
+      sandboxPayload = structuredClone(ctx.payload);
+    } catch {
+      sandboxPayload = JSON.parse(JSON.stringify(ctx.payload));
+    }
+  }
+  const context = buildSandbox(
+    { ...ctx, payload: sandboxPayload },
+    { ...opts, mode: "code" },
+    logs
+  );
+  try {
+    const script = new vm2.Script(`(function() {
+${code}
+})()`, {
+      filename: "code-node.js"
+    });
+    const result = script.runInContext(context, { timeout });
+    if (result == null) {
+      return { output: null, statusCode: 200, logs };
+    }
+    return { output: result, statusCode: 200, logs };
+  } catch (err) {
+    let message;
+    if (err instanceof Error) {
+      message = err.message;
+    } else if (typeof err === "string") {
+      message = err;
+    } else {
+      message = String(err);
+    }
+    return { output: null, statusCode: 500, logs, error: message };
+  }
+}
+
+// src/render.ts
+function resolveTextTemplate(template, ctx, opts) {
+  const output = template.replace(
+    /\{\{([\s\S]*?)\}\}/g,
+    (_, expr) => evaluate(expr, ctx, opts)
+  );
+  return { output };
+}
+function detectMode(template) {
+  return /^\s*[\[{]/.test(template) ? "json" : "text";
+}
+function renderTemplate(template, ctx, opts) {
+  const mode = opts?.mode ?? "auto";
+  switch (mode) {
+    case "code":
+      return executeCodeTemplate(template, ctx, opts ?? {});
+    case "json":
+      return resolveJsonTemplate(template, ctx, opts);
+    case "html":
+      return resolveHtmlTemplate(template, ctx, opts);
+    case "text":
+      return resolveTextTemplate(template, ctx, opts);
+    case "auto": {
+      const detected = detectMode(template);
+      if (detected === "json") {
+        return resolveJsonTemplate(template, ctx, opts);
+      }
+      return resolveTextTemplate(template, ctx, opts);
+    }
+    default:
+      return resolveTextTemplate(template, ctx, opts);
+  }
+}
+export {
+  applyPipe,
+  evaluate,
+  renderTemplate,
+  resolvePath,
+  tryNullCoalesce,
+  tryTernary,
+  valueToString
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@hostwebhook/template-engine",
+  "version": "1.0.0",
+  "description": "Template interpolation and sandboxed JS execution engine for HostWebhook",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "hostwebhook",
+    "template",
+    "interpolation",
+    "sandbox"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^3.0.0"
+  }
+}