better-supabase 0.12.0 → 0.13.0

package/dist/events-SqJLbb8q.js

@@ -0,0 +1,24 @@
+import { n as event, t as defineEvents } from "./event-map-CtPFhcOp.js";
+//#region src/blocks/organizations/events.ts
+/** The `organizations` block's event types, for its manifest and `onBlockEvent`. */
+const organizationsEvents = defineEvents({
+	"organization.created": event(),
+	"organization.updated": event(),
+	"organization.deleted": event(),
+	"organization.member_added": event(),
+	"organization.member_removed": event(),
+	"organization.member_left": event(),
+	"organization.member_suspended": event(),
+	"organization.member_resumed": event(),
+	"organization.role_changed": event(),
+	"organization.ownership_transferred": event(),
+	"organization.switched": event(),
+	"invitation.created": event(),
+	"invitation.resent": event(),
+	"invitation.updated": event(),
+	"invitation.accepted": event(),
+	"invitation.declined": event(),
+	"invitation.revoked": event()
+});
+//#endregion
+export { organizationsEvents as t };

package/dist/executor-C29668fO.d.ts

@@ -0,0 +1,281 @@
+import { T as ErrorMapper, f as Result } from "./result-mijqfoJN.js";
+import { V as TableMeta, d as Codec, g as FunctionMeta, k as RelationMeta } from "./types-DmshMaXz.js";
+//#region src/ir/types.d.ts
+/**
+ * The query IR. Every repository call becomes one of these operations; the
+ * executor compiles it to PostgREST or SQL. Column names in the IR are database
+ * names; `Selection` carries the app aliases.
+ */
+type ColumnOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "is" | "like" | "ilike" | "match" | "imatch" | "contains" | "containedBy" | "overlaps" | "fts";
+type Quantifier = "some" | "none" | "every";
+type Condition = {
+  readonly kind: "and";
+  readonly items: readonly Condition[];
+} | {
+  readonly kind: "or";
+  readonly items: readonly Condition[];
+} | {
+  readonly kind: "not";
+  readonly item: Condition;
+} | {
+  readonly kind: "column";
+  readonly column: string;
+  readonly op: ColumnOp;
+  readonly value: unknown;
+  /** Full-text search configuration for `fts`. */
+  readonly config?: string;
+  /**
+   * The column is `json`/`jsonb`: containment values are JSON documents,
+   * also when they are arrays, never Postgres array literals.
+   */
+  readonly json?: true;
+  /**
+   * Keys into a json column: the condition compares the text at this path
+   * (`column->a->>b`, `column #>> '{a,b}'`), and `is null` holds when the
+   * key is missing or JSON `null`.
+   */
+  readonly path?: readonly string[];
+} | {
+  readonly kind: "relation";
+  readonly name: string;
+  readonly relation: RelationMeta;
+  readonly target: TableMeta;
+  readonly quantifier: Quantifier;
+  readonly where: Condition | undefined;
+};
+interface SelectColumn {
+  /** Key in the returned row. */
+  readonly alias: string;
+  /** Database column name. */
+  readonly column: string;
+  /** Read the column as text, so exact `int8`/`numeric` values survive JSON. */
+  readonly cast?: "text";
+  /** Decodes the returned value (see `ColumnMeta.codec`). */
+  readonly codec?: Codec;
+}
+interface OrderTerm {
+  readonly column: string;
+  readonly direction: "asc" | "desc";
+  readonly nulls?: "first" | "last";
+  /**
+   * Added by the repository (the primary key order of `findMany`), not asked
+   * for by the caller, so a split read may sort it approximately.
+   */
+  readonly implicit?: true;
+  /**
+   * Sort `aggregate()` groups by this aggregate of `column`; `count` counts the
+   * group's rows and its `column` is `*`.
+   */
+  readonly aggregate?: AggregateFn | "count";
+  /** Sort by `column` of this to-one relation's row (only on the root table). */
+  readonly relation?: {
+    readonly name: string;
+    readonly relation: RelationMeta;
+    readonly target: TableMeta;
+  };
+}
+interface Include {
+  readonly alias: string;
+  readonly relation: RelationMeta;
+  readonly target: TableMeta;
+  readonly selection: Selection;
+  readonly where: Condition | undefined;
+  readonly orderBy: readonly OrderTerm[];
+  readonly limit: number | undefined;
+  /** Drop parent rows without a match (`!inner`). */
+  readonly required: boolean;
+  /**
+   * `_count` include: returns the number of matching related rows instead of
+   * rows, folded into `row._count[count]` when decoded.
+   */
+  readonly count?: string;
+  /**
+   * `_sum`/`_avg`/`_min`/`_max` include: `selection.aggregate` holds the
+   * measures, folded into `row[`_${fn}`][name]` when decoded.
+   */
+  readonly aggregate?: {
+    readonly fn: AggregateFn;
+    readonly name: string;
+  };
+}
+type AggregateFn = "sum" | "avg" | "min" | "max";
+interface Measure {
+  readonly fn: AggregateFn;
+  /** Key in the returned row (`_sum_amount`, or the column alias in an include). */
+  readonly key: string;
+  /** App column name, the key under `_sum` in the decoded row. */
+  readonly alias: string;
+  /** Database column name. */
+  readonly column: string;
+  /** Read the result as text, so exact `int8`/`numeric` values survive JSON. */
+  readonly cast?: "text";
+  readonly codec?: Codec;
+}
+/**
+ * Aggregates instead of rows. `Selection.columns` become the grouping columns;
+ * without any, the result is exactly one row.
+ */
+interface Aggregation {
+  /** Also return `_count`, the number of rows in each group. */
+  readonly count: boolean;
+  readonly measures: readonly Measure[];
+}
+interface Selection {
+  readonly columns: readonly SelectColumn[];
+  readonly includes: readonly Include[];
+  readonly aggregate?: Aggregation;
+}
+type CountMode = "exact" | "planned" | "estimated";
+interface SelectOp {
+  readonly kind: "select";
+  readonly table: TableMeta;
+  readonly selection: Selection;
+  readonly where: Condition | undefined;
+  readonly orderBy: readonly OrderTerm[];
+  readonly limit: number | undefined;
+  readonly offset: number | undefined;
+  readonly count: CountMode | undefined;
+  /** Only count, return no rows. */
+  readonly head: boolean;
+  readonly single: "one" | "maybe" | undefined;
+  /**
+   * `limit` includes one row past the page, which `paginate()` reads to set
+   * `hasMore`.
+   */
+  readonly lookAhead?: boolean;
+  /**
+   * `limit` bounds a check, not a page: `findOnly` reads two rows to detect a
+   * second match.
+   */
+  readonly unpaged?: boolean;
+  /**
+   * Read from this set-returning function instead of the table (`db.$search`).
+   * Only executors with `functionSources` honor it.
+   */
+  readonly source?: FunctionSource;
+}
+/** A function returning `setof <table>`, called with named arguments. */
+interface FunctionSource {
+  readonly schema: string;
+  readonly name: string;
+  readonly args: Readonly<Record<string, unknown>>;
+}
+/** The statement a mutation runs. */
+type MutationKind = "insert" | "upsert" | "update" | "delete";
+/**
+ * What the caller asked for: `softDelete` is a `delete` that a plugin turned
+ * into an update.
+ */
+type MutationIntent = MutationKind | "softDelete";
+interface MutationBase {
+  /**
+   * What the caller asked for, when a plugin rewrote the mutation into another
+   * kind. The plugin that rewrites it sets this; mutation events report it.
+   */
+  readonly intent?: MutationIntent;
+  /**
+   * How a mutation without `returning` counts the rows it wrote. Defaults to
+   * `exact`; SQL executors always return the statement's own row count.
+   */
+  readonly count?: CountMode;
+}
+interface BoundedMutation extends MutationBase {
+  /**
+   * The most rows the statement may change. More fails with `max_affected` and
+   * writes nothing. Over PostgREST it needs PostgREST 13 or later.
+   */
+  readonly maxAffected?: number;
+}
+interface InsertOp extends MutationBase {
+  readonly kind: "insert";
+  readonly table: TableMeta;
+  /** Rows keyed by database column names. */
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  readonly returning: Selection | undefined;
+  readonly onConflict: {
+    readonly columns: readonly string[];
+    readonly action: "update" | "ignore";
+  } | undefined;
+  /**
+   * In a multi-row insert, columns some rows leave out become `null` instead of
+   * their column default.
+   */
+  readonly defaultToNull: boolean;
+}
+interface UpdateOp extends BoundedMutation {
+  readonly kind: "update";
+  readonly table: TableMeta;
+  /** Keyed by database column names. */
+  readonly set: Readonly<Record<string, unknown>>;
+  readonly where: Condition | undefined;
+  readonly returning: Selection | undefined;
+}
+interface DeleteOp extends BoundedMutation {
+  readonly kind: "delete";
+  readonly table: TableMeta;
+  readonly where: Condition | undefined;
+  readonly returning: Selection | undefined;
+}
+type Operation = SelectOp | InsertOp | UpdateOp | DeleteOp;
+type MutationOp = InsertOp | UpdateOp | DeleteOp;
+declare const and: (...items: (Condition | undefined)[]) => Condition | undefined;
+declare const or: (...items: Condition[]) => Condition;
+declare const not: (item: Condition) => Condition;
+declare const column: (name: string, op: ColumnOp, value: unknown) => Condition;
+//#endregion
+//#region src/core/executor.d.ts
+interface ExecuteContext {
+  /** Already includes the call's `timeout`, when it has one. */
+  readonly signal?: AbortSignal;
+  readonly errorMappers: readonly ErrorMapper[];
+  /**
+   * The call's `retry` setting. PostgREST passes it to postgrest-js, which
+   * retries idempotent requests on network errors, 503 and 520; executors
+   * without retries ignore it.
+   */
+  readonly retry?: boolean;
+}
+interface ExecuteResult {
+  /** Rows keyed by the aliases in the operation's selection. */
+  readonly rows: readonly Record<string, unknown>[];
+  readonly count: number | null;
+}
+/**
+ * Runs IR operations. PostgREST (`postgrestExecutor`) and SQL
+ * (`better-supabase/postgres`) are built in; any other backend can implement
+ * this interface and prove it with `testExecutor` from
+ * `better-supabase/testing`.
+ */
+interface Executor {
+  readonly name: string;
+  /** Honors `SelectOp.source`. `db.$search` fails on executors without it. */
+  readonly functionSources?: boolean;
+  execute(op: Operation, context: ExecuteContext): Promise<Result<ExecuteResult>>;
+  /** Calls a database function. Optional; `db.$rpc` fails without it. */
+  rpc?(name: string, args: Readonly<Record<string, unknown>>, context: RpcContext): Promise<Result<unknown>>;
+  /**
+   * Runs several reads together, for `db.$many`: one transaction on a SQL
+   * connection. Returns one result per operation, in order. Optional; without
+   * it `db.$many` runs the operations in parallel.
+   */
+  batch?(ops: readonly Operation[], context: ExecuteContext): Promise<readonly Result<ExecuteResult>[]>;
+}
+interface RpcContext extends ExecuteContext {
+  readonly schema: string;
+  /** The function is `stable`: send it as a GET, so read replicas can serve it. */
+  readonly get?: boolean;
+  readonly function?: FunctionMeta;
+  /**
+   * The result columns to select, by database name. Set when a column has a
+   * codec, which reads it as text: a JSON number has already lost an `int8`
+   * past 2^53 or a `numeric`'s digits.
+   */
+  readonly select?: readonly RpcColumn[];
+}
+/** One column of an `RpcContext.select` list. */
+interface RpcColumn {
+  readonly column: string;
+  readonly cast?: "text";
+}
+//#endregion
+export { Selection as C, not as D, column as E, or as O, SelectOp as S, and as T, MutationOp as _, AggregateFn as a, Quantifier as b, Condition as c, FunctionSource as d, Include as f, MutationKind as g, MutationIntent as h, RpcContext as i, CountMode as l, Measure as m, ExecuteResult as n, Aggregation as o, InsertOp as p, Executor as r, ColumnOp as s, ExecuteContext as t, DeleteOp as u, Operation as v, UpdateOp as w, SelectColumn as x, OrderTerm as y };

