better-supabase 0.7.1 → 0.9.0

package/dist/list-query-PvP3pPGQ.d.ts

@@ -0,0 +1,194 @@
+import { E as ValidationIssue, t as AsyncResult } from "./result-Cj3yWhjH.js";
+import { M as Row, a as AnyModels, i as AnyFunctions, z as TableKey } from "./types-YfwpIE-d.js";
+import { l as CountMode } from "./executor-DoE-5iM8.js";
+import { Bt as WhereInput, E as OffsetPageArgs, F as RepositoryOf, Lt as SelectArg, Nt as Payload, T as OffsetPage, g as CursorPageArgs, h as CursorPage, jt as OrderByArg, t as BetterSupabase, wt as IncludeArg, x as FindExt } from "./define-DxHHbNEb.js";
+import { c as FilterFieldLabels, h as FilterQuery, o as FilterField, r as FilterClock, s as FilterFieldInfo, v as ListFilterConfig } from "./filter-query-BKmRYrTE.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/list/list-query.d.ts
+/** Facet value meaning "not set": filters with `is null`. */
+declare const UNSET = "__unset__";
+type Column<M extends AnyModels, T extends keyof M> = Extract<keyof Row<M, T>, string>;
+type TextColumn<M extends AnyModels, T extends keyof M> = { [K in Column<M, T>]: [NonNullable<Row<M, T>[K]>] extends [string] ? K : never; }[Column<M, T>];
+/** `offset` pages by number; `cursor` continues after the last row (keyset). */
+type ListPagination = "offset" | "cursor";
+interface ListQueryConfig<M extends AnyModels, T extends keyof M, S extends string, F extends string, C extends boolean = boolean, P extends ListPagination = ListPagination> {
+  /**
+   * Also count rows per facet value, with one grouped aggregate per facet
+   * that runs next to the page: one wave. Needs PostgREST aggregates.
+   */
+  readonly facetCounts?: C;
+  /** How the page total is counted. Defaults to `'planned'`, the planner's estimate. */
+  readonly count?: CountMode;
+  /** Text columns matched case-insensitively (OR), or a full-text column. */
+  readonly search?: readonly TextColumn<M, T>[] | {
+    readonly fts: Column<M, T>;
+    readonly config?: string;
+  };
+  /** Filterable columns by URL key. Values are validated against enums and CHECK unions. */
+  readonly facets?: { readonly [K in F]: Column<M, T>; };
+  /**
+   * Fields a filter tree (ReUI Filters' `FilterQuery`) may name, by field id.
+   * Each has a type and, optionally, the subset of its operators to allow.
+   */
+  readonly filters?: Readonly<Record<string, ListFilterConfig<Column<M, T>>>>;
+  /** Most nested group levels in a filter tree, the root included. Defaults to 4. */
+  readonly maxFilterDepth?: number;
+  /** Most rules in a filter tree. Defaults to 50. */
+  readonly maxFilterRules?: number;
+  /** Named orderings. Add a unique column last for stable pages. */
+  readonly sorts: { readonly [K in S]: OrderByArg<M, T>; };
+  readonly defaultSort: NoInfer<S>;
+  /**
+   * `cursor` takes an `after` cursor instead of `page` and returns
+   * `nextCursor`: the cost of a page stays the same however deep it is, and
+   * rows inserted meanwhile don't shift it. Defaults to `cursor`; `offset`
+   * takes `page` and returns `total` and `pageCount`.
+   */
+  readonly pagination?: P;
+  /** Defaults to 50. */
+  readonly pageSize?: number;
+  /** Defaults to 200. */
+  readonly maxPageSize?: number;
+  /** Defaults to 200 characters. */
+  readonly maxSearchLength?: number;
+  /**
+   * Most values counted per facet; a facet with more lists its key in
+   * `facetCountsTruncated`. Defaults to 100.
+   */
+  readonly facetLimit?: number;
+}
+interface ListQuery<S extends string, F extends string> {
+  readonly q?: string;
+  readonly sort: S;
+  /** 1-based. Always 1 with cursor pagination. */
+  readonly page: number;
+  /** Cursor pagination: the `nextCursor` of the previous page. */
+  readonly after?: string;
+  readonly size: number;
+  readonly facets: { readonly [K in F]?: readonly string[]; };
+  /** The checked filter tree, without unfinished rules and empty groups. */
+  readonly filter?: FilterQuery;
+  /** The IANA time zone date filters resolve in, from `parse`'s options. */
+  readonly timeZone?: string;
+}
+/** Typed input (JSON APIs, actions, MCP tools). Everything is optional. */
+interface ListQueryInput<S extends string, F extends string> {
+  readonly q?: string;
+  readonly sort?: S;
+  readonly page?: number;
+  readonly after?: string;
+  readonly size?: number;
+  readonly facets?: { readonly [K in F]?: readonly string[]; };
+  readonly filter?: FilterQuery;
+}
+/** URL input: `URLSearchParams` or a Next.js `searchParams` record. */
+type ListSearchParams = URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
+type ListParseResult<S extends string, F extends string> = {
+  readonly ok: true;
+  readonly value: ListQuery<S, F>;
+  readonly issues?: undefined;
+} | {
+  readonly ok: false;
+  readonly value?: undefined;
+  readonly issues: readonly ValidationIssue[];
+};
+interface ParserSpec<V> {
+  parse(value: string): V | null;
+  serialize(value: V): string;
+  /** Equality for object values, which nuqs uses to skip URL updates. */
+  eq?(a: V, b: V): boolean;
+}
+interface OpenApiParameter {
+  readonly name: string;
+  readonly in: "query";
+  readonly required: false;
+  readonly description: string;
+  readonly schema: Readonly<Record<string, unknown>>;
+  readonly style?: "form";
+  readonly explode?: boolean;
+}
+interface ListParseOptions {
+  /** IANA time zone that date filters resolve in, such as the request's. Defaults to `UTC`. */
+  readonly timeZone?: string;
+}
+interface FacetInfo {
+  readonly key: string;
+  readonly column: string;
+  readonly nullable: boolean;
+  /** Allowed values when the column is an enum or CHECK union. */
+  readonly values?: readonly string[];
+}
+/** Rows per facet value, keyed by facet and then by value (`UNSET` for empty). */
+type FacetCounts<F extends string> = { readonly [K in F]: Readonly<Record<string, number>>; };
+/** A page of a list; with `facetCounts: true`, also the counts per facet value. */
+type ListPage<R, F extends string, C extends boolean, P extends ListPagination = "cursor"> = ([P] extends ["cursor"] ? CursorPage<R> : OffsetPage<R>) & ([C] extends [true] ? FacetCountFields<F> : [C] extends [false] ? unknown : Partial<FacetCountFields<F>>);
+/** The facet fields of a page with `facetCounts: true`. */
+interface FacetCountFields<F extends string> {
+  readonly facetCounts: FacetCounts<F>;
+  /** Facets with more values than `facetLimit`, whose counts are cut. */
+  readonly facetCountsTruncated: readonly F[];
+}
+interface ListDefinition<M extends AnyModels, T extends TableKey<M>, E, S extends string, F extends string, C extends boolean = false, P extends ListPagination = "cursor"> {
+  readonly table: T;
+  readonly pagination: P;
+  readonly defaults: ListQuery<S, F>;
+  readonly facets: readonly FacetInfo[];
+  /** The checked `filters` config. */
+  readonly filters: readonly FilterFieldInfo[];
+  /** Validates typed input or URL params. Also a Standard Schema (`schema`). */
+  parse(input: ListQueryInput<S, F> | ListSearchParams | undefined, options?: ListParseOptions): ListParseResult<S, F>;
+  /** `FilterField` objects for ReUI Filters, with labels you can translate. */
+  filterFields(labels?: FilterFieldLabels): FilterField[];
+  /** The repository `where` of the query's filter tree; relative dates resolve against `clock.now`. */
+  filterWhere(query: ListQuery<S, F>, clock?: Pick<FilterClock, "now">): WhereInput<M, T> | undefined;
+  readonly schema: StandardSchemaV1<ListQueryInput<S, F> | ListSearchParams | undefined, ListQuery<S, F>>;
+  /** URL params, leaving out defaults. */
+  toSearchParams(query: Partial<ListQuery<S, F>>): URLSearchParams;
+  /** `{ parse, serialize }` per URL key, for routers and nuqs (`list.nuqs(createParser)`). */
+  readonly parsers: ListParsers<S, F>;
+  nuqs<P>(createParser: (spec: ParserSpec<unknown>) => P): { readonly [K in keyof ListParsers<S, F>]: P; };
+  /** Repository arguments: `where`, `orderBy`, `size`, and `page` and `count` or `after`. */
+  args(query: ListQuery<S, F>, clock?: Pick<FilterClock, "now">): [P] extends ["cursor"] ? CursorPageArgs<M, T> : OffsetPageArgs<M, T>;
+  /**
+   * Runs the list against a table, merging your `select`, `include`, `where`
+   * and `count`. One request, plus one per facet for `facetCounts`, always one wave.
+   */
+  run<const A extends ListExtra<M, T> & FindExt<E, M, T>>(db: { readonly [K in T]: RepositoryOf<M, K, E>; }, query: ListQuery<S, F>, extra?: A): AsyncResult<ListPage<Payload<M, T, A>, F, C, P>>;
+  /** OpenAPI 3.1 query parameters. */
+  readonly openapi: readonly OpenApiParameter[];
+  /** JSON Schema of the typed input, e.g. for MCP tool arguments. */
+  readonly jsonSchema: Readonly<Record<string, unknown>>;
+}
+interface ListExtra<M extends AnyModels, T extends keyof M> {
+  readonly select?: SelectArg<M, T>;
+  readonly include?: IncludeArg<M, T>;
+  readonly where?: WhereInput<M, T>;
+  /** Overrides the config's `count` for this run. */
+  readonly count?: CountMode;
+}
+type ListParsers<S extends string, F extends string> = {
+  readonly q: ParserSpec<string>;
+  readonly sort: ParserSpec<S>;
+  readonly page: ParserSpec<number>;
+  readonly after: ParserSpec<string>;
+  readonly size: ParserSpec<number>;
+  /** The filter tree as base64url JSON, when the list has `filters`; `parse` checks it. */
+  readonly filter?: ParserSpec<FilterQuery>;
+} & { readonly [K in F]: ParserSpec<readonly string[]>; };
+/**
+ * A reusable list endpoint for one table: search, facets, sorts and
+ * pagination, validated from URL params or typed input, with URL parsers,
+ * OpenAPI parameters and a JSON Schema derived from the same definition.
+ *
+ * ```ts
+ * export const customerList = defineListQuery(betterSupabase, 'customers', {
+ *   search: ['name', 'kvk'],
+ *   facets: { status: 'status' },
+ *   sorts: { name: { name: 'asc' }, newest: [{ createdAt: 'desc' }, { id: 'asc' }] },
+ *   defaultSort: 'newest',
+ * });
+ * ```
+ */
+declare function defineListQuery<M extends AnyModels, D, Fn extends AnyFunctions, E, T extends TableKey<M>, const S extends string, const F extends string = never, const C extends boolean = false, const P extends ListPagination = "cursor">(betterSupabase: BetterSupabase<M, D, Fn, E>, table: T, config: ListQueryConfig<M, T, S, F, C, P>): ListDefinition<M, T, E, S, F, C, P>;
+//#endregion
+export { UNSET as _, ListExtra as a, ListParseOptions as c, ListQuery as d, ListQueryConfig as f, ParserSpec as g, OpenApiParameter as h, ListDefinition as i, ListParseResult as l, ListSearchParams as m, FacetCounts as n, ListPage as o, ListQueryInput as p, FacetInfo as r, ListPagination as s, FacetCountFields as t, ListParsers as u, defineListQuery as v };

