better-supabase 0.7.1 → 0.9.0

package/dist/workflow-sdk/builder/index.d.ts

@@ -1,6 +1,6 @@
-import { T as WorkflowGraph, c as NodeRunRecord, i as BuilderStarter } from "../../types-AYOvcyep.js";
-import { i as executeGraph, n as GraphStepCall, r as approvalToken, t as GraphRuntime } from "../../executor-BVBFM86G.js";
-import { o as WorkflowFn } from "../../workflow-sdk-B3yLD6Br.js";
+import { i as BuilderStarter, l as NodeRunRecord, z as WorkflowGraph } from "../../types-vaoP9S9_.js";
+import { a as GraphSubject, i as GraphStepCall, o as approvalToken, r as GraphRuntime, s as executeGraph, t as GraphApprovalCall } from "../../executor-BINiCFNp.js";
+import { s as WorkflowFn } from "../../workflow-sdk-q8cLwW1K.js";
 import { World } from "@workflow/world";
 //#region src/workflow-sdk/builder/builder.d.ts
 /** The env flag the Workflow SDK reads before it starts or runs dynamic source. */
@@ -24,13 +24,27 @@ interface GraphRunMeta {
   readonly runKey: string;
   readonly definition: string;
   readonly version: number;
+  /** The version's id, for `builder.versions.runAs` inside each step. */
+  readonly versionId: string;
+  /** The run's tenant, for `builder.versions.runAs` (a system definition's runs need it). */
+  readonly tenant?: string;
+  /** The record the run belongs to; conditions read it as `subject`. */
+  readonly subject?: GraphSubject;
+  /** `test`: steps return `stubs` and never run, sleeps are skipped. */
+  readonly mode?: "live" | "test";
+  /** The trigger node the run starts at, in a graph with several. */
+  readonly triggerNode?: string;
+  /** A test run's step outputs and approval decisions, by node id. */
+  readonly stubs?: Readonly<Record<string, unknown>>;
 }
 /**
  * Compiles a graph to Workflow SDK dynamic source: plain JavaScript that
- * calls each step node through its own alias, sleeps with `sleep` and waits
- * on approvals with `createHook({ token: "<runKey>:<node>" })`. It runs the
- * same way `executeGraph` does. Throws when the graph is invalid or the
- * source is over 128 KiB. Pass it as `compile` to `createBuilder`.
+ * starts at `meta.triggerNode` (or the only trigger), calls each step node
+ * through its own alias, sleeps with `sleep` and waits on approvals with
+ * `createHook`: the token is the id `steps.bs_approval` returns
+ * (graphStarter's `approval`), else `<runKey>:<node>`. A `meta.mode` of
+ * `test` returns `meta.stubs` instead. It runs the same way `executeGraph` does. Throws when the graph is invalid or the
+ * source is over 128 KiB. Pass it as `compile` to `createWorkflowBuilder`.
  */
 export declare function compileGraph(graph: WorkflowGraph): CompiledGraph;
 /** `value` as a compiled graph, or `undefined` when it isn't one. */
@@ -44,25 +58,42 @@ interface GraphStarterOptions {
   readonly steps: Readonly<Record<string, GraphStep>>;
   /**
    * The static executor: a `"use workflow"` function that calls
-   * `executeGraph(graph, input, runtime)`. Runs start with it when dynamic
-   * workflows are off.
+   * `executeGraph(graph, input, { ...graphRunFields(meta), step, sleep, approval })`.
+   * Runs start with it when dynamic workflows are off.
    */
   readonly executor?: WorkflowFn<[WorkflowGraph, unknown, GraphRunMeta]>;
+  /**
+   * Set once `executor` spreads `graphRunFields(meta)` into its runtime: a
+   * test run through an executor that doesn't would run real steps, so
+   * test runs on the static executor are refused without it.
+   */
+  readonly executorRunsTests?: boolean;
   /** Whether to start dynamic source; defaults to `WORKFLOW_EXPERIMENTAL_DYNAMIC_WORKFLOWS`. */
   readonly dynamic?: boolean;
   /** The World to look idempotency keys up in. Defaults to the configured one. */
   readonly world?: World;
+  /**
+   * A `"use step"` function that files the approval request for an
+   * approval node (a `GraphApprovalCall`) and returns its id, the hook
+   * token. Resume runs with `wakeOnApproval` from your outbox consumer.
+   * Without it the token is `<runKey>:<node>`, which anyone who knows the
+   * run key can guess. The static executor passes it as
+   * `runtime.requestApproval` itself.
+   */
+  readonly approval?: GraphStep;
 }
 /**
- * The `start` for `createBuilder`: starts the published version as dynamic
+ * The `start` for `createWorkflowBuilder`: starts the published version as dynamic
  * source when dynamic workflows are on, and through `executor` otherwise.
  * The source is always compiled from the version's graph; a stored
- * compiled form is never run. Runs carry
- * `bs.tenant`, `bs.actor`, `bs.definition`, `bs.version` and `bs.key`, and
- * a repeated key returns the first run.
+ * compiled form is never run. Runs carry `bs.tenant`, `bs.actor`,
+ * `bs.definition`, `bs.version` and `bs.key`, plus `bs.subject`,
+ * `bs.mode` and `bs.trigger_node` when set. A live run also records its
+ * principal: the publisher (`user`), or the app's service principal for an
+ * organization-owned version. A repeated key returns the first run.
  */
 export declare function graphStarter(options: GraphStarterOptions): BuilderStarter;
