better-supabase 0.3.0 → 0.5.0

package/dist/orpc/index.d.ts

@@ -1,9 +1,9 @@
-import { n as AnyModels, t as AnyFunctions } from "../types-DONv9SHN.js";
-import { o as Result, p as DbError } from "../result-c2OYgCV2.js";
-import { t as BetterSupabase } from "../define-DUbydmJa.js";
-import { r as AuthState } from "../resolve-BRciX2jK.js";
-import { d as ServerContext, f as ServerOptions, l as BetterServer, n as GuardOptions } from "../respond-DAkPIdTH.js";
-import { r as ProblemDetails } from "../problem-Z2RTQjZD.js";
+import { n as AnyFunctions, r as AnyModels } from "../types-Dnf_wRDz.js";
+import { _ as DbError, u as Result } from "../executor-BunPOO-k.js";
+import { t as BetterSupabase } from "../define-Bp_BZa5h.js";
+import { r as AuthState } from "../resolve-C15TJq77.js";
+import { f as ServerContext, n as GuardOptions, p as ServerOptions, r as MiddlewareOptions, u as BetterServer } from "../respond-D2OQl62-.js";
+import { r as ProblemDetails } from "../problem-Blxe8S31.js";
 import { DecoratedMiddleware, ORPCError } from "@orpc/server";
 //#region src/orpc/index.d.ts
 /** Initial context: pass `{ context: { request } }` to the oRPC handler. */
@@ -11,36 +11,53 @@ export interface OrpcRequestContext {
   readonly request: Request;
 }
 /** What `middleware()` adds to `context`. */
