better-supabase 0.3.0 → 0.5.0

package/dist/{json-schema--aOXAGfU.js → json-schema-m1fiwKgN.js}

@@ -32,6 +32,18 @@ function scalarKind(column) {
 	if (column.type === "record" || column.type === "void") return { kind: "unknown" };
 	return { kind: "string" };
 }
+/** App names of the columns that plugins fill from the table's flags. */
+function managedColumns(table) {
+	const { timestamps, actor, softDelete } = table.flags;
+	return new Set([
+		timestamps?.createdAt,
+		timestamps?.updatedAt,
+		actor?.createdBy,
+		actor?.updatedBy,
+		actor?.impersonatedBy,
+		softDelete
+	].filter((name) => name !== void 0));
+}
 /**
 * The generated row type of a field (its element type for arrays). Storage
 * path columns validate as strings and are cast to their `StoragePath` brand.
@@ -43,6 +55,7 @@ function rowType(table, plan) {
 /** The fields a variant accepts; read-only columns are left out of writes. */
 function fieldsFor(table, variant, input) {
 	const fields = [];
+	const managed = managedColumns(table);
 	for (const [name, column] of Object.entries(table.columns)) {
 		if (variant === "Insert" && (column.generated || column.insertable === false)) continue;
 		if (variant === "Update" && (column.generated || column.updatable === false)) continue;
@@ -52,7 +65,8 @@ function fieldsFor(table, variant, input) {
 			scalar: scalarKind(column),
 			nullable: column.nullable,
 			optional: variant === "Update" || variant === "Insert" && (column.nullable || column.hasDefault),
-			customJson: Boolean(column.json && input.config.json[`${table.name}.${column.db}`])
+			customJson: Boolean(column.json && input.config.json[`${table.name}.${column.db}`]),
+			managed: managed.has(name)
 		});
 	}
 	return fields;