-/** Where `nodeRunReporter` writes: `builder.nodeRuns` from `createBuilder`. */
+/** Where `nodeRunReporter` writes: `builder.nodeRuns` from `createWorkflowBuilder`. */
 interface NodeRunSink {
   record(input: NodeRunRecord): PromiseLike<unknown>;
 }
@@ -82,4 +113,4 @@ interface NodeRunSink {
  */
 export declare function nodeRunReporter(sink: NodeRunSink): <T>(call: GraphStepCall, run: () => Promise<T>) => Promise<T>;
 //#endregion
-export { type CompiledGraph, type GraphRunMeta, type GraphRuntime, type GraphStarterOptions, type GraphStep, type GraphStepCall, type NodeRunSink, approvalToken, executeGraph };
+export { type CompiledGraph, type GraphApprovalCall, type GraphRunMeta, type GraphRuntime, type GraphStarterOptions, type GraphStep, type GraphStepCall, type NodeRunSink, approvalToken, executeGraph };

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

@@ -1,7 +1,7 @@
-import { t as WORKFLOW_ATTRIBUTES } from "../../attributes-5dYul0u0.js";
-import { c as topologicalOrder, i as durationMs, l as validateGraph, s as isGraphRecord } from "../../graph-BGyLLFLX.js";
-import { n as executeGraph, t as approvalToken } from "../../executor-C-R4pucm.js";
-import { o as runForKey, r as contextAttributes } from "../../workflow-sdk-C2WJ_G2O.js";
+import { n as subjectAttribute, t as WORKFLOW_ATTRIBUTES } from "../../attributes-D4mA7WhI.js";
+import { c as isGraphRecord, i as durationMs, p as validateGraph, u as topologicalOrder } from "../../graph-Cs28bOlK.js";
+import { i as startNodeOf, n as executeGraph, t as approvalToken } from "../../executor-D3K3tycZ.js";
+import { o as runForKey, r as contextAttributes } from "../../workflow-sdk-BZ6qsRlY.js";
 import { start } from "workflow/api";
 import { getStepMetadata, getWorkflowMetadata } from "workflow";
 //#region src/workflow-sdk/builder/builder.ts
@@ -10,14 +10,25 @@ const DYNAMIC_WORKFLOWS_ENV = "WORKFLOW_EXPERIMENTAL_DYNAMIC_WORKFLOWS";
 /** The Workflow SDK's limit on dynamic source. */
 const DYNAMIC_SOURCE_MAX_BYTES = 131072;
 const EXPORT_NAME = "workflow";
+/** The `steps` key the compiled source calls to file an approval request; never a step alias. */
+const APPROVAL_ALIAS = "bs_approval";
 const literal = (value) => JSON.stringify(value ?? null);
 const aliasOf = (node, index) => `n${index}_${node.id.replaceAll(/[^A-Za-z0-9_]/g, "_").slice(0, 40)}`;
 const RUNTIME = `  const results = {};
   const ran = Object.create(null);
   const runKey = meta !== null && typeof meta === "object" && typeof meta.runKey === "string" ? meta.runKey : "";
+  const versionId = meta !== null && typeof meta === "object" && typeof meta.versionId === "string" ? meta.versionId : undefined;
+  const tenant = meta !== null && typeof meta === "object" && typeof meta.tenant === "string" ? meta.tenant : undefined;
+  const subject = meta !== null && typeof meta === "object" && meta.subject !== null && typeof meta.subject === "object" ? { type: String(meta.subject.type), id: String(meta.subject.id) } : undefined;
+  const start = meta !== null && typeof meta === "object" && typeof meta.triggerNode === "string" ? meta.triggerNode : null;
+  const testing = meta !== null && typeof meta === "object" && meta.mode === "test";
+  const stubs = testing && meta.stubs !== null && typeof meta.stubs === "object" ? meta.stubs : {};
+  function stub(id, fallback) {
+    return Object.prototype.hasOwnProperty.call(stubs, id) ? stubs[id] : fallback;
+  }
   function read(path) {
     const parts = path.split(".");
-    let value = parts[0] === "input" ? input : results;
+    let value = parts[0] === "input" ? input : parts[0] === "subject" ? subject : results;
     for (let i = 1; i < parts.length; i++) {
       if (Array.isArray(value)) value = value[Number(parts[i])];
       else if (value !== null && typeof value === "object") value = value[parts[i]];
@@ -49,13 +60,14 @@ function nodeBody(node, alias) {
 	const id = literal(node.id);
 	switch (node.kind) {
 		case "trigger": return `results[${id}] = input;\n    ran[${id}] = true;`;
-		case "step": return `const output = await steps.${alias ?? ""}({ node: ${id}, step: ${literal(node.step)}, config: ${literal(node.config ?? {})}, input, results: Object.assign({}, results), runKey });
+		case "step": return `const output = testing ? stub(${id}, { stubbed: true }) : await steps.${alias ?? ""}({ node: ${id}, step: ${literal(node.step)}, config: ${literal(node.config ?? {})}, input, results: Object.assign({}, results), runKey, version: versionId, tenant, subject });
     results[${id}] = output === undefined ? null : output;
     ran[${id}] = true;`;
-		case "sleep": return `await sleep(${literal(durationMs(node.config?.["duration"]))});
+		case "sleep": return `if (!testing) await sleep(${literal(durationMs(node.config?.["duration"]))});
     results[${id}] = null;
     ran[${id}] = true;`;
-		case "approval": return `const payload = await createHook({ token: runKey + ":" + ${id} });
+		case "approval": return `const token = testing ? null : steps.${APPROVAL_ALIAS} === undefined ? runKey + ":" + ${id} : await steps.${APPROVAL_ALIAS}({ node: ${id}, config: ${literal(node.config ?? {})}, input, results: Object.assign({}, results), runKey, version: versionId, tenant, subject });
+    const payload = testing ? stub(${id}, { approved: true }) : await createHook({ token });
     results[${id}] = payload === undefined ? null : payload;
     ran[${id}] = !(payload !== null && typeof payload === "object" && !Array.isArray(payload) && payload.approved === false);`;
 		case "condition": return `const outcome = test(${literal(node.config ?? {})});
@@ -70,10 +82,12 @@ function nodeBody(node, alias) {
 const guard = (edges) => edges.map((edge) => `took(${literal(edge.source)}, ${edge.branch === void 0 ? "null" : literal(edge.branch)})`).join(" || ");
 /**
 * Compiles a graph to Workflow SDK dynamic source: plain JavaScript that
-* calls each step node through its own alias, sleeps with `sleep` and waits
-* on approvals with `createHook({ token: "<runKey>:<node>" })`. It runs the
-* same way `executeGraph` does. Throws when the graph is invalid or the
-* source is over 128 KiB. Pass it as `compile` to `createBuilder`.
+* starts at `meta.triggerNode` (or the only trigger), calls each step node
+* through its own alias, sleeps with `sleep` and waits on approvals with
+* `createHook`: the token is the id `steps.bs_approval` returns
+* (graphStarter's `approval`), else `<runKey>:<node>`. A `meta.mode` of
+* `test` returns `meta.stubs` instead. It runs the same way `executeGraph` does. Throws when the graph is invalid or the
+* source is over 128 KiB. Pass it as `compile` to `createWorkflowBuilder`.
 */
 function compileGraph(graph) {
 	const errors = validateGraph(graph);
@@ -81,6 +95,7 @@ function compileGraph(graph) {
 	const order = topologicalOrder(graph) ?? [];
 	const incoming = /* @__PURE__ */ new Map();
 	for (const edge of graph.edges) incoming.set(edge.target, [...incoming.get(edge.target) ?? [], edge]);
+	const triggers = graph.nodes.filter((node) => node.kind === "trigger");
 	const aliases = {};
 	const blocks = order.map((node, index) => {
 		let alias;
@@ -90,12 +105,13 @@ function compileGraph(graph) {
 		}
 		const body = nodeBody(node, alias);
 		const comment = `  // ${node.kind} node ${String(index)}`;
-		if (node.kind === "trigger") return `${comment}\n  {\n    ${body}\n  }`;
+		if (node.kind === "trigger") return `${comment}\n  if (${triggers.length === 1 ? `start === null || start === ${literal(node.id)}` : `start === ${literal(node.id)}`}) {\n    ${body}\n  }`;
 		return `${comment}\n  if (${guard(incoming.get(node.id) ?? [])}) {\n    ${body}\n  }`;
 	});