-export interface OrpcContext<M extends AnyModels, F extends AnyFunctions, E> {
-  readonly bs: ServerContext<M, F, E>;
-  readonly db: ServerContext<M, F, E>["db"];
-  readonly auth: AuthState;
+export interface OrpcContext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> {
+  readonly bs: ServerContext<M, F, E, C, P>;
+  readonly db: ServerContext<M, F, E, C, P>["db"];
+  readonly auth: AuthState<C, P>;
 }
 export interface OrpcOptions extends ServerOptions {
   /** Include internal error messages. Defaults to `NODE_ENV === 'development'`. */
   readonly exposeErrors?: boolean;
 }
-export interface MiddlewareOptions extends GuardOptions {
-  /** Refresh an expired cookie session. Pair with `ctx.bs.resolution.apply` in the handler adapter. */
-  readonly refresh?: boolean;
+/** The part of an oRPC fetch handler (`RPCHandler`, `OpenAPIHandler`) `fetchHandler` calls. */
+export interface OrpcFetchHandler {
+  handle(request: Request, options: {
+    readonly prefix?: `/${string}`;
+    readonly context: OrpcRequestContext;
+  }): Promise<{
+    readonly matched: boolean;
+    readonly response?: Response | undefined;
+  }>;
 }
-export type OrpcMiddleware<M extends AnyModels, F extends AnyFunctions, E> = DecoratedMiddleware<OrpcRequestContext, OrpcContext<M, F, E>, unknown, unknown, Record<never, never>>;
-export interface BetterOrpc<M extends AnyModels, F extends AnyFunctions, E> extends BetterServer<M, F, E> {
+export interface OrpcFetchOptions {
+  /** Path prefix the router is mounted under, e.g. `/rpc`. */
+  readonly prefix?: `/${string}`;
+}
+export type OrpcMiddleware<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> = DecoratedMiddleware<OrpcRequestContext, OrpcContext<M, F, E, C, P>, unknown, unknown, Record<never, never>>;
+export interface BetterOrpc<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends BetterServer<M, F, E, C, P> {
   /**
    * Resolves the caller, enforces `allow` and adds `context.db`, `context.auth`
    * and `context.bs`. Thrown `DbException`s, and errors caused by a
-   * `DbError`, become `ORPCError`s.
+   * `DbError`, become `ORPCError`s. Serve the router with `fetchHandler` so
+   * refreshed session cookies and `bs-primary-until` reach the response.
+   */
+  middleware(options?: MiddlewareOptions): OrpcMiddleware<M, F, E, C, P>;
+  /**
+   * A fetch handler for an oRPC handler: passes `{ request }` as the initial
+   * context, answers 404 when no procedure matched, and applies the cookies
+   * of the request's context (`ctx.apply`).
    */
-  middleware(options?: MiddlewareOptions): OrpcMiddleware<M, F, E>;
+  fetchHandler(handler: OrpcFetchHandler, options?: OrpcFetchOptions): (request: Request) => Promise<Response>;
   /** A `Result` (or `AsyncResult`) as data, throwing an `ORPCError` on failure. */
   unwrap<T>(value: Result<T> | PromiseLike<Result<T>>): Promise<T>;
   /** Plain values pass through; thrown `DbException`s become `ORPCError`s. */
   unwrap<T>(value: T | PromiseLike<T>): Promise<T>;
-  toORPCError(error: DbError): ORPCError<string, ProblemDetails>;
+  toOrpcError(error: DbError): ORPCError<string, ProblemDetails>;
 }
 /** oRPC code for a `DbError`, from its HTTP status. */
 export declare function orpcCode(error: DbError): string;
 /** oRPC integration: middleware adding the caller's repositories to `context`. */
-export declare function createOrpc<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, options?: OrpcOptions): BetterOrpc<M, F, E>;
+export declare function createOrpc<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, options?: OrpcOptions): BetterOrpc<M, F, E, C, P>;
 //#endregion
-export type { GuardOptions };
+export type { GuardOptions, MiddlewareOptions };

package/dist/orpc/index.js

@@ -1,18 +1,19 @@
-import { r as dbErrorOf } from "../errors-Bl3rkOzo.js";
-import { o as toProblem } from "../problem-CGt1ADix.js";
-import { a as settle, n as guard, o as createServer, s as extendServer, t as defaultExpose } from "../respond-C44EZAJo.js";
+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 { COMMON_ERROR_STATUS_MAP, ORPCError, os } from "@orpc/server";
 //#region src/orpc/index.ts
-const CODES = new Map(Object.entries(COMMON_ERROR_STATUS_MAP).map(([code, status]) => [status, code]));
+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. */
 function orpcCode(error) {
 	return CODES.get(error.status) ?? (error.status >= 500 ? "INTERNAL_SERVER_ERROR" : "BAD_REQUEST");
 }
 /** oRPC integration: middleware adding the caller's repositories to `context`. */
-function createOrpc(sb, options = {}) {
-	const server = createServer(sb, options);
+function createOrpc(betterSupabase, options = {}) {
+	const server = createServer(betterSupabase, options);
 	const expose = options.exposeErrors ?? defaultExpose();
-	const toORPCError = (error) => {
+	const contexts = /* @__PURE__ */ new WeakMap();
+	const toOrpcError = (error) => {
 		const problem = toProblem(error, { expose });
 		return new ORPCError(orpcCode(error), {
 			message: problem.detail ?? problem.title,
@@ -20,12 +21,13 @@ function createOrpc(sb, options = {}) {
 		});
 	};
 	return extendServer(server, {
-		toORPCError,
+		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);
+				if (denied) throw toOrpcError(denied);
+				contexts.set(context.request, ctx);
 				try {
 					return await next({ context: {
 						bs: ctx,
@@ -34,14 +36,25 @@ function createOrpc(sb, options = {}) {
 					} });
 				} catch (cause) {
 					const thrown = dbErrorOf(cause);
-					if (thrown) throw toORPCError(thrown);
+					if (thrown) throw toOrpcError(thrown);
 					throw cause;
 				}
 			});
 		},
+		fetchHandler(handler, fetchOptions = {}) {
+			return async (request) => {
+				const { response } = await handler.handle(request, {
+					...fetchOptions.prefix ? { prefix: fetchOptions.prefix } : {},
+					context: { request }
+				});
+				const ctx = contexts.get(request);
+				const answer = response ?? new Response("Not found", { status: 404 });
+				return ctx ? ctx.apply(answer) : answer;
+			};
+		},
 		async unwrap(value) {
 			const settled = await settle(() => value);
-			if (!settled.ok) throw toORPCError(settled.error);
+			if (!settled.ok) throw toOrpcError(settled.error);
 			return settled.data;
 		}
 	});

package/dist/otel/index.d.ts

@@ -1,5 +1,5 @@
-import { a as EventHub } from "../events-Do8jXh4D.js";
-import { f as Plugin } from "../plugin-DVRB8qNE.js";
+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 { Attributes, Meter, Tracer } from "@opentelemetry/api";
 //#region src/otel/index.d.ts
@@ -13,6 +13,16 @@ export interface OtelOptions {
   readonly attributes?: Attributes;
   /** Set `false` to skip the duration histogram. */
   readonly metrics?: boolean;
+  /**
+   * The database name in `db.namespace` (`{database}|{schema}`). Supabase
+   * names it `postgres`, the default for Postgres executors.
+   */
+  readonly database?: string;
+  /** `server.address` and `server.port` on spans and metrics, e.g. the project host. */
+  readonly server?: {
+    readonly address: string;
+    readonly port?: number;
+  };
 }
 /**
  * Database client spans and metrics for every repository operation, using
@@ -20,15 +30,24 @@ export interface OtelOptions {
  * never recorded; `db.query.summary` is `SELECT customers`.
  *
  * ```ts
- * const sb = defineSupabase(schema).use(otel());
+ * const betterSupabase = defineSupabase(schema).use(otel());
  * ```
  */
 export declare function otel(options?: OtelOptions): Plugin<"otel">;
 /**
- * Spans for auth resolution and session refreshes, from `sb.events`.
+ * Spans for auth resolution and session refreshes, from `betterSupabase.events`.
  * Returns a function that stops listening.
  */
-export declare function traceAuth(sb: {
+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`)
+ * set an error status. Returns a function that stops listening.
+ */
+export declare function traceKitEvents(betterSupabase: {
   readonly events: EventHub;
 }, options?: Pick<OtelOptions, "tracer" | "attributes">): () => void;
 /**

package/dist/otel/index.js

@@ -1,11 +1,21 @@
-import { n as definePlugin } from "../plugin-BqR6wKMB.js";
+import { r as definePlugin } from "../plugin-DwARMuQp.js";
 import { t as SPEC_PINS } from "../spec-pins-C3oc-Tdp.js";
-import "../version-BfpG2gks.js";
+import { r as kitEventAttributes } from "../kit-events-CTFDfSwb.js";
+import "../version-DM_Roffb.js";
 import { SpanKind, SpanStatusCode, context, metrics, propagation, trace } from "@opentelemetry/api";
 //#region src/otel/index.ts
 const INSTRUMENTATION_NAME = "better-supabase";
 /** OpenTelemetry semantic conventions version the attributes follow. */
 const SEMCONV_VERSION = SPEC_PINS.otelSemconv;
+/** A five-character SQLSTATE; PostgREST's own codes (`PGRST116`) are not one. */
+const SQLSTATE = /^[0-9A-Z]{5}$/;
+function serverAttributes(server) {
+	if (!server) return {};
+	return server.port === void 0 ? { "server.address": server.address } : {
+		"server.address": server.address,
+		"server.port": server.port
+	};
+}
 const OPERATION_NAME = {
 	select: "SELECT",
 	insert: "INSERT",
@@ -26,13 +36,13 @@ function systemOf(executor) {
 * never recorded; `db.query.summary` is `SELECT customers`.
 *
 * ```ts
-* const sb = defineSupabase(schema).use(otel());
+* const betterSupabase = defineSupabase(schema).use(otel());
 * ```
 */
 function otel(options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.0.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.5.0");
 	let histogram;
-	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.0.0")).createHistogram("db.client.operation.duration", {
+	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.5.0")).createHistogram("db.client.operation.duration", {
 		unit: "s",
 		description: "Duration of database client operations.",
 		advice: { explicitBucketBoundaries: [
@@ -50,76 +60,99 @@ function otel(options = {}) {
 	return definePlugin({
 		name: "otel",
 		enforce: "post",
-		wrapExecutor: (executor) => ({
-			...executor,
-			name: executor.name,
-			execute(op, executeContext) {
+		wrapExecutor: (executor) => {
+			const system = systemOf(executor);
+			const database = options.database ?? (system === "postgresql" ? "postgres" : void 0);
+			const server = serverAttributes(options.server);
+			/** Span and metric attributes per table and operation, built once. */
+			const described = /* @__PURE__ */ new Map();
+			const describe = (op) => {
 				const operation = operationName(op);
-				const summary = `${operation} ${op.table.name}`;
-				const attributes = {
-					...options.attributes,
-					"db.system.name": systemOf(executor),
-					"db.namespace": op.table.schema,
-					"db.collection.name": op.table.name,
-					"db.operation.name": operation,
-					"db.query.summary": summary,
-					"better_supabase.executor": executor.name
-				};
-				const started = performance.now();
-				return tracer.startActiveSpan(summary, {
-					kind: SpanKind.CLIENT,
-					attributes
-				}, async (span) => {
-					const finish = (errorType) => {
-						const metricAttributes = {
-							"db.system.name": attributes["db.system.name"],
+				const key = `${op.table.key}:${operation}`;
+				let entry = described.get(key);
+				if (!entry) {
+					const summary = `${operation} ${op.table.name}`;
+					entry = {
+						summary,
+						attributes: {
+							...options.attributes,
+							"db.system.name": system,
+							"db.namespace": database ? `${database}|${op.table.schema}` : op.table.schema,
 							"db.collection.name": op.table.name,
 							"db.operation.name": operation,
-							...errorType ? { "error.type": errorType } : {}
-						};
-						histogram?.record((performance.now() - started) / 1e3, metricAttributes);
-						span.end();
+							"db.query.summary": summary,
+							"better_supabase.executor": executor.name,
+							...server
+						},
+						metric: {
+							...server,
+							"db.system.name": system,
+							"db.collection.name": op.table.name,
+							"db.operation.name": operation
+						}
 					};
-					try {
-						const result = await executor.execute(op, executeContext);
-						if (result.ok) {
-							span.setAttribute("db.response.returned_rows", result.data.rows.length);
-							finish();
-						} else {
-							span.setAttributes({
-								"error.type": result.error.kind,
-								...result.error.code ? { "db.response.status_code": result.error.code } : {}
-							});
+					described.set(key, entry);
+				}
+				return entry;
+			};
+			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: result.error.message
+								message: error.message
 							});
-							finish(result.error.kind);
+							finish(error.name);
+							throw cause;
 						}
-						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;
-					}
-				});
-			}
-		})
+					});
+				}
+			};
+		}
 	});
 }
 /**
-* Spans for auth resolution and session refreshes, from `sb.events`.
+* Spans for auth resolution and session refreshes, from `betterSupabase.events`.
 * Returns a function that stops listening.
 */
-function traceAuth(sb, options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.0.0");
-	const offAuth = sb.events.on("auth", (event) => {
+function traceAuth(betterSupabase, options = {}) {
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.5.0");
+	const offAuth = betterSupabase.events.on("auth", (event) => {
 		const span = tracer.startSpan("auth.resolve", {
 			kind: SpanKind.INTERNAL,
 			attributes: {
@@ -131,7 +164,7 @@ function traceAuth(sb, options = {}) {
 		if (!event.ok) span.setStatus({ code: SpanStatusCode.ERROR });
 		span.end();
 	});
-	const offRefresh = sb.events.on("refresh", (event) => {
+	const offRefresh = betterSupabase.events.on("refresh", (event) => {
 		const end = Date.now();
 		const span = tracer.startSpan("auth.refresh", {
 			kind: SpanKind.CLIENT,
@@ -150,6 +183,33 @@ function traceAuth(sb, 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`)
+* 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) => {
+		const attributes = {
+			...options.attributes,
+			...kitEventAttributes(event)
+		};
+		const failed = event.type.endsWith(".failed") || event.type.endsWith(".denied");
+		const active = trace.getActiveSpan();
+		if (active) {
+			active.addEvent(event.type, attributes);
+			return;
+		}
+		const span = tracer.startSpan(`kit ${event.type}`, {
+			kind: SpanKind.INTERNAL,
+			attributes
+		});
+		if (failed) span.setStatus({ code: SpanStatusCode.ERROR });
+		span.end();
+	});
+}
+/**
 * A `fetch` that adds W3C `traceparent`/`tracestate` from the active
 * context. Pass it to `createClient(url, key, { global: { fetch } })` so
 * PostgREST, Auth and Storage calls join the trace.
@@ -167,4 +227,4 @@ function tracedFetch(base = fetch) {
 	};
 }
 //#endregion
-export { INSTRUMENTATION_NAME, SEMCONV_VERSION, otel, traceAuth, tracedFetch };
+export { INSTRUMENTATION_NAME, SEMCONV_VERSION, otel, traceAuth, traceKitEvents, tracedFetch };

package/dist/permdock-sql-C2Inc6Xc.d.ts

@@ -0,0 +1,29 @@
+//#region src/core/permdock-sql.d.ts
+/** PermDock's default `rls.schema`, a schema the Data API does not expose. */
+declare const PERMDOCK_SCHEMA = "permdock";
+/**
+ * The part of PermDock's `permissions.catalog.json` the Storage and Realtime
+ * builders read: `import catalog from './permissions.catalog.json'`.
+ */
+interface PermdockCatalog {
+  readonly permissions: readonly {
+    readonly key: string;
+    readonly rowConditions?: boolean;
+    /** The scope PermDock declares the permission at. */
+    readonly scope?: string;
+  }[];
+}
+/**
+ * What PermDock's catalog says about a key: `scope-only` (`rowConditions:
+ * false`), `row-conditions` (`true`), `no-flag` (an entry without a boolean
+ * flag, from an older `permdock catalog`) or `missing`. Only `scope-only` is
+ * safe for the SQL helpers.
+ */
+type PermdockKeyStatus = "scope-only" | "row-conditions" | "no-flag" | "missing";
+declare function permdockKeyStatus(catalog: PermdockCatalog, key: string): PermdockKeyStatus;
+/** The keys a bucket or topic PermDock policy names. */
+declare function permdockKeys(policy: {
+  readonly permdock: object;
+}): string[];
+//#endregion
+export { permdockKeys as a, permdockKeyStatus as i, PermdockCatalog as n, PermdockKeyStatus as r, PERMDOCK_SCHEMA as t };

