@plitzi/sdk-server 0.35.4 → 0.35.6

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @plitzi/sdk-server
 
+## 0.35.6
+
+### Patch Changes
+
+- A failed server action can give back what it already did.
+
+  - **`flow.onFailure` ("On Failure") marks where the undo begins.** A run that reaches it has succeeded and ends there.
+    A run whose step failed jumps to it and runs the steps after it, in order, each still asking its own `when` — the
+    failure may have come before the thing to undo was ever done — with `{{ failure.step }}` and `{{ failure.message }}`
+    in scope. The run still ends failed, with the failure it had; an undo step that fails too is added to it.
+  - **The undo runs on its own clock and budget:** 5 seconds (or the run's own timeout if shorter) and its own outbound
+    request budget, because the run's may be exactly what ran out, and a caller closing the connection does not stop it.
+    A run that hit its deadline is undone too.
+  - **`defineAction` writes it from `onFailure: [...]`**, after the answer. `validateActionDocument` refuses an output
+    step or a second handler after one, warns about a handler with nothing to undo or nothing that undoes, and reserves
+    `failure` as a step id. `FAILURE_HANDLER_TASK` is exported from `@plitzi/sdk-shared/actions`.
+
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.35.6
+  - @plitzi/sdk-shared@0.35.6
+
+## 0.35.5
+
+### Patch Changes
+
+- v0.35.5
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.35.5
+  - @plitzi/sdk-shared@0.35.5
+
 ## 0.35.4
 
 ### Patch Changes

package/dist/actions.d.ts

@@ -56,7 +56,7 @@ export { createKvStore } from './modules/actions/runtime/kvStore';
  */
 export { createRunLogger, createRejectLogger } from './modules/actions/runtime/runLogger';
 export type { TaskRegistryOptions } from './modules/actions/tasks/registry';
-export type { ActionCredential, ActionDbDriver, ActionEmailAdapter, ActionEmailMessage, ActionKvAdapter, ActionKvStore, ActionLookups, ActionRejectRecord, ActionRunRecord, ActionRunRequest, ActionRunResult, ActionsConfig, ActionTask, ActionTaskContext, ActionTaskRegistry, RegisteredTask, ResolvedConnector } from './modules/actions/types';
+export type { ActionCredential, ActionDbDriver, ActionEmailConfig, ActionEmailDelivery, ActionEmailMessage, ActionEmailTransport, ActionKvAdapter, ActionKvStore, ActionLookups, ActionRejectRecord, ActionRunRecord, ActionRunRequest, ActionRunResult, ActionsConfig, ActionTask, ActionTaskContext, ActionTaskRegistry, RegisteredTask, ResolvedConnector } from './modules/actions/types';
 export type { ActionsModule } from './modules/actions';
 export type { ActiveRun, RunGuards } from './modules/actions/runtime/guards';
 export type { ScheduleResult, ScheduleRunner, ScheduleTick } from './modules/actions/runtime/schedule';

package/dist/core/oauth/metadata.js

@@ -1,4 +1,4 @@
-import { requestOrigin } from "@plitzi/sdk-server/kernel";
+import { requestOrigin } from "../requestParser.js";
 //#region src/core/oauth/metadata.ts
 var AUTHORIZE_PATH = "/authorize";
 var TOKEN_PATH = "/token";

package/dist/modules/actions/index.d.ts

@@ -38,4 +38,4 @@ export type { ActiveRun, RunGuards } from './runtime/guards';
 export type { ScheduleResult, ScheduleRunner, ScheduleTick } from './runtime/schedule';
 export type { ActionTaskDescriptor } from './taskCatalog';
 export type { TaskRegistryOptions } from './tasks/registry';
-export type { ActionCredential, ActionDbDriver, ActionEmailAdapter, ActionEmailMessage, ActionKvStore, ActionLookups, ActionRejectRecord, ActionRunRecord, ActionRunRequest, ActionRunResult, ActionsConfig, ActionTask, ActionTaskContext, ActionTaskRegistry, RegisteredTask, ResolvedConnector } from './types';
+export type { ActionCredential, ActionDbDriver, ActionEmailConfig, ActionEmailDelivery, ActionEmailMessage, ActionEmailTransport, ActionKvStore, ActionLookups, ActionRejectRecord, ActionRunRecord, ActionRunRequest, ActionRunResult, ActionsConfig, ActionTask, ActionTaskContext, ActionTaskRegistry, RegisteredTask, ResolvedConnector } from './types';

package/dist/modules/actions/index.js

@@ -25,10 +25,7 @@ import { handleActionCancel } from "./transport/cancelHandler.js";
 * the same as having no single-flight at all. Nothing outside this folder needs to know how a run is assembled.
 */
 var createActionsModule = (config) => {
-	const registry = createTaskRegistry(config.tasks, {
-		db: (config.dbDrivers?.length ?? 0) > 0,
-		email: config.email !== void 0
-	});
+	const registry = createTaskRegistry(config.tasks, { db: (config.dbDrivers?.length ?? 0) > 0 });
 	const { runAction } = createActionRunner(config, registry, config.fetchImpl);
 	/**
 	* Single-flight over the store the deployment already gave the `kv` tasks — its own Redis, table or whatever it

package/dist/modules/actions/runtime/check.js

@@ -1,6 +1,6 @@
 import { triggerParams } from "./triggers.js";
+import { parseCron, readSmtpCredential, triggerHasStaleVerify, triggerVerify } from "@plitzi/sdk-shared/actions";
 import { hasValidToken } from "@plitzi/sdk-shared/helpers/twigWrapper";
-import { parseCron, triggerHasStaleVerify, triggerVerify } from "@plitzi/sdk-shared/actions";
 //#region src/modules/actions/runtime/check.ts
 /** A value the check can reason about: a literal the author typed, not a template resolved at run time. */
 var literal = (value) => {
@@ -82,6 +82,17 @@ var checkAction = async (entry, deps) => {
 		const connector = literal(params.connector);
 		if (connector && !await lookups.getConnector?.(spaceId, connector)) add("error", `nodes.${node.id}.params.connector`, `This space has no connector called "${connector}"`, "Add it in Connectors, or name one that exists");
 		const identifier = literal(params.credential);
+		if (node.action === "email.send") {
+			const path = `nodes.${node.id}.params.credential`;
+			if (!identifier) {
+				add("error", path, "This step names no SMTP server to send through", "Add an SMTP credential and pick it here");
+				return;
+			}
+			const credential = await checkCredential(node, identifier);
+			if (!credential) return;
+			readSmtpCredential(credential).problems.forEach((problem) => add("error", path, `The credential "${identifier}" is not a usable SMTP server: ${problem.key} — ${problem.message}`));
+			return;
+		}
 		if (!identifier) return;
 		if (node.action === "db.query") {
 			const credential = await checkCredential(node, identifier, "dsn");

package/dist/modules/actions/runtime/email.d.ts

@@ -0,0 +1,39 @@
+import { HostLookup } from '../../../helpers/outboundGuard';
+import { ActionKvStore } from '../types';
+import { ActionEmailConfig, ActionEmailMessage } from '@plitzi/sdk-shared';
+import { SmtpSettings } from '@plitzi/sdk-shared/actions';
+export declare const DEFAULT_EMAIL_DAILY_LIMIT = 200;
+/** Hands one message to the SMTP server of a space, at an address this module already resolved and judged. */
+export type SmtpDelivery = (delivery: {
+    /** The IP to connect to. The host name travels separately, as what the TLS certificate must be for. */
+    address: string;
+    smtp: SmtpSettings;
+    message: ActionEmailMessage;
+    signal: AbortSignal;
+}) => Promise<void>;
+/** What the `email.send` task sends through: the policy around a space's own SMTP server, and the connection. */
+export type ActionEmailSender = {
+    send: (spaceId: number, smtp: SmtpSettings, message: ActionEmailMessage, signal: AbortSignal) => Promise<void>;
+};
+export type EmailSenderOptions = ActionEmailConfig & {
+    /** The server's own store, NOT a space's: a flow must not be able to reach the counter that limits it. */
+    kv: ActionKvStore;
+    lookup?: HostLookup;
+    deliver?: SmtpDelivery;
+    now?: () => Date;
+};
+/**
+ * Sends a flow's message under the deployment's rules, in this order:
+ *
+ * 1. **Where it goes is settled.** A deployment's own `transport` owns its connection and receives the message as it
+ *    is. Without one, the message goes to the SMTP server the space's credential names, and the host is resolved and
+ *    every address judged first: a credential is typed by a customer and the connection starts inside the
+ *    deployment's network, so `localhost` or an address that resolves to `10.0.0.5` is refused unless the deployment
+ *    allowed it. The connection then goes to the address that was judged, so a name that answers differently a second
+ *    later cannot be how it gets in.
+ * 2. **The message is counted against the space's day.** Before it leaves, and never given back: a failing server
+ *    still spends the allowance, or retrying against an outage would be how the limit is walked past. A host refused
+ *    in step 1 spends nothing, because nothing was attempted.
+ * 3. **The message is delivered.**
+ */
+export declare const createEmailSender: ({ kv, dailyLimitPerSpace, allowPrivateHosts, transport, lookup, deliver, now }: EmailSenderOptions) => ActionEmailSender;

package/dist/modules/actions/runtime/email.js

@@ -0,0 +1,91 @@
+import { isBlockedHost } from "../../../helpers/outboundGuard.js";
+import { lookup } from "node:dns/promises";
+var DAY_SECONDS = 86400;
+var CONNECTION_TIMEOUT_MS = 1e4;
+var SOCKET_TIMEOUT_MS = 2e4;
+var resolveAll = (hostname) => lookup(hostname, {
+	all: true,
+	verbatim: true
+});
+/** Loaded on the first message, so a server whose flows send no mail never loads a mail client to find that out. */
+var deliverWithNodemailer = async ({ address, smtp, message, signal }) => {
+	const { createTransport } = await import("nodemailer");
+	const transport = createTransport({
+		host: address,
+		port: smtp.port,
+		secure: smtp.security === "tls",
+		requireTLS: smtp.security === "starttls",
+		ignoreTLS: smtp.security === "none",
+		tls: { servername: smtp.host },
+		...smtp.username ? { auth: {
+			user: smtp.username,
+			pass: smtp.password
+		} } : {},
+		connectionTimeout: CONNECTION_TIMEOUT_MS,
+		greetingTimeout: CONNECTION_TIMEOUT_MS,
+		socketTimeout: SOCKET_TIMEOUT_MS
+	});
+	const abort = () => transport.close();
+	signal.addEventListener("abort", abort, { once: true });
+	try {
+		await transport.sendMail({
+			from: {
+				name: smtp.fromName,
+				address: smtp.fromEmail
+			},
+			to: message.to,
+			subject: message.subject,
+			text: message.text,
+			...message.replyTo ? { replyTo: message.replyTo } : {}
+		});
+	} finally {
+		signal.removeEventListener("abort", abort);
+		transport.close();
+	}
+};
+/**
+* Sends a flow's message under the deployment's rules, in this order:
+*
+* 1. **Where it goes is settled.** A deployment's own `transport` owns its connection and receives the message as it
+*    is. Without one, the message goes to the SMTP server the space's credential names, and the host is resolved and
+*    every address judged first: a credential is typed by a customer and the connection starts inside the
+*    deployment's network, so `localhost` or an address that resolves to `10.0.0.5` is refused unless the deployment
+*    allowed it. The connection then goes to the address that was judged, so a name that answers differently a second
+*    later cannot be how it gets in.
+* 2. **The message is counted against the space's day.** Before it leaves, and never given back: a failing server
+*    still spends the allowance, or retrying against an outage would be how the limit is walked past. A host refused
+*    in step 1 spends nothing, because nothing was attempted.
+* 3. **The message is delivered.**
+*/
+var createEmailSender = ({ kv, dailyLimitPerSpace = 200, allowPrivateHosts = false, transport, lookup = resolveAll, deliver = deliverWithNodemailer, now = () => /* @__PURE__ */ new Date() }) => {
+	const viaSmtp = async (smtp) => {
+		let addresses;
+		try {
+			addresses = await lookup(smtp.host);
+		} catch {
+			throw new Error(`The SMTP host "${smtp.host}" does not resolve`);
+		}
+		const [first] = addresses;
+		if (addresses.length === 0) throw new Error(`The SMTP host "${smtp.host}" does not resolve`);
+		if (!allowPrivateHosts && (isBlockedHost(smtp.host) || addresses.some(({ address }) => isBlockedHost(address)))) throw new Error(`The SMTP host "${smtp.host}" is on a private network, which this server does not connect to`);
+		return (delivery) => deliver({
+			address: first.address,
+			smtp: delivery.smtp,
+			message: delivery.message,
+			signal: delivery.signal
+		});
+	};
+	return { send: async (spaceId, smtp, message, signal) => {
+		const deliverMessage = transport ?? await viaSmtp(smtp);
+		const day = now().toISOString().slice(0, 10);
+		if (await kv.increment(`email-limit:${spaceId}:${day}`, 1, 2 * DAY_SECONDS) > dailyLimitPerSpace) throw new Error(`This space has sent its ${dailyLimitPerSpace} emails for today`);
+		await deliverMessage({
+			spaceId,
+			smtp,
+			message,
+			signal
+		});
+	} };
+};
+//#endregion
+export { createEmailSender };

package/dist/modules/actions/runtime/email.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/actions/runtime/runAction.js

@@ -4,9 +4,11 @@ import { createKvStore } from "./kvStore.js";
 import { resolveLimits } from "./limits.js";
 import { createMemoryKv } from "./memoryKv.js";
 import { namespaceKv } from "./namespaceKv.js";
+import { createEmailSender } from "./email.js";
 import { createRedactor, projectUser } from "./scope.js";
 import { precheckRun } from "./precheck.js";
 import onAbort from "../../../helpers/onAbort.js";
+import { FAILURE_HANDLER_TASK } from "@plitzi/sdk-shared/actions";
 import { evaluateRuleGroup } from "@plitzi/sdk-shared/helpers/ruleEvaluator";
 import { hasValidToken, processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
 //#region src/modules/actions/runtime/runAction.ts
@@ -15,6 +17,14 @@ var MAX_TWIG_RESOLUTION_PASSES = 5;
 *  boundaries a flow actually has, and it keeps a long run to sixty reads a minute. */
 var CANCEL_POLL_MS = 1e3;
 /**
+* The most a failed run's undo may take, on a clock of its own.
+*
+* Its own because the run's clock may be exactly what ran out: a run that hit its deadline has seats to give back
+* too. Short because the caller is still waiting for the failure, and giving back what a flow took is a handful of
+* writes, not another run. Never longer than the run itself was allowed.
+*/
+var UNDO_TIMEOUT_MS = 5e3;
+/**
 * The run's deadline, as a promise that loses patience.
 *
 * Aborting the controller is the polite half: a task that watches its signal stops, and the loop refuses to start
@@ -166,6 +176,21 @@ var errorNode = (action) => ({
 	flowId: "",
 	enabled: true
 });
+/**
+* Where a chain's undo begins, if it has one: the first `flow.onFailure` its steps reach.
+*
+* Per trigger, because each way in walks its own chain. Walked with a visited set: the validator refuses a chain that
+* comes back on itself, but a stored document is still customer input, and a lookup must not be what spins.
+*/
+var failureHandlerOf = (nodes, trigger) => {
+	const visited = /* @__PURE__ */ new Set();
+	let next = nodes[trigger.afterNode];
+	while (next && !visited.has(next.id)) {
+		if (next.action === FAILURE_HANDLER_TASK) return next;
+		visited.add(next.id);
+		next = nodes[next.afterNode];
+	}
+};
 var withDefaults = (task, params) => Object.entries(task.params).reduce((acum, [key, param]) => {
 	if (acum[key] === void 0 || acum[key] === "") acum[key] = param.defaultValue ?? "";
 	return acum;
@@ -200,6 +225,10 @@ var runNode = async (node, scope, registry, buildContext) => {
 */
 var createActionRunner = (config, registry, baseFetch = fetch) => {
 	const kv = createKvStore(config.kv ?? createMemoryKv());
+	const emailSender = createEmailSender({
+		...config.email,
+		kv
+	});
 	/** Never allowed to fail a run: a logging outage must not take an action down, the same rule metering follows. */
 	const record = async (entry) => {
 		try {
@@ -224,15 +253,21 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 		const deadline = createDeadline(request.emit ? limits.streamTimeoutMs : limits.timeoutMs, controller);
 		const releaseOuter = onAbort(request.signal, () => controller.abort());
 		const scopedKv = namespaceKv(kv, request.spaceId);
-		const runFetch = createRunFetch(baseFetch, controller.signal, limits, [...request.lineage ?? [], entry.id]);
-		const buildContext = (scope) => ({
+		const lineage = [...request.lineage ?? [], entry.id];
+		/**
+		* What a step runs with, for one abort signal and one outbound budget.
+		*
+		* Two of them per run at most: the flow's, and — only when it failed — the undo's, which must still be able to
+		* reach the outside world after the flow's signal was aborted or its request budget spent.
+		*/
+		const contextFor = (signal, runFetch) => (scope) => ({
 			runId,
 			spaceId: request.spaceId,
 			environment: request.environment,
 			trigger: request.trigger,
 			user: request.user,
 			callerId: request.callerId,
-			signal: controller.signal,
+			signal,
 			scope,
 			/**
 			* The secret a STEP asked for, resolved inside that step and never in the flow scope.
@@ -260,9 +295,10 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 			fetch: runFetch,
 			kv: scopedKv,
 			dbDrivers: config.dbDrivers ?? [],
-			email: config.email,
+			email: emailSender,
 			emit: (chunk) => request.emit?.(redact(chunk))
 		});
+		const buildContext = contextFor(controller.signal, createRunFetch(baseFetch, controller.signal, limits, lineage));
 		const trace = [];
 		const startedAt = Date.now();
 		let failure;
@@ -299,11 +335,15 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 		* hits its deadline answers, releases its slot and closes its connection while whatever step ignored the abort
 		* carries on in the background — which is the difference between a stuck STEP and a stuck server.
 		*/
+		const failureHandler = failureHandlerOf(document.nodes, triggerNode);
+		/** The step the flow was running when it stopped — what `{{ failure.step }}` names to the undo. */
+		let stepInFlight = "";
 		const runFlow = async () => {
 			let current = triggerNode;
 			let executed = 0;
 			let next = document.nodes[current.afterNode];
 			while (next) {
+				if (next.action === FAILURE_HANDLER_TASK) break;
 				if (controller.signal.aborted) {
 					status = "aborted";
 					break;
@@ -316,6 +356,7 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 				executed += 1;
 				if (executed > limits.maxNodes) throw new ActionRunError("over_capacity", `Action exceeded its ${limits.maxNodes} step budget`);
 				const startTime = Date.now();
+				stepInFlight = next.id;
 				const outcome = await runNode(next, scope, registry, buildContext);
 				trace.push({
 					node: next,
@@ -332,6 +373,68 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 				next = document.nodes[current.afterNode];
 			}
 		};
+		/**
+		* Gives back what a run that did not finish already did: the steps after `flow.onFailure`.
+		*
+		* On a clock and an outbound budget of its own, because the run's may be exactly what ran out, and deliberately
+		* NOT tied to the caller's connection — somebody closing the tab is the last reason to leave seats taken. Each step
+		* still asks its own `when`: the failure may have come before the thing to undo was ever done. Nothing it does
+		* changes the run's status or its answer; an undo that fails too is added to the failure, never put in its place.
+		*/
+		const undo = async (handler) => {
+			const undoController = new AbortController();
+			const undoDeadline = createDeadline(Math.min(limits.timeoutMs, UNDO_TIMEOUT_MS), undoController);
+			const buildUndoContext = contextFor(undoController.signal, createRunFetch(baseFetch, undoController.signal, limits, lineage));
+			scope.failure = {
+				step: stepInFlight,
+				message: failure ?? "",
+				status
+			};
+			trace.push({
+				node: handler,
+				status: "success",
+				result: redact(scope.failure),
+				postCallbacks: [],
+				startTime: Date.now(),
+				endTime: Date.now()
+			});
+			const runUndo = async () => {
+				let executed = 0;
+				let next = document.nodes[handler.afterNode];
+				while (next) {
+					executed += 1;
+					if (executed > limits.maxNodes) throw new ActionRunError("over_capacity", `Undoing the action exceeded its ${limits.maxNodes} step budget`);
+					const startTime = Date.now();
+					const outcome = await runNode(next, scope, registry, buildUndoContext);
+					trace.push({
+						node: next,
+						status: outcome.status,
+						result: redact(outcome.result),
+						postCallbacks: [],
+						startTime,
+						endTime: Date.now()
+					});
+					scope[next.id] = outcome.result;
+					next = document.nodes[next.afterNode];
+				}
+			};
+			try {
+				await Promise.race([runUndo(), undoDeadline.promise]);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				trace.push({
+					node: errorNode("undo"),
+					status: "failed",
+					result: redact({ error: message }),
+					postCallbacks: [],
+					startTime: Date.now(),
+					endTime: Date.now()
+				});
+				failure = `${failure ?? "Action failed"} — and undoing it failed too: ${message}`;
+			} finally {
+				undoDeadline.clear();
+			}
+		};
 		/** Set when the run ends in a way the CALLER has to hear as a status code rather than as a result. */
 		let fatal;
 		try {
@@ -375,6 +478,7 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 			deadline.clear();
 			releaseOuter();
 		}
+		if (status !== "completed" && failureHandler?.enabled) await undo(failureHandler);
 		const output = returned ?? {};
 		await record({
 			runId,

package/dist/modules/actions/tasks/builtins.d.ts

@@ -2,8 +2,9 @@ import { ActionTask } from '../types';
 /**
  * The tasks `sdk-server` itself ships: the ones that are mechanism rather than policy.
  *
- * Anything needing an account somewhere — AI, object storage — is the DEPLOYMENT's, registered through
- * `actions.tasks`. `db.query` and `email.send` sit in between: the task is shipped because its rules are the same
- * everywhere, the driver or transport is the deployment's, and the registry offers the task only when one was given.
+ * Anything needing an account somewhere the deployment owns — AI, object storage — is the DEPLOYMENT's, registered
+ * through `actions.tasks`. `email.send` is shipped because the account is the SPACE's: it sends through an SMTP server
+ * the space holds as a credential, so every server can offer it. `db.query` sits in between — the task is shipped,
+ * the engine driver is the deployment's, and the registry offers it only when one was given.
  */
 export declare const builtinTasks: ActionTask<Record<string, unknown>>[];

package/dist/modules/actions/tasks/builtins.js

@@ -1,5 +1,6 @@
 import { authTasks } from "./auth.js";
 import { connectorTasks } from "./connector.js";
+import { emailTasks } from "./email.js";
 import { flowTasks, streamTasks } from "./flow.js";
 import { httpTasks } from "./http.js";
 import { kvTasks } from "./kv.js";
@@ -8,9 +9,10 @@ import { transformTasks } from "./transform.js";
 /**
 * The tasks `sdk-server` itself ships: the ones that are mechanism rather than policy.
 *
-* Anything needing an account somewhere — AI, object storage — is the DEPLOYMENT's, registered through
-* `actions.tasks`. `db.query` and `email.send` sit in between: the task is shipped because its rules are the same
-* everywhere, the driver or transport is the deployment's, and the registry offers the task only when one was given.
+* Anything needing an account somewhere the deployment owns — AI, object storage — is the DEPLOYMENT's, registered
+* through `actions.tasks`. `email.send` is shipped because the account is the SPACE's: it sends through an SMTP server
+* the space holds as a credential, so every server can offer it. `db.query` sits in between — the task is shipped,
+* the engine driver is the deployment's, and the registry offers it only when one was given.
 */
 var builtinTasks = [
 	...flowTasks,
@@ -19,6 +21,7 @@ var builtinTasks = [
 	...connectorTasks,
 	...authTasks,
 	...kvTasks,
+	...emailTasks,
 	...streamTasks
 ];
 //#endregion

package/dist/modules/actions/tasks/email.js

@@ -1,19 +1,20 @@
+import { isSingleEmailAddress, readSmtpCredential } from "@plitzi/sdk-shared/actions";
 //#region src/modules/actions/tasks/email.ts
-/**
-* One address, and nothing a mail header could be split on.
-*
-* Stricter than the standard on purpose: a comma or a semicolon is how one recipient becomes a hundred, and a line
-* break is how a subject becomes a second header. A flow renders what a visitor typed, so this is where that stops.
-*/
-var ADDRESS = /^[^\s@,;<>"]+@[^\s@,;<>"]+\.[^\s@,;<>"]+$/;
 var MAX_SUBJECT = 200;
 var MAX_TEXT = 2e4;
 var emailTasks = [{
 	namespace: "email",
 	action: "send",
 	title: "Send Email",
-	description: "Sends a plain-text message through the transport this deployment configured",
+	description: "Sends a plain-text message through an SMTP server this space holds as a credential",
 	params: {
+		credential: {
+			type: "text",
+			canBind: false,
+			defaultValue: "",
+			label: "SMTP server (credential)",
+			credentialProvider: "smtp"
+		},
 		to: {
 			type: "text",
 			canBind: true,
@@ -39,22 +40,26 @@ var emailTasks = [{
 			label: "Reply to"
 		}
 	},
-	run: async ({ to, subject, text, replyTo }, ctx) => {
-		if (!ctx.email) throw new Error("This server has no email transport");
+	run: async ({ credential, to, subject, text, replyTo }, ctx) => {
+		const identifier = credential.trim();
+		if (identifier === "") throw new Error("This step names no SMTP credential to send through — add one in Credentials and pick it here");
 		const recipient = to.trim();
-		if (!ADDRESS.test(recipient)) throw new Error("The recipient is not one email address");
+		if (!isSingleEmailAddress(recipient)) throw new Error("The recipient is not one email address");
 		const answerTo = replyTo.trim();
-		if (answerTo !== "" && !ADDRESS.test(answerTo)) throw new Error("The reply-to is not one email address");
+		if (answerTo !== "" && !isSingleEmailAddress(answerTo)) throw new Error("The reply-to is not one email address");
 		const title = subject.trim();
 		if (title === "" || /[\r\n]/.test(title) || title.length > MAX_SUBJECT) throw new Error(`The subject must be one line of 1 to ${MAX_SUBJECT} characters`);
 		if (text.trim() === "" || text.length > MAX_TEXT) throw new Error(`The text must have 1 to ${MAX_TEXT} characters`);
-		await ctx.email.send({
-			spaceId: ctx.spaceId,
+		const stored = await ctx.credential(identifier);
+		if (!stored) throw new Error(`This space has no SMTP credential called "${identifier}" — add it in Credentials`);
+		const reading = readSmtpCredential(stored);
+		if (!("settings" in reading)) throw new Error(`Credential "${identifier}" is not a usable SMTP server: ${reading.problems.map((problem) => `${problem.key} — ${problem.message}`).join("; ")}`);
+		await ctx.email.send(ctx.spaceId, reading.settings, {
 			to: recipient,
 			subject: title,
 			text,
 			...answerTo === "" ? {} : { replyTo: answerTo }
-		});
+		}, ctx.signal);
 		return { sent: true };
 	}
 }];

package/dist/modules/actions/tasks/flow.js

@@ -46,6 +46,24 @@ var fail = {
 	}
 };
 /**
+* Where a flow's undo begins — read by the runner, never run as a step.
+*
+* A run that reaches it has succeeded and ends there. A run whose step failed before it jumps here instead and runs
+* the steps after it, each still asking its own `when` — the failure may have come before the thing to undo was ever
+* done — and still ends as failed, with the failure it had. What failed is in their scope as `{{ failure.step }}` and
+* `{{ failure.message }}`.
+*/
+var onFailure = {
+	namespace: "flow",
+	action: "onFailure",
+	title: "On Failure",
+	description: "The steps after this one run only when a step before it fails, to undo what the flow already did",
+	params: {},
+	run: () => {
+		throw new Error("On Failure marks where a failed run’s undo begins; the runner never runs it as a step");
+	}
+};
+/**
 * Declares what the caller gets back — and IS the declaration.
 *
 * The flow scope is not the answer: it holds every node's raw result, including whatever a fetch happened to
@@ -102,7 +120,8 @@ var emit = {
 var flowTasks = [
 	delay,
 	fail,
-	output
+	output,
+	onFailure
 ];
 var streamTasks = [emit];
 //#endregion

package/dist/modules/actions/tasks/registry.d.ts

@@ -4,8 +4,6 @@ export declare const taskName: (task: Pick<ActionTask, "namespace" | "action">)
 export type TaskRegistryOptions = {
     /** At least one database driver is registered, so `db.query` has an engine to run against. */
     db?: boolean;
-    /** An email transport is configured, so `email.send` has somewhere to hand a message. */
-    email?: boolean;
 };
 /**
  * Builds the set of tasks this server can run.
@@ -14,4 +12,4 @@ export type TaskRegistryOptions = {
  * name is unreachable from any document, and one shadowing a built-in silently changes what every existing action
  * in that deployment does. Both are invisible until a run misbehaves in production.
  */
-export declare const createTaskRegistry: (custom?: ActionTask<never>[], { db, email }?: TaskRegistryOptions) => ActionTaskRegistry;
+export declare const createTaskRegistry: (custom?: ActionTask<never>[], { db }?: TaskRegistryOptions) => ActionTaskRegistry;

package/dist/modules/actions/tasks/registry.js

@@ -1,14 +1,9 @@
 import { builtinTasks } from "./builtins.js";
 import { dbTasks } from "./db.js";
-import { emailTasks } from "./email.js";
 //#region src/modules/actions/tasks/registry.ts
 var NAME_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
 var taskName = (task) => `${task.namespace}.${task.action}`;
-var reservedNamespaces = new Set([
-	...builtinTasks,
-	...dbTasks,
-	...emailTasks
-].map((task) => task.namespace));
+var reservedNamespaces = new Set([...builtinTasks, ...dbTasks].map((task) => task.namespace));
 /**
 * Builds the set of tasks this server can run.
 *
@@ -16,13 +11,9 @@ var reservedNamespaces = new Set([
 * name is unreachable from any document, and one shadowing a built-in silently changes what every existing action
 * in that deployment does. Both are invisible until a run misbehaves in production.
 */
-var createTaskRegistry = (custom = [], { db = false, email = false } = {}) => {
+var createTaskRegistry = (custom = [], { db = false } = {}) => {
 	const tasks = /* @__PURE__ */ new Map();
-	[
-		...builtinTasks,
-		...db ? dbTasks : [],
-		...email ? emailTasks : []
-	].forEach((task) => tasks.set(taskName(task), {
+	(db ? [...builtinTasks, ...dbTasks] : builtinTasks).forEach((task) => tasks.set(taskName(task), {
 		...task,
 		name: taskName(task)
 	}));

package/dist/modules/actions/transport/catalogHandler.d.ts

@@ -9,7 +9,7 @@ export type ActionCatalogDeps = {
  *
  * The editor asks the SERVER what steps exist instead of holding a hardcoded list, and that is the whole reason a
  * self-hoster's own task appears in their builder with no fork: registering it is publishing it. It also means a
- * deployment with no mail transport never offers `email.send` — the catalog is what that deployment actually has,
+ * deployment with no database driver never offers `db.query` — the catalog is what that deployment actually has,
  * not what the SDK could imagine.
  *
  * Session-gated by the pipeline: the catalog names a deployment's server-side capabilities, which is not something

package/dist/modules/actions/transport/catalogHandler.js

@@ -5,7 +5,7 @@ import { describeCatalog } from "../taskCatalog.js";
 *
 * The editor asks the SERVER what steps exist instead of holding a hardcoded list, and that is the whole reason a
 * self-hoster's own task appears in their builder with no fork: registering it is publishing it. It also means a
-* deployment with no mail transport never offers `email.send` — the catalog is what that deployment actually has,
+* deployment with no database driver never offers `db.query` — the catalog is what that deployment actually has,
 * not what the SDK could imagine.
 *
 * Session-gated by the pipeline: the catalog names a deployment's server-side capabilities, which is not something

package/dist/modules/actions/types.d.ts

@@ -1,4 +1,5 @@
-import { ActionEmailAdapter, ActionEntry, ActionLimits, ActionRejectRecord, ActionRunRecord, ActionRunStatus, ActionTriggerType, ConnectorManifest, Environment, InteractionCallbackParam, InteractionNode, InteractionNodeStatus, SpaceRevision, SSRUser } from '@plitzi/sdk-shared';
+import { ActionEmailSender } from './runtime/email';
+import { ActionEmailConfig, ActionEntry, ActionLimits, ActionRejectRecord, ActionRunRecord, ActionRunStatus, ActionTriggerType, ConnectorManifest, Environment, InteractionCallbackParam, InteractionNode, InteractionNodeStatus, SpaceRevision, SSRUser } from '@plitzi/sdk-shared';
 /** Resolved secret material, as the connector engine already models it. */
 export type ActionCredential = Record<string, string>;
 /**
@@ -109,8 +110,8 @@ export type ActionTaskContext = {
     kv: ActionKvStore;
     /** The database engines this deployment registered, for the `db.query` task. */
     dbDrivers: ActionDbDriver[];
-    /** The transport this deployment gave the `email.send` task. Absent → that task is not offered at all. */
-    email?: ActionEmailAdapter;
+    /** How `email.send` reaches a space's SMTP server, under the deployment's limits. */
+    email: ActionEmailSender;
     /** Pushes a `data` frame to a streaming caller. A no-op when nobody negotiated a stream. */
     emit: (chunk: unknown) => void;
 };
@@ -164,8 +165,8 @@ export type ActionsConfig = {
     };
     /** Database engines this deployment lets a flow reach. Empty → the `db.query` task is not offered at all. */
     dbDrivers?: ActionDbDriver[];
-    /** How a flow's mail leaves this server. Absent → the `email.send` task is not offered at all. */
-    email?: ActionEmailAdapter;
+    /** The limits on `email.send`: messages per space per day, and whether an SMTP host may be on a private network. */
+    email?: ActionEmailConfig;
     /**
      * Called once per run that started, for a deployment that keeps a record.
      *
@@ -201,7 +202,7 @@ export type ActionsConfig = {
 };
 /** Re-exported so the module's own files import one place, and a deployment writing an `onRun` or an `onReject`
  *  sees the same shapes the module emits. */
-export type { ActionEmailAdapter, ActionEmailMessage, ActionRejectRecord, ActionRunRecord } from '@plitzi/sdk-shared';
+export type { ActionEmailConfig, ActionEmailDelivery, ActionEmailMessage, ActionEmailTransport, ActionRejectRecord, ActionRunRecord } from '@plitzi/sdk-shared';
 export type ResolvedActionLimits = Required<ActionLimits>;
 export type ActionRunRequest = {
     entry: ActionEntry;

package/dist/modules/connectors/engine.js

@@ -1,5 +1,5 @@
-import { getByPath } from "./getByPath.js";
 import { assertOutboundAllowed } from "../../helpers/outboundGuard.js";
+import { getByPath } from "./getByPath.js";
 import { processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
 import { BODYLESS_METHODS, DEFAULT_READ_ENDPOINT, EMPTY_RESPONSE_METHODS } from "@plitzi/sdk-shared/connectors";
 //#region src/modules/connectors/engine.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.35.4",
+  "version": "0.35.6",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -58,11 +58,12 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.35.4",
-    "@plitzi/sdk-shared": "0.35.4",
+    "@plitzi/plitzi-sdk": "0.35.6",
+    "@plitzi/sdk-shared": "0.35.6",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
-    "jsonwebtoken": "^9.0.3"
+    "jsonwebtoken": "^9.0.3",
+    "nodemailer": "^10.0.9"
   },
   "peerDependencies": {
     "mysql2": "^3",
@@ -78,6 +79,7 @@
     "@types/ejs": "^3.1.5",
     "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "^26.5.1",
+    "@types/nodemailer": "^8.0.1",
     "@types/react": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.1",
     "@vitest/coverage-v8": "^5.0.0",