+	const pick = triggers.length === 1 ? "" : `  if (start === null) throw new TypeError("workflow-builder: pass the trigger node the run starts at, the id of one of the graph's trigger nodes");\n`;
 	const source = `async function ${EXPORT_NAME}(input, meta) {
   "use workflow";
-${RUNTIME}
+${RUNTIME}${pick}
 ${blocks.join("\n")}
   return Object.assign({}, results);
 }
@@ -115,7 +131,7 @@ function compiledGraphOf(value) {
 	if (!isGraphRecord(value) || value["engine"] !== "workflow-sdk" || value["format"] !== 1 || typeof value["source"] !== "string" || typeof value["exportName"] !== "string" || !isGraphRecord(value["aliases"])) return;
 	const aliases = {};
 	for (const [alias, step] of Object.entries(value["aliases"])) {
-		if (typeof step !== "string") return void 0;
+		if (typeof step !== "string") return;
 		aliases[alias] = step;
 	}
 	return {
@@ -130,6 +146,21 @@ const dynamicEnabled = () => {
 	const raw = globalThis.process?.env?.[DYNAMIC_WORKFLOWS_ENV];
 	return raw === "1" || raw?.toLowerCase() === "true";
 };
+/** Who a live run's steps run as: the version's publisher, or the app's service principal. */
+function principalAttributes(call) {
+	switch (call.version.owner) {
+		case "user": return call.version.publishedBy === void 0 ? {} : {
+			[WORKFLOW_ATTRIBUTES.principalKind]: "user",
+			[WORKFLOW_ATTRIBUTES.principal]: call.version.publishedBy
+		};
+		case "organization": return { [WORKFLOW_ATTRIBUTES.principalKind]: "service_principal" };
+		case void 0: return {};
+		default: {
+			const unknown = call.version.owner;
+			throw new TypeError(`better-supabase: unknown owner ${String(unknown)}`);
+		}
+	}
+}
 function contextOf(call) {
 	const actor = call.actor === void 0 ? void 0 : {
 		id: call.actor,
@@ -141,12 +172,14 @@ function contextOf(call) {
 	};
 }
 /**
-* The `start` for `createBuilder`: starts the published version as dynamic
+* The `start` for `createWorkflowBuilder`: starts the published version as dynamic
 * source when dynamic workflows are on, and through `executor` otherwise.
 * The source is always compiled from the version's graph; a stored
-* compiled form is never run. Runs carry
-* `bs.tenant`, `bs.actor`, `bs.definition`, `bs.version` and `bs.key`, and
-* a repeated key returns the first run.
+* compiled form is never run. Runs carry `bs.tenant`, `bs.actor`,
+* `bs.definition`, `bs.version` and `bs.key`, plus `bs.subject`,
+* `bs.mode` and `bs.trigger_node` when set. A live run also records its
+* principal: the publisher (`user`), or the app's service principal for an
+* organization-owned version. A repeated key returns the first run.
 */
 function graphStarter(options) {
 	return async (call) => {
@@ -157,17 +190,30 @@ function graphStarter(options) {
 			nodes: [],
 			edges: []
 		};
+		const testing = call.mode === "test";
+		const triggerNode = startNodeOf(graph, call.triggerNode);
 		const meta = {
 			runKey: key,
 			definition: call.definition.id,
-			version: call.version.version
+			version: call.version.version,
+			versionId: call.version.id,
+			triggerNode,
+			...call.tenant === void 0 ? {} : { tenant: call.tenant },
+			...call.subject === void 0 ? {} : { subject: call.subject },
+			...testing ? {
+				mode: "test",
+				stubs: call.stubs ?? {}
+			} : {}
 		};
 		const startOptions = {
 			attributes: {
 				...contextAttributes(contextOf(call)),
 				[WORKFLOW_ATTRIBUTES.definition]: call.definition.id,
 				[WORKFLOW_ATTRIBUTES.version]: String(call.version.version),
-				[WORKFLOW_ATTRIBUTES.key]: key
+				[WORKFLOW_ATTRIBUTES.key]: key,
+				[WORKFLOW_ATTRIBUTES.triggerNode]: triggerNode,
+				...call.subject === void 0 ? {} : { [WORKFLOW_ATTRIBUTES.subject]: subjectAttribute(call.subject) },
+				...testing ? { [WORKFLOW_ATTRIBUTES.mode]: "test" } : principalAttributes(call)
 			},
 			...options.world === void 0 ? {} : { world: options.world }
 		};
@@ -179,6 +225,7 @@ function graphStarter(options) {
 				if (step === void 0) throw new Error(`better-supabase: the graph uses step "${name}", which was not passed to graphStarter`);
 				steps[alias] = step;
 			}
+			if (options.approval !== void 0) steps[APPROVAL_ALIAS] = options.approval;
 			return (await start(compiled.source, [call.input, meta], {
 				...startOptions,
 				experimental_dynamic: {
@@ -188,6 +235,7 @@ function graphStarter(options) {
 			})).runId;
 		}
 		if (options.executor === void 0) throw new Error(`better-supabase: dynamic workflows are off (${DYNAMIC_WORKFLOWS_ENV}); pass an executor to graphStarter`);
+		if (testing && options.executorRunsTests !== true) throw new Error("better-supabase: spread graphRunFields(meta) into the executor's runtime and pass executorRunsTests: true to graphStarter to start test runs without dynamic workflows");
 		return (await start(options.executor, [
 			graph,
 			call.input,

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

@@ -1,4 +1,61 @@
-import { a as StartOnEventOptions, c as contextAttributes, d as startFor, f as startOnEvent, i as StartForOptions, l as hookMetadata, m as workflowStarter, n as HookForbiddenError, o as WorkflowFn, p as workflowContext, r as ProtectWebHandlerOptions, s as authorizeHook, t as AuthorizeHookOptions, u as protectWebHandler } from "../workflow-sdk-B3yLD6Br.js";
+/// <reference lib="esnext.temporal" />
+import { _ as workflowContext, a as StartOnEventOptions, c as WorkflowRunAs, d as authorizeHook, f as contextAttributes, g as startOnEvent, h as startFor, i as StartForOptions, l as WorkflowRunAsFor, m as protectWebHandler, n as HookForbiddenError, o as WorkflowContextOptions, p as hookMetadata, r as ProtectWebHandlerOptions, s as WorkflowFn, t as AuthorizeHookOptions, u as WorkflowStarterOptions, v as workflowStarter } from "../workflow-sdk-q8cLwW1K.js";
+//#region src/workflow-sdk/approval-waiter.d.ts
+/** How `approvalWaiter.wait` ended. */
+type ApprovalWaitResult<P> = {
+  readonly status: "resumed";
+  readonly payload: P;
+} | {
+  readonly status: "expired";
+};
+interface ApprovalWaitOptions {
+  /** When the wait expires: a `Temporal.Instant` or an RFC 3339 timestamp. */
+  readonly expiresAt: Temporal.Instant | string;
+}
+/**
+ * Pauses a workflow on an approval and resumes it by token. `wait` runs
+ * inside a `"use workflow"` function; `wake` runs in server code, after
+ * the approver was checked (`authorizeHook`, or the provider's
+ * `approverOf`). The token is the approval request's id, so the code that
+ * records the decision can wake the run without storing the hook.
+ */
+interface ApprovalWaiter {
+  /**
+   * Waits for `wake(token, payload)` until `expiresAt`: `{ status:
+   * "resumed", payload }`, or `{ status: "expired" }` when the time passes
+   * first (at once for a past `expiresAt`).
+   */
+  wait<P = unknown>(token: string, options: ApprovalWaitOptions): Promise<ApprovalWaitResult<P>>;
+  /** Resumes the run waiting on `token`; `payload` defaults to `null`. */
+  wake(token: string, payload?: unknown): Promise<void>;
+}
+/** `wait` and `wake` for approvals that pause a workflow run. */
+export declare const approvalWaiter: ApprovalWaiter;
+/** The outbox events of the approvals module that end a wait. */
+export declare const APPROVAL_OUTCOME_EVENTS: readonly string[];
+/** The payload `wakeOnApproval` resumes a run with. */
+interface ApprovalOutcome {
+  /** `true` only for `approval.approved`; a builder approval node takes the branch from it. */
+  readonly approved: boolean;
+  readonly status: "approved" | "rejected" | "expired" | "cancelled";
+  readonly requestId: string;
+}
+/** The part of an outbox event `wakeOnApproval` reads. */
+interface ApprovalOutcomeEvent {
+  readonly type: string;
+  readonly payload: unknown;
+}
+/**
+ * Wakes the run waiting on an approval request once the approvals module
+ * decides it: pass every outbox event from your consumer. For
+ * `approval.approved`, `approval.rejected`, `approval.expired` and
+ * `approval.cancelled` it calls `waiter.wake(<request id>, outcome)` and
+ * returns `true`; other events return `false`. The request id is a random
+ * uuid, so only `decide_approval` (and with it the approver check) can end
+ * the wait. A wake for a request no run waits on is ignored.
+ */
+export declare function wakeOnApproval(event: ApprovalOutcomeEvent, waiter?: Pick<ApprovalWaiter, "wake">): Promise<boolean>;
+//#endregion
 //#region src/workflow-sdk/attributes.d.ts
 /** The attributes the Supabase World's status trigger copies into `workflow_runs`. */
 export declare const WORKFLOW_ATTRIBUTES: {
@@ -9,6 +66,22 @@ export declare const WORKFLOW_ATTRIBUTES: {
   readonly definition: "bs.definition";
   /** The builder version number a run started from. */
   readonly version: "bs.version";
+  /** The opaque ticket `bs.forContext` resolves into the context a step runs as. */
+  readonly ticket: "bs.ticket";
+  /** The user an event or schedule start runs as (`runAs`). */
+  readonly publisher: "bs.publisher";
+  /** The event actor or schedule creator behind a `runAs` start, for audit only. */
+  readonly trigger: "bs.trigger";
+  /** The record a run belongs to, as `<type>/<id>`. */
+  readonly subject: "bs.subject";
+  /** What a `runAs` run's steps run as: `user`, `service_principal`, `system` or `external`. */
+  readonly principalKind: "bs.principal_kind";
+  /** The id of that principal, when it has one. */
+  readonly principal: "bs.principal";
+  /** `test` for a builder test run; anything else records `live`. */
+  readonly mode: "bs.mode";
+  /** The trigger node a builder run started at. */
+  readonly triggerNode: "bs.trigger_node";
 };
 //#endregion
-export { type AuthorizeHookOptions, HookForbiddenError, type ProtectWebHandlerOptions, type StartForOptions, type StartOnEventOptions, type WorkflowFn, authorizeHook, contextAttributes, hookMetadata, protectWebHandler, startFor, startOnEvent, workflowContext, workflowStarter };
+export { type ApprovalOutcome, type ApprovalOutcomeEvent, type ApprovalWaitOptions, type ApprovalWaitResult, type ApprovalWaiter, type AuthorizeHookOptions, HookForbiddenError, type ProtectWebHandlerOptions, type StartForOptions, type StartOnEventOptions, type WorkflowContextOptions, type WorkflowFn, type WorkflowRunAs, type WorkflowRunAsFor, type WorkflowStarterOptions, authorizeHook, contextAttributes, hookMetadata, protectWebHandler, startFor, startOnEvent, workflowContext, workflowStarter };

package/dist/workflow-sdk/index.js

@@ -1,3 +1,83 @@
-import { t as WORKFLOW_ATTRIBUTES } from "../attributes-5dYul0u0.js";
-import { a as protectWebHandler, c as startOnEvent, i as hookMetadata, l as workflowContext, n as authorizeHook, r as contextAttributes, s as startFor, t as HookForbiddenError, u as workflowStarter } from "../workflow-sdk-C2WJ_G2O.js";
-export { HookForbiddenError, WORKFLOW_ATTRIBUTES, authorizeHook, contextAttributes, hookMetadata, protectWebHandler, startFor, startOnEvent, workflowContext, workflowStarter };
+import { t as WORKFLOW_ATTRIBUTES } from "../attributes-D4mA7WhI.js";
+import { a as protectWebHandler, c as startOnEvent, i as hookMetadata, l as workflowContext, n as authorizeHook, r as contextAttributes, s as startFor, t as HookForbiddenError, u as workflowStarter } from "../workflow-sdk-BZ6qsRlY.js";
+import { resumeHook } from "workflow/api";
+import { createHook, sleep } from "workflow";
+//#region src/workflow-sdk/approval-waiter.ts
+const RFC_3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/u;
+function tokenOf(token) {
+	if (token === "") throw new TypeError("An approval token is non-empty");
+	return token;
+}
+function epochOf(expiresAt) {
+	if (typeof expiresAt !== "string") return expiresAt.epochMilliseconds;
+	const text = expiresAt.toUpperCase();
+	const epoch = RFC_3339.test(text) ? Date.parse(text) : NaN;
+	if (Number.isNaN(epoch)) throw new TypeError(`expiresAt "${expiresAt}" is not an RFC 3339 timestamp`);
+	return epoch;
+}
+/** `wait` and `wake` for approvals that pause a workflow run. */
+const approvalWaiter = Object.freeze({
+	async wait(token, options) {
+		const key = tokenOf(token);
+		const until = epochOf(options.expiresAt);
+		if (until <= Date.now()) return { status: "expired" };
+		const hook = createHook({ token: key });
+		try {
+			return await Promise.race([hook.then((payload) => ({
+				status: "resumed",
+				payload
+			})), sleep(new Date(until)).then(() => ({ status: "expired" }))]);
+		} finally {
+			hook.dispose();
+		}
+	},
+	async wake(token, payload = null) {
+		await resumeHook(tokenOf(token), payload);
+	}
+});
+/** The outbox events of the approvals module that end a wait. */
+const APPROVAL_OUTCOME_EVENTS = Object.freeze([
+	"approval.approved",
+	"approval.rejected",
+	"approval.expired",
+	"approval.cancelled"
+]);
+/**
+* Wakes the run waiting on an approval request once the approvals module
+* decides it: pass every outbox event from your consumer. For
+* `approval.approved`, `approval.rejected`, `approval.expired` and
+* `approval.cancelled` it calls `waiter.wake(<request id>, outcome)` and
+* returns `true`; other events return `false`. The request id is a random
+* uuid, so only `decide_approval` (and with it the approver check) can end
+* the wait. A wake for a request no run waits on is ignored.
+*/
+async function wakeOnApproval(event, waiter = approvalWaiter) {
+	if (!APPROVAL_OUTCOME_EVENTS.includes(event.type)) return false;
+	const payload = event.payload;
+	const requestId = typeof payload === "object" && payload !== null && "id" in payload && typeof payload.id === "string" ? payload.id : void 0;
+	if (requestId === void 0) return false;
+	const status = statusOf(event.type);
+	const outcome = {
+		approved: status === "approved",
+		status,
+		requestId
+	};
+	try {
+		await waiter.wake(requestId, outcome);
+	} catch (cause) {
+		if (!isMissingHook(cause)) throw cause;
+	}
+	return true;
+}
+function statusOf(type) {
+	switch (type) {
+		case "approval.approved": return "approved";
+		case "approval.rejected": return "rejected";
+		case "approval.expired": return "expired";
+		default: return "cancelled";
+	}
+}
+/** The Workflow SDK's `HookNotFoundError`, matched by name as `HookNotFoundError.is` does. */
+const isMissingHook = (cause) => cause instanceof Error && cause.name === "HookNotFoundError";
+//#endregion
+export { APPROVAL_OUTCOME_EVENTS, HookForbiddenError, WORKFLOW_ATTRIBUTES, approvalWaiter, authorizeHook, contextAttributes, hookMetadata, protectWebHandler, startFor, startOnEvent, wakeOnApproval, workflowContext, workflowStarter };

package/dist/workflow-sdk/world/index.d.ts

@@ -1,14 +1,12 @@
+import { o as EventHub } from "../../events-CTreRrgP.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
 import { Pool } from "pg";
 import { World } from "@workflow/world";
-//#region src/sql/modules/workflow-sdk-world-ddl.generated.d.ts
-/** The `@workflow/world-postgres` version the DDL below was generated from. */
-export declare const WORLD_POSTGRES_VERSION = "5.0.2";
-//#endregion
 //#region src/sql/modules/workflow-sdk-world.d.ts
 declare const WORKFLOW_DELIVERY_MODES: readonly ["poll", "pg_net"];
 type WorkflowDeliveryMode = (typeof WORKFLOW_DELIVERY_MODES)[number];
 //#endregion
-//#region src/workflow-sdk/world/world.d.ts
+//#region src/workflow-sdk/world/types.d.ts
 /**
  * The `@workflow/world` protocol this World speaks: the package version its
  * types and queue format come from. Its tables come from
@@ -43,7 +41,7 @@ interface SupabaseWorldOptions {
    * unencrypted.
    */
   readonly encryptionKey?: string;
-  /** The jobs queue the messages wait in (`sql.modules.workflow-sdk-world.options.queue`). */
+  /** The jobs queue the messages wait in (`blocks.workflow-sdk-world.options.queue`). */
   readonly queue?: string;
   /** The schema of the jobs functions, default `better_supabase`. */
   readonly schema?: string;
@@ -61,17 +59,27 @@ interface SupabaseWorldOptions {
   readonly deliveryTimeout?: number;
   /** The queue namespace, as `WORKFLOW_QUEUE_NAMESPACE`. */
   readonly namespace?: string;
+  /**
+   * Connections the World's own pool opens (default 10). Each delivery holds
+   * one only for its short claim, settle and heartbeat statements, so more
+   * deliveries than connections wait for one instead of failing.
+   */
+  readonly maxConnections?: number;
+  /** Milliseconds a statement waits for a free connection before it fails (default 30000). */
+  readonly connectionTimeout?: number;
+  /** Milliseconds an unused connection stays open (default 10000). */
+  readonly idleTimeout?: number;
+  /** `statement_timeout` of the World's connections, in milliseconds (default 30000). */
+  readonly statementTimeout?: number;
+  /** `idle_in_transaction_session_timeout` of the World's connections, in milliseconds (default 15000). */
+  readonly idleInTransactionTimeout?: number;
+  /** `betterSupabase.events`: errors on idle pooled connections arrive as `error` events. */
+  readonly events?: EventHub;
+  /** Where idle-connection errors go without `error` handlers. Defaults to the console. */
+  readonly logger?: Logger;
 }
-/** The flow route: `flowUrl`, `WORKFLOW_FLOW_URL`, or the local server. */
-export declare function resolveFlowUrl(flowUrl?: string): string;
-/** A 32-byte key from base64 or hex. */
-export declare function parseMasterKey(value: string): Uint8Array;
-/** The run's AES-256 key: HKDF-SHA256 of the master key with info `run:<runId>`. */
-export declare function deriveRunKey(master: Uint8Array, runId: string): Promise<Uint8Array>;
-/** `t=<unix>,v1=<hex>` over `<t>.<job>.<body>`. */
-export declare function signDelivery(secret: string, job: string, body: string, now?: number): Promise<string>;
-/** Whether `header` signs `job` and `body` with `secret` within five minutes of `now`. */
-export declare function verifyDelivery(secret: string, header: string | null, job: string, body: string, now?: number): Promise<boolean>;
+//#endregion
+//#region src/workflow-sdk/world/world.d.ts
 /** The World plus the delivery helpers the tests and routes use. */
 type SupabaseWorld = World & {
   start(): Promise<void>;
@@ -91,17 +99,40 @@ type SupabaseWorld = World & {
  * ```
  */
 export declare function createSupabaseWorld(options?: SupabaseWorldOptions): SupabaseWorld;
