better-supabase 0.7.1 → 0.9.0

package/dist/workflow-builder-OrglbXUh.js

@@ -0,0 +1,681 @@
+import { n as dbError } from "./errors-8i6tSICm.js";
+import { a as ok, r as err, t as AsyncResult } from "./result-BlgnMB0H.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { n as PERMISSION_CAP_CLAIM } from "./delegation-Dt8hMJWu.js";
+import { n as credentialRefInTenant, r as foreignCredentialRef } from "./provider-DKh2xFZb.js";
+import { A as requiredInstant, C as optionalText, D as recordOf, F as stringsOf, I as textOf, M as seconds, O as recordOrEmpty, S as optionalInstant, T as randomToken, d as enumOrThrow, k as recordsOf, n as applyTemporal, o as blockCall, p as injectableOf } from "./block-helpers-CfG_MvDR.js";
+import { r as withBlockHooks } from "./block-hooks-BsXncUlZ.js";
+import { n as blockFields } from "./block-fields-ffD6Gxe4.js";
+import { d as triggerMatches, f as triggerWhenProblem, r as diffGraphs, s as graphOf } from "./graph-Cs28bOlK.js";
+//#region src/blocks/workflow-builder/rows.ts
+const VERSION_STATUSES = [
+	"draft",
+	"published",
+	"archived"
+];
+const VERSION_OWNERS = ["user", "organization"];
+const TRIGGER_KINDS = [
+	"manual",
+	"webhook",
+	"schedule",
+	"event",
+	"form",
+	"chat"
+];
+const SCOPES = ["tenant", "system"];
+const GRANT_PRINCIPALS = [
+	"user",
+	"team",
+	"role"
+];
+const GRANT_ACTIONS = ["run", "edit"];
+const NODE_RUN_STATUSES = [
+	"running",
+	"waiting",
+	"completed",
+	"failed",
+	"skipped"
+];
+function definitionOf(row) {
+	const published = row["published"];
+	return {
+		id: textOf(row["id"]),
+		tenant: optionalText(row["tenant"]),
+		slug: textOf(row["slug"]),
+		name: textOf(row["name"]),
+		description: optionalText(row["description"]),
+		createdBy: optionalText(row["createdBy"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt"),
+		updatedAt: requiredInstant(row["updatedAt"], "updatedAt"),
+		subjectTypes: stringsOf(row["subjectTypes"]),
+		scope: row["scope"] === void 0 || row["scope"] === null ? "tenant" : enumOrThrow(row["scope"], SCOPES, "definition scope"),
+		forkedFrom: optionalText(row["forkedFrom"]),
+		forkedFromVersion: optionalNumber(row["forkedFromVersion"]),
+		restricted: row["restricted"] === true,
+		..."published" in row ? { published: optionalNumber(published) } : {},
+		..."draft" in row ? { draft: row["draft"] === true } : {},
+		..."upstreamVersion" in row ? { upstreamVersion: optionalNumber(row["upstreamVersion"]) } : {},
+		..."behind" in row ? { behind: row["behind"] === true } : {},
+		..."optedOut" in row && typeof row["optedOut"] === "boolean" ? { optedOut: row["optedOut"] } : {},
+		fields: isRecord(row["fields"]) ? row["fields"] : {}
+	};
+}
+function grantOf(row) {
+	return {
+		id: textOf(row["id"]),
+		definition: textOf(row["definition"]),
+		principalKind: enumOrThrow(row["principalKind"], GRANT_PRINCIPALS, "grant principal"),
+		principalId: textOf(row["principalId"]),
+		action: enumOrThrow(row["action"], GRANT_ACTIONS, "grant action"),
+		createdBy: optionalText(row["createdBy"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt")
+	};
+}
+function optionalNumber(value) {
+	return typeof value === "number" ? value : void 0;
+}
+function versionOf(row) {
+	return {
+		id: textOf(row["id"]),
+		definition: textOf(row["definition"]),
+		version: Number(row["version"]),
+		status: enumOrThrow(row["status"], VERSION_STATUSES, "version status"),
+		createdBy: optionalText(row["createdBy"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt"),
+		publishedAt: optionalInstant(row["publishedAt"]),
+		publishedBy: optionalText(row["publishedBy"]),
+		owner: row["owner"] === null || row["owner"] === void 0 ? void 0 : enumOrThrow(row["owner"], VERSION_OWNERS, "version owner"),
+		permissions: Array.isArray(row["permissions"]) ? stringsOf(row["permissions"]) : [],
+		..."graph" in row ? { graph: graphOf(row["graph"]) } : {},
+		..."compiled" in row && row["compiled"] !== null ? { compiled: row["compiled"] } : {},
+		...isRecord(row["inputSchema"]) ? { inputSchema: row["inputSchema"] } : {}
+	};
+}
+function triggerOf(row) {
+	return {
+		id: textOf(row["id"]),
+		definition: textOf(row["definition"]),
+		kind: enumOrThrow(row["kind"], TRIGGER_KINDS, "trigger kind"),
+		config: recordOrEmpty(row["config"]),
+		enabled: row["enabled"] !== false,
+		createdAt: requiredInstant(row["createdAt"], "createdAt"),
+		updatedAt: requiredInstant(row["updatedAt"], "updatedAt")
+	};
+}
+function refOf(value) {
+	if (!isRecord(value) || typeof value["provider"] !== "string") throw new TypeError("workflow-builder: a credential_ref has no provider");
+	return {
+		...value,
+		provider: value["provider"]
+	};
+}
+function credentialOf(row) {
+	return {
+		id: textOf(row["id"]),
+		tenant: optionalText(row["tenant"]),
+		kind: textOf(row["kind"]),
+		name: textOf(row["name"]),
+		ref: refOf(row["ref"]),
+		scopes: Array.isArray(row["scopes"]) ? stringsOf(row["scopes"]) : [],
+		createdBy: optionalText(row["createdBy"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt")
+	};
+}
+function stepOf(row) {
+	return {
+		name: textOf(row["name"]),
+		title: textOf(row["title"]),
+		description: optionalText(row["description"]),
+		inputSchema: recordOrEmpty(row["inputSchema"]),
+		outputSchema: recordOrEmpty(row["outputSchema"]),
+		credentialKind: optionalText(row["credentialKind"]),
+		operation: optionalText(row["operation"])
+	};
+}
+function nodeRunOf(row) {
+	return {
+		run: textOf(row["run"]),
+		node: textOf(row["node"]),
+		status: enumOrThrow(row["status"], NODE_RUN_STATUSES, "node status"),
+		attempts: Number(row["attempts"] ?? 0),
+		output: row["output"] ?? void 0,
+		error: optionalText(row["error"]),
+		startedAt: optionalInstant(row["startedAt"]),
+		endedAt: optionalInstant(row["endedAt"])
+	};
+}
+function alertOf(row) {
+	const threshold = row["threshold"];
+	return {
+		id: textOf(row["id"]),
+		definition: textOf(row["definition"]),
+		onEvent: row["onEvent"] === "slow" ? "slow" : "failed",
+		threshold: threshold === null || threshold === void 0 ? void 0 : Number(threshold),
+		channel: recordOrEmpty(row["channel"]),
+		createdBy: optionalText(row["createdBy"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt")
+	};
+}
+/** `map` over an object result, or `undefined` for anything else. */
+function optionalOf(map) {
+	return (value) => isRecord(value) ? map(value) : void 0;
+}
+//#endregion
+//#region src/blocks/workflow-builder/publisher.ts
+const forbidden = (message, hint, permissions) => dbError("forbidden", message, {
+	hint,
+	...permissions === void 0 ? {} : { permissions }
+});
+/**
+* The claims a step runs with when the app passes no `automation.runAs`:
+* the checked publisher (a user or the tenant's service principal), capped
+* to the version's stored permissions.
+*/
+function defaultClaims(automation, publisher) {
+	return {
+		role: "authenticated",
+		sub: publisher,
+		...automation.tenant === null ? {} : { tenant_id: automation.tenant },
+		[PERMISSION_CAP_CLAIM]: automation.permissions
+	};
+}
+/** A hook's answer, with a throw or a rejection as `undefined`. */
+async function settled(run) {
+	try {
+		return await run();
+	} catch {
+		return;
+	}
+}
+/**
+* Asks `automation.mayPublish` about `version` as the caller: `undefined`
+* when it allows the publish, the refusal otherwise. Without claims, or when
+* the hook refuses or throws, the publish is refused.
+*/
+function mayPublishRefusal(call, mayPublish, version, claims) {
+	return call("workflow_definition_get", { definition: version.definition }, (value) => definitionOf(recordOf(value, "workflow_definition_get")).tenant ?? null).andThen(async (tenant) => {
+		if (claims === void 0) return ok(forbidden("Pass the publisher's claims to versions.publish: authorization.automation.mayPublish decides this publish", "WORKFLOW_PUBLISHER_FORBIDDEN"));
+		const permissions = await call("workflow_graph_permissions", { graph: version.graph ?? graphOf(void 0) }, (value) => Array.isArray(value) ? stringsOf(value) : []);
+		if (!permissions.ok) return permissions;
+		const sub = claims["sub"];
+		const allowed = await settled(() => mayPublish({
+			publisher: typeof sub === "string" ? sub : null,
+			tenant,
+			permissions: permissions.data,
+			claims
+		}));
+		return ok(allowed === true ? void 0 : forbidden("The authorization provider refused to publish this workflow", "WORKFLOW_PUBLISHER_FORBIDDEN", permissions.data));
+	});
+}
+/**
+* The claims a step of `version` runs with: `workflow_run_principal` checks
+* the stored publisher, then `runAs` narrows their claims. `tenant` is the
+* one a system definition's run belongs to. Every refusal is an error;
+* nothing falls back to the service role.
+*/
+function runAsPublisher(serviceCall, runAs, version, tenant) {
+	if (version === void 0) return AsyncResult.err(dbError("invalid_request", "The step call has no version id: pass meta.versionId to the graph runtime as version"));
+	return serviceCall("workflow_run_principal", {
+		version,
+		tenant
+	}, (value) => {
+		const row = recordOf(value, "workflow_run_principal");
+		return {
+			publisher: optionalText(row["publisher"]) ?? null,
+			tenant: optionalText(row["tenant"]) ?? null,
+			permissions: Array.isArray(row["permissions"]) ? stringsOf(row["permissions"]) : []
+		};
+	}).andThen(async (automation) => {
+		if (runAs === void 0) {
+			if (automation.publisher === null) return err(forbidden("Install the service-principals module or pass automation.runAs to createWorkflowBuilder: an organization's workflow runs as its service principal", "WORKFLOW_PUBLISHER_REVOKED"));
+			return ok(defaultClaims(automation, automation.publisher));
+		}
+		const claims = await settled(() => runAs(automation));
+		if (claims === void 0 || claims === null || !isRecord(claims)) return err(forbidden(automation.publisher === null ? "The app has no service principal for this organization's workflow" : "The user who published this workflow can no longer run it", "WORKFLOW_PUBLISHER_REVOKED"));
+		return ok(claims);
+	});
+}
+//#endregion
+//#region src/blocks/workflow-builder/workflow-builder.ts
+const BUILDER_PREFIX = "builder:";
+/**
+* The `workflow-builder` module's definitions, versions, triggers,
+* credentials, step library, node runs and alerts. The engine plugs in
+* through `compile` and `start`; credential rows resolve through the
+* `credentials` providers.
+*
+* ```ts
+* const builder = createWorkflowBuilder({
+*   transport: rpcTransport(supabase),
+*   compile: compileGraph,
+*   start: graphStarter({ executor: builderWorkflow, steps: { runNode } }),
+* });
+* ```
+*/
+function createWorkflowBuilder(options) {
+	applyTemporal(options);
+	const fields = blockFields(options.fields, "workflow definition fields");
+	injectableOf("workflow-builder compiler", options.compile);
+	injectableOf("workflow-builder starter", options.start);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const serviceCall = blockCall(options.service ?? options.transport, options.schema, options.mappers);
+	const providers = options.credentials === void 0 ? [] : Array.isArray(options.credentials) ? options.credentials : [options.credentials];
+	const providerFor = (ref) => providers.find((provider) => provider.name === ref.provider);
+	const noProvider = (ref) => dbError("invalid_request", `No credential provider named "${ref.provider}" was passed to createWorkflowBuilder`);
+	const getVersion = (version) => call("workflow_version_get", { version }, optionalOf(versionOf));
+	const startTarget = (caller, input, start) => (input.subject === void 0 ? caller("workflow_start_target", {
+		definition: input.definition,
+		tenant: input.tenant
+	}, (value) => recordOf(value, "workflow_start_target")) : caller("workflow_subject_start_target", {
+		definition: input.definition,
+		subject_type: input.subject.type,
+		subject_id: input.subject.id,
+		tenant: input.tenant
+	}, (value) => recordOf(value, "workflow_subject_start_target"))).andThen(async (row) => ok(await start(startTargetOf(row))));
+	const starterOf = () => options.start;
+	const missingStarter = () => dbError("invalid_request", "Pass `start` to createWorkflowBuilder to run workflows");
+	const runWith = (caller, input) => {
+		const start = starterOf();
+		if (start === void 0) return AsyncResult.err(missingStarter());
+		return startTarget(caller, {
+			definition: input.definition,
+			tenant: input.tenant,
+			subject: input.subject
+		}, (target) => {
+			const node = input.trigger?.config["node"];
+			return start({
+				definition: target.definition,
+				version: target.version,
+				input: input.input ?? {},
+				tenant: target.tenant,
+				actor: input.actor,
+				idempotencyKey: input.idempotencyKey ?? `run:${randomToken(16)}`,
+				...input.trigger === void 0 ? {} : { trigger: input.trigger },
+				...target.subject === void 0 ? {} : { subject: target.subject },
+				...typeof node === "string" ? { triggerNode: node } : {}
+			});
+		});
+	};
+	const grant = (input, granted) => call("set_workflow_definition_grant", {
+		definition: input.definition,
+		principal_kind: input.principalKind,
+		principal_id: input.principalId,
+		action: input.action,
+		granted
+	}, (value) => value === true);
+	const credentialRow = (id) => serviceCall("workflow_credential_get", { credential: id }, (value) => isRecord(value) ? credentialOf(value) : void 0);
+	return hooked({
+		definitions: {
+			save: (input) => fields.args(input.fields).andThen((checked) => call("save_workflow_definition", {
+				tenant: input.tenant,
+				slug: input.slug,
+				name: input.name,
+				description: input.description,
+				subject_types: input.subjectTypes,
+				scope: input.scope,
+				restricted: input.restricted,
+				fields: checked
+			}, (value) => definitionOf(recordOf(value, "save_workflow_definition"))).andThen(fields.row)),
+			list: (tenant, filter = {}) => call("workflow_definitions_list", {
+				tenant,
+				subject_type: filter.subjectType
+			}, (value) => recordsOf(value, "workflow_definitions_list").map(definitionOf)).andThen(fields.rows),
+			get: (id) => call("workflow_definition_get", { definition: id }, optionalOf(definitionOf)).andThen((definition) => definition === void 0 ? AsyncResult.ok(void 0) : fields.row(definition)),
+			remove: (id) => call("remove_workflow_definition", { definition: id }, (value) => value === true),
+			fork: (input) => call("fork_workflow_definition", {
+				source: input.source,
+				tenant: input.tenant,
+				slug: input.slug
+			}, (value) => definitionOf(recordOf(value, "fork_workflow_definition"))).andThen(fields.row),
+			optOut: (input) => call("set_workflow_opt_out", {
+				tenant: input.tenant,
+				definition: input.definition,
+				opted_out: input.optedOut ?? true
+			}, (value) => value === true),
+			grants: {
+				add: (input) => grant(input, true),
+				remove: (input) => grant(input, false).map(() => true),
+				list: (definition) => call("workflow_definition_grants_list", { definition }, (value) => recordsOf(value, "workflow_definition_grants_list").map(grantOf))
+			}
+		},
+		versions: {
+			save: (definition, graph, saveOptions = {}) => call("save_workflow_draft", {
+				definition,
+				graph,
+				...saveOptions.inputSchema === void 0 ? {} : { input_schema: saveOptions.inputSchema }
+			}, (value) => versionOf(recordOf(value, "save_workflow_draft"))),
+			publish: (version, publishOptions = {}) => getVersion(version).andThen(async (found) => {
+				if (found === void 0) return err(dbError("not_found", "No such workflow version"));
+				const mayPublish = options.authorization?.automation?.mayPublish;
+				if (mayPublish !== void 0 && found.status !== "published") {
+					const refusal = await mayPublishRefusal(call, mayPublish, found, publishOptions.claims);
+					if (!refusal.ok) return refusal;
+					if (refusal.data !== void 0) return err(refusal.data);
+				}
+				let compiled = null;
+				if (options.compile !== void 0 && found.status !== "published") try {
+					compiled = await options.compile(found.graph ?? graphOf(void 0)) ?? null;
+				} catch (cause) {
+					return err(dbError("invalid_input", cause instanceof Error ? cause.message : String(cause)));
+				}
+				const publish = (caller, stored) => caller("publish_workflow_version", {
+					version,
+					compiled: stored
+				}, (value) => versionOf(recordOf(value, "publish_workflow_version")));
+				const result = await publish(call, null);
+				if (!result.ok || compiled === null || options.service === void 0) return result;
+				return publish(serviceCall, compiled);
+			}),
+			list: (definition) => call("workflow_versions_list", { definition }, (value) => recordsOf(value, "workflow_versions_list").map(versionOf)),
+			get: getVersion,
+			runAs: (version, tenant) => runAsPublisher(serviceCall, options.authorization?.automation?.runAs, version, tenant),
+			diff: (from, to) => getVersion(from).andThen(async (before) => {
+				const after = await getVersion(to);
+				if (!after.ok) return after;
+				if (before === void 0 || after.data === void 0) return err(dbError("not_found", "No such workflow version"));
+				return ok(diffGraphs(before.graph ?? graphOf(void 0), after.data.graph ?? graphOf(void 0)));
+			})
+		},
+		run: (input) => runWith(call, input),
+		test: (input) => {
+			const start = starterOf();
+			if (start === void 0) return AsyncResult.err(missingStarter());
+			return call("start_test_run", {
+				definition: input.definition,
+				version: input.version,
+				trigger_node: input.triggerNode,
+				input: input.input ?? {},
+				stubs: input.stubs ?? {}
+			}, (value) => recordOf(value, "start_test_run")).andThen(async (row) => {
+				const target = startTargetOf(row);
+				const subject = input.subject;
+				if (subject !== void 0 && !target.definition.subjectTypes.includes(subject.type)) return err(dbError("invalid_input", "This workflow doesn't run on that subject type", { hint: "WORKFLOW_SUBJECT_TYPE" }));
+				const node = row["triggerNode"];
+				return ok(await start({
+					definition: target.definition,
+					version: target.version,
+					input: row["input"] ?? {},
+					tenant: target.tenant,
+					actor: void 0,
+					idempotencyKey: `test:${randomToken(16)}`,
+					mode: "test",
+					stubs: {
+						...exampleStubs(target.version, options.steps ?? []),
+						...isRecord(row["stubs"]) ? row["stubs"] : {}
+					},
+					...typeof node === "string" ? { triggerNode: node } : {},
+					...subject === void 0 ? {} : { subject }
+				}));
+			});
+		},
+		triggers: {
+			save: (input) => {
+				const problem = input.kind === "event" ? triggerWhenProblem(input.config ?? {}) : void 0;
+				if (problem !== void 0) return AsyncResult.err(dbError("invalid_input", problem));
+				return call("save_workflow_trigger", {
+					definition: input.definition,
+					kind: input.kind,
+					config: input.config ?? {},
+					enabled: input.enabled ?? true,
+					trigger: input.id
+				}, (value) => triggerOf(recordOf(value, "save_workflow_trigger")));
+			},
+			list: (definition) => call("workflow_triggers_list", { definition }, (value) => recordsOf(value, "workflow_triggers_list").map(triggerOf)),
+			remove: (id) => call("remove_workflow_trigger", { trigger: id }, (value) => value === true),
+			rotateToken: (id) => call("rotate_workflow_webhook_token", { trigger: id }, textOf),
+			webhook: async (request) => {
+				if (request.method !== "POST") return Response.json({ error: "Method not allowed" }, {
+					status: 405,
+					headers: { allow: "POST" }
+				});
+				const token = webhookToken(request);
+				if (token === void 0) return Response.json({ error: "Not found" }, { status: 404 });
+				const target = await serviceCall("workflow_webhook_target", { token }, (value) => isRecord(value) ? value : void 0);
+				if (!target.ok) return Response.json({ error: target.error.message }, { status: 500 });
+				if (target.data === void 0) return Response.json({ error: "Not found" }, { status: 404 });
+				const trigger = triggerOf(recordOf(target.data["trigger"], "trigger"));
+				const key = request.headers.get("idempotency-key");
+				const started = await runWith(serviceCall, {
+					definition: trigger.definition,
+					input: await bodyOf(request),
+					idempotencyKey: key === null || key.length === 0 ? `webhook:${trigger.id}:${randomToken(16)}` : `webhook:${trigger.id}:${key}`,
+					trigger
+				});
+				return started.ok ? Response.json({ runId: started.data }, { status: 202 }) : Response.json({ error: started.error.message }, { status: started.error.status });
+			},
+			onEvent: (event) => serviceCall("workflow_event_targets", {
+				type: event.type,
+				tenant: event.tenant
+			}, (value) => recordsOf(value, "workflow_event_targets")).andThen(async (rows) => {
+				const runs = [];
+				for (const row of rows) {
+					const trigger = triggerOf(recordOf(row["trigger"], "trigger"));
+					if (!triggerMatches(trigger.config, event)) continue;
+					const subject = eventSubject(event, stringsOf(row["subjectTypes"]));
+					const tenant = optionalText(row["tenant"]);
+					const started = await runWith(serviceCall, {
+						definition: trigger.definition,
+						input: event.payload ?? {},
+						idempotencyKey: `event:${trigger.id}:${event.id}`,
+						trigger,
+						...event.actorId == null ? {} : { actor: event.actorId },
+						...tenant === void 0 ? {} : { tenant },
+						...subject === void 0 ? {} : { subject }
+					});
+					if (!started.ok) return started;
+					runs.push(started.data);
+				}
+				return ok(runs);
+			}),
+			syncSchedule: (trigger, tenant) => {
+				const cron = trigger.config["cron"];
+				if (trigger.kind !== "schedule" || typeof cron !== "string") return AsyncResult.err(dbError("invalid_input", "Only a schedule trigger with config.cron has a schedule"));
+				const timezone = trigger.config["timezone"];
+				const workflows = options.workflows;
+				if (workflows === void 0) return AsyncResult.err(dbError("invalid_request", "createWorkflowBuilder needs the workflows block to sync a schedule", { hint: "WORKFLOW_BUILDER_WORKFLOWS_CLIENT" }));
+				return workflows.schedules.create({
+					name: `builder-trigger:${trigger.id}`,
+					workflow: `${BUILDER_PREFIX}${trigger.definition}`,
+					cron,
+					...typeof timezone === "string" ? { timezone } : {},
+					input: trigger.config["input"] ?? {},
+					...tenant === void 0 ? {} : { tenant }
+				});
+			},
+			starter: (fallback) => async (scheduled) => {
+				if (!scheduled.workflow.startsWith(BUILDER_PREFIX)) {
+					if (fallback === void 0) throw new Error(`better-supabase: no starter for workflow "${scheduled.workflow}"`);
+					return fallback(scheduled);
+				}
+				const started = await runWith(serviceCall, {
+					definition: scheduled.workflow.slice(8),
+					input: scheduled.input,
+					idempotencyKey: scheduled.idempotencyKey,
+					...scheduled.actor === void 0 ? {} : { actor: scheduled.actor },
+					...scheduled.tenant === void 0 ? {} : { tenant: scheduled.tenant },
+					...scheduled.subject === void 0 ? {} : { subject: scheduled.subject }
+				});
+				if (!started.ok && started.error.hint === "WORKFLOW_OPTED_OUT") return "";
+				return AsyncResult.from(() => Promise.resolve(started)).orThrow();
+			}
+		},
+		credentials: {
+			list: (tenant) => call("workflow_credentials_list", { tenant }, (value) => recordsOf(value, "workflow_credentials_list").map(credentialOf)),
+			create: (input) => {
+				const save = () => call("save_workflow_credential", {
+					tenant: input.tenant,
+					kind: input.kind,
+					name: input.name,
+					ref: input.ref,
+					scopes: input.scopes ?? []
+				}, (value) => credentialOf(recordOf(value, "save_workflow_credential")));
+				if (input.secret === void 0) return save();
+				if (!credentialRefInTenant(input.ref, input.tenant)) return AsyncResult.err(foreignCredentialRef(input.tenant));
+				const provider = providerFor(input.ref);
+				if (provider === void 0) return AsyncResult.err(noProvider(input.ref));
+				if (provider.set === void 0) return AsyncResult.err(dbError("unsupported", `The credential provider "${provider.name}" can't store secrets`));
+				return provider.set(input.ref, input.secret, { subject: { type: "app" } }).andThen(() => save());
+			},
+			authorize: (id, authorize) => credentialRow(id).andThen(async (row) => {
+				if (row === void 0) return err(dbError("not_found", "No such credential"));
+				const provider = providerFor(row.ref);
+				if (provider === void 0) return err(noProvider(row.ref));
+				if (provider.startAuthorization === void 0 || !provider.capabilities(row.ref).authorization) return err(dbError("unsupported", `The credential provider "${provider.name}" doesn't authorize accounts`));
+				return provider.startAuthorization(row.ref, {
+					subject: { type: "app" },
+					redirectUri: authorize.redirectUri,
+					scopes: row.scopes,
+					...authorize.state === void 0 ? {} : { state: authorize.state }
+				}).map((started) => started.url);
+			}),
+			revoke: (id) => call("remove_workflow_credential", { credential: id }, (value) => isRecord(value) ? credentialOf(value) : void 0).andThen(async (row) => {
+				if (row === void 0) return ok(false);
+				if (!credentialRefInTenant(row.ref, row.tenant)) return ok(true);
+				const provider = providerFor(row.ref);
+				if (provider === void 0) return err(noProvider(row.ref));
+				if (!provider.capabilities(row.ref).revoke) return ok(true);
+				const revoked = await provider.revoke(row.ref, { subject: { type: "app" } });
+				return revoked.ok ? ok(true) : revoked;
+			}),
+			resolve: (id) => credentialRow(id).andThen(async (row) => {
+				if (row === void 0) return err(dbError("not_found", "No such credential"));
+				if (!credentialRefInTenant(row.ref, row.tenant)) return err(foreignCredentialRef(row.tenant));
+				const provider = providerFor(row.ref);
+				if (provider === void 0) return err(noProvider(row.ref));
+				return provider.getToken(row.ref, {
+					subject: { type: "app" },
+					scopes: row.scopes
+				});
+			})
+		},
+		steps: {
+			sync: (steps = options.steps ?? []) => serviceCall("sync_workflow_steps", { steps: Object.fromEntries(steps.map((step) => [step.name, {
+				title: step.title,
+				description: step.description,
+				inputSchema: step.inputSchema ?? {},
+				outputSchema: step.outputSchema ?? {},
+				credentialKind: step.credentialKind,
+				operation: step.operation
+			}])) }, Number),
+			list: () => call("workflow_steps_list", {}, (value) => recordsOf(value, "workflow_steps_list").map(stepOf))
+		},
+		nodeRuns: {
+			record: (input) => serviceCall("record_workflow_node_run", {
+				run: input.run,
+				node: input.node,
+				status: input.status,
+				attempt: input.attempt,
+				output: input.output,
+				error: input.error
+			}, (value) => value === true),
+			list: (run) => call("workflow_node_runs_list", { run }, (value) => recordsOf(value, "workflow_node_runs_list").map(nodeRunOf))
+		},
+		alerts: {
+			save: (input) => call("save_workflow_alert", {
+				definition: input.definition,
+				on_event: input.onEvent,
+				channel: input.channel ?? {},
+				threshold: input.threshold === void 0 ? void 0 : seconds(input.threshold),
+				alert: input.id
+			}, (value) => alertOf(recordOf(value, "save_workflow_alert"))),
+			list: (definition) => call("workflow_alerts_list", { definition }, (value) => recordsOf(value, "workflow_alerts_list").map(alertOf)),
+			remove: (id) => call("remove_workflow_alert", { alert: id }, (value) => value === true),
+			check: (check = {}) => serviceCall("check_workflow_alerts", { batch: check.batch }, Number)
+		}
+	}, options);
+}
+/** The builder with `options.hooks` around `run`, `test` and each group's methods. */
+function hooked(builder, options) {
+	const hooks = options.hooks;
+	if (hooks === void 0) return builder;
+	const logger = options.logger ? { logger: options.logger } : {};
+	const block = (group) => ({
+		block: `workflow-builder.${group}`,
+		...logger
+	});
+	const top = withBlockHooks({
+		run: (input) => builder.run(input),
+		test: (input) => builder.test(input)
+	}, {
+		...hooks.run === void 0 ? {} : { run: hooks.run },
+		...hooks.test === void 0 ? {} : { test: hooks.test }
+	}, {
+		block: "workflow-builder",
+		...logger
+	});
+	return {
+		...builder,
+		run: top.run,
+		test: top.test,
+		definitions: withBlockHooks(builder.definitions, hooks.definitions, block("definitions")),
+		versions: withBlockHooks(builder.versions, hooks.versions, block("versions")),
+		triggers: withBlockHooks(builder.triggers, hooks.triggers, block("triggers")),
+		credentials: withBlockHooks(builder.credentials, hooks.credentials, block("credentials")),
+		steps: withBlockHooks(builder.steps, hooks.steps, block("steps")),
+		nodeRuns: withBlockHooks(builder.nodeRuns, hooks.nodeRuns, block("nodeRuns")),
+		alerts: withBlockHooks(builder.alerts, hooks.alerts, block("alerts"))
+	};
+}
+/**
+* A test run's default stubs: each step node's library `outputSchema`
+* example (its first `examples` entry, else its `default`).
+*/
+function exampleStubs(version, steps) {
+	const schemas = new Map(steps.map((step) => [step.name, step.outputSchema]));
+	const stubs = {};
+	for (const node of version.graph?.nodes ?? []) {
+		if (node.kind !== "step" || node.step === void 0) continue;
+		const schema = schemas.get(node.step);
+		if (schema === void 0) continue;
+		const examples = schema["examples"];
+		if (Array.isArray(examples) && examples.length > 0) stubs[node.id] = examples[0];
+		else if (Object.hasOwn(schema, "default")) stubs[node.id] = schema["default"];
+	}
+	return stubs;
+}
+function startTargetOf(row) {
+	const definition = definitionOf(recordOf(row["definition"], "definition"));
+	const subject = isRecord(row["subject"]) ? row["subject"] : void 0;
+	return {
+		definition,
+		version: versionOf(recordOf(row["version"], "version")),
+		tenant: "tenant" in row ? optionalText(row["tenant"]) : definition.tenant,
+		subject: subject === void 0 ? void 0 : {
+			type: textOf(subject["type"]),
+			id: textOf(subject["id"])
+		}
+	};
+}
+/**
+* A subject event's record (the event's `subjectType` and `subjectId`, else
+* its payload's), when the definition runs on its type.
+*/
+function eventSubject(event, subjectTypes) {
+	const payload = isRecord(event.payload) ? event.payload : {};
+	const type = event.subjectType ?? payload["subjectType"];
+	const id = event.subjectId ?? payload["subjectId"];
+	return typeof type === "string" && typeof id === "string" && subjectTypes.includes(type) ? {
+		type,
+		id
+	} : void 0;
+}
+function webhookToken(request) {
+	const header = request.headers.get("authorization");
+	if (header !== null && /^bearer\s+/i.test(header)) {
+		const token = header.replace(/^bearer\s+/i, "").trim();
+		return token.length > 0 ? token : void 0;
+	}
+	const segment = new URL(request.url).pathname.split("/").findLast(Boolean);
+	return segment?.startsWith("wfh_") === true ? decodeURIComponent(segment) : void 0;
+}
+async function bodyOf(request) {
+	const text = await request.text();
+	if (text.length === 0) return {};
+	try {
+		return JSON.parse(text);
+	} catch {
+		return { body: text };
+	}
+}
+//#endregion
+export { createWorkflowBuilder as t };