package/dist/live-DwDreq1n.js

@@ -0,0 +1,239 @@
+import { t as refreshRealtimeAuth } from "./auth-CdBKt0CS.js";
+import { REALTIME_SUBSCRIBE_STATES } from "@supabase/supabase-js";
+//#region src/realtime/live.ts
+/**
+* Topic a `realtime-tables` trigger broadcasts on:
+* `bs:t:<schema>.<table>[:<tenant>]`, or `bs:t:<schema>.<table>:u:<user>`
+* for a `realtime.users` table.
+*/
+function liveTopic(meta, table, tenant, user) {
+	const found = meta.tables[table];
+	if (!found) throw new TypeError(`better-supabase: unknown table "${table}"`);
+	const base = `bs:t:${found.schema}.${found.name}`;
+	if (meta.realtime?.[table]?.user) {
+		if (user === void 0) throw new TypeError(`better-supabase: "${table}" broadcasts per user; pass \`user\` to watch it`);
+		return `${base}:u:${user}`;
+	}
+	if (!meta.realtime?.[table]?.tenant) return base;
+	if (tenant === void 0) throw new TypeError(`better-supabase: "${table}" broadcasts per tenant; pass \`tenant\` to watch it`);
+	return `${base}:${tenant}`;
+}
+const channels = /* @__PURE__ */ new WeakMap();
+function join(client, topic, listener, onStatus) {
+	let byTopic = channels.get(client);
+	if (!byTopic) {
+		byTopic = /* @__PURE__ */ new Map();
+		channels.set(client, byTopic);
+	}
+	let shared = byTopic.get(topic);
+	if (!shared) {
+		const channel = client.channel(topic, { config: { private: true } });
+		const listeners = /* @__PURE__ */ new Set();
+		const statuses = /* @__PURE__ */ new Set();
+		channel.on("broadcast", { event: "change" }, () => {
+			for (const notify of listeners) notify();
+		});
+		let joined = false;
+		const evict = () => {
+			if (byTopic.get(topic) !== entry) return;
+			byTopic.delete(topic);
+			client.removeChannel(channel);
+		};
+		const ready = (async () => {
+			await refreshRealtimeAuth(client);
+			await new Promise((resolve, reject) => {
+				channel.subscribe((status, error) => {
+					switch (status) {
+						case REALTIME_SUBSCRIBE_STATES.SUBSCRIBED:
+							if (joined) {
+								for (const notify of listeners) notify();
+								for (const notify of statuses) notify("subscribed");
+							}
+							joined = true;
+							resolve();
+							return;
+						case REALTIME_SUBSCRIBE_STATES.CLOSED:
+							resolve();
+							return;
+						case REALTIME_SUBSCRIBE_STATES.CHANNEL_ERROR:
+						case REALTIME_SUBSCRIBE_STATES.TIMED_OUT: {
+							const failure = error ?? /* @__PURE__ */ new Error(`Realtime ${status.toLowerCase()} on ${topic}`);
+							if (joined) for (const notify of statuses) notify("error", failure);
+							reject(failure);
+							if (!joined) evict();
+							return;
+						}
+						default: reject(/* @__PURE__ */ new Error(`Unknown realtime status ${String(status)}`));
+					}
+				});
+			});
+		})();
+		ready.catch(() => void 0);
+		const entry = {
+			channel,
+			listeners,
+			statuses,
+			ready
+		};
+		shared = entry;
+		byTopic.set(topic, entry);
+	}
+	const current = shared;
+	current.listeners.add(listener);
+	if (onStatus) current.statuses.add(onStatus);
+	let left = false;
+	return {
+		ready: current.ready,
+		leave: async () => {
+			if (left) return;
+			left = true;
+			current.listeners.delete(listener);
+			if (onStatus) current.statuses.delete(onStatus);
+			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);
+		}
+	};
+}
+/**
+* Calls `onChange` when a table the spec reads changes, so you can refetch.
+* Needs the `realtime-tables` SQL module and the tables in
+* `realtime.tables`. Live queries on the same client share one channel per
+* table, so any number of them can run at once.
+*
+* ```ts
+* using live = liveQuery(betterSupabase, supabase, spec, { onChange: () => refetch() });
+* ```
+*/
+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;
+	let closed = false;
+	const flush = () => {
+		timer = void 0;
+		if (closed || changed.size === 0) return;
+		const batch = [...changed];
+		changed.clear();
+		options.onChange(batch);
+	};
+	const onTableChange = (table) => () => {
+		changed.add(table);
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(flush, debounceMs);
+	};
+	const failed = /* @__PURE__ */ new Set();
+	const onChannelStatus = (topic) => (status, error) => {
+		if (closed) return;
+		if (status === "error") failed.add(topic);
+		else failed.delete(topic);
+		if (status === "error") options.onStatus?.("error", error);
+		else if (failed.size === 0) options.onStatus?.("subscribed");
+	};
+	const topics = tables.map((table) => ({
+		table,
+		topic: liveTopic(betterSupabase.meta, table, options.tenant, options.user)
+	}));
+	const joinAll = () => topics.map(({ table, topic }) => join(client, topic, onTableChange(table), onChannelStatus(topic)));
+	let memberships = joinAll();
+	let retryTimer;
+	let delay = 1e3;
+	const settle = (attempt) => Promise.all(attempt.map((member) => member.ready)).then(() => {
+		if (!closed && tables.length > 0) options.onStatus?.("subscribed");
+	}, (cause) => {
+		const error = cause instanceof Error ? cause : new Error(String(cause));
+		if (!closed) {
+			options.onStatus?.("error", error);
+			if (options.retry !== false) scheduleRetry(attempt);
+		}
+		throw error;
+	});
+	const scheduleRetry = (attempt) => {
+		retryTimer = setTimeout(() => {
+			retryTimer = void 0;
+			if (closed || attempt !== memberships) return;
+			Promise.all(attempt.map((member) => member.leave()));
+			memberships = joinAll();
+			options.onStatus?.("joining");
+			settle(memberships).then(() => {
+				if (closed) return;
+				for (const table of tables) changed.add(table);
+				flush();
+			}, () => void 0);
+		}, delay);
+		delay = Math.min(delay * 2, 3e4);
+	};
+	options.onStatus?.(tables.length === 0 ? "closed" : "joining");
+	const ready = settle(memberships);
+	ready.catch(() => void 0);
+	const unsubscribe = async () => {
+		if (closed) return;
+		closed = true;
+		if (timer !== void 0) clearTimeout(timer);
+		if (retryTimer !== void 0) clearTimeout(retryTimer);
+		await Promise.all(memberships.map((member) => member.leave()));
+		options.onStatus?.("closed");
+	};
+	return {
+		tables,
+		unwatched,
+		ready,
+		unsubscribe,
+		[Symbol.dispose]: () => void unsubscribe(),
+		[Symbol.asyncDispose]: unsubscribe
+	};
+}
+/**
+* Keeps a count current: runs the `count` spec (a HEAD request) now, after
+* each debounced change to a table it reads, and after the channel rejoins.
+* Responses that arrive out of order are dropped.
+*
+* ```ts
+* using live = liveCount(betterSupabase, supabase, db, betterSupabase.spec.notes.count(), {
+*   onCount: (count) => render(count),
+* });
+* ```
+*/
+function liveCount(betterSupabase, client, db, spec, options) {
+	let latest = 0;
+	let closed = false;
+	const refetch = () => {
+		const call = ++latest;
+		Promise.resolve(db.$run(spec)).then((result) => {
+			if (closed || call !== latest) return;
+			if (result.ok) options.onCount(result.data);
+			else options.onError?.(result.error);
+		});
+	};
+	const live = liveQuery(betterSupabase, client, spec, {
+		onChange: refetch,
+		...options.tenant === void 0 ? {} : { tenant: options.tenant },
+		...options.user === void 0 ? {} : { user: options.user },
+		...options.debounceMs === void 0 ? {} : { debounceMs: options.debounceMs },
+		...options.onStatus ? { onStatus: options.onStatus } : {}
+	});
+	if (options.immediate ?? true) refetch();
+	const since = options.since;
+	if (since !== void 0) live.ready.then(() => {
+		if (!closed && Date.now() - since > 1e3) refetch();
+	}, () => void 0);
+	const unsubscribe = async () => {
+		closed = true;
+		await live.unsubscribe();
+	};
+	return {
+		...live,
+		unsubscribe,
+		[Symbol.dispose]: () => void unsubscribe(),
+		[Symbol.asyncDispose]: unsubscribe
+	};
+}
+//#endregion
+export { liveQuery as n, liveTopic as r, liveCount as t };

