@manablox/workflows 0.2.0 → 0.4.0

package/dist/index.js

@@ -0,0 +1,1255 @@
+import { ManabloxError, WORKFLOW_CONDITION_OPERATORS, WORKFLOW_CONDITION_OPERATOR_LABELS, WORKFLOW_EVENTS, WORKFLOW_EVENT_LABELS, WORKFLOW_STEP_LABELS, WORKFLOW_STEP_TYPES, diffRecords, isEmailAddress, runAsActor, snapshotChanges } from "@manablox/core";
+import { createHmac, randomUUID } from "node:crypto";
+import nodemailer from "nodemailer";
+import webpush from "web-push";
+import { requireInSpace } from "@manablox/services";
+//#region src/template.ts
+/**
+* The placeholder syntax templates use: `{{ content.title }}`, `{{ content.fields.body }}`,
+* `{{ actor.email }}`. A path resolves into the run context; an object or array comes out
+* as JSON, anything missing as an empty string. Deliberately no logic — a workflow that
+* needs a branch has a condition step for it.
+*/
+const PLACEHOLDER = /\{\{\s*([a-zA-Z0-9_.[\]-]+)\s*\}\}/g;
+function resolvePath(root, path) {
+	let current = root;
+	for (const segment of path.replace(/\[(\d+)\]/g, ".$1").split(".")) {
+		if (segment === "") continue;
+		if (current === null || current === void 0) return void 0;
+		if (typeof current !== "object") return void 0;
+		current = current[segment];
+	}
+	return current;
+}
+function stringify(value) {
+	if (value === null || value === void 0) return "";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (value instanceof Date) return value.toISOString();
+	return JSON.stringify(value);
+}
+function render(template, context) {
+	return template.replace(PLACEHOLDER, (_match, path) => stringify(resolvePath(context, path)));
+}
+/**
+* Renders inside a JSON document: a placeholder that stands alone in a string is
+* replaced by the value itself (`"count": "{{ documents.length }}"` becomes a number,
+* `"doc": "{{ content }}"` an object); one embedded in text renders as text.
+*/
+function renderJson(template, context) {
+	const parsed = JSON.parse(template);
+	const walk = (value) => {
+		if (typeof value === "string") {
+			const alone = /^\{\{\s*([a-zA-Z0-9_.[\]-]+)\s*\}\}$/.exec(value);
+			if (alone) {
+				const resolved = resolvePath(context, alone[1]);
+				return resolved === void 0 ? null : resolved;
+			}
+			return render(value, context);
+		}
+		if (Array.isArray(value)) return value.map(walk);
+		if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, walk(entry)]));
+		return value;
+	};
+	return JSON.stringify(walk(parsed));
+}
+/** Every placeholder a template names, for the editor's hints and for validation. */
+function placeholders(template) {
+	return [...template.matchAll(PLACEHOLDER)].map((match) => match[1]);
+}
+//#endregion
+//#region src/conditions.ts
+const isEmpty = (value) => value === null || value === void 0 || value === "" || Array.isArray(value) && value.length === 0 || typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0;
+const asNumber = (value) => {
+	if (typeof value === "number") return value;
+	if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) return Number(value);
+	return null;
+};
+/** Loose equality across the types a field can hold: `"true"` matches `true`, `"3"` matches `3`. */
+const same = (actual, expected) => {
+	if (typeof actual === "string") return actual === expected;
+	if (typeof actual === "number" || typeof actual === "boolean") return String(actual) === expected;
+	if (actual === null || actual === void 0) return expected === "" || expected === "null";
+	return stringify(actual) === expected;
+};
+/** `changed` compares the path under `content` with the same path under `previous`. */
+function previousValue(context, field) {
+	if (!field.startsWith("content")) return void 0;
+	const rest = field.slice(7);
+	return resolvePath(context.previous, rest.replace(/^\./, ""));
+}
+function evaluateRule(rule, context) {
+	const actual = resolvePath(context, rule.field);
+	const expected = render(rule.value ?? "", context);
+	switch (rule.operator) {
+		case "equals": return same(actual, expected);
+		case "notEquals": return !same(actual, expected);
+		case "contains": return Array.isArray(actual) ? actual.some((entry) => same(entry, expected)) : stringify(actual).toLowerCase().includes(expected.toLowerCase());
+		case "notContains": return Array.isArray(actual) ? !actual.some((entry) => same(entry, expected)) : !stringify(actual).toLowerCase().includes(expected.toLowerCase());
+		case "startsWith": return stringify(actual).toLowerCase().startsWith(expected.toLowerCase());
+		case "isEmpty": return isEmpty(actual);
+		case "isNotEmpty": return !isEmpty(actual);
+		case "greaterThan": {
+			const a = asNumber(actual);
+			const b = asNumber(expected);
+			return a !== null && b !== null ? a > b : stringify(actual) > expected;
+		}
+		case "lessThan": {
+			const a = asNumber(actual);
+			const b = asNumber(expected);
+			return a !== null && b !== null ? a < b : stringify(actual) < expected;
+		}
+		case "changed":
+			if (!context.previous) return true;
+			return stringify(actual) !== stringify(previousValue(context, rule.field));
+	}
+}
+/** Whether the run may continue past this step. */
+function evaluateCondition(step, context) {
+	if (step.rules.length === 0) return true;
+	const results = step.rules.map((rule) => evaluateRule(rule, context));
+	return step.match === "any" ? results.some(Boolean) : results.every(Boolean);
+}
+//#endregion
+//#region src/cron.ts
+const MONTHS = [
+	"jan",
+	"feb",
+	"mar",
+	"apr",
+	"may",
+	"jun",
+	"jul",
+	"aug",
+	"sep",
+	"oct",
+	"nov",
+	"dec"
+];
+const DAYS = [
+	"sun",
+	"mon",
+	"tue",
+	"wed",
+	"thu",
+	"fri",
+	"sat"
+];
+const FIELDS = [
+	{
+		min: 0,
+		max: 59
+	},
+	{
+		min: 0,
+		max: 23
+	},
+	{
+		min: 1,
+		max: 31
+	},
+	{
+		min: 1,
+		max: 12,
+		names: MONTHS
+	},
+	{
+		min: 0,
+		max: 6,
+		names: DAYS,
+		alias: { 7: 0 }
+	}
+];
+function parseValue(raw, field) {
+	const lower = raw.toLowerCase();
+	if (field.names) {
+		const index = field.names.indexOf(lower);
+		if (index !== -1) return field.min + index;
+	}
+	if (!/^\d+$/.test(raw)) return null;
+	let value = Number(raw);
+	if (field.alias && value in field.alias) value = field.alias[value];
+	if (value < field.min || value > field.max) return null;
+	return value;
+}
+/** One comma-separated part: `*`, `n`, `a-b`, `*​/s`, `a-b/s`, `a/s`. */
+function parsePart(part, field, into) {
+	const [rangePart, stepPart] = part.split("/");
+	if (rangePart === void 0 || stepPart === "") return false;
+	let step = 1;
+	if (stepPart !== void 0) {
+		if (!/^\d+$/.test(stepPart)) return false;
+		step = Number(stepPart);
+		if (step < 1) return false;
+	}
+	let from;
+	let to;
+	if (rangePart === "*") {
+		from = field.min;
+		to = field.max;
+	} else if (rangePart.includes("-")) {
+		const [a, b] = rangePart.split("-");
+		const start = a === void 0 ? null : parseValue(a, field);
+		const end = b === void 0 ? null : parseValue(b, field);
+		if (start === null || end === null || end < start) return false;
+		from = start;
+		to = end;
+	} else {
+		const value = parseValue(rangePart, field);
+		if (value === null) return false;
+		from = value;
+		to = stepPart !== void 0 ? field.max : value;
+	}
+	for (let value = from; value <= to; value += step) into.add(value);
+	return true;
+}
+function parseCron(expression) {
+	const fields = expression.trim().split(/\s+/);
+	if (fields.length !== 5) return null;
+	const sets = [];
+	for (const [index, raw] of fields.entries()) {
+		const field = FIELDS[index];
+		const set = /* @__PURE__ */ new Set();
+		for (const part of raw.split(",")) if (!part || !parsePart(part, field, set)) return null;
+		sets.push(set);
+	}
+	const [minute, hour, dayOfMonth, month, dayOfWeek] = sets;
+	return {
+		minute,
+		hour,
+		dayOfMonth,
+		month,
+		dayOfWeek,
+		anyDayOfMonth: fields[2] === "*",
+		anyDayOfWeek: fields[4] === "*"
+	};
+}
+function isValidCron(expression) {
+	return parseCron(expression) !== null;
+}
+function isValidTimezone(timezone) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: timezone });
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** The wall-clock reading of an instant in a timezone. */
+function wallClock(date, timezone) {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone: timezone,
+		hourCycle: "h23",
+		minute: "numeric",
+		hour: "numeric",
+		day: "numeric",
+		month: "numeric",
+		weekday: "short"
+	}).formatToParts(date);
+	const read = (type) => parts.find((part) => part.type === type)?.value ?? "";
+	return {
+		minute: Number(read("minute")),
+		hour: Number(read("hour")) % 24,
+		dayOfMonth: Number(read("day")),
+		month: Number(read("month")),
+		dayOfWeek: DAYS.indexOf(read("weekday").toLowerCase().slice(0, 3))
+	};
+}
+/**
+* Whether the minute containing `date` matches. As in Vixie cron, when both day fields
+* are restricted a match on either is enough.
+*/
+function cronMatches(spec, date, timezone) {
+	const clock = wallClock(date, timezone);
+	if (!spec.minute.has(clock.minute)) return false;
+	if (!spec.hour.has(clock.hour)) return false;
+	if (!spec.month.has(clock.month)) return false;
+	const domMatch = spec.dayOfMonth.has(clock.dayOfMonth);
+	const dowMatch = spec.dayOfWeek.has(clock.dayOfWeek);
+	if (spec.anyDayOfMonth && spec.anyDayOfWeek) return true;
+	if (spec.anyDayOfMonth) return dowMatch;
+	if (spec.anyDayOfWeek) return domMatch;
+	return domMatch || dowMatch;
+}
+/** The start of the minute an instant falls in — the unit the scheduler claims. */
+function floorToMinute(date) {
+	return /* @__PURE__ */ new Date(Math.floor(date.getTime() / 6e4) * 6e4);
+}
+//#endregion
+//#region src/steps.ts
+/** Runs one step against a context. Throws when the step fails; the runner logs it. */
+async function executeStep(step, context, env) {
+	switch (step.type) {
+		case "email": return sendEmail(step, context, env);
+		case "http": return callHttp(step, context, env);
+		case "push": return sendPush(step, context, env);
+		case "condition": return evaluateCondition(step, context) ? {
+			kind: "ok",
+			message: "Conditions met",
+			detail: null
+		} : {
+			kind: "stop",
+			message: "Conditions not met"
+		};
+		case "delay": return {
+			kind: "wait",
+			minutes: step.minutes
+		};
+		case "branch": return evaluateCondition(step, context) ? {
+			kind: "ok",
+			message: "Rules hold",
+			detail: { branch: "then" }
+		} : {
+			kind: "ok",
+			message: "Rules do not hold",
+			detail: { branch: "else" }
+		};
+	}
+}
+async function sendEmail(step, context, env) {
+	if (!env.mailer) throw new ManabloxError("workflow.mail.notConfigured");
+	const recipients = /* @__PURE__ */ new Set();
+	for (const template of step.to) for (const address of render(template, context).split(/[,\s;]+/)) if (address && isEmailAddress(address)) recipients.add(address.toLowerCase());
+	if (step.toRoles.length) {
+		const members = await env.repos.users.membersOf(context.space.id);
+		for (const member of members) if (step.toRoles.includes(member.role) && member.user.email) recipients.add(member.user.email.toLowerCase());
+	}
+	if (recipients.size === 0) throw new Error("No recipient address resolved");
+	const subject = render(step.subject, context);
+	const body = render(step.body, context);
+	const to = [...recipients];
+	const sent = await env.mailer.send({
+		to,
+		subject,
+		text: step.html ? stripTags(body) : body,
+		...step.html ? { html: body } : {}
+	});
+	return {
+		kind: "ok",
+		message: `Sent to ${to.join(", ")}`,
+		detail: {
+			to,
+			subject,
+			messageId: sent.id
+		}
+	};
+}
+function stripTags(html) {
+	return html.replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<br\s*\/?>/gi, "\n").replace(/<\/p>/gi, "\n\n").replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").trim();
+}
+async function callHttp(step, context, env) {
+	const url = render(step.url, context);
+	const headers = new Headers();
+	for (const header of step.headers) headers.set(header.name, render(header.value, context));
+	let body;
+	if (step.method !== "GET" && step.body.mode !== "none") {
+		if (step.body.mode === "event") {
+			body = JSON.stringify(context);
+			if (!headers.has("content-type")) headers.set("content-type", "application/json");
+		} else {
+			const template = step.body.template;
+			body = looksLikeJson(template) ? renderJson(template, context) : render(template, context);
+			if (!headers.has("content-type")) headers.set("content-type", looksLikeJson(template) ? "application/json" : "text/plain");
+		}
+	}
+	headers.set("x-manablox-event", context.event);
+	headers.set("x-manablox-workflow", context.workflow.id);
+	if (step.secret && body !== void 0) headers.set("x-manablox-signature", `sha256=${createHmac("sha256", step.secret).update(body).digest("hex")}`);
+	const started = Date.now();
+	let response;
+	try {
+		response = await env.fetch(url, {
+			method: step.method,
+			headers,
+			...body !== void 0 ? { body } : {},
+			signal: AbortSignal.timeout(step.timeoutMs)
+		});
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`${step.method} ${url} failed: ${reason}`);
+	}
+	const snippet = (await response.text().catch(() => "")).slice(0, 500);
+	const detail = {
+		url,
+		method: step.method,
+		status: response.status,
+		ms: Date.now() - started,
+		response: snippet
+	};
+	if (!response.ok) {
+		const error = /* @__PURE__ */ new Error(`${step.method} ${url} answered HTTP ${response.status}`);
+		error.detail = detail;
+		throw error;
+	}
+	return {
+		kind: "ok",
+		message: `HTTP ${response.status}`,
+		detail
+	};
+}
+function looksLikeJson(template) {
+	const trimmed = template.trim();
+	if (!(trimmed.startsWith("{") && trimmed.endsWith("}")) && !(trimmed.startsWith("[") && trimmed.endsWith("]"))) return false;
+	try {
+		JSON.parse(trimmed);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function sendPush(step, context, env) {
+	if (!env.pusher) throw new ManabloxError("workflow.push.notConfigured");
+	const userIds = new Set(step.userIds);
+	if (step.roles.length || userIds.size === 0) {
+		const members = await env.repos.users.membersOf(context.space.id);
+		for (const member of members) if (step.roles.length === 0 || step.roles.includes(member.role)) userIds.add(member.userId);
+	}
+	const subscriptions = await env.repos.workflows.subscriptionsFor([...userIds]);
+	if (subscriptions.length === 0) return {
+		kind: "ok",
+		message: "Nobody among the recipients has enabled notifications",
+		detail: {
+			recipients: userIds.size,
+			devices: 0
+		}
+	};
+	const renderedUrl = render(step.url, context).trim();
+	const url = renderedUrl ? /^https?:\/\//i.test(renderedUrl) ? renderedUrl : `${env.adminUrl.replace(/\/$/, "")}/${renderedUrl.replace(/^\//, "")}` : context.url;
+	const payload = {
+		title: render(step.title, context),
+		body: render(step.body, context),
+		url
+	};
+	let sent = 0;
+	let gone = 0;
+	const failures = [];
+	for (const subscription of subscriptions) try {
+		if (await env.pusher.send({
+			endpoint: subscription.endpoint,
+			keys: subscription.keys
+		}, payload) === "gone") {
+			gone++;
+			await env.repos.workflows.dropSubscription(subscription.id);
+		} else {
+			sent++;
+			await env.repos.workflows.markSubscriptionUsed(subscription.id);
+		}
+	} catch (error) {
+		failures.push(error instanceof Error ? error.message : String(error));
+	}
+	const detail = {
+		recipients: userIds.size,
+		devices: subscriptions.length,
+		sent,
+		gone,
+		failures
+	};
+	if (sent === 0 && failures.length) {
+		const error = /* @__PURE__ */ new Error(`Every push failed: ${failures[0]}`);
+		error.detail = detail;
+		throw error;
+	}
+	return {
+		kind: "ok",
+		message: `Sent to ${sent} device${sent === 1 ? "" : "s"}`,
+		detail
+	};
+}
+//#endregion
+//#region src/engine.ts
+/** The hook events a content change raises, and the trigger events each satisfies. */
+const EVENT_ALIASES = {
+	"content.created": ["content.created", "content.saved"],
+	"content.updated": ["content.updated", "content.saved"],
+	"content.saved": ["content.saved"],
+	"content.deleted": ["content.deleted"],
+	"content.published": ["content.published"],
+	"content.unpublished": ["content.unpublished"]
+};
+/**
+* Runs workflows: listens for content events, keeps the clock for scheduled ones, and
+* executes a run's steps one after another, pausing at a delay and picking it up again.
+*
+* A run is a row from the moment it is queued, so nothing is lost if the process goes
+* away mid-way: the next tick finds `waiting` runs whose time has come, and a worker
+* claims a run before touching it so two never execute the same one.
+*/
+var WorkflowEngine = class {
+	manablox;
+	repos;
+	env;
+	dispatch;
+	now;
+	tickMs;
+	pending = /* @__PURE__ */ new Set();
+	timer = null;
+	ticking = false;
+	constructor(manablox, repos, options = {}) {
+		this.manablox = manablox;
+		this.repos = repos;
+		this.env = {
+			repos,
+			mailer: options.mailer ?? null,
+			pusher: options.pusher ?? null,
+			fetch: options.fetch ?? globalThis.fetch,
+			adminUrl: options.adminUrl ?? manablox.config.server.adminUrl
+		};
+		this.dispatch = options.dispatch ?? ((runId) => this.background(this.run(runId)));
+		this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+		this.tickMs = options.tickMs ?? 2e4;
+	}
+	get adminUrl() {
+		return this.env.adminUrl;
+	}
+	/** Registers the content hooks. Call once, at boot. */
+	attach() {
+		const source = "@manablox/workflows";
+		const on = (event) => async (row, context) => {
+			await this.onContentEvent(event, row, context);
+		};
+		this.manablox.hooks.on("content:afterCreate", on("content.created"), { source });
+		this.manablox.hooks.on("content:afterUpdate", on("content.updated"), { source });
+		this.manablox.hooks.on("content:afterPublish", on("content.published"), { source });
+		this.manablox.hooks.on("content:afterDelete", async (payload, context) => {
+			await this.onContentEvent("content.deleted", payload.record, context);
+		}, { source });
+		this.manablox.hooks.on("content:afterUnpublish", async (payload, context) => {
+			const row = await this.repos.content.findById(payload.id);
+			if (row) await this.onContentEvent("content.unpublished", row, context);
+		}, { source });
+	}
+	/** Starts the clock for scheduled workflows and paused runs. */
+	start() {
+		if (this.timer) return;
+		this.timer = setInterval(() => void this.tick(), this.tickMs);
+		this.timer.unref?.();
+		this.manablox.onDispose(() => this.stop());
+	}
+	async stop() {
+		if (this.timer) clearInterval(this.timer);
+		this.timer = null;
+		await this.idle();
+	}
+	/** Resolves once every run started in this process has finished. For tests and shutdown. */
+	async idle() {
+		while (this.pending.size) await Promise.allSettled([...this.pending]);
+	}
+	async onContentEvent(event, row, context) {
+		const matching = (await this.repos.workflows.listEnabled(row.spaceId)).filter((workflow) => matchesEvent(workflow.trigger, event, row));
+		if (matching.length === 0) return;
+		const space = await this.spaceInfo(row.spaceId);
+		const actor = await this.actorInfo(context.actor?.userId ?? null);
+		const previous = context.previous ? serialise(context.previous) : null;
+		for (const workflow of matching) {
+			const runContext = {
+				event,
+				workflow: {
+					id: workflow.id,
+					name: workflow.name
+				},
+				space,
+				content: serialise(row),
+				previous: event === "content.updated" ? previous : null,
+				documents: [],
+				actor,
+				url: event === "content.deleted" ? null : this.documentUrl(row.id),
+				at: this.now().toISOString()
+			};
+			await this.enqueue(workflow, event, runContext);
+		}
+	}
+	/**
+	* One look at the clock: start every scheduled workflow whose cron names this minute,
+	* and resume every paused run whose time has come. Safe to call from several
+	* processes — each claim is an atomic update.
+	*/
+	async tick(now = this.now()) {
+		if (this.ticking) return;
+		this.ticking = true;
+		try {
+			const minute = floorToMinute(now);
+			const enabled = await this.repos.workflows.listEnabled();
+			for (const workflow of enabled) {
+				if (workflow.trigger.kind !== "schedule") continue;
+				const spec = parseCron(workflow.trigger.cron);
+				if (!spec || !cronMatches(spec, minute, workflow.trigger.timezone)) continue;
+				if (!await this.repos.workflows.claimSchedule(workflow.id, minute)) continue;
+				await this.startScheduled(workflow);
+			}
+			for (const run of await this.repos.workflows.dueRuns(now)) await this.dispatch(run.id);
+		} catch (error) {
+			this.manablox.logger.error({ err: error }, "workflow tick failed");
+		} finally {
+			this.ticking = false;
+		}
+	}
+	async startScheduled(workflow) {
+		if (workflow.trigger.kind !== "schedule") return;
+		const space = await this.spaceInfo(workflow.spaceId);
+		const selection = workflow.trigger.selection;
+		const documents = selection ? (await this.repos.workflows.selectDocuments(workflow.spaceId, selection)).map(serialise) : [];
+		const base = {
+			event: "schedule",
+			workflow: {
+				id: workflow.id,
+				name: workflow.name
+			},
+			space,
+			previous: null,
+			actor: null,
+			at: this.now().toISOString()
+		};
+		if (workflow.trigger.perDocument) {
+			for (const document of documents) await this.enqueue(workflow, "schedule", {
+				...base,
+				content: document,
+				documents: [],
+				url: this.documentUrl(String(document.id))
+			});
+			return;
+		}
+		await this.enqueue(workflow, "schedule", {
+			...base,
+			content: null,
+			documents,
+			url: null
+		});
+	}
+	/** A run started by hand from the editor, executed inline so the caller sees the log. */
+	async runManually(workflow, document) {
+		const space = await this.spaceInfo(workflow.spaceId);
+		const documents = workflow.trigger.kind === "schedule" && workflow.trigger.selection && !document ? (await this.repos.workflows.selectDocuments(workflow.spaceId, workflow.trigger.selection)).map(serialise) : [];
+		const run = await this.repos.workflows.createRun({
+			workflowId: workflow.id,
+			spaceId: workflow.spaceId,
+			trigger: "manual",
+			context: {
+				event: "manual",
+				workflow: {
+					id: workflow.id,
+					name: workflow.name
+				},
+				space,
+				content: document ? serialise(document) : null,
+				previous: null,
+				documents,
+				actor: null,
+				url: document ? this.documentUrl(document.id) : null,
+				at: this.now().toISOString()
+			}
+		});
+		await this.run(run.id);
+		return await this.repos.workflows.findRun(run.id) ?? run;
+	}
+	async enqueue(workflow, trigger, context) {
+		const run = await this.repos.workflows.createRun({
+			workflowId: workflow.id,
+			spaceId: workflow.spaceId,
+			trigger,
+			context
+		});
+		await this.dispatch(run.id);
+	}
+	background(work) {
+		const tracked = work.catch((error) => {
+			this.manablox.logger.error({ err: error }, "workflow run crashed");
+		}).finally(() => {
+			this.pending.delete(tracked);
+		});
+		this.pending.add(tracked);
+		return Promise.resolve();
+	}
+	/** Executes a queued or paused run from where it stands. The worker entry point. */
+	async run(runId) {
+		const run = await this.repos.workflows.claimRun(runId);
+		if (!run) return;
+		const workflow = await this.repos.workflows.findById(run.workflowId);
+		if (!workflow) {
+			await this.repos.workflows.saveRunProgress(run.id, {
+				status: "failed",
+				cursor: run.cursor,
+				log: run.log,
+				error: "The workflow no longer exists",
+				finished: true
+			});
+			return;
+		}
+		const actor = {
+			kind: "workflow",
+			id: workflow.id,
+			label: workflow.name,
+			detail: {
+				runId: run.id,
+				trigger: run.trigger
+			}
+		};
+		await runAsActor(actor, async () => {
+			const log = [...run.log];
+			const outcome = await this.runChain(run, workflow, workflow.steps, [], run.cursor, log);
+			if (outcome.kind === "done") await this.finish(run, workflow, "succeeded", [], log, null);
+			else if (outcome.kind === "stop") await this.finish(run, workflow, "skipped", outcome.cursor, log, null);
+			else if (outcome.kind === "fail") await this.finish(run, workflow, "failed", outcome.cursor, log, outcome.error);
+		});
+	}
+	/**
+	* Walks one chain — the top level, or a side of a fork — from `resume` when the run is
+	* being picked up inside it. A fork's chosen side is walked recursively; the position
+	* saved at a delay is the full path, so a resume finds its way back down.
+	*/
+	async runChain(run, workflow, steps, prefix, resume, log) {
+		let index = 0;
+		let inner = null;
+		if (resume?.length) {
+			index = resume[0];
+			const side = resume[1];
+			if (side === "then" || side === "else") inner = {
+				side,
+				cursor: resume.slice(2)
+			};
+		}
+		for (; index < steps.length; index++) {
+			const step = steps[index];
+			if (!step) break;
+			const here = [...prefix, index];
+			const startedAt = this.now();
+			const entry = (status, message, detail = null) => ({
+				stepId: step.id,
+				type: step.type,
+				name: step.name,
+				status,
+				message,
+				detail,
+				startedAt: startedAt.toISOString(),
+				ms: this.now().getTime() - startedAt.getTime()
+			});
+			if (inner) {
+				const { side, cursor } = inner;
+				inner = null;
+				if (step.type === "branch") {
+					const outcome = await this.runChain(run, workflow, step[side], [...here, side], cursor, log);
+					if (outcome.kind !== "done") return outcome;
+				}
+				continue;
+			}
+			if (!step.enabled) {
+				log.push(entry("skipped", "Step is switched off"));
+				continue;
+			}
+			if (step.type === "branch") {
+				const holds = evaluateCondition(step, run.context);
+				const side = holds ? "then" : "else";
+				log.push(entry("ok", holds ? "Rules hold — taking the yes side" : "Rules do not hold — taking the no side", { branch: side }));
+				const outcome = await this.runChain(run, workflow, step[side], [...here, side], null, log);
+				if (outcome.kind !== "done") return outcome;
+				continue;
+			}
+			try {
+				const outcome = await executeStep(step, run.context, this.env);
+				if (outcome.kind === "wait") {
+					const resumeAt = new Date(this.now().getTime() + outcome.minutes * 6e4);
+					log.push(entry("waiting", `Waiting until ${resumeAt.toISOString()}`, { resumeAt: resumeAt.toISOString() }));
+					await this.repos.workflows.saveRunProgress(run.id, {
+						status: "waiting",
+						cursor: [...prefix, index + 1],
+						log,
+						resumeAt
+					});
+					return { kind: "wait" };
+				}
+				if (outcome.kind === "stop") {
+					log.push(entry("stopped", outcome.message));
+					return {
+						kind: "stop",
+						cursor: here
+					};
+				}
+				log.push(entry("ok", outcome.message, outcome.detail));
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				const detail = error.detail ?? null;
+				log.push(entry("failed", message, detail));
+				this.manablox.logger.warn({
+					workflow: workflow.id,
+					run: run.id,
+					step: step.id,
+					err: error
+				}, "workflow step failed");
+				if (!step.continueOnError) return {
+					kind: "fail",
+					cursor: here,
+					error: message
+				};
+			}
+		}
+		return { kind: "done" };
+	}
+	async finish(run, workflow, status, cursor, log, error) {
+		await this.repos.workflows.saveRunProgress(run.id, {
+			status,
+			cursor,
+			log,
+			error,
+			finished: true
+		});
+		await this.repos.workflows.touchRun(workflow.id, this.now());
+		await this.manablox.hooks.run("workflow:afterRun", {
+			runId: run.id,
+			workflowId: workflow.id,
+			spaceId: workflow.spaceId,
+			status,
+			trigger: run.trigger
+		}, {
+			manablox: this.manablox,
+			spaceId: workflow.spaceId
+		});
+		await this.repos.audit.record({
+			spaceId: workflow.spaceId,
+			action: "workflowRun.finish",
+			targetKind: "workflowRun",
+			targetId: run.id,
+			targetLabel: workflow.name,
+			meta: {
+				workflowId: workflow.id,
+				status,
+				trigger: run.trigger,
+				error,
+				contentId: run.context.content?.id ?? null,
+				steps: log.map((entry) => ({
+					step: entry.name || entry.type,
+					status: entry.status
+				}))
+			}
+		});
+	}
+	async spaceInfo(spaceId) {
+		const space = await this.repos.spaces.findById(spaceId);
+		return space ? {
+			id: space.id,
+			name: space.name,
+			machineName: space.machineName,
+			url: space.url
+		} : {
+			id: spaceId,
+			name: "",
+			machineName: "",
+			url: ""
+		};
+	}
+	async actorInfo(userId) {
+		if (!userId) return null;
+		const user = await this.repos.users.findById(userId);
+		return user ? {
+			id: user.id,
+			name: user.name,
+			email: user.email
+		} : null;
+	}
+	documentUrl(contentId) {
+		return `${this.env.adminUrl.replace(/\/$/, "")}/content/${contentId}`;
+	}
+};
+/** Whether an event trigger wants this event for this document. */
+function matchesEvent(trigger, event, row) {
+	if (trigger.kind !== "event") return false;
+	const satisfied = EVENT_ALIASES[event];
+	if (!trigger.events.some((wanted) => satisfied.includes(wanted))) return false;
+	if (trigger.typeIds.length && !trigger.typeIds.includes(row.typeId)) return false;
+	if (trigger.locales.length && !trigger.locales.includes(row.locale)) return false;
+	return true;
+}
+/** A row as a template sees it: plain JSON, without the search machinery. */
+function serialise(row) {
+	const { search: _search, searchText: _searchText, ...rest } = row;
+	return JSON.parse(JSON.stringify(rest));
+}
+//#endregion
+//#region src/mail.ts
+/**
+* A mailer over the configured SMTP URL, or `null` when there is none — the step then
+* fails with `workflow.mail.notConfigured`, which the run log shows verbatim.
+*/
+function createMailer(config, logger) {
+	if (!config.smtpUrl) return null;
+	const transport = nodemailer.createTransport(config.smtpUrl);
+	const from = config.from ?? "Manablox <no-reply@localhost>";
+	return { async send(message) {
+		const info = await transport.sendMail({
+			from,
+			to: message.to,
+			subject: message.subject,
+			text: message.text,
+			...message.html ? { html: message.html } : {}
+		});
+		logger.debug({
+			to: message.to,
+			id: info.messageId
+		}, "workflow mail sent");
+		return { id: info.messageId ?? null };
+	} };
+}
+//#endregion
+//#region src/push.ts
+function isPushConfigured(config) {
+	return Boolean(config.vapidPublicKey && config.vapidPrivateKey);
+}
+/**
+* A Web Push sender over the configured VAPID keys, or `null` when there are none. The
+* keys are made once per installation with `pnpm --filter @manablox/api push:keys`.
+*/
+function createPusher(config, logger) {
+	if (!config.vapidPublicKey || !config.vapidPrivateKey) return null;
+	const subject = config.subject ?? "mailto:admin@localhost";
+	const publicKey = config.vapidPublicKey;
+	const privateKey = config.vapidPrivateKey;
+	return {
+		publicKey,
+		async send(target, payload) {
+			try {
+				await webpush.sendNotification(target, JSON.stringify(payload), {
+					vapidDetails: {
+						subject,
+						publicKey,
+						privateKey
+					},
+					TTL: 86400
+				});
+				return "sent";
+			} catch (error) {
+				const status = error.statusCode;
+				if (status === 404 || status === 410) {
+					logger.debug({ endpoint: target.endpoint }, "push subscription gone");
+					return "gone";
+				}
+				throw error;
+			}
+		}
+	};
+}
+/** A fresh VAPID key pair, for the CLI that prints them. */
+function generatePushKeys() {
+	return webpush.generateVAPIDKeys();
+}
+//#endregion
+//#region src/validate.ts
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const MAX_DELAY_MINUTES = 43200;
+/**
+* Checks everything the shape alone cannot: an event that exists, a cron that parses, a
+* step with somewhere to send to. Every problem is reported at once, each with the path
+* of the field it concerns, so the editor can mark them all in one round.
+*/
+function validateWorkflow(input, env) {
+	const problems = [];
+	const add = (key, path, params) => problems.push({
+		key,
+		path,
+		...params ? { params } : {}
+	});
+	const name = input.name.trim();
+	if (!name) add("workflow.name.required", ["name"]);
+	const trigger = validateTrigger(input.trigger, env, add);
+	const steps = validateSteps(input.steps, ["steps"], add);
+	if (steps.length === 0) add("workflow.steps.required", ["steps"]);
+	if (problems.length) throw ManabloxError.validation(problems, "workflow.validation.failed");
+	return {
+		name,
+		description: input.description?.trim() || null,
+		enabled: input.enabled ?? false,
+		trigger,
+		steps
+	};
+}
+function validateTrigger(trigger, env, add) {
+	if (trigger.kind === "schedule") {
+		if (!isValidCron(trigger.cron)) add("workflow.trigger.cronInvalid", ["trigger", "cron"]);
+		if (!isValidTimezone(trigger.timezone)) add("workflow.trigger.timezoneInvalid", ["trigger", "timezone"]);
+		for (const [index, typeId] of (trigger.selection?.typeIds ?? []).entries()) if (!env.typeExists(typeId)) add("workflow.trigger.typeNotFound", [
+			"trigger",
+			"selection",
+			"typeIds",
+			index
+		], { typeId });
+		return {
+			kind: "schedule",
+			cron: trigger.cron.trim(),
+			timezone: trigger.timezone,
+			selection: trigger.selection ? {
+				typeIds: trigger.selection.typeIds,
+				status: trigger.selection.status,
+				changedWithinHours: trigger.selection.changedWithinHours ?? null,
+				locale: trigger.selection.locale || null
+			} : null,
+			perDocument: Boolean(trigger.perDocument && trigger.selection)
+		};
+	}
+	const events = [...new Set(trigger.events)];
+	if (events.length === 0) add("workflow.trigger.eventsRequired", ["trigger", "events"]);
+	for (const [index, event] of events.entries()) if (!WORKFLOW_EVENTS.includes(event)) add("workflow.trigger.eventUnknown", [
+		"trigger",
+		"events",
+		index
+	], { event });
+	for (const [index, typeId] of trigger.typeIds.entries()) if (!env.typeExists(typeId)) add("workflow.trigger.typeNotFound", [
+		"trigger",
+		"typeIds",
+		index
+	], { typeId });
+	return {
+		kind: "event",
+		events,
+		typeIds: trigger.typeIds,
+		locales: trigger.locales ?? []
+	};
+}
+/** Checks every step of a chain, recursing into the two sides of a fork. */
+function validateSteps(steps, prefix, add) {
+	return steps.map((step, index) => validateStep(step, [...prefix, index], add));
+}
+function validateRules(step, at, add) {
+	if (step.rules.length === 0) add("workflow.step.condition.rulesRequired", at("rules"));
+	for (const [i, rule] of step.rules.entries()) {
+		if (!rule.field.trim()) add("workflow.step.condition.fieldRequired", at("rules", i, "field"));
+		if (!WORKFLOW_CONDITION_OPERATORS.includes(rule.operator)) add("workflow.step.typeUnknown", at("rules", i, "operator"), { type: rule.operator });
+	}
+	return {
+		match: step.match === "any" ? "any" : "all",
+		rules: step.rules.map((rule) => ({
+			field: rule.field.trim(),
+			operator: rule.operator,
+			value: rule.value ?? ""
+		}))
+	};
+}
+function validateStep(step, path, add) {
+	const at = (...rest) => [...path, ...rest];
+	const base = {
+		id: step.id || randomUUID(),
+		name: (step.name ?? "").trim(),
+		enabled: step.enabled ?? true,
+		continueOnError: step.continueOnError ?? false
+	};
+	if (!WORKFLOW_STEP_TYPES.includes(step.type)) {
+		add("workflow.step.typeUnknown", at("type"), { type: step.type });
+		return step;
+	}
+	switch (step.type) {
+		case "email": {
+			const to = step.to.map((address) => address.trim()).filter(Boolean);
+			const toRoles = step.toRoles.map((role) => role.trim()).filter(Boolean);
+			if (to.length === 0 && toRoles.length === 0) add("workflow.step.email.recipientRequired", at("to"));
+			for (const [i, address] of to.entries()) if (!address.includes("{{") && !isEmailAddress(address)) add("workflow.step.email.recipientInvalid", at("to", i), { address });
+			if (!step.subject.trim()) add("workflow.step.email.subjectRequired", at("subject"));
+			return {
+				...base,
+				type: "email",
+				to,
+				toRoles,
+				subject: step.subject.trim(),
+				body: step.body ?? "",
+				html: Boolean(step.html)
+			};
+		}
+		case "http": {
+			const url = step.url.trim();
+			if (!url.includes("{{") && !isHttpUrl(url)) add("workflow.step.http.urlInvalid", at("url"));
+			if (url.includes("{{") && !/^https?:\/\//i.test(url)) add("workflow.step.http.urlInvalid", at("url"));
+			const headers = step.headers.map((header) => ({
+				name: header.name.trim(),
+				value: header.value
+			})).filter((header) => header.name || header.value.trim());
+			for (const [i, header] of headers.entries()) if (!HEADER_NAME.test(header.name)) add("workflow.step.http.headerNameInvalid", at("headers", i, "name"), { name: header.name });
+			return {
+				...base,
+				type: "http",
+				method: step.method,
+				url,
+				headers,
+				body: {
+					mode: step.body?.mode ?? "event",
+					template: step.body?.template ?? ""
+				},
+				secret: step.secret?.trim() || null,
+				timeoutMs: clamp(step.timeoutMs ?? 1e4, 1e3, 12e4)
+			};
+		}
+		case "push":
+			if (!step.title.trim()) add("workflow.step.push.titleRequired", at("title"));
+			return {
+				...base,
+				type: "push",
+				roles: step.roles.map((role) => role.trim()).filter(Boolean),
+				userIds: step.userIds.filter(Boolean),
+				title: step.title.trim(),
+				body: step.body ?? "",
+				url: step.url?.trim() ?? ""
+			};
+		case "condition": return {
+			...base,
+			type: "condition",
+			...validateRules(step, at, add)
+		};
+		case "branch": return {
+			...base,
+			type: "branch",
+			...validateRules(step, at, add),
+			then: validateSteps(step.then ?? [], at("then"), add),
+			else: validateSteps(step.else ?? [], at("else"), add)
+		};
+		case "delay": {
+			const minutes = Number(step.minutes);
+			if (!Number.isFinite(minutes) || minutes < 1 || minutes > MAX_DELAY_MINUTES) add("workflow.step.delay.minutesInvalid", at("minutes"), { max: MAX_DELAY_MINUTES });
+			return {
+				...base,
+				type: "delay",
+				minutes: Math.round(minutes)
+			};
+		}
+	}
+}
+function isHttpUrl(value) {
+	try {
+		const url = new URL(value);
+		return url.protocol === "http:" || url.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+//#endregion
+//#region src/service.ts
+/** The scheduler's bookkeeping columns change on their own; the log records what people set. */
+const WORKFLOW_DIFF = { ignore: ["lastScheduledAt", "lastRunAt"] };
+/**
+* Workflows: the rules — a trigger that exists, steps with somewhere to go, a run that
+* belongs to the space it is asked for in — with the engine doing the running.
+*/
+var WorkflowService = class {
+	manablox;
+	repos;
+	engine;
+	constructor(manablox, repos, engine) {
+		this.manablox = manablox;
+		this.repos = repos;
+		this.engine = engine;
+	}
+	catalog() {
+		const mail = Boolean(this.manablox.config.mail.smtpUrl);
+		const push = Boolean(this.manablox.config.push.vapidPublicKey && this.manablox.config.push.vapidPrivateKey);
+		return {
+			events: WORKFLOW_EVENTS.map((id) => ({
+				id,
+				...WORKFLOW_EVENT_LABELS[id]
+			})),
+			stepTypes: WORKFLOW_STEP_TYPES.map((id) => ({
+				id,
+				...WORKFLOW_STEP_LABELS[id],
+				available: id === "email" ? mail : id === "push" ? push : true
+			})),
+			operators: WORKFLOW_CONDITION_OPERATORS.map((id) => ({
+				id,
+				label: WORKFLOW_CONDITION_OPERATOR_LABELS[id]
+			})),
+			mail,
+			push,
+			pushPublicKey: push ? this.manablox.config.push.vapidPublicKey ?? null : null,
+			adminUrl: this.engine.adminUrl
+		};
+	}
+	list(spaceId) {
+		return this.repos.workflows.listBySpace(spaceId);
+	}
+	get(spaceId, id) {
+		return this.find(spaceId, id);
+	}
+	async create(spaceId, input) {
+		const valid = validateWorkflow(input, this.validationEnvironment());
+		const row = await this.repos.workflows.create({
+			spaceId,
+			...valid
+		});
+		await this.audit("workflow.create", row, snapshotChanges(row, "created", WORKFLOW_DIFF));
+		return row;
+	}
+	async update(spaceId, id, input) {
+		const before = await this.find(spaceId, id);
+		const valid = validateWorkflow(input, this.validationEnvironment());
+		const row = await this.repos.workflows.update(id, valid);
+		await this.audit("workflow.update", row, diffRecords(before, row, WORKFLOW_DIFF));
+		return row;
+	}
+	/** The on/off switch, kept apart from a full save so the list can flip it. */
+	async setEnabled(spaceId, id, enabled) {
+		const before = await this.find(spaceId, id);
+		const row = await this.repos.workflows.update(id, { enabled });
+		await this.audit("workflow.setEnabled", row, [{
+			path: "enabled",
+			from: before.enabled,
+			to: row.enabled
+		}]);
+		return row;
+	}
+	async delete(spaceId, id) {
+		const row = await this.find(spaceId, id);
+		await this.repos.workflows.delete(id);
+		await this.audit("workflow.delete", row, snapshotChanges(row, "deleted", WORKFLOW_DIFF));
+	}
+	async runs(spaceId, id, limit = 50) {
+		await this.find(spaceId, id);
+		return this.repos.workflows.listRuns(id, limit);
+	}
+	async run(spaceId, id) {
+		return requireInSpace(await this.repos.workflows.findRun(id), spaceId, "workflow.run.notFound", { id });
+	}
+	/**
+	* Runs a workflow now, against a document of the space when one is named. An
+	* event-triggered workflow needs one — its steps read `content` — while a scheduled
+	* workflow may run against its own selection.
+	*/
+	async runNow(spaceId, id, contentId) {
+		const workflow = await this.find(spaceId, id);
+		let document = null;
+		if (contentId) document = requireInSpace(await this.repos.content.findById(contentId), spaceId, "content.notFound", { id: contentId });
+		else if (workflow.trigger.kind === "event") throw ManabloxError.badRequest("workflow.run.documentRequired");
+		const run = await this.engine.runManually(workflow, document);
+		await this.audit("workflow.runNow", workflow, [], {
+			runId: run.id,
+			status: run.status,
+			contentId: document?.id ?? null
+		});
+		return run;
+	}
+	subscriptions(userId) {
+		return this.repos.workflows.subscriptionsOf(userId);
+	}
+	async subscribe(userId, subscription, userAgent) {
+		if (!this.catalog().push) throw ManabloxError.badRequest("workflow.push.notConfigured");
+		if (!/^https:\/\//.test(subscription.endpoint)) throw ManabloxError.badRequest("workflow.push.subscriptionInvalid");
+		return this.repos.workflows.subscribe({
+			userId,
+			...subscription,
+			userAgent
+		});
+	}
+	unsubscribe(userId, endpoint) {
+		return this.repos.workflows.unsubscribe(userId, endpoint);
+	}
+	audit(action, workflow, changes, meta = null) {
+		return this.repos.audit.record({
+			spaceId: workflow.spaceId,
+			action,
+			targetKind: "workflow",
+			targetId: workflow.id,
+			targetLabel: workflow.name,
+			changes,
+			meta
+		});
+	}
+	async find(spaceId, id) {
+		return requireInSpace(await this.repos.workflows.findById(id), spaceId, "workflow.notFound", { id });
+	}
+	validationEnvironment() {
+		return { typeExists: (typeId) => this.manablox.contentTypes.tryGet(typeId) !== void 0 };
+	}
+};
+//#endregion
+export { WorkflowEngine, WorkflowService, createMailer, createPusher, cronMatches, evaluateCondition, evaluateRule, executeStep, floorToMinute, generatePushKeys, isPushConfigured, isValidCron, isValidTimezone, matchesEvent, parseCron, placeholders, render, renderJson, resolvePath, serialise, stringify, validateWorkflow, wallClock };