@@ -65,7 +79,7 @@ function variantsFor(table) {
 	];
 }
 function tableEntries(input) {
-	return Object.entries(input.meta.tables).sort(([a], [b]) => a.localeCompare(b));
+	return Object.entries(input.meta.tables).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
 }
 function propertyKey(name) {
 	return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
@@ -130,6 +144,13 @@ function scalar(kind) {
 	}
 }
 function property(plan) {
+	const schema = nullable(plan);
+	return plan.managed ? {
+		...schema,
+		readOnly: true
+	} : schema;
+}
+function nullable(plan) {
 	let schema = scalar(plan.scalar);
 	if (plan.column.array) schema = {
 		type: "array",

package/dist/kit-events-CTFDfSwb.js

@@ -0,0 +1,60 @@
+import { t as cloneValue } from "./clone-BfgmLU90.js";
+import { n as nowInstant } from "./temporal-CVlIV2DZ.js";
+//#region src/core/kit-events.ts
+/**
+* Fixed OpenTelemetry attribute names for kit work, so dashboards and
+* queries can rely on them.
+*/
+const KIT_ATTRIBUTES = {
+	event: "better_supabase.kit.event",
+	tenant: "better_supabase.tenant",
+	actor: "better_supabase.actor.id",
+	supportSessionId: "better_supabase.support.session_id",
+	orgId: "better_supabase.org.id",
+	invitationId: "better_supabase.invitation.id",
+	notificationType: "better_supabase.notification.type",
+	webhookEndpointId: "better_supabase.webhook.endpoint_id"
+};
+/** The `KIT_ATTRIBUTES` an event carries. */
+function kitEventAttributes(event) {
+	const attributes = { [KIT_ATTRIBUTES.event]: event.type };
+	if (event.tenant) attributes[KIT_ATTRIBUTES.tenant] = event.tenant;
+	if (event.actorId) attributes[KIT_ATTRIBUTES.actor] = event.actorId;
+	const data = Object.fromEntries(Object.entries(event.data));
+	const add = (key, value) => {
+		if (typeof value === "string" && value.length > 0) attributes[key] = value;
+	};
+	add(KIT_ATTRIBUTES.supportSessionId, data["sessionId"]);
+	add(KIT_ATTRIBUTES.orgId, data["organizationId"]);
+	add(KIT_ATTRIBUTES.invitationId, data["invitationId"]);
+	add(KIT_ATTRIBUTES.notificationType, data["type"]);
+	add(KIT_ATTRIBUTES.webhookEndpointId, data["endpointId"]);
+	return attributes;
+}
+/**
+* Emits a kit event on `events` with a copy of `data`. Does nothing without
+* a `kit` handler, so kits call it unconditionally.
+*/
+function emitKitEvent(events, type, data, meta = {}) {
+	if (!events.has("kit")) return;
+	const event = {
+		...meta,
+		type,
+		data: cloneValue(data),
+		time: nowInstant()
+	};
+	events.emit("kit", event);
+}
+const matches = (pattern, type) => pattern.endsWith(".*") ? type.startsWith(pattern.slice(0, -1)) : pattern === type;
+/**
+* Listens to the kit events that match `pattern` (`'support.started'` or
+* `'support.*'`). Returns a function that stops listening.
+*/
+function onKitEvent(betterSupabase, pattern, handler) {
+	return betterSupabase.events.on("kit", (event) => {
+		if (!matches(pattern, event.type)) return;
+		handler(event);
+	});
+}
+//#endregion
+export { onKitEvent as i, emitKitEvent as n, kitEventAttributes as r, KIT_ATTRIBUTES as t };

package/dist/kit-transport-B82k1djG.d.ts

@@ -0,0 +1,33 @@
+import { t as SqlClient } from "./executor-Cghdstwu.js";
+//#region src/core/kit-transport.d.ts
+/**
+ * Calls a kit function as the current user and resolves with its result.
+ * Rejects with the raw database error (a `pg` error or a PostgREST error
+ * object), which the kit maps to a `DbError`.
+ */
+interface KitTransport {
+  call(schema: string, fn: string, args: Readonly<Record<string, unknown>>): Promise<unknown>;
+}
+/**
+ * Calls the functions over Postgres, as the user `client` runs as:
+ * `sqlTransport(postgres.asUser(ctx.auth.claims))`. Works for any schema.
+ */
+declare function sqlTransport(client: SqlClient): KitTransport;
+interface RpcResponse {
+  readonly data: unknown;
+  readonly error: unknown;
+}
+/** The part of a supabase-js client `rpcTransport` uses. */
+interface RpcClient {
+  schema(name: string): {
+    rpc(fn: string, args: Record<string, unknown>): PromiseLike<RpcResponse>;
+  };
+}
+/**
+ * Calls the functions over the Data API with the user's session. The kit
+ * schema must be exposed (`[api] schemas` in `config.toml`), or the modules
+ * installed in `public` (`kits.<module>.schema`).
+ */
+declare function rpcTransport(client: RpcClient): KitTransport;
+//#endregion
+export { sqlTransport as i, RpcClient as n, rpcTransport as r, KitTransport as t };

package/dist/kit-transport-DJlHQUBU.js

@@ -0,0 +1,55 @@
+import { r as sqlIdent } from "./template-TxrGI5jR.js";
+//#region src/core/kit-transport.ts
+/**
+* Calls the functions over Postgres, as the user `client` runs as:
+* `sqlTransport(postgres.asUser(ctx.auth.claims))`. Works for any schema.
+*/
+function sqlTransport(client) {
+	return { async call(schema, fn, args) {
+		const entries = Object.entries(args).filter(([, value]) => value !== void 0);
+		const params = entries.map(([, value]) => value !== null && typeof value === "object" && !Array.isArray(value) ? JSON.stringify(value) : value);
+		const list = entries.map(([name], index) => `${sqlIdent(name)} => $${String(index + 1)}`).join(", ");
+		const [row] = await client.queryRaw(`select ${sqlIdent(schema)}.${sqlIdent(fn)}(${list}) as value`, params);
+		return row?.value ?? null;
+	} };
+}
+/**
+* Calls the functions over the Data API with the user's session. The kit
+* schema must be exposed (`[api] schemas` in `config.toml`), or the modules
+* installed in `public` (`kits.<module>.schema`).
+*/
+function rpcTransport(client) {
+	return { async call(schema, fn, args) {
+		const defined = Object.fromEntries(Object.entries(args).filter(([, value]) => value !== void 0));
+		const { data, error } = await client.schema(schema).rpc(fn, defined);
+		if (error) {
+			const message = typeof error === "object" && "message" in error ? String(error.message) : String(error);
+			throw Object.assign(new Error(message), error);
+		}
+		return data;
+	} };
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The Postgres or PostgREST error a transport rejected with, if it is one. */
+function rawError(cause) {
+	if (!isRecord(cause)) return void 0;
+	const field = (key) => {
+		const value = cause[key];
+		return typeof value === "string" ? value : void 0;
+	};
+	if (field("code") === void 0) return void 0;
+	const raw = {};
+	for (const key of [
+		"message",
+		"code",
+		"details",
+		"hint",
+		"constraint"
+	]) {
+		const value = field(key);
+		if (value !== void 0) raw[key] = value;
+	}
+	return raw;
+}
+//#endregion
+export { rpcTransport as n, sqlTransport as r, rawError as t };

package/dist/{config-Be4GwsqI.js → kits-CGLLrNPd.js}

@@ -1,4 +1,4 @@
-import { t as DEFAULT_CLAIMS } from "./claims-CoTobNC-.js";
+import { t as DEFAULT_CLAIMS } from "./claims-BAf6c7is.js";
 //#region src/config/config.ts
 /** The JSON Schema document for a `json[...].schema` entry. */
 function resolveJsonSchema(source) {
@@ -9,14 +9,16 @@ function resolveJsonSchema(source) {
 	return jsonSchema.input({ target: "draft-2020-12" });
 }
 function entitlementsOf(config = {}) {
-	const customer = config.customer ?? "organizations.stripe_customer_id";
-	const dot = customer.lastIndexOf(".");
-	if (dot <= 0) throw new TypeError(`entitlements.customer must be "table.column", got "${customer}"`);
+	const customer = config.customer;
+	const dot = customer?.lastIndexOf(".") ?? -1;
+	if (customer !== void 0 && dot <= 0) throw new TypeError(`entitlements.customer must be "table.column", got "${customer}"`);
 	return {
-		table: customer.slice(0, dot),
-		column: customer.slice(dot + 1),
+		...customer === void 0 ? {} : {
+			table: customer.slice(0, dot),
+			column: customer.slice(dot + 1)
+		},
 		key: config.key ?? "id",
-		permdock: config.permdock === false ? false : { scope: config.permdock?.scope ?? "organization" }
+		permdock: config.permdock === false ? false : config.permdock?.scope === void 0 ? {} : { scope: config.permdock.scope }
 	};
 }
 function vectorSearchOf(config = {}) {
@@ -86,7 +88,8 @@ function resolveConfig(config, root) {
 			tenant: pick(config.plugins?.tenant, { column: "organization_id" }),
 			actor: pick(config.plugins?.actor, {
 				createdBy: "created_by",
-				updatedBy: "updated_by"
+				updatedBy: "updated_by",
+				impersonatedBy: "impersonated_by"
 			})
 		},
 		claims: {
@@ -95,7 +98,10 @@ function resolveConfig(config, root) {
 		},
 		buckets: config.buckets ?? {},
 		topics: config.topics ?? {},
-		realtime: { tables: config.realtime?.tables ?? [] },
+		realtime: {
+			tables: config.realtime?.tables ?? [],
+			global: config.realtime?.global ?? []
+		},
 		entitlements: entitlementsOf(config.entitlements),
 		permdock: {
 			manifest: config.permdock?.manifest ?? "permdock.manifest.json",
@@ -108,6 +114,7 @@ function resolveConfig(config, root) {
 			testsDir: config.sql?.testsDir ?? "supabase/tests",
 			kit: config.sql?.kit ?? []
 		},
+		kits: config.kits ?? {},
 		seed: {
 			entry: config.seed?.entry ?? "supabase/seed.ts",
 			output: config.seed?.output ?? "supabase/seeds/000_better_supabase.sql"
@@ -126,4 +133,25 @@ function resolveConfig(config, root) {
 	};
 }
 //#endregion
-export { resolveJsonSchema as i, defineConfig as n, resolveConfig as r, CONFIG_SCHEMA_URL as t };
+//#region src/config/kits.ts
+/** URL tenancy: the tenant comes from the request (a slug), not a stored setting. */
+const DEFAULT_ACTIVE_TENANT = "resolver";
+const KIT_SCHEMA = "better_supabase";
+function resolveKitModule(config = {}) {
+	return {
+		mode: config.mode ?? "managed",
+		schema: config.schema ?? KIT_SCHEMA,
+		tables: config.tables ?? {},
+		columns: config.columns ?? {},
+		...config.idType === void 0 ? {} : { idType: config.idType },
+		permissions: config.permissions ?? {},
+		options: config.options ?? {},
+		hooks: {
+			schema: config.hooks?.schema ?? "public",
+			functions: config.hooks?.functions ?? {}
+		},
+		events: config.events ?? true
+	};
+}
+//#endregion
+export { resolveConfig as a, defineConfig as i, resolveKitModule as n, resolveJsonSchema as o, CONFIG_SCHEMA_URL as r, DEFAULT_ACTIVE_TENANT as t };

package/dist/list/index.d.ts

@@ -1,2 +1,2 @@
-import { a as ListPage, c as ListParsers, d as ListQueryInput, f as ListSearchParams, g as defineListQuery, h as UNSET, i as ListExtra, l as ListQuery, m as ParserSpec, n as FacetInfo, o as ListPagination, p as OpenApiParameter, r as ListDefinition, s as ListParseResult, t as FacetCounts, u as ListQueryConfig } from "../index-CADlNHK-.js";
+import { a as ListPage, c as ListParsers, d as ListQueryInput, f as ListSearchParams, g as defineListQuery, h as UNSET, i as ListExtra, l as ListQuery, m as ParserSpec, n as FacetInfo, o as ListPagination, p as OpenApiParameter, r as ListDefinition, s as ListParseResult, t as FacetCounts, u as ListQueryConfig } from "../index-fag8VJZ2.js";
 export { type FacetCounts, type FacetInfo, type ListDefinition, type ListExtra, type ListPage, type ListPagination, type ListParseResult, type ListParsers, type ListQuery, type ListQueryConfig, type ListQueryInput, type ListSearchParams, type OpenApiParameter, type ParserSpec, UNSET, defineListQuery };

package/dist/list/index.js

@@ -35,7 +35,7 @@ function toInt(raw) {
 * OpenAPI parameters and a JSON Schema derived from the same definition.
 *
 * ```ts
-* export const customerList = defineListQuery(sb, 'customers', {
+* export const customerList = defineListQuery(betterSupabase, 'customers', {
 *   search: ['name', 'kvk'],
 *   facets: { status: 'status' },
 *   sorts: { name: { name: 'asc' }, newest: [{ createdAt: 'desc' }, { id: 'asc' }] },
@@ -43,8 +43,8 @@ function toInt(raw) {
 * });
 * ```
 */
-function defineListQuery(sb, table, config) {
-	const meta = sb.meta.tables[table];
+function defineListQuery(betterSupabase, table, config) {
+	const meta = betterSupabase.meta.tables[table];
 	if (!meta) throw new TypeError(`defineListQuery: unknown table "${table}"`);
 	const pageSize = config.pageSize ?? 50;
 	const maxPageSize = config.maxPageSize ?? 200;

package/dist/{live-D8rV1Ldw.js → live-CdJBOc4f.js}

@@ -64,6 +64,10 @@ function join(client, topic, listener) {
 			left = true;
 			current.listeners.delete(listener);
 			if (current.listeners.size > 0) return;
+			await new Promise((resolve) => {
+				setTimeout(resolve, 0);
+			});
+			if (current.listeners.size > 0 || byTopic.get(topic) !== current) return;
 			byTopic.delete(topic);
 			await client.removeChannel(current.channel);
 		}
@@ -76,13 +80,13 @@ function join(client, topic, listener) {
 * table, so any number of them can run at once.
 *
 * ```ts
-* using live = liveQuery(sb, supabase, spec, { onChange: () => refetch() });
+* using live = liveQuery(betterSupabase, supabase, spec, { onChange: () => refetch() });
 * ```
 */
-function liveQuery(sb, client, spec, options) {
-	const touched = Array.isArray(spec) ? spec : sb.tablesOf(spec);
-	const tables = touched.filter((table) => sb.meta.realtime?.[table]);
-	const unwatched = touched.filter((table) => !sb.meta.realtime?.[table]);
+function liveQuery(betterSupabase, client, spec, options) {
+	const touched = Array.isArray(spec) ? spec : betterSupabase.tablesOf(spec);
+	const tables = touched.filter((table) => betterSupabase.meta.realtime?.[table]);
+	const unwatched = touched.filter((table) => !betterSupabase.meta.realtime?.[table]);
 	const debounceMs = options.debounceMs ?? 100;
 	const changed = /* @__PURE__ */ new Set();
 	let timer;
@@ -94,7 +98,7 @@ function liveQuery(sb, client, spec, options) {
 		changed.clear();
 		options.onChange(batch);
 	};
-	const memberships = tables.map((table) => join(client, liveTopic(sb.meta, table, options.tenant), () => {
+	const memberships = tables.map((table) => join(client, liveTopic(betterSupabase.meta, table, options.tenant), () => {
 		changed.add(table);
 		if (timer !== void 0) clearTimeout(timer);
 		timer = setTimeout(flush, debounceMs);
@@ -130,12 +134,12 @@ function liveQuery(sb, client, spec, options) {
 * Responses that arrive out of order are dropped.
 *
 * ```ts
-* using live = liveCount(sb, supabase, db, sb.spec.notes.count(), {
+* using live = liveCount(betterSupabase, supabase, db, betterSupabase.spec.notes.count(), {
 *   onCount: (count) => render(count),
 * });
 * ```
 */
-function liveCount(sb, client, db, spec, options) {
+function liveCount(betterSupabase, client, db, spec, options) {
 	let latest = 0;
 	let closed = false;
 	const refetch = () => {
@@ -146,7 +150,7 @@ function liveCount(sb, client, db, spec, options) {
 			else options.onError?.(result.error);
 		});
 	};
-	const live = liveQuery(sb, client, spec, {
+	const live = liveQuery(betterSupabase, client, spec, {
 		onChange: refetch,
 		...options.tenant === void 0 ? {} : { tenant: options.tenant },
 		...options.debounceMs === void 0 ? {} : { debounceMs: options.debounceMs },

package/dist/{live-QE3UPbGm.d.ts → live-D9W2M5aO.d.ts}

@@ -1,7 +1,7 @@
-import { A as SchemaMeta, N as TableKey, O as Row, n as AnyModels, t as AnyFunctions, x as PermdockTopicPolicy } from "./types-DONv9SHN.js";
-import { b as ValidationIssue, o as Result, p as DbError, t as AsyncResult } from "./result-c2OYgCV2.js";
-import { Z as QuerySpec, t as BetterSupabase } from "./define-DUbydmJa.js";
-import { t as PermdockCatalog } from "./permdock-sql-DImJULY-.js";
+import { P as TableKey, S as PermdockTopicPolicy, j as SchemaMeta, k as Row, n as AnyFunctions, r as AnyModels } from "./types-Dnf_wRDz.js";
+import { _ as DbError, a as AsyncResult, u as Result, w as ValidationIssue } from "./executor-BunPOO-k.js";
+import { Z as QuerySpec, t as BetterSupabase } from "./define-Bp_BZa5h.js";
+import { n as PermdockCatalog } from "./permdock-sql-C2Inc6Xc.js";
 import { n as TemplateValues, t as TemplateParams } from "./template-mbvlysOo.js";
 import { RealtimeChannel, SupabaseClient } from "@supabase/supabase-js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
@@ -41,7 +41,8 @@ interface TopicOptions<E extends EventSchemas> {
   readonly permdock?: PermdockTopicPolicy;
   /**
    * PermDock's `permissions.catalog.json`. With it, a `permdock` policy
-   * naming a permission with `rowConditions: true` throws.
+   * naming a permission without `rowConditions: false` (including one the
+   * catalog doesn't list) throws.
    */
   readonly catalog?: PermdockCatalog;
   /** Let clients broadcast on the topic, not only receive. Defaults to `false`. */
@@ -78,7 +79,7 @@ interface Subscription extends Disposable, AsyncDisposable {
   readonly ready: Promise<void>;
   unsubscribe(): Promise<void>;
 }
-type RealtimeClient = Pick<SupabaseClient, "channel" | "removeChannel" | "realtime">;
+type RealtimeClient = Pick<SupabaseClient, "channel" | "getChannels" | "removeChannel" | "realtime">;
 interface TriggerOptions<M extends AnyModels, T extends keyof M, P extends string> {
   /** Column that fills each placeholder. */
   readonly values: { readonly [K in TemplateParams<P>]: Extract<keyof Row<M, T>, string>; };
@@ -106,7 +107,7 @@ interface Topic<P extends string, E extends EventSchemas> {
   /** `realtime.messages` policies for this topic. Idempotent. */
   sql(): string;
   /** A trigger that broadcasts row changes (`realtime.broadcast_changes`) to this topic. */
-  triggerSql<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(sb: BetterSupabase<M, D, F, X>, table: T, options: TriggerOptions<M, T, P>): string;
+  triggerSql<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, F, X>, table: T, options: TriggerOptions<M, T, P>): string;
   subscribe(client: RealtimeClient, values: TemplateValues<P>, handlers: TopicHandlers<E>, options?: SubscribeOptions): Subscription;
   /** Sends over HTTP, without joining the channel. */
   send<K extends TopicEvent<E>>(client: RealtimeClient, values: TemplateValues<P>, event: K, payload: TopicPayload<E, K>): AsyncResult<void>;
@@ -127,10 +128,10 @@ declare function defineTopic<const P extends string, const E extends EventSchema
  * Reads a `realtime.broadcast_changes` message as an app-cased row change.
  * Returns `null` for messages about other tables.
  */
-declare function rowChange<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(sb: BetterSupabase<M, D, F, X>, table: T, message: TopicMessage): RowChange<Row<M, T>> | null;
+declare function rowChange<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, F, X>, table: T, message: TopicMessage): RowChange<Row<M, T>> | null;
 //#endregion
 //#region src/realtime/live.d.ts
-/** What `liveQuery` needs from `sb`: metadata and the tables a spec reads. */
+/** What `liveQuery` needs from `betterSupabase`: metadata and the tables a spec reads. */
 interface LiveSource {
   readonly meta: SchemaMeta;
   tablesOf(spec: QuerySpec): string[];
@@ -154,7 +155,7 @@ interface LiveSubscription extends Disposable, AsyncDisposable {
 }
 /**
  * A count from the server plus the spec to keep it live on the client:
- * `next.liveCount(spec)` makes one, `useLiveCount(seed)` reads it. `count`
+ * `bs.liveCount(spec)` makes one, `useLiveCount(seed)` reads it. `count`
  * is `null` when the server read failed; the client then fetches it.
  */
 interface LiveCountSeed<T extends string = string> {
@@ -170,11 +171,11 @@ declare function liveTopic(meta: SchemaMeta, table: string, tenant?: string): st
  * table, so any number of them can run at once.
  *
  * ```ts
- * using live = liveQuery(sb, supabase, spec, { onChange: () => refetch() });
+ * using live = liveQuery(betterSupabase, supabase, spec, { onChange: () => refetch() });
  * ```
  */
-declare function liveQuery(sb: LiveSource, client: RealtimeClient, spec: QuerySpec | readonly string[], options: LiveQueryOptions): LiveSubscription;
-/** What `liveCount` runs the spec with: a `db` from `sb.connect()` or `createBrowser()`. */
+declare function liveQuery(betterSupabase: LiveSource, client: RealtimeClient, spec: QuerySpec | readonly string[], options: LiveQueryOptions): LiveSubscription;
+/** What `liveCount` runs the spec with: a `db` from `betterSupabase.connect()` or `createClient()`. */
 interface CountRunner {
   $run(spec: QuerySpec): PromiseLike<Result<unknown>>;
 }
@@ -191,11 +192,11 @@ interface LiveCountOptions extends Omit<LiveQueryOptions, "onChange"> {
  * Responses that arrive out of order are dropped.
  *
  * ```ts
- * using live = liveCount(sb, supabase, db, sb.spec.notes.count(), {
+ * using live = liveCount(betterSupabase, supabase, db, betterSupabase.spec.notes.count(), {
  *   onCount: (count) => render(count),
  * });
  * ```
  */
-declare function liveCount(sb: LiveSource, client: RealtimeClient, db: CountRunner, spec: QuerySpec<string, "count", number>, options: LiveCountOptions): LiveSubscription;
+declare function liveCount(betterSupabase: LiveSource, client: RealtimeClient, db: CountRunner, spec: QuerySpec<string, "count", number>, options: LiveCountOptions): LiveSubscription;
 //#endregion
 export { defineTopic as C, TriggerOptions as S, TopicEvent as _, LiveSource as a, TopicOptions as b, liveQuery as c, RealtimeClient as d, RowChange as f, Topic as g, SubscriptionStatus as h, LiveQueryOptions as i, liveTopic as l, Subscription as m, LiveCountOptions as n, LiveSubscription as o, SubscribeOptions as p, LiveCountSeed as r, liveCount as s, CountRunner as t, EventSchemas as u, TopicHandlers as v, rowChange as w, TopicPayload as x, TopicMessage as y };

package/dist/lookup-BaP5bI27.js

@@ -0,0 +1,18 @@
+//#region src/schema/lookup.ts
+const lookups = /* @__PURE__ */ new WeakMap();
+/** The cached lookup for a table; metadata is immutable after `defineSchema`. */
+function lookupOf(table) {
+	let lookup = lookups.get(table);
+	if (!lookup) {
+		const entries = Object.entries(table.columns);
+		lookup = {
+			entries,
+			byDb: new Map(entries.map((entry) => [entry[1].db, entry])),
+			keys: [table.primaryKey, ...Object.values(table.uniqueKeys)]
+		};
+		lookups.set(table, lookup);
+	}
+	return lookup;
+}
+//#endregion
+export { lookupOf as t };

package/dist/mcp/index.d.ts

@@ -1,7 +1,8 @@
-import { N as TableKey, n as AnyModels, t as AnyFunctions } from "../types-DONv9SHN.js";
-import { t as BetterSupabase } from "../define-DUbydmJa.js";
-import { d as ServerContext, f as ServerOptions, l as BetterServer, n as GuardOptions } from "../respond-DAkPIdTH.js";
-import { a as ResourceRouteOptions } from "../resource-CwVgiI5q.js";
+import { P as TableKey, n as AnyFunctions, r as AnyModels } from "../types-Dnf_wRDz.js";
+import { t as BetterSupabase } from "../define-Bp_BZa5h.js";
+import { f as ServerContext, n as GuardOptions, p as ServerOptions, u as BetterServer } from "../respond-D2OQl62-.js";
+import { i as ResourceOperation } from "../index-C7f8cOBM.js";
+import { a as ResourceRouteOptions } from "../resource-D8iqWMr-.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/mcp/mcp.d.ts
 export declare const MCP_PROTOCOL_VERSION: string;
@@ -23,22 +24,22 @@ interface ToolInfo {
   readonly outputSchema?: Json;
   readonly annotations?: ToolAnnotations;
 }
-interface ToolContext<M extends AnyModels, F extends AnyFunctions, E> extends ServerContext<M, F, E> {
+interface ToolContext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends ServerContext<M, F, E, C, P> {
   readonly request: Request;
   readonly signal: AbortSignal;
 }
-interface McpTool<M extends AnyModels, F extends AnyFunctions, E> {
+interface McpTool<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> {
   readonly info: ToolInfo;
   /** Validates arguments; its output is what `run` receives. */
   readonly input?: StandardSchemaV1;
   /** Opaque data for the `authorize` and `visible` hooks. Never sent to clients. */
   readonly meta?: unknown;
-  run(args: never, ctx: ToolContext<M, F, E>): unknown;
+  run(args: never, ctx: ToolContext<M, F, E, C, P>): unknown;
 }
 /** What the `authorize` and `visible` hooks see of a tool. */
 interface ToolRef {
   readonly info: ToolInfo;
-  /** The tool's `meta`, e.g. a PermDock permission. `undefined` for table tools. */
+  /** The tool's `meta`, e.g. a PermDock permission. For table tools, the resource's `meta` for that operation. */
   readonly meta: unknown;
 }
 /** The outcome of `authorize`. `scopes` turns a refusal into an OAuth challenge. */
@@ -50,7 +51,7 @@ type ToolDecision = {
   /** OAuth scopes the call needs, sent in an `insufficient_scope` challenge. */
   readonly scopes?: readonly string[];
 };
-interface ToolDefinition<M extends AnyModels, F extends AnyFunctions, E, I> {
+interface ToolDefinition<M extends AnyModels, F extends AnyFunctions, E, I, C = unknown, P = unknown> {
   readonly name: string;
   readonly title?: string;
   readonly description: string;
@@ -64,10 +65,19 @@ interface ToolDefinition<M extends AnyModels, F extends AnyFunctions, E, I> {
   readonly annotations?: ToolAnnotations;
   /** Opaque data for the `authorize` and `visible` hooks. Never sent to clients. */
   readonly meta?: unknown;
-  run(args: I, ctx: ToolContext<M, F, E>): unknown;
+  run(args: I, ctx: ToolContext<M, F, E, C, P>): unknown;
 }
-type ToolResources<M extends AnyModels> = { readonly [T in TableKey<M>]?: ResourceRouteOptions<M, T> | true; };
-interface McpOptions<M extends AnyModels, F extends AnyFunctions, E> extends ServerOptions, GuardOptions {
+/** A table's tools: the REST resource options, plus `meta` per operation for `authorize` and `visible`. */
+type ToolResourceOptions<M extends AnyModels, T extends TableKey<M>> = ResourceRouteOptions<M, T> & {
+  /**
+   * Opaque data per operation, e.g. a PermDock permission, passed to
+   * `authorize` and `visible` as the table tool's `meta`. Never sent to
+   * clients. An operation without an entry gets `undefined`.
+   */
+  readonly meta?: { readonly [K in ResourceOperation]?: unknown; };
+};
+type ToolResources<M extends AnyModels> = { readonly [T in TableKey<M>]?: ToolResourceOptions<M, T> | true; };
+interface McpOptions<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends ServerOptions, Omit<GuardOptions, "scopes"> {
   readonly name: string;
   readonly version: string;
   readonly title?: string;
@@ -75,7 +85,7 @@ interface McpOptions<M extends AnyModels, F extends AnyFunctions, E> extends Ser
   readonly instructions?: string;
   /** Tables exposed as tools: `<table>_list`, `_get`, `_create`, `_update`, `_delete`. */
   readonly resources?: ToolResources<M>;
-  readonly tools?: readonly McpTool<M, F, E>[];
+  readonly tools?: readonly McpTool<M, F, E, C, P>[];
   /**
    * Canonical URL of this MCP server (RFC 9728 `resource`). Defaults to the
    * request URL without query.
@@ -88,7 +98,14 @@ interface McpOptions<M extends AnyModels, F extends AnyFunctions, E> extends Ser
    * `insufficient_scope` challenges. `offline_access` is left out: refresh
    * tokens are between the client and the authorization server.
    */
+  readonly advertisedScopes?: readonly string[];
+  /** @deprecated Use `advertisedScopes`; `requiredScopes` is what `guard` enforces. */
   readonly scopes?: readonly string[];
+  /**
+   * Scopes a delegated token (an OAuth client or an `act` chain) needs to call
+   * the server at all. A missing one answers 403 `insufficient_scope`.
+   */
+  readonly requiredScopes?: readonly string[];
   /** Origins allowed to call the server (DNS rebinding protection). Defaults to any. */
   readonly allowedOrigins?: readonly string[];
   /**
@@ -108,25 +125,25 @@ interface McpOptions<M extends AnyModels, F extends AnyFunctions, E> extends Ser
    * validate in the repository). A refusal is a tool error; a refusal with
    * `scopes` is a 403 `insufficient_scope` challenge naming them.
    */
-  readonly authorize?: (ctx: ToolContext<M, F, E>, tool: ToolRef, args: unknown) => ToolDecision | Promise<ToolDecision>;
+  readonly authorize?: (ctx: ToolContext<M, F, E, C, P>, tool: ToolRef, args: unknown) => ToolDecision | Promise<ToolDecision>;
   /**
    * Whether the caller sees a tool in `tools/list`. A hidden tool is called
    * like an unknown one. Lists are cached per token (`cacheScope: 'private'`).
    */
-  readonly visible?: (ctx: ToolContext<M, F, E>, tool: ToolRef) => boolean | Promise<boolean>;
+  readonly visible?: (ctx: ToolContext<M, F, E, C, P>, tool: ToolRef) => boolean | Promise<boolean>;
 }
-interface BetterMcp<M extends AnyModels, F extends AnyFunctions, E> extends BetterServer<M, F, E> {
+interface BetterMcp<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends BetterServer<M, F, E, C, P> {
   /** Everything in one handler: the MCP endpoint and `/.well-known/oauth-protected-resource`. */
   readonly fetch: (request: Request) => Promise<Response>;
   /** The Streamable HTTP endpoint (POST JSON-RPC). */
-  readonly handler: (request: Request) => Promise<Response>;
+  readonly endpoint: (request: Request) => Promise<Response>;
   /** RFC 9728 protected resource metadata. */
   metadata(request: Request): Response;
   readonly tools: readonly ToolInfo[];
   /** Adds a tool typed against this app's repositories. */
-  tool<I = Record<string, unknown>>(definition: ToolDefinition<M, F, E, I>): this;
+  tool<I = Record<string, unknown>>(definition: ToolDefinition<M, F, E, I, C, P>): this;
   /** Calls a tool directly, e.g. from tests or another transport. */
-  call(name: string, args: unknown, ctx: ToolContext<M, F, E>): Promise<ToolResult>;
+  call(name: string, args: unknown, ctx: ToolContext<M, F, E, C, P>): Promise<ToolResult>;
 }
 interface ToolResult {
   readonly content: readonly {
@@ -137,13 +154,13 @@ interface ToolResult {
   readonly isError?: boolean;
 }
 /** A custom tool. Pass it in `createMcp({ tools: [...] })`. */
-export declare function defineTool<M extends AnyModels, F extends AnyFunctions, E, I = Record<string, unknown>>(definition: ToolDefinition<M, F, E, I>): McpTool<M, F, E>;
+export declare function defineTool<M extends AnyModels, F extends AnyFunctions, E, I = Record<string, unknown>, C = unknown, P = unknown>(definition: ToolDefinition<M, F, E, I, C, P>): McpTool<M, F, E, C, P>;
 /**
  * An MCP server (Streamable HTTP, stateless) whose tools run as the caller:
  * the Bearer token from the MCP client is verified and every query goes
  * through RLS. Answers 401 with RFC 9728 metadata so clients can sign in with
  * Supabase Auth's OAuth server.
  */
-export declare function createMcp<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, options: McpOptions<M, F, E>): BetterMcp<M, F, E>;
+export declare function createMcp<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, options: McpOptions<M, F, E, C, P>): BetterMcp<M, F, E, C, P>;
 //#endregion
-export type { BetterMcp, GuardOptions, McpOptions, McpTool, ResourceRouteOptions, ToolAnnotations, ToolContext, ToolDecision, ToolDefinition, ToolInfo, ToolRef, ToolResources, ToolResult };
+export type { BetterMcp, GuardOptions, McpOptions, McpTool, ResourceRouteOptions, ToolAnnotations, ToolContext, ToolDecision, ToolDefinition, ToolInfo, ToolRef, ToolResourceOptions, ToolResources, ToolResult };