package/dist/mcp/index.d.ts

@@ -1,13 +1,29 @@
-import { L as TableKey, a as AnyModels, i as AnyFunctions } from "../types-6BdhkmZe.js";
-import { t as BetterSupabase } from "../define-CJJkkr1-.js";
-import { i as ServerContext, o as ServerOptions, t as BetterServer } from "../server-Bh0EVSwU.js";
-import { r as GuardOptions } from "../respond-DprrgyXX.js";
-import { i as ResourceOperation } from "../index-Bxih3l0u.js";
-import { a as ResourceRouteOptions } from "../resource-IPS5xi9q.js";
+import { a as AnyModels, i as AnyFunctions, z as TableKey } from "../types-YfwpIE-d.js";
+import { t as OperationTable } from "../operations-C9-UcReN.js";
+import { D as ResourceOperation } from "../model-lUafmeBQ.js";
+import { s as PermissionRef, t as AnyAuthorizer } from "../authorizer-eiOjo-3l.js";
+import { t as BetterSupabase } from "../define-DxHHbNEb.js";
+import { i as ServerContext, s as ServerOptions, t as BetterServer } from "../server-types-OohhIQb2.js";
+import { r as GuardOptions } from "../respond-C7I8kLK_.js";
+import { l as ResourceRouteOptions } from "../resource-types-D2vEQVXI.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/mcp/json-rpc.d.ts
+/** A JSON object. */
+type Json = Readonly<Record<string, unknown>>;
+//#endregion
+//#region src/mcp/dialect.d.ts
+/** The JSON Schema dialect of tool schemas, which depends on the protocol revision. */
+type ToolSchemaTarget = "draft-2020-12" | "draft-07";
+//#endregion
+//#region src/mcp/permissions.d.ts
+/** `McpOptions.requiredRoles`: the roles, or the roles and the claim to read. */
+type RequiredRoles = readonly string[] | {
+  readonly roles: readonly string[];
+  readonly claim?: string;
+};
+//#endregion
 //#region src/mcp/mcp.d.ts
 export declare const MCP_PROTOCOL_VERSION: string;
