better-supabase 0.14.0 → 0.15.1

package/dist/workflow-sdk-Cf0LAOFF.js

@@ -0,0 +1,242 @@
+import { r as PERMISSION_CAP_CLAIM } from "./delegation-DGOIiT8k.js";
+import { n as withContext, t as unwrap } from "./envelope-DEI2iX-d.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 };

package/dist/workflows-B0ZPAQu0.d.ts

@@ -0,0 +1,255 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-DZeA5KS6.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { i as CursorPageOptions, r as BlockTemporalOptions } from "./block-helpers-CRpAHrp_.js";
+import { t as BlockTransport } from "./block-transport-DWZSJrwN.js";
+import { n as BlockHooks } from "./block-hooks-DZN2w69m.js";
+import { r as RunState } from "./run-state-BMCD_1Lt.js";
+//#region src/blocks/workflows/workflows.d.ts
+/** A workflow run's state, in the words ai-chat and ai-schedules runs share. */
+type WorkflowRunStatus = Exclude<RunState, "cancel_requested">;
+/** The record a run belongs to: a subject type from `config.records` and its id. */
+interface WorkflowSubject {
+  readonly type: string;
+  readonly id: string;
+}
+/** Who a run's steps act as. */
+type WorkflowPrincipalKind = "user" | "service_principal" | "system" | "external";
+interface WorkflowPrincipal {
+  readonly kind: WorkflowPrincipalKind;
+  /** The user's or service principal's id; absent for `system`. */
+  readonly id: string | undefined;
+}
+/** `test` runs come from the builder's test button: no outbox events, no alerts. */
+type WorkflowRunMode = "live" | "test";
+/** A run of any engine, as the `workflows` module records it. */
+interface WorkflowRun {
+  readonly id: string;
+  /** The engine that runs it, e.g. `workflow-sdk`. */
+  readonly engine: string;
+  /** The engine's id for the run. */
+  readonly externalId: string;
+  /** The workflow it runs. */
+  readonly definition: string;
+  readonly tenant: string | undefined;
+  readonly actor: string | undefined;
+  readonly status: WorkflowRunStatus;
+  readonly attributes: Readonly<Record<string, unknown>>;
+  readonly error: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  readonly startedAt: Temporal.Instant | undefined;
+  readonly completedAt: Temporal.Instant | undefined;
+  readonly cancelRequestedAt: Temporal.Instant | undefined;
+  /** The record it was started on. */
+  readonly subject: WorkflowSubject | undefined;
+  /** Who its steps act as, when the engine reported it. */
+  readonly principal: WorkflowPrincipal | undefined;
+  readonly mode: WorkflowRunMode;
+  /** The trigger node it started from, in a graph with several. */
+  readonly triggerNode: string | undefined;
+}
+interface WorkflowSchedule {
+  readonly id: string;
+  readonly tenant: string | undefined;
+  readonly name: string;
+  readonly workflow: string;
+  readonly input: unknown;
+  readonly cron: string;
+  readonly timezone: string;
+  readonly nextRunAt: Temporal.Instant;
+  readonly lastRunAt: Temporal.Instant | undefined;
+  readonly paused: boolean;
+  readonly createdBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+}
+interface WorkflowRunsQuery extends CursorPageOptions<Temporal.Instant> {
+  readonly tenant?: string;
+  readonly definition?: string;
+  readonly status?: WorkflowRunStatus;
+  /** One record's runs. */
+  readonly subject?: WorkflowSubject;
+  /** `live` (the default), `test`, or `all`. */
+  readonly mode?: WorkflowRunMode | "all";
+  /** At most this many runs, newest first (default 50, at most 500). */
+  readonly limit?: number;
+  /** Runs created before this instant, for the next page. */
+  readonly cursor?: Temporal.Instant;
+}
+/** What an engine reports about a run (service role). */
+interface WorkflowRunRecord {
+  readonly engine: string;
+  readonly externalId: string;
+  readonly definition: string;
+  readonly status: WorkflowRunStatus;
+  readonly tenant?: string;
+  readonly actor?: string;
+  readonly attributes?: Readonly<Record<string, unknown>>;
+  readonly error?: string;
+  readonly startedAt?: Temporal.Instant;
+  readonly completedAt?: Temporal.Instant;
+  /** Kept from the first report that names one. */
+  readonly subject?: WorkflowSubject;
+  /** Kept from the first report that names one. */
+  readonly principal?: WorkflowPrincipal;
+  /** Set by the first report (default `live`). */
+  readonly mode?: WorkflowRunMode;
+  readonly triggerNode?: string;
+}
+interface WorkflowScheduleInput {
+  /** Unique per tenant: creating it again replaces it. */
+  readonly name: string;
+  readonly workflow: string;
+  /**
+   * Five cron fields, a macro such as `@daily`, or an interval such as `30
+   * seconds`.
+   */
+  readonly cron: string;
+  /** IANA time zone the cron fields are read in (default `UTC`). */
+  readonly timezone?: string;
+  /** The workflow's arguments. */
+  readonly input?: unknown;
+  readonly tenant?: string;
+}
+/** One start the tick asks the engine for. */
+interface WorkflowStartCall {
+  /** A due schedule or a queued admission request. */
+  readonly source: "schedule" | "admission";
+  readonly workflow: string;
+  readonly input: unknown;
+  readonly tenant: string | undefined;
+  /**
+   * The schedule's creator or the request's actor. For a schedule it is the
+   * trigger, recorded for audit; the run needs a `runAs` publisher.
+   */
+  readonly actor: string | undefined;
+  /** The record a queued request named. */
+  readonly subject?: WorkflowSubject;
+  /** Pass to the engine so a repeated tick doesn't start the run twice. */
+  readonly idempotencyKey: string;
+}
+/** Starts a run and returns the engine's run id. */
+type WorkflowStarter = (call: WorkflowStartCall) => Promise<string>;
+interface WorkflowTickOptions {
+  readonly start: WorkflowStarter;
+  /** Seconds a claimed row stays leased (default 60). */
+  readonly lease?: number;
+  readonly batch?: number;
+}
+interface WorkflowTickResult {
+  readonly started: number;
+  /** The rows whose start threw; they run again once their lease ends. */
+  readonly failed: readonly {
+    readonly id: string;
+    readonly error: string;
+  }[];
+}
+interface WorkflowStartRequest {
+  /** The admission key: runs with the same key share the limits below. */
+  readonly key: string;
+  readonly workflow: string;
+  readonly input?: unknown;
+  readonly tenant?: string;
+  readonly actor?: string;
+  /** The record the run belongs to. */
+  readonly subject?: WorkflowSubject;
+  /** At most this many runs with the key at once. */
+  readonly concurrency?: number;
+  /** Waits this many seconds and replaces a request with the key still waiting. */
+  readonly debounce?: number;
+  /** Drops the request while a run with the key is waiting or active. */
+  readonly singleton?: boolean;
+}
+interface WorkflowStartTicket {
+  readonly id: string | undefined;
+  readonly status: "pending" | "dropped";
+}
+interface WorkflowsOptions extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`. Default `better_supabase`.
+   */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /**
+   * `withBlockHooks` hooks around the methods of each group, such as a rule on
+   * who may create a schedule: `{ schedules: { create: { before } } }`.
+   */
+  readonly hooks?: WorkflowsHooks;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** Hooks for the methods of each group of `Workflows`. */
+interface WorkflowsHooks {
+  readonly runs?: BlockHooks<Workflows["runs"]>;
+  readonly schedules?: BlockHooks<Workflows["schedules"]>;
+  readonly semaphores?: BlockHooks<Workflows["semaphores"]>;
+  readonly admission?: BlockHooks<Workflows["admission"]>;
+}
+interface Workflows {
+  readonly runs: {
+    /** The runs the caller may read, newest first. */
+    list(query?: WorkflowRunsQuery): AsyncResult<readonly WorkflowRun[]>;
+    /** A run by its id or its engine's id. */
+    get(run: string): AsyncResult<WorkflowRun | undefined>;
+    /**
+     * Marks a run for cancellation: the actor, `workflow.admin` in its tenant,
+     * or the service role. The engine does the cancelling.
+     */
+    requestCancel(run: string): AsyncResult<WorkflowRun | undefined>;
+    /** Creates or updates a run (service role; engines call it). */
+    record(run: WorkflowRunRecord): AsyncResult<string>;
+    /** Deletes finished runs older than `olderThan` seconds (default 30 days). */
+    purge(options?: {
+      readonly olderThan?: number;
+      readonly batch?: number;
+    }): AsyncResult<number>;
+  };
+  readonly schedules: {
+    /**
+     * Creates or replaces a schedule: the service role, or `workflow.admin` in
+     * its tenant.
+     */
+    create(input: WorkflowScheduleInput): AsyncResult<WorkflowSchedule>;
+    list(tenant?: string): AsyncResult<readonly WorkflowSchedule[]>;
+    pause(id: string, paused?: boolean): AsyncResult<boolean>;
+    remove(id: string): AsyncResult<boolean>;
+    /**
+     * Starts every due schedule once (service role), with the idempotency key
+     * `schedule:<id>:<fire time>`, then moves it to its next cron time after
+     * now. Call it from a cron route or a job.
+     */
+    tick(options: WorkflowTickOptions): AsyncResult<WorkflowTickResult>;
+  };
+  readonly semaphores: {
+    /**
+     * Takes one of `max` slots of `key` for `holder`, for `ttl` seconds
+     * (default 300).
+     */
+    acquire(key: string, holder: string, options: {
+      readonly max: number;
+      readonly ttl?: number;
+    }): AsyncResult<boolean>;
+    release(key: string, holder: string): AsyncResult<boolean>;
+  };
+  readonly admission: {
+    /** Queues a start under its key's concurrency, debounce and singleton rules. */
+    request(input: WorkflowStartRequest): AsyncResult<WorkflowStartTicket>;
+    /** Starts the queued requests whose key has room (service role). */
+    tick(options: WorkflowTickOptions): AsyncResult<WorkflowTickResult>;
+  };
+}
+/**
+ * The `workflows` module's runs, schedules, semaphores and start admission, for
+ * any engine. Run with the user's transport to read what RLS allows; the ticks
+ * and `record` need the service role.
+ *
+ * ```ts
+ * const workflows = createWorkflows({ transport: rpcTransport(supabase) });
+ * const runs = await workflows.runs.list({ tenant: orgId }).orThrow();
+ * ```
+ */
+declare function createWorkflows(options: WorkflowsOptions): Workflows;
+//#endregion
+export { WorkflowsHooks as _, WorkflowRunStatus as a, WorkflowScheduleInput as c, WorkflowStartTicket as d, WorkflowStarter as f, Workflows as g, WorkflowTickResult as h, WorkflowRunRecord as i, WorkflowStartCall as l, WorkflowTickOptions as m, WorkflowRun as n, WorkflowRunsQuery as o, WorkflowSubject as p, WorkflowRunMode as r, WorkflowSchedule as s, WorkflowPrincipalKind as t, WorkflowStartRequest as u, WorkflowsOptions as v, createWorkflows as y };

package/dist/yjs/index.d.ts

@@ -1,6 +1,6 @@
-import { t as AsyncResult } from "../result-C6jDfedy.js";
-import { c as RealtimeClient, r as PresenceMember } from "../topic-D9j8G2dw.js";
-import { a as DocumentSuggestion, d as OpenedDocument, l as Documents, r as DocumentRef, t as DecidedSuggestion } from "../documents-kgDOHUfn.js";
+import { t as AsyncResult } from "../result-DZeA5KS6.js";
+import { c as RealtimeClient, r as PresenceMember } from "../topic-DNFEFGKI.js";
+import { a as DocumentSuggestion, d as OpenedDocument, l as Documents, r as DocumentRef, t as DecidedSuggestion } from "../documents-Cup1rpjF.js";
 //#region src/yjs/yjs.d.ts
 type PresenceState = Readonly<Record<string, unknown>>;
 /** The part of a `Y.Doc` the provider uses. */

package/dist/yjs/index.js

@@ -1,8 +1,8 @@
-import { a as ok, r as err, t as AsyncResult } from "../result-B3m7xtRY.js";
 import { n as isRecord } from "../guards-6F2bCtQR.js";
+import { a as ok, r as err, t as AsyncResult } from "../result-ntFBW2p2.js";
 import { i as toBase64, r as fromBase64 } from "../base64-B9Wlsdj7.js";
 import { t as importOptionalPeer } from "../optional-peer-C1NbBRJm.js";
-import { t as defineTopic } from "../topic-CPOmMgkf.js";
+import { t as defineTopic } from "../topic-ikV_pLTX.js";
 //#region src/yjs/yjs.ts
 function isYjs(value) {
 	return isRecord(value) && typeof value["applyUpdate"] === "function" && typeof value["mergeUpdates"] === "function";