package/dist/permdock-sql-DgOfeixi.js

@@ -0,0 +1,51 @@
+import { i as sqlString, r as sqlIdent } from "./template-TxrGI5jR.js";
+//#region src/core/permdock-sql.ts
+const SCOPE = /^[a-z][a-z0-9_]*$/;
+/** PermDock's default `rls.schema`, a schema the Data API does not expose. */
+const PERMDOCK_SCHEMA = "permdock";
+/** PermDock splits a key with row conditions into `key#1`, `key#2`, ...: those need its own policies. */
+const SPLIT_KEY = /#\d+$/;
+function permdockKeyStatus(catalog, key) {
+	const entry = catalog.permissions.find((permission) => permission.key === key);
+	if (!entry) return "missing";
+	if (entry.rowConditions === true) return "row-conditions";
+	if (entry.rowConditions === false) return "scope-only";
+	return "no-flag";
+}
+const REGENERATE = "Regenerate permissions.catalog.json with a current `permdock catalog`, which writes rowConditions for every permission.";
+/**
+* The SQL condition for one PermDock permission key. `id` is the text
+* expression holding the scope id; it is compared as text, so a malformed
+* path never raises a cast error.
+*
+* The helpers check role and scope, not a permission's row conditions, so
+* the condition is only correct for permissions whose grants have none
+* beyond the scope. `#n` keys are refused. With a catalog, only keys it marks
+* `rowConditions: false` are accepted: `true`, a missing flag and a key the
+* catalog doesn't list are refused.
+*/
+function permdockCheck(where, target, key, id, catalog) {
+	if (key === "") throw new TypeError(`${where}: a PermDock permission key is empty`);
+	if (SPLIT_KEY.test(key)) throw new TypeError(`${where}: "${key}" is one part of a permission PermDock splits by row condition. Use PermDock's generated policies for it.`);
+	if (catalog) {
+		const status = permdockKeyStatus(catalog, key);
+		switch (status) {
+			case "scope-only": break;
+			case "row-conditions": throw new TypeError(`${where}: "${key}" has row conditions in PermDock's catalog (rowConditions: true), which the SQL helpers don't check. Use PermDock's generated policies for it.`);
+			case "no-flag": throw new TypeError(`${where}: "${key}" has no rowConditions flag in PermDock's catalog, so whether the SQL helpers check it fully is unknown. ${REGENERATE}`);
+			case "missing": throw new TypeError(`${where}: "${key}" is not in PermDock's catalog. ${REGENERATE}`);
+			default: return status;
+		}
+	}
+	const schema = sqlIdent(target.schema ?? "permdock");
+	if (target.scope === "global") return `(select ${schema}.permdock_has(${sqlString(key)}))`;
+	if (!SCOPE.test(target.scope)) throw new TypeError(`${where}: invalid PermDock scope "${target.scope}"`);
+	if (id === void 0) throw new TypeError(`${where}: scope "${target.scope}" needs a segment`);
+	return `${id} in (select t.id::text from ${schema}.${sqlIdent(`permitted_${target.scope}_ids`)}(${sqlString(key)}) as t(id))`;
+}
+/** The keys a bucket or topic PermDock policy names. */
+function permdockKeys(policy) {
+	return Object.values(policy.permdock).filter((key) => typeof key === "string");
+}
+//#endregion
+export { permdockKeys as i, permdockCheck as n, permdockKeyStatus as r, PERMDOCK_SCHEMA as t };