-type Json = Readonly<Record<string, unknown>>;
 /** MCP tool annotations (hints for clients, not guarantees). */
 interface ToolAnnotations {
   readonly title?: string;
@@ -31,10 +47,19 @@ interface ToolContext<M extends AnyModels, F extends AnyFunctions, E, C = unknow
 }
 interface McpTool<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> {
   readonly info: ToolInfo;
+  /**
+   * The input schema in another dialect, for clients on an older protocol
+   * revision. Without it, `info.inputSchema` is rewritten.
+   */
+  readonly inputSchemaFor?: (target: ToolSchemaTarget) => Json | undefined;
   /** 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;
+  /** Checked by the authorizer on every call; callers it denies don't see the tool. */
+  readonly permission?: unknown;
+  /** The provider operation the tool checks, in place of `mcp.tool.<name>`. */
+  readonly operation?: string;
   run(args: never, ctx: ToolContext<M, F, E, C, P>): unknown;
 }
 /** What the `authorize` and `visible` hooks see of a tool. */
@@ -52,7 +77,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, C = unknown, P = unknown> {
+interface ToolDefinition<M extends AnyModels, F extends AnyFunctions, E, I, C = unknown, P = unknown, Ref = unknown> {
   readonly name: string;
   readonly title?: string;
   readonly description: string;
@@ -63,13 +88,30 @@ interface ToolDefinition<M extends AnyModels, F extends AnyFunctions, E, I, C =
   readonly input?: StandardSchemaV1<unknown, I>;
   readonly inputSchema?: Json;
   readonly outputSchema?: Json;
+  /**
+   * The dialect `input` converts to for `ToolInfo` and the `tools` list.
+   * Defaults to `draft-2020-12`. `tools/list` converts again for clients on
+   * 2025-06-18 and earlier, which get draft-07.
+   */
+  readonly jsonSchemaTarget?: ToolSchemaTarget;
   readonly annotations?: ToolAnnotations;
   /** Opaque data for the `authorize` and `visible` hooks. Never sent to clients. */
   readonly meta?: unknown;
+  /**
+   * Checked by the authorizer after the arguments are validated, with the
+   * tool as the resource (`mcp_tool`). `tools/list` hides the tool from
+   * callers it denies.
+   */
+  readonly permission?: Ref;
+  /**
+   * The provider operation whose permission the tool checks, in place of
+   * `mcp.tool.<name>` (`invoices.void`).
+   */
+  readonly operation?: string;
   run(args: I, ctx: ToolContext<M, F, E, C, P>): unknown;
 }
 /** 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> & {
+type ToolResourceOptions<M extends AnyModels, T extends TableKey<M>, Ref = string> = ResourceRouteOptions<M, T, Ref> & {
   /**
    * Opaque data per operation, e.g. a permission, passed to
    * `authorize` and `visible` as the table tool's `meta`. Never sent to
@@ -77,16 +119,22 @@ type ToolResourceOptions<M extends AnyModels, T extends TableKey<M>> = ResourceR
    */
   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"> {
+type ToolResources<M extends AnyModels, Ref = string> = { readonly [T in TableKey<M>]?: ToolResourceOptions<M, T, Ref> | true; };
+interface McpOptions<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, Ref = string> extends ServerOptions, Omit<GuardOptions, "scopes"> {
   readonly name: string;
   readonly version: string;
   readonly title?: string;
   /** Sent to clients on `initialize`, e.g. how the tools fit together. */
   readonly instructions?: string;
   /** Tables exposed as tools: `<table>_list`, `_get`, `_create`, `_update`, `_delete`. */
-  readonly resources?: ToolResources<M>;
+  readonly resources?: ToolResources<M, Ref>;
   readonly tools?: readonly McpTool<M, F, E, C, P>[];
+  /**
+   * The authorization provider's operations (`authorization.operations` in
+   * the config). A tool's `mcp.tool.<name>` entry replaces its `permission`,
+   * so the provider decides what each tool needs.
+   */
+  readonly operations?: OperationTable;
   /**
    * Canonical URL of this MCP server (RFC 9728 `resource`). Defaults to the
    * request URL without query; on Supabase Edge Functions, to the public
@@ -118,10 +166,7 @@ interface McpOptions<M extends AnyModels, F extends AnyFunctions, E, C = unknown
    * requiredRoles: { roles: ['admin', 'support'], claim: 'app_metadata.roles' }
    * ```
    */
-  readonly requiredRoles?: readonly string[] | {
-    readonly roles: readonly string[];
-    readonly claim?: string;
-  };
+  readonly requiredRoles?: RequiredRoles;
   /** Origins allowed to call the server (DNS rebinding protection). Defaults to any. */
   readonly allowedOrigins?: readonly string[];
   /**
@@ -159,7 +204,7 @@ interface McpOptions<M extends AnyModels, F extends AnyFunctions, E, C = unknown
    */
   readonly visible?: (ctx: ToolContext<M, F, E, C, P>, tool: ToolRef) => boolean | Promise<boolean>;
 }
-interface BetterMcp<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends BetterServer<M, F, E, C, P> {
+interface BetterMcp<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, Ref = string> 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). */
@@ -168,7 +213,7 @@ interface BetterMcp<M extends AnyModels, F extends AnyFunctions, E, C = unknown,
   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, C, P>): this;
