@plitzi/sdk-shared 0.35.5 → 0.35.7

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @plitzi/sdk-shared
 
+## 0.35.7
+
+### Patch Changes
+
+- An SMTP failure says which credential it was, and a credential's values can be replaced from the builder.
+
+  - **`email.send` names the credential it could not send through:** `Could not send through the SMTP credential
+"ceniza-smtp": its SMTP host is on a private network…`. The host used to be in the sentence, and a run's trace
+    redacts every value of a credential it resolved, so the message read `The SMTP host "«redacted»"…`.
+  - **Credentials can be edited in the builder.** A pencil on each row opens the form with the name and the provider
+    fixed and nothing it holds shown: every value is entered again, and saving replaces all of them. SMTP credentials
+    are also labelled in the list.
+
+## 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`.
+
 ## 0.35.5
 
 ### Patch Changes

package/dist/actions/failureHandler.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The step that marks where a server action's undo begins.
+ *
+ * Steps after it run only when a step before it failed, so an action can give back what it already did — seats it took,
+ * a row it wrote — instead of leaving it behind a failure. Named once because four places read it: the runner that jumps
+ * to it, the validator that checks where it sits, the authoring API that writes it and the task catalog that offers it.
+ */
+export declare const FAILURE_HANDLER_TASK = "flow.onFailure";

package/dist/actions/failureHandler.mjs

@@ -0,0 +1,4 @@
+//#region src/actions/failureHandler.ts
+var e = "flow.onFailure";
+//#endregion
+export { e as FAILURE_HANDLER_TASK };

package/dist/actions/index.d.ts

@@ -1,4 +1,5 @@
 export { cronMatches, isKnownTimeZone, parseCron, zonedClock } from './cron';
+export { FAILURE_HANDLER_TASK } from './failureHandler';
 export { triggerAccess, triggerCacheMs, triggerHasStaleVerify, triggerInput, triggerVerify } from './triggerParams';
 export { actionName, actionTriggers, isActionEnabled } from './triggers';
 export { validateActionDocument } from './validateDocument';

package/dist/actions/index.mjs

@@ -1,6 +1,7 @@
 import { cronMatches as e, isKnownTimeZone as t, parseCron as n, zonedClock as r } from "./cron.mjs";
-import { triggerAccess as i, triggerCacheMs as a, triggerHasStaleVerify as o, triggerInput as s, triggerVerify as c } from "./triggerParams.mjs";
-import { actionName as l, actionTriggers as u, isActionEnabled as d } from "./triggers.mjs";
-import { validateActionDocument as f } from "./validateDocument.mjs";
-import { SMTP_CREDENTIAL_KEYS as p, isSingleEmailAddress as m, readSmtpCredential as h } from "./smtp.mjs";
-export { p as SMTP_CREDENTIAL_KEYS, l as actionName, u as actionTriggers, e as cronMatches, d as isActionEnabled, t as isKnownTimeZone, m as isSingleEmailAddress, n as parseCron, h as readSmtpCredential, i as triggerAccess, a as triggerCacheMs, o as triggerHasStaleVerify, s as triggerInput, c as triggerVerify, f as validateActionDocument, r as zonedClock };
+import { FAILURE_HANDLER_TASK as i } from "./failureHandler.mjs";
+import { triggerAccess as a, triggerCacheMs as o, triggerHasStaleVerify as s, triggerInput as c, triggerVerify as l } from "./triggerParams.mjs";
+import { actionName as u, actionTriggers as d, isActionEnabled as f } from "./triggers.mjs";
+import { validateActionDocument as p } from "./validateDocument.mjs";
+import { SMTP_CREDENTIAL_KEYS as m, isSingleEmailAddress as h, readSmtpCredential as g } from "./smtp.mjs";
+export { i as FAILURE_HANDLER_TASK, m as SMTP_CREDENTIAL_KEYS, u as actionName, d as actionTriggers, e as cronMatches, f as isActionEnabled, t as isKnownTimeZone, h as isSingleEmailAddress, n as parseCron, g as readSmtpCredential, a as triggerAccess, o as triggerCacheMs, s as triggerHasStaleVerify, c as triggerInput, l as triggerVerify, p as validateActionDocument, r as zonedClock };

package/dist/actions/validateDocument.mjs

@@ -1,41 +1,43 @@
 import { isKnownTimeZone as e, parseCron as t } from "./cron.mjs";