package/dist/plugin-DwARMuQp.js

@@ -0,0 +1,59 @@
+//#region src/core/plugin.ts
+const PLUGIN_API_VERSION = 1;
+const RANK = {
+	pre: 0,
+	normal: 1,
+	post: 2
+};
+/**
+* `rules()` checks the query as the caller wrote it, so it runs before every
+* other `pre` plugin (soft delete turns deletes into updates, tenant adds
+* filters).
+*/
+function rankOf(plugin) {
+	return plugin.name === "rules" ? -1 : RANK[plugin.enforce ?? "normal"];
+}
+/**
+* Plugins in hook order: `rules`, then `pre`, then unmarked in `use()` order,
+* then `post`.
+*/
+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
+	};
+}
+/** Tenants that `tenant()` resolved from claims, per connection context. */
+const resolvedTenants = /* @__PURE__ */ new WeakMap();
+/** Records the tenant a plugin resolved for `context`, so mutation notices carry it. */
+function recordTenant(context, tenant) {
+	resolvedTenants.set(context, tenant);
+}
+/** `context.tenant`, else the tenant a plugin resolved for this connection. */
+function tenantOf(context) {
+	return context.tenant ?? resolvedTenants.get(context);
+}
+/**
+* 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 { recordTenant as a, orderPlugins as i, allTenantsContext as n, spansAllTenants as o, definePlugin as r, tenantOf as s, PLUGIN_API_VERSION as t };

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

@@ -1,7 +1,6 @@
 /// <reference lib="esnext.temporal" />
-import { A as SchemaMeta, P as TableMeta, n as AnyModels } from "./types-DONv9SHN.js";
-import { g as Operation, h as MutationOp, r as Executor } from "./executor-DynmIWhq.js";
-import { v as ErrorMapper } from "./result-c2OYgCV2.js";
+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";
 //#region src/core/plugin.d.ts
 /** Who is making the request. */
 interface Actor {
@@ -32,11 +31,24 @@ interface HookArgs {
   readonly now: () => Temporal.Instant;
 }
 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. */
   readonly kind: MutationKind;
-  /** App-cased rows returned by the mutation. */
+  /** What the caller asked for; differs from `kind` when a plugin rewrote the mutation. */
+  readonly intent?: MutationIntent;
+  /** App-cased rows returned by the mutation. A copy: changing it never changes the result. */
   readonly rows: readonly Readonly<Record<string, unknown>>[];
+  /**
+   * App-cased primary keys of the changed rows, when they are known: from
+   * the returned rows, or from a `where` on the primary key when nothing is
+   * returned (soft deletes, `returning: false`).
+   */
+  readonly keys?: readonly Readonly<Record<string, unknown>>[];
+  /** The tenant of the write: `context.tenant`, or the one `tenant()` resolved. */
+  readonly tenant?: string;
   readonly context: RequestContext;
 }
 /** Runtime handle passed to `Plugin.repository`. */
