better-supabase 0.8.0 → 0.9.0

package/dist/workflow-sdk/world/index.js

@@ -1,15 +1,18 @@
-import { n as dbError } from "../../errors-2M6CKMP4.js";
-import { o as problemResponse } from "../../problem-CJvFeGu7.js";
-import { i as sqlIdent } from "../../template-lPVh-EwW.js";
+import { n as dbError } from "../../errors-8i6tSICm.js";
+import { o as problemResponse } from "../../problem-pIiL3WbE.js";
+import { i as sqlIdent } from "../../template-DdgYjIZ5.js";
 import { n as hmacHex, r as timingSafeEqual } from "../../hmac-DCud0myt.js";
-import { n as memoized } from "../../optional-peer-D1pi-skw.js";
-import { i as WORLD_POSTGRES_VERSION, r as WORKFLOW_VAULT_SECRETS } from "../../workflow-sdk-world-CMV1ahFW.js";
+import { t as watchPoolErrors } from "../../pool-errors-GMjlCN0d.js";
+import { n as memoized } from "../../optional-peer-Dx8TaYXw.js";
+import { i as WORLD_POSTGRES_VERSION, r as WORKFLOW_VAULT_SECRETS } from "../../workflow-sdk-world-DPMdBfzn.js";
 import { Pool } from "pg";
 import { reenqueueActiveRuns } from "@workflow/world";
 import { createWorld as createWorld$1 } from "@workflow/world-postgres";
 //#region src/workflow-sdk/world/analytics.ts
 /** world-postgres stores UTC in `timestamp without time zone` columns. */
 const utc = (column) => `(${column} at time zone 'UTC')`;
+/** The column every keyset query adds: the row's sort key as `text[]`. */
+const CURSOR = "__cursor";
 const RUN_COLUMNS = `
   r.id as "runId", r.status::text as status, r.deployment_id as "deploymentId",
   r.name as "workflowName", nullif(r.spec_version, '')::int as "specVersion",
@@ -56,37 +59,63 @@ const HOOKS = `
     ${utc("max(e.created_at)")} as "updatedAt",
     ${utc("max(e.created_at) filter (where e.type = 'hook_received')")} as "receivedAt",
     ${utc("max(e.created_at) filter (where e.type = 'hook_disposed')")} as "disposedAt",
