better-supabase 0.5.1 → 0.6.0

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

@@ -0,0 +1,98 @@
+import { m as RequestContext } from "./plugin-FGY8UhYm.js";
+import { a as OutboxEvent, o as OutboxHandler } from "./outbox-Cq7pPYvl.js";
+import { u as WorkflowStarter } from "./workflows-B0j9WKPu.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>;
+/**
+ * The actor and tenant 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. Claims and anything else in `context` stay out of the run's
+ * serialized state.
+ */
+declare function workflowContext(context: RequestContext): RequestContext;
+/** The `bs.tenant` and `bs.actor` attributes for `context`. */
+declare function contextAttributes(context: RequestContext): 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. */
+  readonly attributes?: Readonly<Record<string, string>>;
+  /** The World to look the key up in. Defaults to the configured one. */
+  readonly world?: World;
+}
+/**
+ * `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>>;
+/**
+ * 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.
+ */
+declare function workflowStarter(workflows: Readonly<Record<string, WorkflowFn<never[]>>>, options?: Pick<StartForOptions, "world">): 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]`. */
+  readonly args?: (event: OutboxEvent) => TArgs;
+  readonly world?: World;
+}
+/**
+ * An outbox handler (`outbox.consume(name, handler)`) that starts
+ * `workflow` for each matching event, as the event's actor in its 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 { StartOnEventOptions as a, contextAttributes as c, startFor as d, startOnEvent as f, StartForOptions as i, hookMetadata as l, workflowStarter as m, HookForbiddenError as n, WorkflowFn as o, workflowContext as p, ProtectWebHandlerOptions as r, authorizeHook as s, AuthorizeHookOptions as t, protectWebHandler as u };

package/dist/workflow-sdk-C2WJ_G2O.js

@@ -0,0 +1,173 @@
+import { n as withContext, t as unwrap } from "./envelope-DqnYGRw7.js";
+import { t as WORKFLOW_ATTRIBUTES } from "./attributes-5dYul0u0.js";
+import { getHookByToken, getRun, start } from "workflow/api";
+import { getWorld } from "workflow/runtime";
+//#region src/workflow-sdk/workflow-sdk.ts
+/**
+* The actor and tenant 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. Claims and anything else in `context` stay out of the run's
+* serialized state.
+*/
+function workflowContext(context) {
+	return unwrap(withContext(null, context)).context;
+}
+/** The `bs.tenant` and `bs.actor` attributes for `context`. */
+function contextAttributes(context) {
+	const recorded = workflowContext(context);
+	return {
+		...recorded.tenant === void 0 ? {} : { [WORKFLOW_ATTRIBUTES.tenant]: recorded.tenant },
+		...recorded.actor?.kind === "user" ? { [WORKFLOW_ATTRIBUTES.actor]: recorded.actor.id } : {}
+	};
+}
+/** 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 void 0;
+	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).
+*/
+async function startFor(context, workflow, args, options = {}) {
+	const key = options.idempotencyKey;
+	if (key !== void 0) {
+		const existing = await runForKey(key, options.world);
+		if (existing !== void 0) return getRun(existing);
+	}
+	return start(workflow, args, {
+		attributes: {
+			...options.attributes,
+			...contextAttributes(context),
+			...key === void 0 ? {} : { [WORKFLOW_ATTRIBUTES.key]: key }
+		},
+		...options.world === void 0 ? {} : { world: options.world }
+	});
+}
+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.
+*/
+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 args = Array.isArray(call.input) ? call.input : [call.input];
+		return (await startFor(userContext(call), workflow, args, {
+			idempotencyKey: call.idempotencyKey,
+			...options
+		})).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 void 0;
+	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 the event's actor in its 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 args = options.args?.(event) ?? [event.payload];
+			await startFor({
+				...event.actorId === null ? {} : { actor: {
+					id: event.actorId,
+					kind: "user"
+				} },
+				...event.tenant === null ? {} : { tenant: event.tenant }
+			}, workflow, args, {
+				idempotencyKey: `event:${event.id}`,
+				...options.world === void 0 ? {} : { world: options.world }
+			});
+		}
+	};
+}
+function problem(status) {
+	return new Response(JSON.stringify({
+		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 };