-import { triggerAccess as n, triggerHasStaleVerify as r, triggerVerify as i } from "./triggerParams.mjs";
+import { FAILURE_HANDLER_TASK as n } from "./failureHandler.mjs";
+import { triggerAccess as r, triggerHasStaleVerify as i, triggerVerify as a } from "./triggerParams.mjs";
 //#region src/actions/validateDocument.ts
-var a = [
+var o = [
 	"text",
 	"number",
 	"boolean",
 	"date",
 	"json",
 	"file"
-], o = [
+], s = [
 	"public",
 	"session",
 	"role"
-], s = [
+], c = [
 	"call",
 	"webhook",
 	"schedule",
 	"render",
 	"custom"
-], c = ["sha256", "sha1"], l = /* @__PURE__ */ new Set([
+], l = ["sha256", "sha1"], u = /* @__PURE__ */ new Set([
 	"input",
 	"user",
 	"spaceId",
 	"environment",
 	"trigger",
 	"runId",
-	"now"
-]), u = /^[a-z][a-zA-Z0-9]*\.[a-z][a-zA-Z0-9]*$/, d = (e) => typeof e == "object" && !!e && !Array.isArray(e), f = (e) => typeof e == "string" && e.trim() !== "", p = (e) => {
+	"now",
+	"failure"
+]), d = /^[a-z][a-zA-Z0-9]*\.[a-z][a-zA-Z0-9]*$/, f = (e) => typeof e == "object" && !!e && !Array.isArray(e), p = (e) => typeof e == "string" && e.trim() !== "", m = (e) => {
 	try {
 		let t = JSON.parse(e);
-		return d(t) ? t : void 0;
+		return f(t) ? t : void 0;
 	} catch {
 		return;
 	}
-}, m = (e, t, n) => {
+}, h = (e, t, n) => {
 	if (e !== void 0) {
-		if (!d(e)) {
+		if (!f(e)) {
 			n.push({
 				path: t,
 				message: "must be an object of field definitions"
@@ -43,215 +45,245 @@ var a = [
 			return;
 		}
 		Object.entries(e).forEach(([e, r]) => {
-			if (!d(r) || !f(r.type)) {
+			if (!f(r) || !p(r.type)) {
 				n.push({
 					path: `${t}.${e}`,
 					message: "must declare a type"
 				});
 				return;
 			}
-			a.includes(r.type) || n.push({
+			o.includes(r.type) || n.push({
 				path: `${t}.${e}.type`,
 				message: `unknown field type "${r.type}"`,
-				hint: `one of ${a.join(", ")}`
+				hint: `one of ${o.join(", ")}`
 			});
 		});
 	}
-}, h = (a, l, u, h) => {
-	let g = `nodes.${a}`, _ = l.action;
-	if (!f(_) || !s.includes(_)) {
+}, g = (n, o, u, d) => {
+	let g = `nodes.${n}`, _ = o.action;
+	if (!p(_) || !c.includes(_)) {
 		u.push({
 			path: `${g}.action`,
 			message: `"${String(_)}" is not a way an action can be started`,
-			hint: `one of ${s.join(", ")}`
+			hint: `one of ${c.join(", ")}`
 		});
 		return;
 	}
-	let v = d(l.params) ? l.params : {};
-	if (f(v.input)) {
-		let e = p(v.input);
+	let v = f(o.params) ? o.params : {};
+	if (p(v.input)) {
+		let e = m(v.input);
 		e === void 0 ? u.push({
 			path: `${g}.params.input`,
 			message: "is not valid JSON"
-		}) : m(e, `${g}.params.input`, u);
+		}) : h(e, `${g}.params.input`, u);
 	}
 	if (_ !== "schedule") {
-		if (!f(v.access) || !o.includes(v.access)) u.push({
+		if (!p(v.access) || !s.includes(v.access)) u.push({
 			path: `${g}.params.access`,
 			message: "must say who may start a run this way",
-			hint: `one of ${o.join(", ")}`
+			hint: `one of ${s.join(", ")}`
 		});
 		else if (v.access === "role") {
-			let e = n(v);
+			let e = r(v);
 			e?.mode === "role" && e.permissions.length === 0 && u.push({
 				path: `${g}.params.permissions`,
 				message: "role access must name at least one permission"
 			});
 		}
 	}
-	if (_ === "schedule" && (f(v.cron) ? t(v.cron) || u.push({
+	if (_ === "schedule" && (p(v.cron) ? t(v.cron) || u.push({
 		path: `${g}.params.cron`,
 		message: `"${v.cron}" is not an expression this server can read, so it would never fire`,
 		hint: "five fields — minute hour day-of-month month day-of-week — with *, lists, ranges and steps"
 	}) : u.push({
 		path: `${g}.params.cron`,
 		message: "a scheduled trigger needs a cron expression"
-	}), f(v.timezone) && !e(v.timezone) && u.push({
+	}), p(v.timezone) && !e(v.timezone) && u.push({
 		path: `${g}.params.timezone`,
 		message: `"${v.timezone}" is not a time zone this server knows, so the schedule would never fire`,
 		hint: "an IANA name like America/Santiago or Europe/Madrid — leave it empty for UTC"
-	})), f(v.cacheSeconds)) {
+	})), p(v.cacheSeconds)) {
 		let e = Number.parseFloat(v.cacheSeconds);
 		!Number.isFinite(e) || e < 0 ? u.push({
 			path: `${g}.params.cacheSeconds`,
 			message: "must be a number of seconds, or left empty"
-		}) : _ !== "render" && h.push({
+		}) : _ !== "render" && d.push({
 			path: `${g}.params.cacheSeconds`,
 			message: `a "${_}" trigger is never answered from a cache`,
 			hint: "reuse only applies to a render, where the same page is built for one visitor after another"
 		});
 	}
-	_ === "custom" && !f(v.name) && u.push({
+	_ === "custom" && !p(v.name) && u.push({
 		path: `${g}.params.name`,
 		message: "a custom trigger needs a name to be mounted under"
-	}), _ === "webhook" && (r(v) && u.push({
+	}), _ === "webhook" && (i(v) && u.push({
 		path: `${g}.params.signatureCredential`,
 		message: "this signature check is in a format nothing reads any more, so the webhook is unverified",
 		hint: "name the credential holding the signing secret in \"Signing secret\", and its header beside it"
-	}), i(v) || h.push({
+	}), a(v) || d.push({
 		path: `${g}.params.signatureCredential`,
 		message: "this webhook accepts unsigned requests",
 		hint: "name the credential holding the signing secret, and only the sender you expect can start a run"
-	}), f(v.signatureAlgorithm) && !c.includes(v.signatureAlgorithm) && h.push({
+	}), p(v.signatureAlgorithm) && !l.includes(v.signatureAlgorithm) && d.push({
 		path: `${g}.params.signatureAlgorithm`,
 		message: `"${v.signatureAlgorithm}" is not an algorithm this server signs with, so sha256 is used`,
-		hint: `one of ${c.join(", ")}`
-	}), f(v.signatureToleranceSeconds) && !f(v.signatureTimestampHeader) && h.push({
+		hint: `one of ${l.join(", ")}`
+	}), p(v.signatureToleranceSeconds) && !p(v.signatureTimestampHeader) && d.push({
 		path: `${g}.params.signatureToleranceSeconds`,
 		message: "a tolerance with no timestamp header expires nothing",
 		hint: "name the header the sender puts the signing time in, or drop the tolerance"
-	})), _ === "call" && v.access === "public" && h.push({
+	})), _ === "call" && v.access === "public" && d.push({
 		path: `${g}.params.access`,
 		message: "anyone can run this action, including signed-out visitors",
 		hint: "use session access unless the page needs it before anyone signs in"
 	});
-}, g = (e, t, n, r) => {
-	if (!d(e)) {
-		n.push({
+}, _ = (e, t, r, i) => {
+	if (!f(e)) {
+		r.push({
 			path: "nodes",
 			message: "must be an object of steps"
 		});
 		return;
 	}
-	let i = Object.entries(e), a = i.filter(([, e]) => d(e) && e.type === "trigger");
-	a.length === 0 && n.push({
+	let a = Object.entries(e), o = a.filter(([, e]) => f(e) && e.type === "trigger");
+	o.length === 0 && r.push({
 		path: "nodes",
 		message: "this action has no way in",
 		hint: "add a trigger step — call, webhook, schedule, render or custom"
 	});
-	let o = /* @__PURE__ */ new Map();
-	a.forEach(([e, t]) => {
-		f(t.action) && o.set(t.action, [...o.get(t.action) ?? [], e]);
-	}), o.forEach((e, t) => {
-		e.length > 1 && n.push({
+	let s = /* @__PURE__ */ new Map();
+	o.forEach(([e, t]) => {
+		p(t.action) && s.set(t.action, [...s.get(t.action) ?? [], e]);
+	}), s.forEach((e, t) => {
+		e.length > 1 && r.push({
 			path: `nodes.${e[1]}`,
 			message: `this action has ${e.length} "${t}" triggers`,
 			hint: "one step per way in — a second flow starts from a different kind of trigger"
 		});
-	}), i.forEach(([t, i]) => {
+	}), a.forEach(([t, n]) => {
 		let a = `nodes.${t}`;
-		if (!d(i)) {
-			n.push({
+		if (!f(n)) {
+			r.push({
 				path: a,
 				message: "must be an object"
 			});
 			return;
 		}
-		if (i.type === "trigger") {
-			h(t, i, n, r);
+		if (n.type === "trigger") {
+			g(t, n, r, i);
 			return;
 		}
-		if (i.type !== "task") {
-			n.push({
+		if (n.type !== "task") {
+			r.push({
 				path: `${a}.type`,
-				message: `"${String(i.type)}" steps run in the browser and cannot run on the server`,
+				message: `"${String(n.type)}" steps run in the browser and cannot run on the server`,
 				hint: "a server action is made of task steps"
 			});
 			return;
 		}
-		if (!f(i.action) || !u.test(i.action)) {
-			n.push({
+		if (!p(n.action) || !d.test(n.action)) {
+			r.push({
 				path: `${a}.action`,
 				message: "must name a task as <namespace>.<action>",
 				hint: "for example flow.output or http.request"
 			});
 			return;
 		}
-		f(i.afterNode) && !Object.hasOwn(e, i.afterNode) && n.push({
+		p(n.afterNode) && !Object.hasOwn(e, n.afterNode) && r.push({
 			path: `${a}.afterNode`,
-			message: `points at "${i.afterNode}", which is not a step here`
+			message: `points at "${n.afterNode}", which is not a step here`
 		});
-	}), i.forEach(([e]) => {
-		l.has(e) && n.push({
+	}), a.forEach(([e]) => {
+		u.has(e) && r.push({
 			path: `nodes.${e}`,
 			message: `"${e}" is what the run itself publishes in the flow scope, so a step may not take the name`,
 			hint: `rename the step — every later step reads {{ ${e} }} expecting the run's own value`
 		});
 	});
-	let s = /* @__PURE__ */ new Set(), c = /* @__PURE__ */ new Set();
-	a.forEach(([t]) => {
-		let n = /* @__PURE__ */ new Set(), r = t;
-		for (; r;) {
-			if (n.has(r)) {
-				c.add(r);
+	let c = /* @__PURE__ */ new Set(), l = /* @__PURE__ */ new Set(), m = [];
+	o.forEach(([t]) => {
+		let n = /* @__PURE__ */ new Set(), r = [], i = t;
+		for (; i;) {
+			if (n.has(i)) {
+				l.add(i);
 				break;
 			}
-			n.add(r), s.add(r);
-			let t = e[r];
-			r = f(t?.afterNode) ? t.afterNode : "";
+			n.add(i), r.push(i), c.add(i);
+			let t = e[i];
+			i = p(t?.afterNode) ? t.afterNode : "";
 		}
-	}), c.forEach((e) => {
-		n.push({
+		m.push(r);
+	}), l.forEach((e) => {
+		r.push({
 			path: `nodes.${e}`,
 			message: "this step is reached again by its own chain, so the flow never ends",
 			hint: "break the `afterNode` chain that comes back to it"
 		});
-	}), i.forEach(([e]) => {
-		s.has(e) || r.push({
+	}), a.forEach(([e]) => {
+		c.has(e) || i.push({
 			path: `nodes.${e}`,
 			message: "no trigger reaches this step, so it never runs",
 			hint: "chain it with `afterNode` from a trigger, or delete it"
 		});
 	});
-	let p = i.filter(([, e]) => d(e) && e.action === "flow.output");
-	for (let [t, n] of p) f(n.afterNode) && Object.hasOwn(e, n.afterNode) && r.push({
-		path: `nodes.${t}.afterNode`,
-		message: "the output step is not the last one, so the steps after it run for nothing",
-		hint: "move flow.output to the end of the flow"
-	});
-	p.length === 0 && d(t) && Object.keys(t).length > 0 && r.push({
+	let h = (t) => e[t]?.action, _ = a.filter(([, e]) => f(e) && e.action === "flow.output");
+	for (let [t, n] of _) {
+		let r = p(n.afterNode) && h(n.afterNode) === "flow.onFailure";
+		p(n.afterNode) && Object.hasOwn(e, n.afterNode) && !r && i.push({
+			path: `nodes.${t}.afterNode`,
+			message: "the output step is not the last one, so the steps after it run for nothing",
+			hint: "move flow.output to the end of the flow"
+		});
+	}
+	let v = /* @__PURE__ */ new Set(), y = (e, t) => {
+		v.has(`${t.path}|${t.message}`) || (v.add(`${t.path}|${t.message}`), e.push(t));
+	};
+	m.forEach((e) => {
+		let t = e.findIndex((e) => h(e) === n);
+		if (t === -1) return;
+		let a = e[t];
+		t === 1 && y(i, {
+			path: `nodes.${a}`,
+			message: "nothing runs before this step, so nothing can fail and the steps after it never run",
+			hint: "put On Failure after the steps whose work it undoes"
+		}), t === e.length - 1 && y(i, {
+			path: `nodes.${a}`,
+			message: "nothing follows this step, so a failed run undoes nothing",
+			hint: "add the steps that give back what the flow already did"
+		}), e.slice(t + 1).forEach((e) => {
+			h(e) === "flow.onFailure" && y(r, {
+				path: `nodes.${e}`,
+				message: "a flow has one place its undo begins, and this is a second one",
+				hint: "keep one On Failure step and put every undo step after it"
+			}), h(e) === "flow.output" && y(r, {
+				path: `nodes.${e}`,
+				message: "an output step after On Failure answers a run that has already failed",
+				hint: "move flow.output before On Failure"
+			});
+		});
+	}), _.length === 0 && f(t) && Object.keys(t).length > 0 && i.push({
 		path: "nodes",
 		message: "this action is expected to answer values but no step names any",
 		hint: "add a flow.output step at the end naming what the caller should get"
 	});
-}, _ = /\{\{\s*credential\./, v = (e, t) => {
+}, v = /\{\{\s*credential\./, y = (e, t) => {
 	Object.entries(e).forEach(([e, n]) => {
-		if (!d(n) || !d(n.params)) return;
-		let r = f(n.params.credential) ? n.params.credential : "";
+		if (!f(n) || !f(n.params)) return;
+		let r = p(n.params.credential) ? n.params.credential : "";
 		Object.entries(n.params).forEach(([n, i]) => {
-			typeof i == "string" && _.test(i) && r === "" && t.push({
+			typeof i == "string" && v.test(i) && r === "" && t.push({
 				path: `nodes.${e}.params.${n}`,
 				message: "this step reads a credential it did not ask for, so the token resolves to nothing",
 				hint: "set the step’s `credential` to the identifier it should use"
 			});
 		});
 	});
-}, y = (e) => {
+}, b = (e) => {
 	let t = [], n = [];
-	return d(e) ? (f(e.name) || t.push({
+	return f(e) ? (p(e.name) || t.push({
 		path: "name",
 		message: "must have a name"
-	}), m(e.output, "output", t), g(e.nodes, e.output, t, n), v(d(e.nodes) ? e.nodes : {}, n), {
+	}), h(e.output, "output", t), _(e.nodes, e.output, t, n), y(f(e.nodes) ? e.nodes : {}, n), {
 		valid: t.length === 0,
 		errors: t,
 		warnings: n
@@ -265,4 +297,4 @@ var a = [
 	};
 };
 //#endregion
-export { y as validateActionDocument };
+export { b as validateActionDocument };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-shared",
-  "version": "0.35.5",
+  "version": "0.35.7",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -22,6 +22,10 @@
       "types": "./dist/actions/cron.d.ts",
       "import": "./dist/actions/cron.mjs"
     },
+    "./actions/failureHandler": {
+      "types": "./dist/actions/failureHandler.d.ts",
+      "import": "./dist/actions/failureHandler.mjs"
+    },
     "./actions/index": {
       "types": "./dist/actions/index.d.ts",
       "import": "./dist/actions/index.mjs"