better-supabase 0.5.0 → 0.6.0

package/dist/orpc/index.js

@@ -1,7 +1,39 @@
-import { r as dbErrorOf } from "../errors-DtwXa6b8.js";
-import { o as toProblem } from "../problem-BW1KhzSG.js";
-import { d as guard, m as settle, n as createServer, r as extendServer, u as defaultExpose } from "../server-Csx2sRjg.js";
+import { r as dbErrorOf } from "../errors-B11Duf73.js";
+import { o as toProblem } from "../problem-BreOl8b8.js";
+import { i as claimsOf } from "../claims-PqzCxaTD.js";
+import { t as tenantOf } from "../tenant-I1TEZ_BX.js";
+import { c as extendServer, n as flushEvents, s as createServer, y as refreshFor } from "../adapter-Bc1o3zyy.js";
+import { n as toSession } from "../view-BeFcRV6G.js";
+import { o as settle, r as guard, t as defaultExpose } from "../respond-BUgsXNgk.js";
+import { t as authorizeCaller } from "../kit-Fm-Fv7q5.js";
+import { bufferRequest, pipeline, seedContext } from "@supabase/middleware";
 import { COMMON_ERROR_STATUS_MAP, ORPCError, os } from "@orpc/server";
+//#region src/bridges/orpc.ts
+/**
+* Runs an entry array around an oRPC fetch handler. The procedures' initial
+* context is `{ request }` plus every contributed key, and the response
+* passes back through the entries, so refreshed cookies and response-phase
+* headers reach it. A request no procedure matched answers 404.
+*
+* ```ts
+* const os = implement(contract).$context<{ request: Request; db: Db }>()
+* export default { fetch: toOrpc([withBetterSupabase(server)], new RPCHandler(router), { prefix: '/rpc' }) }
+* ```
+*/
+function toOrpc(entries, handler, options = {}) {
+	const run = pipeline(entries, async (request, ctx) => {
+		const { response } = await handler.handle(request, {
+			...options.prefix ? { prefix: options.prefix } : {},
+			context: {
+				...ctx,
+				request
+			}
+		});
+		return response ?? new Response("Not found", { status: 404 });
+	});
+	return (request, env) => run(request.body ? bufferRequest(request) : request, seedContext(env));
+}
+//#endregion
 //#region src/orpc/index.ts
 const CODES = /* @__PURE__ */ new Map(Object.entries(COMMON_ERROR_STATUS_MAP).map(([code, status]) => [status, code]));
 /** oRPC code for a `DbError`, from its HTTP status. */