-/** The options `createWorld()` reads from the environment. */
-export declare function worldOptionsFromEnv(source?: Readonly<Record<string, string | undefined>>): SupabaseWorldOptions;
 /**
  * The World from the environment, the factory the Workflow SDK calls for
  * `WORKFLOW_TARGET_WORLD=better-supabase/workflow-sdk/world`: the connection
  * 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`.
  */
 export declare function createWorld(): SupabaseWorld;
 //#endregion
+//#region src/sql/modules/workflow-sdk-world-ddl.generated.d.ts
+/** The `@workflow/world-postgres` version the DDL below was generated from. */
+export declare const WORLD_POSTGRES_VERSION = "5.0.4";
+//#endregion
+//#region src/workflow-sdk/world/crypto.d.ts
+/** A 32-byte key from base64 or hex. */
+export declare function parseMasterKey(value: string): Uint8Array;
+/** The run's AES-256 key: HKDF-SHA256 of the master key with info `run:<runId>`. */
+export declare function deriveRunKey(master: Uint8Array, runId: string): Promise<Uint8Array>;
+/** `t=<unix>,v1=<hex>` over `<t>.<job>.<body>`. */
+export declare function signDelivery(secret: string, job: string, body: string, now?: number): Promise<string>;
+/** Whether `header` signs `job` and `body` with `secret` within five minutes of `now`. */
+export declare function verifyDelivery(secret: string, header: string | null, job: string, body: string, now?: number): Promise<boolean>;
+//#endregion
+//#region src/workflow-sdk/world/env.d.ts
+/** The flow route: `flowUrl`, `WORKFLOW_FLOW_URL`, or the local server. */
+export declare function resolveFlowUrl(flowUrl?: string): string;
+/** The options `createWorld()` reads from the environment. */
+export declare function worldOptionsFromEnv(source?: Readonly<Record<string, string | undefined>>): SupabaseWorldOptions;
+//#endregion
 export { type SupabaseWorld, type SupabaseWorldOptions, type WorkflowDeliveryMode, createWorld as default };