better-supabase 0.13.0 → 0.15.0

package/dist/workflow-sdk-BFHu4sci.d.ts

@@ -0,0 +1,163 @@
+import { Ft as RequestContext } from "./types-DFdg_4yN.js";
+import { f as WorkflowStarter, l as WorkflowStartCall, p as WorkflowSubject, t as WorkflowPrincipalKind } from "./workflows-B0ZPAQu0.js";
+import { a as OutboxEvent, o as OutboxHandler } from "./outbox-HvGAJuBe.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 `bsb.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, `bsb.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 `bsb.tenant`, `bsb.actor` and `bsb.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; `bsb.*` keys are set from the context, and
+   * `bsb.principal_kind` and `bsb.principal` only by `runAs` starts.
+   */
+  readonly attributes?: Readonly<Record<string, string>>;
+  /** The record the run belongs to, stored as `bsb.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 `bsb.ticket` attribute instead of
+   * `context.ticket`. Pass `workflowContext(context, { ticket })` as an
+   * argument too, so a step's `bsb.forContext` resolves it.
+   */
+  readonly ticket?: string;
+}
+/**
+ * `start(workflow, args)` for the caller in `context`: the run carries
+ * `bsb.tenant` and `bsb.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
+ * `bsb.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 `bsb.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 `bsb.ticket`; `undefined`
+   * for none.
+   */
+  readonly ticket?: (event: OutboxEvent) => string | undefined;
+  /**
+   * The publisher each run starts as. The event's actor is recorded as
+   * `bsb.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 };

package/dist/workflow-sdk-BVlFEB5Q.js

@@ -0,0 +1,242 @@
+import { n as PERMISSION_CAP_CLAIM } from "./delegation--93jRsVO.js";
+import { n as withContext, t as unwrap } from "./envelope-Bzu0JnY2.js";
+import { n as subjectAttribute, t as WORKFLOW_ATTRIBUTES } from "./attributes-Bzf51_nc.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, `bsb.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 `bsb.tenant`, `bsb.actor` and `bsb.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
+* `bsb.tenant` and `bsb.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 `bsb.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 `bsb.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 ? {} : { "bsb.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, "bsb.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 };