-    bool_or(h.is_webhook) as "isWebhook", bool_or(h.is_system) as "isSystem"
+    bool_or(h.is_webhook) as "isWebhook", bool_or(h.is_system) as "isSystem",
+    ${cursorColumn(["min(e.created_at)", "e.correlation_id"])}
   from workflow.workflow_events e
   left join workflow.workflow_hooks h on h.hook_id = e.correlation_id
   where e.type like 'hook\\_%' and e.correlation_id is not null`;
-function page(pagination, max) {
+function encodeCursor(key) {
+	return Buffer.from(JSON.stringify(key)).toString("base64url");
+}
+function decodeCursor(cursor, width) {
+	let key;
+	try {
+		key = JSON.parse(Buffer.from(cursor, "base64url").toString("utf-8"));
+	} catch {
+		key = void 0;
+	}
+	if (!Array.isArray(key) || key.length !== width || !key.every((part) => typeof part === "string")) throw new RangeError("better-supabase: not an analytics cursor; pass the cursor of the previous page");
+	return key;
+}
+function page(pagination, max, width) {
 	const limit = Math.min(max, Math.max(1, pagination?.limit ?? max));
 	if (pagination?.limit !== void 0 && pagination.limit > max) throw new RangeError(`better-supabase: the analytics page limit is ${String(max)}, got ${String(pagination.limit)}`);
-	const offset = Number(pagination?.cursor ?? 0);
+	const cursor = pagination?.cursor;
 	return {
 		limit,
-		offset: Number.isSafeInteger(offset) && offset > 0 ? offset : 0,
+		after: cursor === void 0 || cursor === "" ? void 0 : decodeCursor(cursor, width),
 		order: pagination?.sortOrder === "asc" ? "asc" : "desc"
 	};
 }
-function paged(rows, limit, offset) {
-	const hasMore = rows.length > limit;
-	return {
-		data: rows.slice(0, limit),
-		hasMore,
-		cursor: hasMore ? String(offset + limit) : null
-	};
+/**
+* ` and (a, b) > ($n, $m)` past the previous page's last row, `<` when the
+* order is descending. The row comparison uses an index on `(a, b)`.
+*/
+function keyset(columns, { after, order }, values) {
+	if (after === void 0) return "";
+	const params = after.map((part) => {
+		values.push(part);
+		return `$${String(values.length)}`;
+	});
+	return ` and (${columns.join(", ")}) ${order === "asc" ? ">" : "<"} (${params.join(", ")})`;
 }
-/** Converts SQL nulls to the optional fields the analytics schemas allow. */
+/** `array[...]::text[] as "__cursor"`: the sort key a page's cursor carries. */
+function cursorColumn(columns) {
+	return `array[${columns.map((column) => `(${column})::text`).join(", ")}] as "${CURSOR}"`;
+}
+/** Converts SQL nulls to the optional fields the analytics schemas allow, and drops the cursor column. */
 function compact(row) {
 	const out = {};
-	for (const [key, value] of Object.entries(row)) if (value !== null) out[key] = value;
+	for (const [key, value] of Object.entries(row)) if (value !== null && key !== CURSOR) out[key] = value;
 	return out;
 }
 function notFound(what, id) {
 	return /* @__PURE__ */ new Error(`better-supabase: workflow ${what} "${id}" not found`);
 }
+const RUN_KEY = ["r.created_at", "r.id"];
+const STEP_KEY = ["s.created_at", "s.step_id"];
+const WAIT_KEY = ["w.created_at", "w.wait_id"];
+const HOOK_KEY = ["min(e.created_at)", "e.correlation_id"];
 const RUN_SCOPED_LIMIT = 1e3;
 const LIMIT = 100;
 const MAX_ATTRIBUTE_FILTERS = 8;
@@ -99,6 +128,16 @@ function createAnalytics(pool) {
 	const rows = async (sql, params) => {
 		return (await pool.query(sql, [...params])).rows.map((row) => compact(row));
 	};
+	const paged = async (sql, params, limit) => {
+		const raw = (await pool.query(sql, [...params])).rows.map((row) => row);
+		const hasMore = raw.length > limit;
+		const key = raw[limit - 1]?.[CURSOR];
+		return {
+			data: raw.slice(0, limit).map((row) => compact(row)),
+			hasMore,
+			cursor: hasMore && Array.isArray(key) ? encodeCursor(key.map(String)) : null
+		};
+	};
 	const one = async (sql, params, what, id) => {
 		const [row] = await rows(sql, params);
 		if (row === void 0) throw notFound(what, id);
@@ -111,7 +150,7 @@ function createAnalytics(pool) {
 		return ` and ${utc(column)} between $${String(values.length - 1)}::timestamptz and $${String(values.length)}::timestamptz`;
 	};
 	const listEvents = async (params) => {
-		const { limit, offset, order } = page(params.pagination, RUN_SCOPED_LIMIT);
+		const current = page(params.pagination, RUN_SCOPED_LIMIT, 1);
 		const values = [params.runId];
 		let where = "e.run_id = $1";
 		if (params.eventType !== void 0) {
@@ -122,17 +161,19 @@ function createAnalytics(pool) {
 			values.push(params.correlationId);
 			where += ` and e.correlation_id = $${String(values.length)}`;
 		}
-		values.push(limit + 1, offset);
-		return paged(await rows(`select ${EVENT_COLUMNS} from workflow.workflow_events e
+		where += keyset(["e.id"], current, values);
+		values.push(current.limit + 1);
+		return paged(`select ${EVENT_COLUMNS}, ${cursorColumn(["e.id"])}
+       from workflow.workflow_events e
        join workflow.workflow_runs r on r.id = e.run_id
-       where ${where} order by e.id ${order}
-       limit $${String(values.length - 1)} offset $${String(values.length)}`, values), limit, offset);
+       where ${where} order by e.id ${current.order}
+       limit $${String(values.length)}`, values, current.limit);
 	};
 	return {
 		runs: {
 			get: (runId) => one(`select ${RUN_COLUMNS} from workflow.workflow_runs r where r.id = $1`, [runId], "run", runId),
 			async list(params = {}) {
-				const { limit, offset, order } = page(params.pagination, LIMIT);
+				const current = page(params.pagination, LIMIT, 2);
 				const values = [];
 				let where = "true";
 				if (params.workflowName !== void 0) {
@@ -149,14 +190,19 @@ function createAnalytics(pool) {
 					where += ` and r.attributes @> $${String(values.length)}::jsonb`;
 				}
 				where += window(params, "r.updated_at", values);
-				values.push(limit + 1, offset);
-				return paged(await rows(`select ${RUN_COLUMNS} from workflow.workflow_runs r where ${where}
-           order by r.created_at ${order}, r.id ${order}
-           limit $${String(values.length - 1)} offset $${String(values.length)}`, values), limit, offset);
+				where += keyset(RUN_KEY, current, values);
+				values.push(current.limit + 1);
+				return paged(`select ${RUN_COLUMNS}, ${cursorColumn(RUN_KEY)}
+           from workflow.workflow_runs r where ${where}
+           order by r.created_at ${current.order}, r.id ${current.order}
+           limit $${String(values.length)}`, values, current.limit);
 			}
 		},
 		attributes: { async list(params = {}) {
-			const { limit, offset } = page(params.pagination, LIMIT);
+			const current = {
+				...page(params.pagination, LIMIT, 1),
+				order: "asc"
+			};
 			const values = [];
 			let where = "true";
 			if (params.workflowName !== void 0) {
@@ -164,26 +210,29 @@ function createAnalytics(pool) {
 				where += ` and r.name = $${String(values.length)}`;
 			}
 			where += window(params, "r.updated_at", values);
-			values.push(limit + 1, offset);
-			return paged(await rows(`select k.key, count(*)::int as "runCount",
+			where += keyset(["k.key"], current, values);
+			values.push(current.limit + 1);
+			return paged(`select k.key, count(*)::int as "runCount",
              ${utc("min(r.created_at)")} as "firstSeenAt",
-             ${utc("max(r.updated_at)")} as "lastSeenAt"
+             ${utc("max(r.updated_at)")} as "lastSeenAt",
+             ${cursorColumn(["k.key"])}
            from workflow.workflow_runs r
            cross join lateral jsonb_object_keys(coalesce(r.attributes, '{}'::jsonb)) as k(key)
            where ${where}
            group by k.key order by k.key
-           limit $${String(values.length - 1)} offset $${String(values.length)}`, values), limit, offset);
+           limit $${String(values.length)}`, values, current.limit);
 		} },
 		steps: {
 			get: (runId, stepId) => one(`select ${STEP_COLUMNS} from workflow.workflow_steps s where s.run_id = $1 and s.step_id = $2`, [runId, stepId], "step", stepId),
 			async list(params) {
-				const { limit, offset, order } = page(params.pagination, RUN_SCOPED_LIMIT);
-				return paged(await rows(`select ${STEP_COLUMNS} from workflow.workflow_steps s where s.run_id = $1
-           order by s.created_at ${order}, s.step_id ${order} limit $2 offset $3`, [
-					params.runId,
-					limit + 1,
-					offset
-				]), limit, offset);
+				const current = page(params.pagination, RUN_SCOPED_LIMIT, 2);
+				const values = [params.runId];
+				const where = `s.run_id = $1${keyset(STEP_KEY, current, values)}`;
+				values.push(current.limit + 1);
+				return paged(`select ${STEP_COLUMNS}, ${cursorColumn(STEP_KEY)}
+           from workflow.workflow_steps s where ${where}
+           order by s.created_at ${current.order}, s.step_id ${current.order}
+           limit $${String(values.length)}`, values, current.limit);
 			}
 		},
 		events: {
@@ -209,30 +258,33 @@ function createAnalytics(pool) {
 			get: (hookId, params) => one(`${HOOKS} and e.correlation_id = $1 and ($2::text is null or e.run_id = $2)
            group by e.run_id, e.correlation_id`, [hookId, params?.runId ?? null], "hook", hookId),
 			async list(params) {
-				const { limit, offset, order } = page(params.pagination, LIMIT);
-				return paged(await rows(`${HOOKS} and e.run_id = $1 group by e.run_id, e.correlation_id
-           order by "createdAt" ${order}, "hookId" ${order} limit $2 offset $3`, [
-					params.runId,
-					limit + 1,
-					offset
-				]), limit, offset);
+				const current = page(params.pagination, LIMIT, 2);
+				const values = [params.runId];
+				const having = keyset(HOOK_KEY, current, values);
+				values.push(current.limit + 1);
+				return paged(`${HOOKS} and e.run_id = $1 group by e.run_id, e.correlation_id
+           having true${having}
+           order by min(e.created_at) ${current.order}, e.correlation_id ${current.order}
+           limit $${String(values.length)}`, values, current.limit);
 			}
 		},
 		waits: {
 			get: (runId, waitId) => one(`select ${WAIT_COLUMNS} from workflow.workflow_waits w
            where w.run_id = $1 and w.wait_id in ($2::text, $1::text || '-' || $2::text)`, [runId, waitId], "wait", waitId),
 			async list(params) {
-				const { limit, offset, order } = page(params.pagination, RUN_SCOPED_LIMIT);
+				const current = page(params.pagination, RUN_SCOPED_LIMIT, 2);
 				const values = [params.runId];
 				let where = "w.run_id = $1";
 				if (params.status !== void 0) {
 					values.push(params.status);
 					where += ` and w.status::text = $${String(values.length)}`;
 				}
-				values.push(limit + 1, offset);
-				return paged(await rows(`select ${WAIT_COLUMNS} from workflow.workflow_waits w where ${where}
-           order by w.created_at ${order}, w.wait_id ${order}
-           limit $${String(values.length - 1)} offset $${String(values.length)}`, values), limit, offset);
+				where += keyset(WAIT_KEY, current, values);
+				values.push(current.limit + 1);
+				return paged(`select ${WAIT_COLUMNS}, ${cursorColumn(WAIT_KEY)}
+           from workflow.workflow_waits w where ${where}
+           order by w.created_at ${current.order}, w.wait_id ${current.order}
+           limit $${String(values.length)}`, values, current.limit);
 			}
 		}
 	};
@@ -286,6 +338,11 @@ function worldOptionsFromEnv(source = process.env) {
 	const namespace = read("WORKFLOW_QUEUE_NAMESPACE");
 	const concurrency = positiveInt(read("WORKFLOW_POSTGRES_WORKER_CONCURRENCY"));
 	const pollInterval = positiveInt(read("WORKFLOW_POSTGRES_POLL_INTERVAL_MS"));
+	const maxConnections = positiveInt(read("WORKFLOW_POSTGRES_MAX_CONNECTIONS"));
+	const connectionTimeout = positiveInt(read("WORKFLOW_POSTGRES_CONNECTION_TIMEOUT_MS"));
+	const idleTimeout = positiveInt(read("WORKFLOW_POSTGRES_IDLE_TIMEOUT_MS"));
+	const statementTimeout = positiveInt(read("WORKFLOW_POSTGRES_STATEMENT_TIMEOUT_MS"));
+	const idleInTransactionTimeout = positiveInt(read("WORKFLOW_POSTGRES_IDLE_IN_TRANSACTION_TIMEOUT_MS"));
 	return {
 		...connectionString === void 0 ? {} : { connectionString },
 		...delivery === void 0 ? {} : { delivery },
@@ -295,12 +352,17 @@ function worldOptionsFromEnv(source = process.env) {
 		...queue === void 0 ? {} : { queue },
 		...namespace === void 0 ? {} : { namespace },
 		...concurrency === void 0 ? {} : { concurrency },
-		...pollInterval === void 0 ? {} : { pollInterval }
+		...pollInterval === void 0 ? {} : { pollInterval },
+		...maxConnections === void 0 ? {} : { maxConnections },
+		...connectionTimeout === void 0 ? {} : { connectionTimeout },
+		...idleTimeout === void 0 ? {} : { idleTimeout },
+		...statementTimeout === void 0 ? {} : { statementTimeout },
+		...idleInTransactionTimeout === void 0 ? {} : { idleInTransactionTimeout }
 	};
 }
 //#endregion
 //#region src/workflow-sdk/world/crypto.ts
-const encoder = new TextEncoder();
+const encoder = /* @__PURE__ */ new TextEncoder();
 /** A 32-byte key from base64 or hex. */
 function parseMasterKey(value) {
 	const text = value.trim();
@@ -380,7 +442,18 @@ function createSupabaseWorld(options = {}) {
 	const pollInterval = Math.max(10, options.pollInterval ?? 250);
 	const lease = Math.max(5, options.lease ?? 60);
 	const deliveryTimeout = Math.max(lease, options.deliveryTimeout ?? 300);
-	const pool = options.pool ?? new Pool({ connectionString: options.connectionString ?? env("WORKFLOW_POSTGRES_URL") ?? env("SUPABASE_DB_URL") ?? env("DATABASE_URL") });
+	const pool = options.pool ?? new Pool({
+		connectionString: options.connectionString ?? env("WORKFLOW_POSTGRES_URL") ?? env("SUPABASE_DB_URL") ?? env("DATABASE_URL"),
+		max: Math.max(1, options.maxConnections ?? 10),
+		connectionTimeoutMillis: options.connectionTimeout ?? 3e4,
+		idleTimeoutMillis: options.idleTimeout ?? 1e4,
+		statement_timeout: options.statementTimeout ?? 3e4,
+		idle_in_transaction_session_timeout: options.idleInTransactionTimeout ?? 15e3
+	});
+	watchPoolErrors(pool, {
+		...options.events ? { events: options.events } : {},
+		...options.logger ? { logger: options.logger } : {}
+	});
 	const base = createWorld$1({
 		pool,
 		...options.namespace === void 0 ? {} : { namespace: options.namespace }
@@ -506,7 +579,7 @@ function createSupabaseWorld(options = {}) {
 		controller.signal.addEventListener("abort", stop, { once: true });
 		try {
 			const secret = await deliverySecret();
-			if (secret !== void 0) headers.set(SIGNATURE_HEADER, await signDelivery(secret, "", body.toString("utf8")));
+			if (secret !== void 0) headers.set(SIGNATURE_HEADER, await signDelivery(secret, "", body.toString("utf-8")));
 			const response = await fetch(flowUrl(), {
 				method: "POST",
 				headers,
@@ -640,7 +713,7 @@ function createSupabaseWorld(options = {}) {
 	};
 	async function getEncryptionKeyForRun(run) {
 		const master = await masterKey();
-		if (master === void 0) return void 0;
+		if (master === void 0) return;
 		return deriveRunKey(master, typeof run === "string" ? run : run.runId);
 	}
 	return {
@@ -672,8 +745,13 @@ function createSupabaseWorld(options = {}) {
 * from `WORKFLOW_POSTGRES_URL`, `SUPABASE_DB_URL` or `DATABASE_URL`, and
 * `WORKFLOW_DELIVERY`, `WORKFLOW_FLOW_URL`, `WORKFLOW_DELIVERY_SECRET`,
 * `WORKFLOW_ENCRYPTION_KEY`, `WORKFLOW_DELIVERY_QUEUE`,
-* `WORKFLOW_QUEUE_NAMESPACE`, `WORKFLOW_POSTGRES_WORKER_CONCURRENCY` and
-* `WORKFLOW_POSTGRES_POLL_INTERVAL_MS`.
+* `WORKFLOW_QUEUE_NAMESPACE`, `WORKFLOW_POSTGRES_WORKER_CONCURRENCY`,
+* `WORKFLOW_POSTGRES_POLL_INTERVAL_MS`, and the pool settings
+* `WORKFLOW_POSTGRES_MAX_CONNECTIONS`,
+* `WORKFLOW_POSTGRES_CONNECTION_TIMEOUT_MS`,
+* `WORKFLOW_POSTGRES_IDLE_TIMEOUT_MS`,
+* `WORKFLOW_POSTGRES_STATEMENT_TIMEOUT_MS` and
+* `WORKFLOW_POSTGRES_IDLE_IN_TRANSACTION_TIMEOUT_MS`.
 */
 function createWorld() {
 	return createSupabaseWorld(worldOptionsFromEnv());

package/dist/workflow-sdk-BZ6qsRlY.js

@@ -0,0 +1,243 @@
+import { n as PERMISSION_CAP_CLAIM } from "./delegation-Dt8hMJWu.js";
+import { n as withContext, t as unwrap } from "./envelope-CHYk5MXU.js";
+import { n as subjectAttribute, t as WORKFLOW_ATTRIBUTES } from "./attributes-D4mA7WhI.js";
+import { getHookByToken, getRun, start } from "workflow/api";
+import { getWorld } from "workflow/runtime";
+//#region src/workflow-sdk/workflow-sdk.ts
+/**
+* The actor, tenant and ticket of `context` as plain data, to pass into a
+* workflow as an argument; inside a step, `bs.forContext(context)` runs as
+* that user with RLS. A delegated token's `client_id`, `scope`,
+* `authorization_details` and `act` chain stay in `claims`, so the step is
+* as narrow as the token; other claims stay out of the run's serialized
+* state. Throws a `TypeError` for an invalid `act` chain or ticket.
+*/
+function workflowContext(context, options = {}) {
+	return unwrap(withContext(null, context, options)).context;
+}
+/** The `bs.tenant`, `bs.actor` and `bs.ticket` attributes for `context`. */
+function contextAttributes(context, options = {}) {
+	const recorded = workflowContext(context, options);
+	const ticket = recorded["ticket"];
+	return {
+		...recorded.tenant === void 0 ? {} : { [WORKFLOW_ATTRIBUTES.tenant]: recorded.tenant },
+		...recorded.actor?.kind === "user" ? { [WORKFLOW_ATTRIBUTES.actor]: recorded.actor.id } : {},
+		...typeof ticket === "string" ? { [WORKFLOW_ATTRIBUTES.ticket]: ticket } : {}
+	};
+}
+/** The run a start with idempotency `key` created, while it is in the World. */
+async function runForKey(key, world) {
+	const target = world ?? await getWorld();
+	if (target.analytics === void 0) return;
+	return (await target.analytics.runs.list({
+		attributes: { [WORKFLOW_ATTRIBUTES.key]: key },
+		pagination: { limit: 1 }
+	})).data[0]?.runId;
+}
+/**
+* `start(workflow, args)` for the caller in `context`: the run carries
+* `bs.tenant` and `bs.actor`, so `workflow_runs` lists it to the tenant and
+* the actor under RLS. With `idempotencyKey`, a run that already has the key
+* is returned instead of starting another (the key lookup needs a World with
+* `analytics`, as the Supabase World has).
+*/
+function startFor(context, workflow, args, options = {}) {
+	return startRun(context, workflow, args, options, {});
+}
+const RUN_AS_ATTRIBUTES = /* @__PURE__ */ new Set([WORKFLOW_ATTRIBUTES.principalKind, WORKFLOW_ATTRIBUTES.principal]);
+/**
+* `startFor` with `trusted` applied last: a `runAs` start sets the
+* principal and replaces `bs.actor` with the user who triggered it
+* (`undefined` removes a key).
+*/
+async function startRun(context, workflow, args, options, trusted) {
+	const key = options.idempotencyKey;
+	if (key !== void 0) {
+		const existing = await runForKey(key, options.world);
+		if (existing !== void 0) return getRun(existing);
+	}
+	const attributes = {};
+	for (const [name, value] of Object.entries(options.attributes ?? {})) if (!RUN_AS_ATTRIBUTES.has(name)) attributes[name] = value;
+	Object.assign(attributes, contextAttributes(context, options.ticket === void 0 ? {} : { ticket: options.ticket }), options.subject === void 0 ? {} : { [WORKFLOW_ATTRIBUTES.subject]: subjectAttribute(options.subject) }, key === void 0 ? {} : { [WORKFLOW_ATTRIBUTES.key]: key });
+	for (const [name, value] of Object.entries(trusted)) if (value === void 0) delete attributes[name];
+	else attributes[name] = value;
+	return start(workflow, args, {
+		attributes,
+		...options.world === void 0 ? {} : { world: options.world }
+	});
+}
+const PRINCIPAL_KINDS = [
+	"user",
+	"service_principal",
+	"system",
+	"external"
+];
+async function resolveRunAs(runAs, source) {
+	const resolved = typeof runAs === "function" ? await runAs(source) : runAs;
+	if (resolved === null || resolved === void 0) return;
+	if (typeof resolved.publisher !== "string" || resolved.publisher === "" || !Array.isArray(resolved.permissions) || !resolved.permissions.every((key) => typeof key === "string") || resolved.principalKind !== void 0 && !PRINCIPAL_KINDS.includes(resolved.principalKind)) throw new TypeError("better-supabase: runAs needs a publisher and a list of permission keys");
+	return resolved;
+}
+/**
+* The context and attributes of a start that runs as `runAs`; `trusted`
+* replaces the context's `bs.actor` with the trigger and records the
+* principal.
+*/
+function runAsStart(runAs, start) {
+	const tenant = runAs.tenant ?? start.tenant;
+	return {
+		context: workflowContext({
+			actor: {
+				id: runAs.publisher,
+				kind: "user"
+			},
+			...tenant === void 0 ? {} : { tenant },
+			claims: { [PERMISSION_CAP_CLAIM]: [...runAs.permissions] },
+			...start.ticket === void 0 ? {} : { ticket: start.ticket }
+		}),
+		attributes: {
+			[WORKFLOW_ATTRIBUTES.publisher]: runAs.publisher,
+			...start.trigger === void 0 ? {} : { [WORKFLOW_ATTRIBUTES.trigger]: start.trigger }
+		},
+		trusted: {
+			[WORKFLOW_ATTRIBUTES.actor]: start.trigger,
+			[WORKFLOW_ATTRIBUTES.principalKind]: runAs.principalKind ?? "user",
+			[WORKFLOW_ATTRIBUTES.principal]: runAs.publisher
+		}
+	};
+}
+function userContext(call) {
+	const actor = call.actor === void 0 ? void 0 : {
+		id: call.actor,
+		kind: "user"
+	};
+	return {
+		...actor === void 0 ? {} : { actor },
+		...call.tenant === void 0 ? {} : { tenant: call.tenant }
+	};
+}
+/**
+* The `start` callback for `schedules.tick` and `admission.tick` of
+* `better-supabase/blocks/workflows`: looks the workflow up by the name the
+* schedule or request stored and starts it with `startFor`, keyed by the
+* tick's idempotency key. A schedule runs as its `runAs` publisher.
+*/
+function workflowStarter(workflows, options = {}) {
+	return async (call) => {
+		const workflow = workflows[call.workflow];
+		if (workflow === void 0) throw new Error(`better-supabase: no workflow named "${call.workflow}" was passed to workflowStarter`);
+		const runAs = options.runAs === void 0 ? void 0 : await resolveRunAs(options.runAs, call);
+		if (runAs === void 0 && (call.source === "schedule" || options.runAs)) throw new Error(options.runAs === void 0 ? `better-supabase: the schedule for "${call.workflow}" needs a runAs publisher: pass workflowStarter(workflows, { runAs })` : `better-supabase: runAs refused the start of "${call.workflow}"`);
+		const started = runAs === void 0 ? {
+			context: userContext(call),
+			attributes: {},
+			trusted: {}
+		} : runAsStart(runAs, {
+			tenant: call.tenant,
+			trigger: call.actor
+		});
+		const input = Array.isArray(call.input) ? call.input : [call.input];
+		const args = options.args?.(call, started.context) ?? input;
+		return (await startRun(started.context, workflow, args, {
+			idempotencyKey: call.idempotencyKey,
+			attributes: started.attributes,
+			...call.subject === void 0 ? {} : { subject: call.subject },
+			...options.world === void 0 ? {} : { world: options.world }
+		}, started.trusted)).runId;
+	};
+}
+/**
+* Hook metadata that `authorizeHook` checks: the actor and tenant of
+* `context`, and the permission a tenant member needs to resume it instead.
+*/
+function hookMetadata(context, permission) {
+	return {
+		...contextAttributes(context),
+		...permission === void 0 ? {} : { "bs.permission": permission }
+	};
+}
+/** `authorizeHook` refused the caller. */
+var HookForbiddenError = class extends Error {
+	status = 403;
+	constructor(message) {
+		super(message);
+		this.name = "HookForbiddenError";
+	}
+};
+function stringField(value, key) {
+	if (typeof value !== "object" || value === null) return;
+	const field = { ...value }[key];
+	return typeof field === "string" ? field : void 0;
+}
+/**
+* The hook for `token` when the caller in `context` may resume it: the
+* actor in its `hookMetadata`, or a member of its tenant whom `can` grants
+* its permission. Throws `HookForbiddenError` otherwise, so a leaked token
+* alone never resumes a run.
+*/
+async function authorizeHook(token, context, options = {}) {
+	const hook = await getHookByToken(token);
+	const metadata = await hook.metadata;
+	const actor = context.actor?.kind === "user" ? context.actor.id : void 0;
+	const owner = stringField(metadata, WORKFLOW_ATTRIBUTES.actor);
+	if (actor !== void 0 && owner === actor) return hook;
+	const tenant = stringField(metadata, WORKFLOW_ATTRIBUTES.tenant);
+	const permission = stringField(metadata, "bs.permission");
+	if (actor !== void 0 && tenant !== void 0 && permission !== void 0 && options.can !== void 0 && await options.can(tenant, permission)) return hook;
+	throw new HookForbiddenError("better-supabase: the caller may not resume this workflow hook");
+}
+/** Whether `type` matches `pattern` (`invoice.paid`, `organization.*` or `*`). */
+function matches(pattern, type) {
+	if (pattern === "*" || pattern === type) return true;
+	return pattern.endsWith(".*") && type.startsWith(pattern.slice(0, -1));
+}
+/**
+* An outbox handler (`outbox.consume(name, handler)`) that starts
+* `workflow` for each matching event, as its `runAs` publisher in the
+* event's tenant, keyed by `event:{id}` so a redelivered batch starts
+* nothing twice.
+*/
+function startOnEvent(workflow, options) {
+	return async (events) => {
+		for (const event of events) {
+			if (!options.types.some((pattern) => matches(pattern, event.type))) continue;
+			const runAs = await resolveRunAs(options.runAs, event);
+			if (runAs === void 0) continue;
+			const { context, attributes, trusted } = runAsStart(runAs, {
+				tenant: event.tenant ?? void 0,
+				trigger: event.actorId ?? void 0,
+				ticket: options.ticket?.(event)
+			});
+			await startRun(context, workflow, options.args?.(event, context) ?? [event.payload], {
+				idempotencyKey: `event:${event.id}`,
+				attributes,
+				...options.world === void 0 ? {} : { world: options.world }
+			}, trusted);
+		}
+	};
+}
+function problem(status) {
+	return Response.json({
+		type: "about:blank",
+		title: status === 401 ? "Unauthorized" : "Forbidden",
+		status
+	}, {
+		status,
+		headers: { "content-type": "application/problem+json" }
+	});
+}
+/**
+* Puts a route of the workflow web UI or a run's stream behind
+* `permission`: answers 401 without a session and 403 without the
+* permission, as `application/problem+json`.
+*/
+function protectWebHandler(handler, permission, options) {
+	return async (request) => {
+		const allowed = await options.can(request, permission);
+		if (allowed === void 0) return problem(401);
+		if (!allowed) return problem(403);
+		return handler(request);
+	};
+}
+//#endregion
+export { protectWebHandler as a, startOnEvent as c, hookMetadata as i, workflowContext as l, authorizeHook as n, runForKey as o, contextAttributes as r, startFor as s, HookForbiddenError as t, workflowStarter as u };