+  tool<I = Record<string, unknown>>(definition: ToolDefinition<M, F, E, I, C, P, Ref>): this;
   /** Calls a tool directly, e.g. from tests or another transport. */
   call(name: string, args: unknown, ctx: ToolContext<M, F, E, C, P>): Promise<ToolResult>;
 }
@@ -181,13 +226,15 @@ 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>, C = unknown, P = unknown>(definition: ToolDefinition<M, F, E, I, C, P>): McpTool<M, F, E, C, P>;
+export declare function defineTool<M extends AnyModels, F extends AnyFunctions, E, I = Record<string, unknown>, C = unknown, P = unknown, Ref = unknown>(definition: ToolDefinition<M, F, E, I, C, P, Ref>): 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, 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>;
+export declare function createMcp<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown, A extends AnyAuthorizer | undefined = undefined>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, options: McpOptions<M, F, E, C, P, PermissionRef<A>> & {
+  readonly authorizer?: A;
+}): BetterMcp<M, F, E, C, P, PermissionRef<A>>;
 //#endregion
 export type { BetterMcp, GuardOptions, McpOptions, McpTool, ResourceRouteOptions, ToolAnnotations, ToolContext, ToolDecision, ToolDefinition, ToolInfo, ToolRef, ToolResourceOptions, ToolResources, ToolResult };