package/dist/executor-C5uyGttm.js

@@ -0,0 +1,207 @@
+import { r as isPlainObject } from "./clone-CkG0-hlI.js";
+import { c as mapDbError, d as withMaxAffected, n as dbError } from "./errors-D7u24ZJH.js";
+import { a as ok, r as err, s as toDbError } from "./result-DIT_qp4G.js";
+import { n as quoteIdent, t as compileSql } from "./sql-CQIikLnQ.js";
+import { t as fromPgError } from "./pg-error-B5QLDcbG.js";
+//#region src/postgres/executor.ts
+/**
+* A `count(*)::bigint`, which node-postgres returns as text. A count past
+* `Number.MAX_SAFE_INTEGER` fails instead of losing precision.
+*/
+function countOf(value) {
+	const count = value === null || value === void 0 ? 0 : typeof value === "number" ? value : typeof value === "bigint" || typeof value === "string" ? Number(value) : NaN;
+	if (!Number.isSafeInteger(count) || count < 0) throw new TypeError(`Unreadable row count: ${String(value)}`);
+	return count;
+}
+/** `Plan Rows` of the top node of an `explain (format json)` result. */
+async function plannedRows(client, query) {
+	const [first] = await client.queryRaw(query.text, [...query.params]);
+	const raw = first?.["QUERY PLAN"];
+	const plan = typeof raw === "string" ? JSON.parse(raw) : raw;
+	const top = Array.isArray(plan) ? plan[0] : void 0;
+	const rows = isPlainObject(top) && isPlainObject(top["Plan"]) ? top["Plan"]["Plan Rows"] : void 0;
+	if (typeof rows !== "number" || !Number.isFinite(rows) || rows < 0) throw new TypeError("The query plan has no row estimate");
+	return Math.min(Math.round(rows), Number.MAX_SAFE_INTEGER);
+}
+async function run(client, plan, op) {
+	const rows = plan.rows ? (await client.queryRaw(plan.rows.text, [...plan.rows.params])).map((entry) => entry.row) : [];
+	let count = null;
+	if (plan.count) {
+		const [first] = await client.queryRaw(plan.count.text, [...plan.count.params]);
+		count = first ? countOf(first.count) : 0;
+		if (plan.plannedCount && plan.countThreshold !== void 0 && count > plan.countThreshold) count = Math.max(count, await plannedRows(client, plan.plannedCount));
+	} else if (plan.plannedCount) count = await plannedRows(client, plan.plannedCount);
+	else if (op.kind !== "select") count = rows.length;
+	for (const next of plan.chunks ?? []) {
+		const more = await run(client, next, op);
+		rows.push(...more.rows);
+		count = (count ?? 0) + (more.count ?? 0);
+	}
+	return {
+		rows,
+		count
+	};
+}
+/**
+* Executes repository operations as SQL on a direct Postgres connection. Rows
+* have the same shape as over PostgREST. RLS applies when the client runs as
+* the caller (`ctx.postgres`, `createPostgres().asUser()`).
+*
+* `maxAffected` fails the statement itself, so its writes roll back. A call's
+* `timeout` is checked before the statement starts; set `statement_timeout` on
+* the connection to bound a running statement. `retry` does nothing here.
+*
+* `count: "planned"` reads the planner's row estimate from `explain (format
+* json)`; `count: "estimated"` counts exactly up to `estimatedCountThreshold`
+* rows and uses the estimate past it, like PostgREST.
+*/
+function postgresExecutor(client, options = {}) {
+	const signatures = /* @__PURE__ */ new Map();
+	const compile = options.estimatedCountThreshold === void 0 ? {} : { estimatedCountThreshold: options.estimatedCountThreshold };
+	const executeOn = (scoped, op, context) => executeWith(scoped, op, context, compile);
+	return {
+		name: "postgres",
+		functionSources: true,
+		execute: (op, context) => executeOn(client, op, context),
+		rpc: (name, args, context) => callFunction(client, name, args, context, signatures),
+		async batch(ops, context) {
+			if (!client.transaction) return Promise.all(ops.map((op) => executeOn(client, op, context)));
+			try {
+				return await client.transaction(async (scoped) => {
+					const results = [];
+					for (const op of ops) {
+						const result = await executeOn(scoped, op, context);
+						if (!result.ok) throw new BatchFailed();
+						results.push(result);
+					}
+					return results;
+				});
+			} catch (cause) {
+				if (!(cause instanceof BatchFailed)) {
+					const raw = fromPgError(cause);
+					if (!raw) throw cause;
+					const error = mapDbError(raw, context.errorMappers);
+					return ops.map(() => err(error));
+				}
+				return Promise.all(ops.map((op) => executeOn(client, op, context)));
+			}
+		}
+	};
+}
+var BatchFailed = class extends Error {};
+async function executeWith(client, op, context, options) {
+	let plan;
+	try {
+		plan = compileSql(op, options);
+	} catch (cause) {
+		return err(toDbError(cause));
+	}
+	if (plan.never) return ok({
+		rows: [],
+		count: 0
+	});
+	if (context.signal?.aborted) return err(dbError("aborted", "The request was aborted"));
+	const together = plan.chunks !== void 0 || plan.rows !== void 0 && plan.count !== void 0;
+	let result;
+	try {
+		result = together && client.transaction ? await client.transaction((scoped) => run(scoped, plan, op)) : await run(client, plan, op);
+	} catch (cause) {
+		const raw = fromPgError(cause);
+		const error = raw ? mapDbError(raw, context.errorMappers) : toDbError(cause);
+		return err(withMaxAffected(error, op.kind === "update" || op.kind === "delete" ? op.maxAffected : void 0));
+	}
+	if (op.kind === "select" && op.single) {
+		if (result.rows.length > 1) return err(dbError("multiple_rows", `Expected one ${op.table.key} row`));
+		if (result.rows.length === 0 && op.single === "one") return err(dbError("not_found", `No ${op.table.key} row matched`));
+	}
+	return ok(result);
+}
+const JSON_TYPES = /* @__PURE__ */ new Set(["json", "jsonb"]);
+const NO_NAMES = /* @__PURE__ */ new Set();
+/**
+* Undefined_function, invalid_function_definition and datatype_mismatch: the
+* function changed.
+*/
+const CHANGED_FUNCTION = /* @__PURE__ */ new Set([
+	"42883",
+	"42P13",
+	"42804"
+]);
+async function signatureOf(client, name, context, cache) {
+	const fn = context.function;
+	if (fn) return {
+		returnsSet: fn.returnsSet,
+		returnsVoid: fn.returns === "void",
+		json: new Set(fn.args.filter((arg) => JSON_TYPES.has(arg.type)).map((arg) => arg.name)),
+		outputOnly: NO_NAMES
+	};
+	const key = `${context.schema}.${name}`;
+	const cached = cache.get(key);
+	if (cached) return cached;
+	const found = await lookUp(client, name, context.schema);
+	if (found) cache.set(key, found);
+	return found;
+}
+async function lookUp(client, name, schema) {
+	const [found] = await client.queryRaw("select p.proretset as returns_set, p.prorettype = 'pg_catalog.void'::pg_catalog.regtype as returns_void, p.proargnames as arg_names, p.proargmodes::text[] as arg_modes, (select array_agg(t.typname::text order by a.ordinality) from unnest(p.proargtypes::oid[]) with ordinality as a(oid, ordinality) join pg_catalog.pg_type t on t.oid = a.oid) as arg_types from pg_catalog.pg_proc p join pg_catalog.pg_namespace n on n.oid = p.pronamespace where n.nspname = $1 and p.proname = $2 limit 1", [schema, name]);
+	if (!found) return;
+	const json = /* @__PURE__ */ new Set();
+	const outputOnly = /* @__PURE__ */ new Set();
+	if (found.arg_names && found.arg_types) {
+		const modes = found.arg_modes;
+		for (const [index, mode] of (modes ?? []).entries()) {
+			const argName = found.arg_names[index];
+			if ((mode === "o" || mode === "t") && argName) outputOnly.add(argName);
+		}
+		const inputIndexes = modes ? modes.flatMap((mode, index) => mode === "i" || mode === "v" || mode === "b" ? [index] : []) : found.arg_names.map((_, index) => index);
+		for (const [position, index] of inputIndexes.entries()) {
+			const argName = found.arg_names[index];
+			const type = found.arg_types[position];
+			if (typeof argName === "string" && type !== void 0 && JSON_TYPES.has(type)) json.add(argName);
+		}
+	}
+	return {
+		returnsSet: found.returns_set,
+		returnsVoid: found.returns_void,
+		json,
+		outputOnly
+	};
+}
+function argValue(value, json) {
+	if (value === null) return null;
+	if (json) return JSON.stringify(value);
+	if (typeof value === "bigint") return value.toString();
+	if (Array.isArray(value)) return value.map((item) => argValue(item, false));
+	if (isPlainObject(value)) return JSON.stringify(value);
+	if (typeof value === "object" && !(value instanceof Date) && !(value instanceof Uint8Array)) return String(value);
+	return value;
+}
+async function callFunction(client, name, args, context, cache) {
+	if (context.signal?.aborted) return err(dbError("aborted", "The request was aborted"));
+	try {
+		const signature = await signatureOf(client, name, context, cache);
+		if (!signature) return err(mapDbError({
+			code: "PGRST202",
+			message: `Could not find the function ${context.schema}.${name} in the database`
+		}, context.errorMappers));
+		const params = [];
+		const named = Object.entries(args).filter(([key, value]) => value !== void 0 && !signature.outputOnly.has(key)).map(([key, value]) => {
+			params.push(argValue(value, signature.json.has(key)));
+			return `${quoteIdent(key)} => $${String(params.length)}`;
+		});
+		const call = `${quoteIdent(context.schema)}.${quoteIdent(name)}(${named.join(", ")})`;
+		if (signature.returnsVoid) {
+			await client.queryRaw(`select ${call}`, params);
+			return ok(null);
+		}
+		const source = context.select ? `(select ${context.select.map(({ column, cast }) => cast ? `bs_call.${quoteIdent(column)}::${cast} as ${quoteIdent(column)}` : `bs_call.${quoteIdent(column)}`).join(", ")} from ${call} as bs_call)` : call;
+		const values = (await client.queryRaw(`select to_json(bs_call) as value from ${source} as bs_call`, params)).map((row) => row.value);
+		return ok(signature.returnsSet ? values : values[0] ?? null);
+	} catch (cause) {
+		const raw = fromPgError(cause);
+		if (raw?.code && CHANGED_FUNCTION.has(raw.code)) cache.delete(`${context.schema}.${name}`);
+		return err(raw ? mapDbError(raw, context.errorMappers) : toDbError(cause));
+	}
+}
+//#endregion
+export { postgresExecutor as t };

