better-supabase 0.8.0 → 0.10.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 { i as WORLD_POSTGRES_VERSION, r as WORKFLOW_VAULT_SECRETS } from "../../workflow-sdk-world-DPMdBfzn.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-C94tPR_G.js";
+import { n as memoized } from "../../optional-peer-Dx8TaYXw.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-Di5pmCAu.d.ts

@@ -0,0 +1,161 @@
+import { m as RequestContext } from "./plugin-D5OIaP93.js";
+import { f as WorkflowStarter, l as WorkflowStartCall, p as WorkflowSubject, t as WorkflowPrincipalKind } from "./workflows-DJXoxDZH.js";
+import { a as OutboxEvent, o as OutboxHandler } from "./outbox-BCGHl9X6.js";
+import { Hook, Run } from "workflow/api";
+import { World } from "@workflow/world";
+//#region src/workflow-sdk/workflow-sdk.d.ts
+/** A workflow function (a `"use workflow"` export), typed structurally. */
+type WorkflowFn<TArgs extends unknown[] = unknown[], TResult = unknown> = (...args: TArgs) => Promise<TResult>;
+interface WorkflowContextOptions {
+  /** The opaque ticket `bs.forContext` resolves; wins over `context.ticket`. */
+  readonly ticket?: string;
+}
+/**
+ * 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.
+ */
+declare function workflowContext(context: RequestContext, options?: WorkflowContextOptions): RequestContext;
+/** The `bs.tenant`, `bs.actor` and `bs.ticket` attributes for `context`. */
+declare function contextAttributes(context: RequestContext, options?: WorkflowContextOptions): Record<string, string>;
+interface StartForOptions {
+  /**
+   * Starting again with the same key returns the run the first start
+   * created, while that run is in the World. Schedules and admission pass
+   * `schedule:{id}:{fireAt}` and `admission:{id}`.
+   */
+  readonly idempotencyKey?: string;
+  /**
+   * More attributes for the run; `bs.*` keys are set from the context, and
+   * `bs.principal_kind` and `bs.principal` only by `runAs` starts.
+   */
+  readonly attributes?: Readonly<Record<string, string>>;
+  /** The record the run belongs to, stored as `bs.subject`. */
+  readonly subject?: WorkflowSubject;
+  /** The World to look the key up in. Defaults to the configured one. */
+  readonly world?: World;
+  /**
+   * An opaque ticket, stored as the `bs.ticket` attribute instead of
+   * `context.ticket`. Pass `workflowContext(context, { ticket })` as an
+   * argument too, so a step's `bs.forContext` resolves it.
+   */
+  readonly ticket?: string;
+}
+/**
+ * `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).
+ */
+declare function startFor<TArgs extends unknown[], TResult>(context: RequestContext, workflow: WorkflowFn<TArgs, TResult>, args: TArgs, options?: StartForOptions): Promise<Run<TResult>>;
+/**
+ * Who an event or schedule start runs as: the publisher, a user who holds
+ * the permissions, and the permission keys its steps may use. A step's
+ * `bs.forContext(context)` runs as the publisher, capped to `permissions`,
+ * so a publisher who lost one fails the step. The event actor or schedule
+ * creator is the run's actor (and `bs.trigger`) and grants nothing; the
+ * publisher is recorded as the run's principal.
+ */
+interface WorkflowRunAs {
+  readonly publisher: string;
+  readonly permissions: readonly string[];
+  /** The tenant the steps run in. Defaults to the event's or schedule's. */
+  readonly tenant?: string;
+  /**
+   * What the publisher is, recorded as the run's `principal_kind`:
+   * `user` (default), or `service_principal` for the app's service
+   * principal (an auth user too, so steps still run as it).
+   */
+  readonly principalKind?: WorkflowPrincipalKind;
+}
+/** A fixed `WorkflowRunAs`, or one per start; `null` refuses the start. */
+type WorkflowRunAsFor<T> = WorkflowRunAs | ((source: T) => WorkflowRunAs | null | undefined | Promise<WorkflowRunAs | null | undefined>);
+interface WorkflowStarterOptions extends Pick<StartForOptions, "world"> {
+  /**
+   * The publisher a start runs as. Required for schedules: a schedule start
+   * without it, or with `null` for it, throws and the tick records the
+   * failure. An admission request runs as its actor unless this is set.
+   */
+  readonly runAs?: WorkflowRunAsFor<WorkflowStartCall>;
+  /**
+   * The workflow's arguments. Defaults to the stored input. `context` is the
+   * context the run starts as, to pass to the workflow for its steps.
+   */
+  readonly args?: (call: WorkflowStartCall, context: RequestContext) => readonly unknown[];
+}
+/**
+ * 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.
+ */
+declare function workflowStarter(workflows: Readonly<Record<string, WorkflowFn<never[]>>>, options?: WorkflowStarterOptions): WorkflowStarter;
+/**
+ * Hook metadata that `authorizeHook` checks: the actor and tenant of
+ * `context`, and the permission a tenant member needs to resume it instead.
+ */
+declare function hookMetadata(context: RequestContext, permission?: string): Record<string, string>;
+/** `authorizeHook` refused the caller. */
+declare class HookForbiddenError extends Error {
+  readonly status = 403;
+  constructor(message: string);
+}
+interface AuthorizeHookOptions {
+  /**
+   * Whether the caller holds `permission` in `tenant`, for hooks created
+   * with `hookMetadata(context, permission)`, such as an approval any admin
+   * of the tenant may give.
+   */
+  readonly can?: (tenant: string, permission: string) => boolean | Promise<boolean>;
+}
+/**
+ * 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.
+ */
+declare function authorizeHook(token: string, context: RequestContext, options?: AuthorizeHookOptions): Promise<Hook>;
+interface StartOnEventOptions<TArgs extends unknown[]> {
+  /** Type patterns such as `invoice.paid` or `organization.*`. */
+  readonly types: readonly string[];
+  /**
+   * The workflow's arguments for an event. Defaults to `[event.payload]`.
+   * `context` is the event's `workflowContext`, with its ticket.
+   */
+  readonly args?: (event: OutboxEvent, context: RequestContext) => TArgs;
+  /** The opaque ticket for an event's run, stored as `bs.ticket`; `undefined` for none. */
+  readonly ticket?: (event: OutboxEvent) => string | undefined;
+  /**
+   * The publisher each run starts as. The event's actor is recorded as
+   * `bs.trigger` and grants nothing; `null` for an event starts nothing.
+   */
+  readonly runAs: WorkflowRunAsFor<OutboxEvent>;
+  readonly world?: World;
+}
+/**
+ * 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.
+ */
+declare function startOnEvent<TArgs extends unknown[]>(workflow: WorkflowFn<TArgs>, options: StartOnEventOptions<TArgs>): OutboxHandler;
+interface ProtectWebHandlerOptions {
+  /**
+   * Whether the request's caller holds `permission`: resolve the session
+   * (`server.context(request)`) and check it, e.g. with `member_can`.
+   * Return `undefined` when there is no session (401).
+   */
+  readonly can: (request: Request, permission: string) => boolean | undefined | Promise<boolean | undefined>;
+}
+/**
+ * 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`.
+ */
+declare function protectWebHandler(handler: (request: Request) => Response | Promise<Response>, permission: string, options: ProtectWebHandlerOptions): (request: Request) => Promise<Response>;
+//#endregion
+export { workflowContext as _, StartOnEventOptions as a, WorkflowRunAs as c, authorizeHook as d, contextAttributes as f, startOnEvent as g, startFor as h, StartForOptions as i, WorkflowRunAsFor as l, protectWebHandler as m, HookForbiddenError as n, WorkflowContextOptions as o, hookMetadata as p, ProtectWebHandlerOptions as r, WorkflowFn as s, AuthorizeHookOptions as t, WorkflowStarterOptions as u, workflowStarter as v };