@@ -12,6 +44,7 @@ function orpcCode(error) {
 function createOrpc(betterSupabase, options = {}) {
 	const server = createServer(betterSupabase, options);
 	const expose = options.exposeErrors ?? defaultExpose();
+	const tenantClaim = claimsOf(betterSupabase.meta).tenant;
 	const contexts = /* @__PURE__ */ new WeakMap();
 	const toOrpcError = (error) => {
 		const problem = toProblem(error, { expose });
@@ -20,35 +53,51 @@ function createOrpc(betterSupabase, options = {}) {
 			data: problem
 		});
 	};
+	const middleware = (middlewareOptions = {}) => {
+		return os.$context().middleware(async ({ context, next }) => {
+			const refresh = refreshFor(middlewareOptions.refresh, context.request) ?? false;
+			const known = contexts.get(context.request);
+			const ctx = known && (known.refresh || !refresh) ? known.ctx : await server.context(context.request, { refresh });
+			contexts.set(context.request, {
+				ctx,
+				refresh: refresh || (known?.refresh ?? false)
+			});
+			const denied = guard(ctx.auth, middlewareOptions.allow, middlewareOptions.aal, middlewareOptions.scopes);
+			if (denied) throw toOrpcError(denied);
+			if (middlewareOptions.requireTenant || middlewareOptions.authorize) {
+				const caller = await authorizeCaller(ctx.auth, middlewareOptions, void 0, tenantOf(toSession(ctx.auth), tenantClaim));
+				if ("kind" in caller) throw toOrpcError(caller);
+			}
+			try {
+				return await next({ context: {
+					bs: ctx,
+					db: ctx.db,
+					auth: ctx.auth
+				} });
+			} catch (cause) {
+				const thrown = dbErrorOf(cause);
+				if (thrown) throw toOrpcError(thrown);
+				throw cause;
+			}
+		});
+	};
 	return extendServer(server, {
 		toOrpcError,
-		middleware(middlewareOptions = {}) {
-			return os.$context().middleware(async ({ context, next }) => {
-				const ctx = await server.context(context.request, { refresh: middlewareOptions.refresh ?? false });
-				const denied = guard(ctx.auth, middlewareOptions.allow, middlewareOptions.aal, middlewareOptions.scopes);
-				if (denied) throw toOrpcError(denied);
-				contexts.set(context.request, ctx);
-				try {
-					return await next({ context: {
-						bs: ctx,
-						db: ctx.db,
-						auth: ctx.auth
-					} });
-				} catch (cause) {
-					const thrown = dbErrorOf(cause);
-					if (thrown) throw toOrpcError(thrown);
-					throw cause;
-				}
-			});
+		middleware,
+		authed(authedOptions) {
+			return os.$context().use(middleware(authedOptions));
 		},
 		fetchHandler(handler, fetchOptions = {}) {
-			return async (request) => {
+			return async (request, _env, executionContext) => {
 				const { response } = await handler.handle(request, {
 					...fetchOptions.prefix ? { prefix: fetchOptions.prefix } : {},
 					context: { request }
 				});
-				const ctx = contexts.get(request);
+				const ctx = contexts.get(request)?.ctx;
 				const answer = response ?? new Response("Not found", { status: 404 });
+				flushEvents(server, options.waitUntil ?? (executionContext ? (promise) => {
+					executionContext.waitUntil(promise);
+				} : void 0));
 				return ctx ? ctx.apply(answer) : answer;
 			};
 		},
@@ -60,4 +109,4 @@ function createOrpc(betterSupabase, options = {}) {
 	});
 }
 //#endregion
-export { createOrpc, orpcCode };
+export { createOrpc, orpcCode, toOrpc };

package/dist/otel/index.d.ts

@@ -1,6 +1,6 @@
-import { a as EventHub } from "../events-aIO7vsIk.js";
-import { p as Plugin } from "../plugin-o144f322.js";
-import { t as SPEC_PINS } from "../spec-pins-CqorWDnO.js";
+import { d as Plugin } from "../plugin-FGY8UhYm.js";
+import { a as EventHub } from "../events-DWDhx77e.js";
+import { t as SPEC_PINS } from "../spec-pins-C89s6DyW.js";
 import { Attributes, Meter, Tracer } from "@opentelemetry/api";
 //#region src/otel/index.d.ts
 export declare const INSTRUMENTATION_NAME = "better-supabase";
@@ -42,12 +42,12 @@ export declare function traceAuth(betterSupabase: {
   readonly events: EventHub;
 }, options?: Pick<OtelOptions, "tracer" | "attributes">): () => void;
 /**
- * Records kit events (`support.started`, `webhook.failed`, ...) with the
- * `KIT_ATTRIBUTES` names: as an event on the active span, or as a short
- * `kit <type>` span when there is none. Failures (`*.failed`, `*.denied`)
+ * Records block events (`support.started`, `webhook.failed`, ...) with the
+ * `BLOCK_ATTRIBUTES` names: as an event on the active span, or as a short
+ * `block <type>` span when there is none. Failures (`*.failed`, `*.denied`)
  * set an error status. Returns a function that stops listening.
  */
-export declare function traceKitEvents(betterSupabase: {
+export declare function traceBlockEvents(betterSupabase: {
   readonly events: EventHub;
 }, options?: Pick<OtelOptions, "tracer" | "attributes">): () => void;
 /**

package/dist/otel/index.js

@@ -1,7 +1,7 @@
-import { r as definePlugin } from "../plugin-DwARMuQp.js";
-import { t as SPEC_PINS } from "../spec-pins-C3oc-Tdp.js";
-import { r as kitEventAttributes } from "../kit-events-CTFDfSwb.js";
-import "../version-DM_Roffb.js";
+import { r as definePlugin } from "../plugin-tfXW1-qO.js";
+import { t as SPEC_PINS } from "../spec-pins--j6mTok4.js";
+import { r as blockEventAttributes } from "../block-events-CrT8r7Fe.js";
+import "../version-Bvv6aLjZ.js";
 import { SpanKind, SpanStatusCode, context, metrics, propagation, trace } from "@opentelemetry/api";
 //#region src/otel/index.ts
 const INSTRUMENTATION_NAME = "better-supabase";
@@ -40,9 +40,9 @@ function systemOf(executor) {
 * ```
 */
 function otel(options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.5.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.6.0");
 	let histogram;
-	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.5.0")).createHistogram("db.client.operation.duration", {
+	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.6.0")).createHistogram("db.client.operation.duration", {
 		unit: "s",
 		description: "Duration of database client operations.",
 		advice: { explicitBucketBoundaries: [
@@ -95,53 +95,83 @@ function otel(options = {}) {
 				}
 				return entry;
 			};
+			const failed = (span, error) => {
+				span.setAttributes({
+					"error.type": error.kind,
+					...error.code && SQLSTATE.test(error.code) ? { "db.response.status_code": error.code } : {}
+				});
+				span.setStatus({
+					code: SpanStatusCode.ERROR,
+					message: error.message
+				});
+				return error.kind;
+			};
+			/** Runs `run` in a client span; `settle` returns the error type, if any. */
+			const traced = (summary, attributes, metric, run, settle) => {
+				const started = performance.now();
+				return tracer.startActiveSpan(summary, {
+					kind: SpanKind.CLIENT,
+					attributes
+				}, async (span) => {
+					const finish = (errorType) => {
+						histogram?.record((performance.now() - started) / 1e3, errorType ? {
+							...metric,
+							"error.type": errorType
+						} : metric);
+						span.end();
+					};
+					try {
+						const result = await run();
+						finish(settle(span, result));
+						return result;
+					} catch (cause) {
+						const error = cause instanceof Error ? cause : new Error(String(cause));
+						span.recordException(error);
+						span.setAttribute("error.type", error.name);
+						span.setStatus({
+							code: SpanStatusCode.ERROR,
+							message: error.message
+						});
+						finish(error.name);
+						throw cause;
+					}
+				});
+			};
+			const base = {
+				...options.attributes,
+				"db.system.name": system,
+				"better_supabase.executor": executor.name,
+				...server
+			};
+			const baseMetric = {
+				...server,
+				"db.system.name": system
+			};
+			const rpc = executor.rpc?.bind(executor);
 			return {
 				...executor,
 				name: executor.name,
 				execute(op, executeContext) {
 					const { summary, attributes, metric } = describe(op);
-					const started = performance.now();
-					return tracer.startActiveSpan(summary, {
-						kind: SpanKind.CLIENT,
-						attributes
-					}, async (span) => {
-						const finish = (errorType) => {
-							histogram?.record((performance.now() - started) / 1e3, errorType ? {
-								...metric,
-								"error.type": errorType
-							} : metric);
-							span.end();
-						};
-						try {
-							const result = await executor.execute(op, executeContext);
-							if (result.ok) {
-								if (span.isRecording()) span.setAttribute("db.response.returned_rows", result.data.rows.length);
-								finish();
-							} else {
-								span.setAttributes({
-									"error.type": result.error.kind,
-									...result.error.code && SQLSTATE.test(result.error.code) ? { "db.response.status_code": result.error.code } : {}
-								});
-								span.setStatus({
-									code: SpanStatusCode.ERROR,
-									message: result.error.message
-								});
-								finish(result.error.kind);
-							}
-							return result;
-						} catch (cause) {
-							const error = cause instanceof Error ? cause : new Error(String(cause));
-							span.recordException(error);
-							span.setAttribute("error.type", error.name);
-							span.setStatus({
-								code: SpanStatusCode.ERROR,
-								message: error.message
-							});
-							finish(error.name);
-							throw cause;
-						}
+					return traced(summary, attributes, metric, () => executor.execute(op, executeContext), (span, result) => {
+						if (!result.ok) return failed(span, result.error);
+						if (span.isRecording()) span.setAttribute("db.response.returned_rows", result.data.rows.length);
 					});
-				}
+				},
+				...rpc ? { rpc(name, args, rpcContext) {
+					const summary = `EXECUTE ${name}`;
+					return traced(summary, {
+						...base,
+						"db.namespace": database ? `${database}|${rpcContext.schema}` : rpcContext.schema,
+						"db.operation.name": "EXECUTE",
+						"db.stored_procedure.name": name,
+						"db.query.summary": summary
+					}, {
+						...baseMetric,
+						"db.operation.name": "EXECUTE",
+						"db.stored_procedure.name": name
+					}, () => rpc(name, args, rpcContext), (span, result) => result.ok ? void 0 : failed(span, result.error));
+				} } : {}
 			};
 		}
 	});
@@ -151,7 +181,7 @@ function otel(options = {}) {
 * Returns a function that stops listening.
 */
 function traceAuth(betterSupabase, options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.5.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.6.0");
 	const offAuth = betterSupabase.events.on("auth", (event) => {
 		const span = tracer.startSpan("auth.resolve", {
 			kind: SpanKind.INTERNAL,
@@ -183,17 +213,17 @@ function traceAuth(betterSupabase, options = {}) {
 	};
 }
 /**
-* Records kit events (`support.started`, `webhook.failed`, ...) with the
-* `KIT_ATTRIBUTES` names: as an event on the active span, or as a short
-* `kit <type>` span when there is none. Failures (`*.failed`, `*.denied`)
+* Records block events (`support.started`, `webhook.failed`, ...) with the
+* `BLOCK_ATTRIBUTES` names: as an event on the active span, or as a short
+* `block <type>` span when there is none. Failures (`*.failed`, `*.denied`)
 * set an error status. Returns a function that stops listening.
 */
-function traceKitEvents(betterSupabase, options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.5.0");
-	return betterSupabase.events.on("kit", (event) => {
+function traceBlockEvents(betterSupabase, options = {}) {
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.6.0");
+	return betterSupabase.events.on("block", (event) => {
 		const attributes = {
 			...options.attributes,
-			...kitEventAttributes(event)
+			...blockEventAttributes(event)
 		};
 		const failed = event.type.endsWith(".failed") || event.type.endsWith(".denied");
 		const active = trace.getActiveSpan();
@@ -201,7 +231,7 @@ function traceKitEvents(betterSupabase, options = {}) {
 			active.addEvent(event.type, attributes);
 			return;
 		}
-		const span = tracer.startSpan(`kit ${event.type}`, {
+		const span = tracer.startSpan(`block ${event.type}`, {
 			kind: SpanKind.INTERNAL,
 			attributes
 		});
@@ -227,4 +257,4 @@ function tracedFetch(base = fetch) {
 	};
 }
 //#endregion
-export { INSTRUMENTATION_NAME, SEMCONV_VERSION, otel, traceAuth, traceKitEvents, tracedFetch };
+export { INSTRUMENTATION_NAME, SEMCONV_VERSION, otel, traceAuth, traceBlockEvents, tracedFetch };

package/dist/outbox-Cq7pPYvl.d.ts

@@ -0,0 +1,161 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, t as AsyncResult } from "./result-D7y2fT87.js";
+import { t as SqlClient } from "./executor-DbvExCFC.js";
+import { t as BlockTransport } from "./block-transport-DvaoPuZ9.js";
+import { i as CursorPageOptions, r as BlockTemporalOptions } from "./block-helpers-CKtbFcRv.js";
+import { t as BlockProblemOptions } from "./problem-DD8LZFjc.js";
+import { r as EventSink, t as CloudEvent } from "./cloud-event-C1JCc1bH.js";
+//#region src/blocks/outbox/outbox.d.ts
+/** One row of the outbox, as `outbox_claim` and `outbox_history` return it. */
+interface OutboxEvent {
+  /** The cursor value: increases with every event. */
+  readonly position: number;
+  readonly id: string;
+  readonly type: string;
+  readonly payload: unknown;
+  /** The module or function that wrote it, e.g. `better-supabase/blocks/organizations`. */
+  readonly source: string | null;
+  readonly subject: string | null;
+  readonly tenant: string | null;
+  readonly key: string | null;
+  readonly actorId: string | null;
+  readonly createdAt: Temporal.Instant;
+}
+interface EmitOptions {
+  readonly subject?: string;
+  readonly tenant?: string;
+  /** With a key, emitting again (per tenant) returns the first event. */
+  readonly key?: string;
+  readonly source?: string;
+}
+interface OutboxOptions extends BlockTemporalOptions {
+  /** The schema of the `outbox` module. Defaults to `better_supabase`. */
+  readonly schema?: string;
+  /** CloudEvents `source` of the relayed events, e.g. `https://crm.example.com`. */
+  readonly source: string;
+  /** Prepended to each type with a dot when relaying, e.g. `com.example`. Defaults to `dev.better-supabase`. */
+  readonly typePrefix?: string;
+}
+interface RegisterOptions {
+  /** Type patterns such as `organization.*` or `invoice.paid`. Defaults to every event. */
+  readonly types?: readonly string[];
+  /** Start at the first kept event instead of after the latest one. */
+  readonly fromStart?: boolean;
+}
+interface RelayOptions {
+  /** Events per claim and per `sink.send`. Defaults to 100. */
+  readonly batch?: number;
+  /** How long a claim holds the consumer. Defaults to `1 minute`. */
+  readonly lease?: string;
+  /** Stops claiming after this many milliseconds. */
+  readonly budgetMs?: number;
+  /** Identifies this worker in the lease. Defaults to a random id. */
+  readonly owner?: string;
+  /**
+   * Failures in a row before the event that keeps failing goes to the dead
+   * letters and the cursor moves past it. Defaults to 10.
+   */
+  readonly maxAttempts?: number;
+  /** The longest wait between failed attempts. Defaults to `10 minutes`. */
+  readonly maxBackoff?: string;
+}
+interface RelayResult {
+  readonly delivered: number;
+  /**
+   * Set when the sink threw: the consumer backs off and retries the batch
+   * one event at a time.
+   */
+  readonly error?: DbError;
+  /** 1 when this run moved the failing event to the dead letters. */
+  readonly deadLettered?: number;
+}
+/** An event a consumer skipped after `maxAttempts` failures. */
+interface OutboxDeadLetter {
+  readonly consumer: string;
+  readonly event: OutboxEvent;
+  readonly attempts: number;
+  readonly error: string | null;
+  readonly deadAt: Temporal.Instant;
+}
+interface OutboxPurgeOptions {
+  /**
+   * A consumer that hasn't claimed for this long (a Postgres interval such
+   * as `30 days`) no longer holds events back. Defaults to waiting for
+   * every consumer.
+   */
+  readonly ignoreIdle?: string;
+}
+/**
+ * Takes a batch of outbox rows, with the actor and tenant that CloudEvents
+ * leave out. Throwing counts a failed attempt: the consumer backs off, then
+ * retries one event at a time until the event that fails goes to the dead
+ * letters.
+ */
+type OutboxHandler = (events: readonly OutboxEvent[]) => unknown;
+interface OutboxRouteOptions extends Omit<RelayOptions, "owner">, BlockProblemOptions {
+  /** The bearer secret, such as `process.env.CRON_SECRET`. */
+  readonly secret: string | undefined;
+  /** Consumer name to the sink its events go to, or a handler that takes the rows. */
+  readonly consumers: Readonly<Record<string, EventSink | OutboxHandler>>;
+  readonly onError?: (error: DbError, consumer: string) => void;
+}
+interface OutboxRouteResult {
+  readonly consumers: Readonly<Record<string, RelayResult>>;
+  readonly budgetExhausted: boolean;
+}
+interface HistoryFilter extends CursorPageOptions<number> {
+  readonly subject?: string;
+  readonly type?: string;
+  /** Only events after this position. */
+  readonly cursor?: number;
+  readonly limit?: number;
+}
+interface Outbox {
+  /** Writes an event in the current transaction and returns its id. */
+  emit(type: string, payload?: unknown, options?: EmitOptions): AsyncResult<string>;
+  /** Creates the consumer, or changes its types. Returns its cursor position. */
+  register(consumer: string, options?: RegisterOptions): AsyncResult<number>;
+  /** Removes the consumer, so purges stop waiting for it. */
+  unregister(consumer: string): AsyncResult<boolean>;
+  /**
+   * Claims the consumer's next events, sends them to `sink` as CloudEvents and
+   * moves the cursor, until none are left or the budget runs out. A sink that
+   * throws leaves the batch for a later run with backoff, so delivery is at
+   * least once; an event that fails `maxAttempts` times goes to the dead
+   * letters.
+   */
+  relay(consumer: string, sink: EventSink, options?: RelayOptions): Promise<RelayResult>;
+  /**
+   * Like `relay`, but hands `handler` the outbox rows themselves, with
+   * `actorId`, `tenant` and `key`, for consumers inside the app (search
+   * indexing, notifications) that need the actor.
+   */
+  consume(consumer: string, handler: OutboxHandler, options?: RelayOptions): Promise<RelayResult>;
+  /** A `GET`/`POST` handler for a cron that relays every consumer at once, within one budget. */
+  relayRoute(options: OutboxRouteOptions): (request: Request) => Promise<Response>;
+  history(filter?: HistoryFilter): AsyncResult<readonly OutboxEvent[]>;
+  /** The consumer's dead letters, newest first (default 100, at most 1000). */
+  deadLetters(consumer: string, limit?: number): AsyncResult<readonly OutboxDeadLetter[]>;
+  /**
+   * Deletes up to `batch` events (default 10,000) older than `olderThan` that
+   * every consumer has passed, and dead letters older than `olderThan`. Call
+   * it again while it returns `batch`.
+   */
+  purge(olderThan?: string, batch?: number, options?: OutboxPurgeOptions): AsyncResult<number>;
+}
+/**
+ * The CloudEvent for an outbox row: the row id as `id` (stable, so receivers
+ * can deduplicate), the payload as `data`, the tenant as `partitionkey` and
+ * the writing module as `producer`. The actor stays out of the context
+ * attributes, which must not carry personal data.
+ */
+declare function outboxCloudEvent(event: OutboxEvent, options: Pick<OutboxOptions, "source" | "typePrefix">): CloudEvent;
+/**
+ * The outbox over a server connection (`SqlClient`), or over a
+ * `BlockTransport` such as `rpcTransport(serviceClient, { schema: "api" })`
+ * for apps that reach the database only through the Data API. Over a
+ * transport, `emit` writes in its own transaction.
+ */
+declare function createOutbox(source: SqlClient | BlockTransport, options: OutboxOptions): Outbox;
+//#endregion
+export { OutboxEvent as a, OutboxPurgeOptions as c, RegisterOptions as d, RelayOptions as f, outboxCloudEvent as h, OutboxDeadLetter as i, OutboxRouteOptions as l, createOutbox as m, HistoryFilter as n, OutboxHandler as o, RelayResult as p, Outbox as r, OutboxOptions as s, EmitOptions as t, OutboxRouteResult as u };

package/dist/{plugin-o144f322.d.ts → plugin-FGY8UhYm.d.ts}

@@ -1,6 +1,7 @@
 /// <reference lib="esnext.temporal" />
-import { F as TableMeta, j as SchemaMeta, r as AnyModels } from "./types-Dnf_wRDz.js";
-import { H as MutationOp, S as ErrorMapper, U as Operation, r as Executor } from "./executor-BunPOO-k.js";
+import { w as ErrorMapper } from "./result-D7y2fT87.js";
+import { I as TableFlags, P as SchemaMeta, R as TableMeta, a as AnyModels } from "./types-6BdhkmZe.js";
+import { _ as MutationOp, g as MutationKind, h as MutationIntent, r as Executor, v as Operation } from "./executor-DvsBbNBS.js";
 //#region src/core/plugin.d.ts
 /** Who is making the request. */
 interface Actor {
@@ -29,10 +30,9 @@ interface HookArgs {
   readonly context: RequestContext;
   readonly options: CallOptions;
   readonly now: () => Temporal.Instant;
+  /** The caller's `signal`, when it passed one. Hooks that do I/O should honor it. */
+  readonly signal?: AbortSignal;
 }
-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 MutationEvent {
   readonly table: TableMeta;
   /** The statement that ran. */
@@ -47,7 +47,7 @@ interface MutationEvent {
    * returned (soft deletes, `returning: false`).
    */
   readonly keys?: readonly Readonly<Record<string, unknown>>[];
-  /** The tenant of the write: `context.tenant`, or the one `tenant()` resolved. */
+  /** The tenant of the write: `context.tenant`, which `tenant()` fills from the claims. */
   readonly tenant?: string;
   readonly context: RequestContext;
 }
@@ -99,10 +99,30 @@ interface Plugin<Name extends string = string, Ext extends RepositoryExtension =
   readonly apiVersion: 1;
   readonly name: Name;
   /**
-   * Hook order: `pre` plugins run first, `post` plugins last, the rest in
-   * `use()` order. Validation is `post` so it sees columns other plugins fill.
+   * Hook order: `first`, then `pre`, then unmarked plugins, then `post`;
+   * plugins at the same level keep `use()` order. `first` is for plugins
+   * that check the query as the caller wrote it, before a `pre` plugin
+   * rewrites it (`rules()`). Validation is `post` so it sees columns other
+   * plugins fill.
    */
-  readonly enforce?: "pre" | "post";
+  readonly enforce?: "first" | "pre" | "post";
+  /**
+   * The table flags whose tables this plugin's `transformQuery` filters
+   * (`tenant()` declares `['tenant']`). Read sets warn when they read such a
+   * table, because their generated SQL function runs without the plugin.
+   * `[]` means the plugin only inspects queries. A plugin with
+   * `transformQuery` that leaves this out is assumed to filter every table.
+   */
+  readonly scopes?: readonly (keyof TableFlags)[];
+  /**
+   * `context`: derive values from the connection's context once per
+   * `connect()` and `$with()`, so `db.$context` carries them (`tenant()`
+   * adds the tenant it resolved). Runs in hook order on the context the
+   * caller passed. A throw is logged and leaves the context unchanged.
+   */
+  readonly context?: (context: RequestContext, args: {
+    readonly schema: SchemaMeta;
+  }) => RequestContext;
   /** `ir`: rewrite an operation before it runs (filters, defaults). */
   readonly transformQuery?: (op: Operation, args: HookArgs) => Operation;
   /** `mutation`: rewrite a mutation or reject it by throwing a `DbException`. */
@@ -128,4 +148,4 @@ declare function definePlugin<const Name extends string, Ext extends RepositoryE
   readonly apiVersion?: 1;
 }): Plugin<Name, Ext>;
 //#endregion
-export { WithExtension as _, ExtensionOf as a, MutationEvent as c, NoExtension as d, PLUGIN_API_VERSION as f, RequestContext as g, RepositoryExtension as h, CallOptions as i, MutationIntent as l, RepositoryApi as m, AnyPlugin as n, HasFlag as o, Plugin as p, ApplyExtension as r, HookArgs as s, Actor as t, MutationKind as u, definePlugin as v };
+export { ExtensionOf as a, MutationEvent as c, Plugin as d, RepositoryApi as f, definePlugin as g, WithExtension as h, CallOptions as i, NoExtension as l, RequestContext as m, AnyPlugin as n, HasFlag as o, RepositoryExtension as p, ApplyExtension as r, HookArgs as s, Actor as t, PLUGIN_API_VERSION as u };

package/dist/plugin-tfXW1-qO.js

@@ -0,0 +1,45 @@
+//#region src/core/plugin.ts
+const PLUGIN_API_VERSION = 1;
+const RANK = {
+	first: 0,
+	pre: 1,
+	normal: 2,
+	post: 3
+};
+function rankOf(plugin) {
+	return RANK[plugin.enforce ?? "normal"];
+}
+/**
+* Plugins in hook order: `first`, `pre`, unmarked, then `post`, each level
+* in `use()` order.
+*/
+function orderPlugins(plugins) {
+	return plugins.map((plugin, index) => ({
+		plugin,
+		index
+	})).sort((a, b) => rankOf(a.plugin) - rankOf(b.plugin) || a.index - b.index).map(({ plugin }) => plugin);
+}
+/** Identity helper that fixes `apiVersion` and infers the plugin types. */
+function definePlugin(plugin) {
+	return {
+		...plugin,
+		apiVersion: 1
+	};
+}
+/**
+* A symbol key, so JSON, claims and spread request data can't set it, while
+* `$with` copies it to the derived context.
+*/
+const ALL_TENANTS = Symbol("better-supabase.allTenants");
+/** `context`, marked so `tenant()` and tenant buckets skip their tenant scope. */
+function allTenantsContext(context) {
+	return {
+		...context,
+		[ALL_TENANTS]: true
+	};
+}
+function spansAllTenants(context) {
+	return Object.hasOwn(context, ALL_TENANTS);
+}
+//#endregion
+export { spansAllTenants as a, orderPlugins as i, allTenantsContext as n, definePlugin as r, PLUGIN_API_VERSION as t };

package/dist/plugins/actor/index.d.ts

@@ -1,4 +1,4 @@
-import { g as RequestContext, p as Plugin } from "../../plugin-o144f322.js";
+import { d as Plugin, m as RequestContext } from "../../plugin-FGY8UhYm.js";
 //#region src/plugins/actor/index.d.ts
 export interface ActorOptions {
   /** Custom actor id resolution. Defaults to `context.actor.id` for users and services. */
@@ -9,7 +9,7 @@ export interface ActorOptions {
  * `updatedBy` on insert and update. Soft deletes are updates, so they record
  * who deleted the row. `impersonatedBy` gets `context.actor.impersonator` on
  * an impersonated insert or update and is left alone otherwise, so a user's
- * own update keeps the stamp, like the SQL kit's `track_actor`. Without an
+ * own update keeps the stamp, like the SQL modules' `track_actor`. Without an
  * actor (anonymous requests) nothing is set.
  */
 export declare function actor(options?: ActorOptions): Plugin<"actor">;

package/dist/plugins/actor/index.js

@@ -1,5 +1,5 @@
-import { r as definePlugin } from "../../plugin-DwARMuQp.js";
-import { a as insertsOnly, i as guardManaged, t as dbName, u as withDefault } from "../../shared-D1dRUrAg.js";
+import { r as definePlugin } from "../../plugin-tfXW1-qO.js";
+import { a as insertsOnly, i as guardManaged, t as dbName, u as withDefault } from "../../shared-CxWmcyqB.js";
 //#region src/plugins/actor/index.ts
 function defaultActor(context) {
 	const actor = context.actor;
@@ -10,7 +10,7 @@ function defaultActor(context) {
 * `updatedBy` on insert and update. Soft deletes are updates, so they record
 * who deleted the row. `impersonatedBy` gets `context.actor.impersonator` on
 * an impersonated insert or update and is left alone otherwise, so a user's
-* own update keeps the stamp, like the SQL kit's `track_actor`. Without an
+* own update keeps the stamp, like the SQL modules' `track_actor`. Without an
 * actor (anonymous requests) nothing is set.
 */
 function actor(options = {}) {