package/dist/executor-Cy1nk4MZ.d.ts

@@ -0,0 +1,104 @@
+import { B as WorkflowGraph } from "./types-vVsLvOUJ.js";
+//#region src/blocks/workflow-builder/executor.d.ts
+/** The record a run belongs to. */
+interface GraphSubject {
+  readonly type: string;
+  readonly id: string;
+}
+/** What a step node passes to the engine's step: plain data, so it serializes. */
+interface GraphStepCall {
+  /** The node id, which `workflow_node_runs` keys on. */
+  readonly node: string;
+  /** The library step's name. */
+  readonly step: string;
+  readonly config: Readonly<Record<string, unknown>>;
+  /** The trigger's input. */
+  readonly input: unknown;
+  /** The outputs of the nodes that ran before it, by node id. */
+  readonly results: Readonly<Record<string, unknown>>;
+  /** The run's key; approval hooks use `<runKey>:<node>` as their token. */
+  readonly runKey: string;
+  /** The published version's id; pass it to `builder.versions.runAs`. */
+  readonly version?: string;
+  /** The tenant the run belongs to; pass it to `builder.versions.runAs` too. */
+  readonly tenant?: string;
+  readonly subject?: GraphSubject;
+}
+/**
+ * What an approval node passes to `GraphRuntime.requestApproval`: plain data,
+ * so it serializes.
+ */
+interface GraphApprovalCall {
+  readonly node: string;
+  /** The node's config, e.g. the approvals `action` to file the request under. */
+  readonly config: Readonly<Record<string, unknown>>;
+  readonly input: unknown;
+  readonly results: Readonly<Record<string, unknown>>;
+  readonly runKey: string;
+  readonly version?: string;
+  readonly tenant?: string;
+  readonly subject?: GraphSubject;
+}
+/** What the engine does for each kind of node. */
+interface GraphRuntime {
+  readonly runKey: string;
+  /** The published version's id (`GraphRunMeta.versionId`), passed to each step. */
+  readonly version?: string;
+  /** The run's tenant, passed to each step. */
+  readonly tenant?: string;
+  /**
+   * The record the run belongs to: passed to each step, and conditions read it
+   * as `subject`.
+   */
+  readonly subject?: GraphSubject;
+  /** The trigger node the run starts at; required when the graph has several. */
+  readonly triggerNode?: string;
+  /**
+   * Set for a test run: each step node returns its stub (by node id, else `{
+   * stubbed: true }`) instead of calling `step`, sleeps are skipped, and an
+   * approval node takes its stub as the decision (else approved).
+   */
+  readonly stubs?: Readonly<Record<string, unknown>>;
+  step(call: GraphStepCall): PromiseLike<unknown>;
+  sleep(ms: number): PromiseLike<unknown>;
+  /**
+   * Files the approval request for an approval node and returns its id, which
+   * becomes the hook token. Run it as a step that calls the approvals block's
+   * `request`; `wakeOnApproval` resumes the run once an eligible approver
+   * decides. Without it the token is `<runKey>:<node>`, which anyone who knows
+   * the run key can guess.
+   */
+  requestApproval?(call: GraphApprovalCall): PromiseLike<string>;
+  /** Waits for the approval hook with `token` and returns its payload. */
+  approval(token: string, node: string): PromiseLike<unknown>;
+}
+/** The hook token of an approval node without `requestApproval`. */
+declare const approvalToken: (runKey: string, node: string) => string;
+/**
+ * The run fields a graph run's meta carries (`GraphRunMeta` in
+ * `workflow-sdk/builder`).
+ */
+type GraphRunFields = Pick<GraphRuntime, "runKey" | "version" | "tenant" | "subject" | "triggerNode" | "stubs">;
+/**
+ * The runtime fields of a static executor's `meta`: spread them into the
+ * runtime passed to `executeGraph`, so a run starts at its trigger node,
+ * conditions read its subject, and a test run returns its stubs instead of
+ * running steps.
+ */
+declare function graphRunFields(meta: unknown): GraphRunFields;
+/**
+ * The trigger node a run starts at: `requested` when the graph has it, else the
+ * graph's only trigger. Throws when neither picks one.
+ */
+declare function startNodeOf(graph: WorkflowGraph, requested: string | undefined): string;
+/**
+ * Runs `graph` in dependency order from its start trigger
+ * (`runtime.triggerNode`): a node runs when the trigger reaches it through
+ * edges whose sources ran (and, from a condition or an approval, took the
+ * edge's branch). Returns each node's output by id. It only calls `runtime`, so
+ * it is deterministic and runs inside a `"use workflow"` function as the static
+ * executor.
+ */
+declare function executeGraph(graph: WorkflowGraph, input: unknown, runtime: GraphRuntime): Promise<Record<string, unknown>>;
+//#endregion
+export { GraphSubject as a, graphRunFields as c, GraphStepCall as i, startNodeOf as l, GraphRunFields as n, approvalToken as o, GraphRuntime as r, executeGraph as s, GraphApprovalCall as t };