better-supabase 0.1.0 → 0.3.0

package/dist/jobs/index.js

@@ -1,10 +1,12 @@
 import { c as mapDbError, n as dbError, t as DbException } from "../errors-Bl3rkOzo.js";
+import { n as nowInstant } from "../temporal-BwshQk0W.js";
+import { t as temporal } from "../temporal-required-CMxeSVPo.js";
 import { i as ok, n as err, o as toDbError, t as AsyncResult } from "../result-DWXatkd6.js";
 import { t as validate } from "../standard-FUi3Z3-7.js";
-import { a as problemResponse } from "../problem-DPu6Fh-t.js";
-import { t as fromPgError } from "../executor-Ceq60hPM.js";
-import { c as verifyWebhook } from "../webhooks-DbMTJJX2.js";
-//#region src/jobs/index.ts
+import { a as problemResponse } from "../problem-CGt1ADix.js";
+import { t as fromPgError } from "../executor-C57jx2pn.js";
+import { c as verifyWebhook } from "../webhooks-CAIFQSTM.js";
+//#region src/jobs/jobs.ts
 function run(fn) {
 	return AsyncResult.from(async () => {
 		try {
@@ -22,7 +24,10 @@ function workerId() {
 	return `worker-${crypto.randomUUID().slice(0, 8)}`;
 }
 const sleep = (ms, signal) => new Promise((resolve) => {
-	if (signal?.aborted) return resolve();
+	if (signal?.aborted) {
+		resolve();
+		return;
+	}
 	const timer = setTimeout(done, ms);
 	function done() {
 		clearTimeout(timer);
@@ -102,7 +107,7 @@ function postgrestTransport(client) {
 	const call = async (fn, args) => {
 		const { data, error } = await client.schema("pgmq_public").rpc(fn, args);
 		if (error) {
-			const message = typeof error === "object" && error !== null && "message" in error ? String(error.message) : String(error);
+			const message = typeof error === "object" && "message" in error ? String(error.message) : String(error);
 			throw new Error(`pgmq_public.${fn}: ${message}`, { cause: error });
 		}
 		return data;
@@ -149,7 +154,8 @@ function postgrestTransport(client) {
 		unschedule: () => sqlOnly("unschedule")
 	};
 }
-const toDate = (value) => value instanceof Date ? value : new Date(value);
+/** pgmq and the inbox return `timestamptz` as text over RPC and as `Date` from `pg`. */
+const toInstant = (value) => value instanceof Date ? temporal().Instant.fromEpochMilliseconds(value.getTime()) : temporal().Instant.from(value);
 function toJob(queue, row) {
 	const message = row.message ?? {};
 	return {
@@ -158,8 +164,8 @@ function toJob(queue, row) {
 		payload: message.payload,
 		attempts: row.attempts,
 		maxAttempts: message.max_attempts ?? 5,
-		enqueuedAt: toDate(row.enqueued_at),
-		visibleUntil: toDate(row.visible_until),
+		enqueuedAt: toInstant(row.enqueued_at),
+		visibleUntil: toInstant(row.visible_until),
 		lastError: message.last_error ?? null
 	};
 }
@@ -254,7 +260,7 @@ function createJobs(source, queues) {
 			return AsyncResult.from(async () => {
 				const valid = await validate(schemaOf(queue), payload, "payload");
 				if (!valid.ok) return valid;
-				const delay = enqueueOptions.delay ?? (enqueueOptions.runAt ? Math.max(0, Math.ceil((enqueueOptions.runAt.getTime() - Date.now()) / 1e3)) : 0);
+				const delay = enqueueOptions.delay ?? (enqueueOptions.runAt ? Math.max(0, Math.ceil((enqueueOptions.runAt.epochMilliseconds - nowInstant().epochMilliseconds) / 1e3)) : 0);
 				return run(() => transport.send(queue, valid.data, delay, enqueueOptions.maxAttempts ?? 5, enqueueOptions.dedupeKey));
 			});
 		},
@@ -435,7 +441,7 @@ function createInbox(sql, options) {
 						payload: row.payload,
 						headers: row.headers,
 						attempts: row.attempts,
-						receivedAt: toDate(row.received_at)
+						receivedAt: toInstant(row.received_at)
 					};
 					try {
 						const outcome = await handler(message);
@@ -458,7 +464,8 @@ function createInbox(sql, options) {
 /** The Stripe event sent when a customer's active entitlements change. */
 const ENTITLEMENTS_UPDATED = "entitlements.active_entitlement_summary.updated";
 function stripeCustomerOf(payload) {
-	const customer = (payload?.data?.object)?.customer;
+	if (typeof payload !== "object" || payload === null) return void 0;
+	const customer = (payload.data?.object)?.customer;
 	if (typeof customer === "string") return customer;
 	const id = customer?.id;
 	return typeof id === "string" ? id : void 0;

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

@@ -1,3 +1,4 @@
+import { t as isList } from "./guards-BnzDvFrz.js";
 //#region src/generators/shared.ts
 const INTEGER = /* @__PURE__ */ new Set([
 	"int2",
@@ -18,7 +19,8 @@ function scalarKind(column) {
 		values: column.enum
 	};
 	if (column.json) return { kind: "json" };
-	if (column.codec === "date") return { kind: "dateObject" };
+	if (column.codec === "instant") return { kind: "instant" };
+	if (column.codec === "plainDateTime") return { kind: "plainDateTime" };
 	if (column.codec === "bigint") return { kind: "bigint" };
 	if (column.codec === "string") return { kind: "string" };
 	if (column.type === "uuid") return { kind: "uuid" };
@@ -106,10 +108,14 @@ function scalar(kind) {
 			type: "string",
 			format: "date"
 		};
-		case "dateObject": return {
+		case "instant": return {
 			type: "string",
 			format: "date-time"
 		};
+		case "plainDateTime": return {
+			type: "string",
+			pattern: "^\\d{4}-\\d{2}-\\d{2}[T ]\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?$"
+		};
 		case "bigint": return {
 			type: "string",
 			pattern: "^-?\\d+$"
@@ -132,7 +138,7 @@ function property(plan) {
 	if (!plan.nullable) return schema;
 	if (Object.keys(schema).length === 0) return schema;
 	const { enum: values, ...rest } = schema;
-	if (Array.isArray(values)) return {
+	if (isList(values)) return {
 		...rest,
 		type: ["string", "null"],
 		enum: [...values, null]

package/dist/lint/index.js

@@ -16,7 +16,7 @@ function receiverName(node) {
 	return receiver.property.name;
 }
 /** Matches `order_items`, `orderItems` and `public.order_items` alike. */
-const tableKey = (name) => (name.split(".").at(-1) ?? name).replace(/_/g, "").toLowerCase();
+const tableKey = (name) => (name.split(".").at(-1) ?? name).replaceAll("_", "").toLowerCase();
 function keyName(property) {
 	if (property.computed) return void 0;
 	if (property.key.type === "Identifier") return property.key.name;

package/dist/list/index.d.ts

@@ -1,2 +1,2 @@
-import { a as ListPage, c as ListQuery, d as ListSearchParams, f as OpenApiParameter, h as defineListQuery, i as ListExtra, l as ListQueryConfig, m as UNSET, n as FacetInfo, o as ListParseResult, p as ParserSpec, r as ListDefinition, s as ListParsers, t as FacetCounts, u as ListQueryInput } from "../index-JXHBuS53.js";
-export { FacetCounts, FacetInfo, ListDefinition, ListExtra, ListPage, ListParseResult, ListParsers, ListQuery, ListQueryConfig, ListQueryInput, ListSearchParams, OpenApiParameter, ParserSpec, UNSET, defineListQuery };
+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";
+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

@@ -1,10 +1,11 @@
-//#region src/list/index.ts
+//#region src/list/list-query.ts
 /** Facet value meaning "not set": filters with `is null`. */
 const UNSET = "__unset__";
 const RESERVED = /* @__PURE__ */ new Set([
 	"q",
 	"sort",
 	"page",
+	"after",
 	"size"
 ]);
 function first(value) {
@@ -13,8 +14,9 @@ function first(value) {
 function all(value) {
 	return (typeof value === "string" ? [value] : [...value ?? []]).flatMap((entry) => entry.split(",")).map((entry) => entry.trim()).filter(Boolean);
 }
+const isParamValue = (value) => value === void 0 || typeof value === "string" || Array.isArray(value) && value.every((entry) => typeof entry === "string");
 function isSearchParams(value) {
-	return value instanceof URLSearchParams || !("facets" in value && typeof value.facets === "object");
+	return value instanceof URLSearchParams || !("facets" in value && typeof value.facets === "object") && Object.values(value).every(isParamValue);
 }
 function readRecord(input) {
 	if (!(input instanceof URLSearchParams)) return input;
@@ -47,6 +49,7 @@ function defineListQuery(sb, table, config) {
 	const pageSize = config.pageSize ?? 50;
 	const maxPageSize = config.maxPageSize ?? 200;
 	const maxSearch = config.maxSearchLength ?? 200;
+	const cursor = config.pagination === "cursor";
 	const sortKeys = Object.keys(config.sorts);
 	const facetEntries = Object.entries(config.facets ?? {});
 	for (const [key, column] of facetEntries) {
@@ -96,6 +99,18 @@ function defineListQuery(sb, table, config) {
 			message: "Must be a whole number of at least 1",
 			path: ["page"]
 		});
+		else if (cursor && page !== 1) issues.push({
+			message: "This list pages with `after`, not `page`",
+			path: ["page"]
+		});
+		let after;
+		if (raw.after !== void 0 && raw.after !== "") {
+			if (cursor && typeof raw.after === "string") after = raw.after;
+			else issues.push({
+				message: cursor ? "Must be text" : "This list pages with `page`, not `after`",
+				path: ["after"]
+			});
+		}
 		const size = raw.size === void 0 || raw.size === "" ? pageSize : toInt(raw.size);
 		if (size === void 0 || !Number.isInteger(size) || size < 1 || size > maxPageSize) issues.push({
 			message: `Must be a whole number from 1 to ${String(maxPageSize)}`,
@@ -121,6 +136,7 @@ function defineListQuery(sb, table, config) {
 				...q ? { q } : {},
 				sort,
 				page: page ?? 1,
+				...after ? { after } : {},
 				size: size ?? pageSize,
 				facets: facetValues
 			}
@@ -143,6 +159,7 @@ function defineListQuery(sb, table, config) {
 				q: first(record["q"]),
 				sort: first(record["sort"]),
 				page: first(record["page"]),
+				after: first(record["after"]),
 				size: first(record["size"]),
 				facets: facetValues
 			});
@@ -160,6 +177,7 @@ function defineListQuery(sb, table, config) {
 			q: typed.q,
 			sort: typed.sort,
 			page: typed.page,
+			after: typed.after,
 			size: typed.size,
 			facets: rawFacets
 		});
@@ -195,12 +213,15 @@ function defineListQuery(sb, table, config) {
 	}
 	function args(query) {
 		const filter = where(query);
+		const paging = cursor ? { after: query.after ?? null } : {
+			page: query.page,
+			count: config.count ?? "exact"
+		};
 		return {
 			...filter ? { where: filter } : {},
 			orderBy: config.sorts[query.sort],
-			page: query.page,
 			size: query.size,
-			count: config.count ?? "exact"
+			...paging
 		};
 	}
 	/** Whether a group's value passes the facet's selected values. */
@@ -249,6 +270,10 @@ function defineListQuery(sb, table, config) {
 			serialize: (value) => value
 		},
 		page: intParser,
+		after: {
+			parse: (value) => value || null,
+			serialize: (value) => value
+		},
 		size: intParser,
 		...Object.fromEntries(facets.map((facet) => [facet.key, listParser]))
 	};
@@ -261,8 +286,102 @@ function defineListQuery(sb, table, config) {
 		uniqueItems: true
 	});
 	const searchDescription = config.search ? Array.isArray(config.search) ? `Case-insensitive search in ${config.search.join(", ")}.` : "Full-text search (web search syntax)." : void 0;
+	const openapi = [
+		...searchDescription ? [{
+			name: "q",
+			in: "query",
+			required: false,
+			description: searchDescription,
+			schema: {
+				type: "string",
+				maxLength: maxSearch
+			}
+		}] : [],
+		{
+			name: "sort",
+			in: "query",
+			required: false,
+			description: `Ordering. Default \`${config.defaultSort}\`.`,
+			schema: {
+				type: "string",
+				enum: sortKeys,
+				default: config.defaultSort
+			}
+		},
+		cursor ? {
+			name: "after",
+			in: "query",
+			required: false,
+			description: "`nextCursor` of the previous page. Leave it out for the first page.",
+			schema: { type: "string" }
+		} : {
+			name: "page",
+			in: "query",
+			required: false,
+			description: "1-based page number.",
+			schema: {
+				type: "integer",
+				minimum: 1,
+				default: 1
+			}
+		},
+		{
+			name: "size",
+			in: "query",
+			required: false,
+			description: "Page size.",
+			schema: {
+				type: "integer",
+				minimum: 1,
+				maximum: maxPageSize,
+				default: pageSize
+			}
+		},
+		...facets.map((facet) => ({
+			name: facet.key,
+			in: "query",
+			required: false,
+			description: `Filter on ${facet.column}. Comma-separated; any value matches.${facet.nullable ? ` \`${UNSET}\` matches empty.` : ""}`,
+			schema: facetSchema(facet),
+			style: "form",
+			explode: false
+		}))
+	];
+	const jsonSchema = {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			...searchDescription ? { q: {
+				type: "string",
+				maxLength: maxSearch,
+				description: searchDescription
+			} } : {},
+			sort: {
+				type: "string",
+				enum: sortKeys,
+				default: config.defaultSort
+			},
+			...cursor ? { after: { type: "string" } } : { page: {
+				type: "integer",
+				minimum: 1,
+				default: 1
+			} },
+			size: {
+				type: "integer",
+				minimum: 1,
+				maximum: maxPageSize,
+				default: pageSize
+			},
+			...facets.length > 0 ? { facets: {
+				type: "object",
+				additionalProperties: false,
+				properties: Object.fromEntries(facets.map((facet) => [facet.key, facetSchema(facet)]))
+			} } : {}
+		}
+	};
 	return {
 		table,
+		pagination: config.pagination ?? "offset",
 		defaults,
 		facets,
 		parse,
@@ -279,7 +398,8 @@ function defineListQuery(sb, table, config) {
 			if (query.q) params.set("q", query.q);
 			if (query.sort && query.sort !== config.defaultSort) params.set("sort", query.sort);
 			if (query.page && query.page !== 1) params.set("page", String(query.page));
-			if (query.size && query.size !== pageSize) params.set("size", String(query.size));
+			if (query.after) params.set("after", query.after);
+			if (query.size !== void 0 && query.size > 0 && query.size !== pageSize) params.set("size", String(query.size));
 			for (const facet of facets) {
 				const values = query.facets?.[facet.key];
 				if (values && values.length > 0) params.set(facet.key, values.join(","));
@@ -297,7 +417,7 @@ function defineListQuery(sb, table, config) {
 			const page = repository.paginate({
 				...extra,
 				...base,
-				count: count ?? base["count"],
+				...cursor ? {} : { count: count ?? base["count"] },
 				...combined ? { where: combined } : {}
 			});
 			if (!config.facetCounts) return page;
@@ -317,93 +437,8 @@ function defineListQuery(sb, table, config) {
 				facetCounts: marginals(rows, query)
 			})));
 		},
-		openapi: [
-			...searchDescription ? [{
-				name: "q",
-				in: "query",
-				required: false,
-				description: searchDescription,
-				schema: {
-					type: "string",
-					maxLength: maxSearch
-				}
-			}] : [],
-			{
-				name: "sort",
-				in: "query",
-				required: false,
-				description: `Ordering. Default \`${config.defaultSort}\`.`,
-				schema: {
-					type: "string",
-					enum: sortKeys,
-					default: config.defaultSort
-				}
-			},
-			{
-				name: "page",
-				in: "query",
-				required: false,
-				description: "1-based page number.",
-				schema: {
-					type: "integer",
-					minimum: 1,
-					default: 1
-				}
-			},
-			{
-				name: "size",
-				in: "query",
-				required: false,
-				description: "Page size.",
-				schema: {
-					type: "integer",
-					minimum: 1,
-					maximum: maxPageSize,
-					default: pageSize
-				}
-			},
-			...facets.map((facet) => ({
-				name: facet.key,
-				in: "query",
-				required: false,
-				description: `Filter on ${facet.column}. Comma-separated; any value matches.${facet.nullable ? ` \`${UNSET}\` matches empty.` : ""}`,
-				schema: facetSchema(facet),
-				style: "form",
-				explode: false
-			}))
-		],
-		jsonSchema: {
-			type: "object",
-			additionalProperties: false,
-			properties: {
-				...searchDescription ? { q: {
-					type: "string",
-					maxLength: maxSearch,
-					description: searchDescription
-				} } : {},
-				sort: {
-					type: "string",
-					enum: sortKeys,
-					default: config.defaultSort
-				},
-				page: {
-					type: "integer",
-					minimum: 1,
-					default: 1
-				},
-				size: {
-					type: "integer",
-					minimum: 1,
-					maximum: maxPageSize,
-					default: pageSize
-				},
-				...facets.length > 0 ? { facets: {
-					type: "object",
-					additionalProperties: false,
-					properties: Object.fromEntries(facets.map((facet) => [facet.key, facetSchema(facet)]))
-				} } : {}
-			}
-		}
+		openapi,
+		jsonSchema
 	};
 }
 //#endregion

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

@@ -1,10 +1,11 @@
-import { E as SchemaMeta, k as TableKey, n as AnyModels, t as AnyFunctions, w as Row } from "./types-C2fslP1z.js";
-import { b as ValidationIssue, o as Result, p as DbError, t as AsyncResult } from "./result-CTkCZ6JA.js";
-import { Z as QuerySpec, t as BetterSupabase } from "./define-CTfWw-SS.js";
+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 { n as TemplateValues, t as TemplateParams } from "./template-mbvlysOo.js";
 import { RealtimeChannel, SupabaseClient } from "@supabase/supabase-js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
-//#region src/realtime/index.d.ts
+//#region src/realtime/topic.d.ts
 type EventSchemas = Readonly<Record<string, StandardSchemaV1>>;
 interface TopicOptions<E extends EventSchemas> {
   /** Name used for generated policies and functions. Defaults to the template's literal parts. */
@@ -15,7 +16,7 @@ interface TopicOptions<E extends EventSchemas> {
   readonly private?: boolean;
   /**
    * Tenant check for the generated policy. Defaults to `{orgId}` against
-   * `org_id` / `app_metadata.org_id` when the template has `{orgId}`.
+   * `tenant_id` / `app_metadata.tenant_id` when the template has `{orgId}`.
    */
   readonly tenant?: false | {
     readonly param?: string;
@@ -26,6 +27,23 @@ interface TopicOptions<E extends EventSchemas> {
   readonly owner?: false | {
     readonly param?: string;
   };
+  /**
+   * Authorize with PermDock's SQL helpers instead of the tenant claim:
+   * `permitted_<scope>_ids(receive)` on the scope segment (or
+   * `permdock_has` for `scope: 'global'`), and `send` for broadcasting.
+   *
+   * The helpers check role and scope only. Use this just for permissions
+   * whose grants have no row conditions beyond the scope: for a permission
+   * with row conditions (e.g. `authorId = principal.id`) every member of the
+   * scope could join. Pass `catalog` to refuse those keys here;
+   * `better-supabase doctor` (BS214) refuses them from the catalog file.
+   */
+  readonly permdock?: PermdockTopicPolicy;
+  /**
+   * PermDock's `permissions.catalog.json`. With it, a `permdock` policy
+   * naming a permission with `rowConditions: true` throws.
+   */
+  readonly catalog?: PermdockCatalog;
   /** Let clients broadcast on the topic, not only receive. Defaults to `false`. */
   readonly send?: boolean;
   /** Also authorize presence. Defaults to `false`. */
@@ -66,7 +84,10 @@ interface TriggerOptions<M extends AnyModels, T extends keyof M, P extends strin
   readonly values: { readonly [K in TemplateParams<P>]: Extract<keyof Row<M, T>, string>; };
   /** Defaults to all three. */
   readonly events?: readonly ("insert" | "update" | "delete")[];
-  /** Schema for the generated function. Defaults to `public`. */
+  /**
+   * Schema for the generated function. Defaults to `better_supabase`, which
+   * the Data API does not expose.
+   */
   readonly functionSchema?: string;
 }
 interface RowChange<R> {

package/dist/logger-glM28NVN.js

@@ -0,0 +1,21 @@
+//#region src/core/logger.ts
+const log = (method) => (message, fields) => {
+	if (fields === void 0) console[method](`better-supabase: ${message}`);
+	else console[method](`better-supabase: ${message}`, fields);
+};
+/** The default: `console`, with a `better-supabase:` prefix. */
+const consoleLogger = {
+	debug: log("debug"),
+	info: log("info"),
+	warn: log("warn"),
+	error: log("error")
+};
+const noop = () => {};
+const silentLogger = {
+	debug: noop,
+	info: noop,
+	warn: noop,
+	error: noop
+};
+//#endregion
+export { silentLogger as n, consoleLogger as t };

package/dist/mcp/index.d.ts

@@ -1,13 +1,13 @@
-import { k as TableKey, n as AnyModels, t as AnyFunctions } from "../types-C2fslP1z.js";
-import { t as BetterSupabase } from "../define-CTfWw-SS.js";
-import { d as ServerContext, f as ServerOptions, l as BetterServer, n as GuardOptions } from "../respond-PoTpy5DT.js";
-import { i as ResourceRouteOptions } from "../resource-SkPTRJDD.js";
+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 { StandardSchemaV1 } from "@standard-schema/spec";
-//#region src/mcp/index.d.ts
+//#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). */
-export interface ToolAnnotations {
+interface ToolAnnotations {
   readonly title?: string;
   readonly readOnlyHint?: boolean;
   readonly destructiveHint?: boolean;
@@ -15,7 +15,7 @@ export interface ToolAnnotations {
   readonly openWorldHint?: boolean;
 }
 /** A tool as listed by `tools/list`. */
-export interface ToolInfo {
+interface ToolInfo {
   readonly name: string;
   readonly title?: string;
   readonly description?: string;
@@ -23,17 +23,34 @@ export interface ToolInfo {
   readonly outputSchema?: Json;
   readonly annotations?: ToolAnnotations;
 }
-export interface ToolContext<M extends AnyModels, F extends AnyFunctions, E> extends ServerContext<M, F, E> {
+interface ToolContext<M extends AnyModels, F extends AnyFunctions, E> extends ServerContext<M, F, E> {
   readonly request: Request;
   readonly signal: AbortSignal;
 }
-export interface McpTool<M extends AnyModels, F extends AnyFunctions, E> {
+interface McpTool<M extends AnyModels, F extends AnyFunctions, E> {
   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;
 }
-export interface ToolDefinition<M extends AnyModels, F extends AnyFunctions, E, I> {
+/** 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. */
+  readonly meta: unknown;
+}
+/** The outcome of `authorize`. `scopes` turns a refusal into an OAuth challenge. */
+type ToolDecision = {
+  readonly allowed: true;
+} | {
+  readonly allowed: false;
+  readonly reason?: string;
+  /** 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> {
   readonly name: string;
   readonly title?: string;
   readonly description: string;
@@ -45,10 +62,12 @@ export interface ToolDefinition<M extends AnyModels, F extends AnyFunctions, E,
   readonly inputSchema?: Json;
   readonly outputSchema?: Json;
   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;
 }
-export type ToolResources<M extends AnyModels> = { readonly [T in TableKey<M>]?: ResourceRouteOptions<M, T> | true; };
-export interface McpOptions<M extends AnyModels, F extends AnyFunctions, E> extends ServerOptions, GuardOptions {
+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 {
   readonly name: string;
   readonly version: string;
   readonly title?: string;
@@ -64,14 +83,39 @@ export interface McpOptions<M extends AnyModels, F extends AnyFunctions, E> exte
   readonly resource?: string | ((request: Request) => string);
   /** Defaults to Supabase Auth of `env.url` (`<url>/auth/v1`). */
   readonly authorizationServers?: readonly string[];
+  /**
+   * Scopes the tools need, published as RFC 9728 `scopes_supported` and in
+   * `insufficient_scope` challenges. `offline_access` is left out: refresh
+   * tokens are between the client and the authorization server.
+   */
+  readonly scopes?: readonly string[];
   /** Origins allowed to call the server (DNS rebinding protection). Defaults to any. */
   readonly allowedOrigins?: readonly string[];
+  /**
+   * Hostnames the `Host` header may name, without the port (DNS rebinding
+   * protection). List the production, preview and local hosts. Defaults to any.
+   */
+  readonly allowedHosts?: readonly string[];
+  /** A page that explains how to connect, published as RFC 9728 `resource_documentation`. */
+  readonly resourceDocumentation?: string;
   /** Custom jsonb types, as in `createOpenApi`. */
   readonly json?: Readonly<Record<string, unknown>>;
   /** Include internal error messages in tool results. Defaults to `NODE_ENV === 'development'`. */
   readonly exposeErrors?: boolean;
+  /**
+   * Decides each `tools/call` after the arguments are validated and before
+   * `run`. `args` are the validated arguments (raw for table tools, which
+   * 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>;
+  /**
+   * 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>;
 }
-export interface BetterMcp<M extends AnyModels, F extends AnyFunctions, E> extends BetterServer<M, F, E> {
+interface BetterMcp<M extends AnyModels, F extends AnyFunctions, E> extends BetterServer<M, F, E> {
   /** 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). */
@@ -84,7 +128,7 @@ export interface BetterMcp<M extends AnyModels, F extends AnyFunctions, E> exten
   /** Calls a tool directly, e.g. from tests or another transport. */
   call(name: string, args: unknown, ctx: ToolContext<M, F, E>): Promise<ToolResult>;
 }
-export interface ToolResult {
+interface ToolResult {
   readonly content: readonly {
     readonly type: "text";
     readonly text: string;
@@ -102,4 +146,4 @@ export declare function defineTool<M extends AnyModels, F extends AnyFunctions,
  */
 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>;
 //#endregion
-export type { GuardOptions, ResourceRouteOptions };
+export type { BetterMcp, GuardOptions, McpOptions, McpTool, ResourceRouteOptions, ToolAnnotations, ToolContext, ToolDecision, ToolDefinition, ToolInfo, ToolRef, ToolResources, ToolResult };