@@ -116,4 +128,4 @@ declare function definePlugin<const Name extends string, Ext extends RepositoryE
   readonly apiVersion?: 1;
 }): Plugin<Name, Ext>;
 //#endregion
-export { definePlugin as _, ExtensionOf as a, MutationEvent as c, PLUGIN_API_VERSION as d, Plugin as f, WithExtension as g, RequestContext as h, CallOptions as i, MutationKind as l, RepositoryExtension as m, AnyPlugin as n, HasFlag as o, RepositoryApi as p, ApplyExtension as r, HookArgs as s, Actor as t, NoExtension as u };
+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 };

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

@@ -1,4 +1,4 @@
-import { f as Plugin, h as RequestContext } from "../../plugin-DVRB8qNE.js";
+import { g as RequestContext, p as Plugin } from "../../plugin-o144f322.js";
 //#region src/plugins/actor/index.d.ts
 export interface ActorOptions {
   /** Custom actor id resolution. Defaults to `context.actor.id` for users and services. */
@@ -7,7 +7,10 @@ export interface ActorOptions {
 /**
  * Stamps the columns generated as `Flags.actor`: `createdBy` on insert and
  * `updatedBy` on insert and update. Soft deletes are updates, so they record
- * who deleted the row. Without an actor (anonymous requests) nothing is set.
+ * 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
+ * actor (anonymous requests) nothing is set.
  */
 export declare function actor(options?: ActorOptions): Plugin<"actor">;
 //#endregion