better-supabase 0.14.0 → 0.15.0

package/dist/build-QitPVzzO.js

@@ -0,0 +1,2073 @@
+import { r as isPlainObject } from "./clone-CkG0-hlI.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { n as instanceProperty } from "./db-blocks-DJGbjIPz.js";
+import { s as problemType, t as PROBLEM_CONTENT_TYPE } from "./problem-Bf0cJ7tk.js";
+import { t as buildJsonSchema } from "./json-schema-Ca6gYbEP.js";
+import { r as dataschemaOf } from "./cloud-event-XsM53POL.js";
+import { r as planResource } from "./resource-DvgXqZB_.js";
+import { n as pageQuery, r as pageSchema } from "./resource-schemas-up6bKOUi.js";
+import { ROW_EVENT_TYPES } from "./events/index.js";
+import { t as topicStatus } from "./realtime-status-asHvhiOh.js";
+//#region src/spec/merge.ts
+/** Escapes a key for a JSON Pointer (RFC 6901). */
+function pointerToken(key) {
+	return key.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+/**
+* Deep merge: objects merge key by key, anything else (arrays included) is
+* replaced by the patch. `onConflict` hears each replaced leaf whose value
+* differs, with its JSON Pointer. Neither input is changed.
+*/
+function mergeJson(base, patch, onConflict, pointer = "") {
+	if (!isPlainObject(base) || !isPlainObject(patch)) {
+		if (onConflict && base !== void 0 && JSON.stringify(base) !== JSON.stringify(patch)) onConflict(pointer);
+		return patch;
+	}
+	const out = { ...base };
+	for (const [key, value] of Object.entries(patch)) out[key] = Object.hasOwn(base, key) ? mergeJson(base[key], value, onConflict, `${pointer}/${pointerToken(key)}`) : value;
+	return out;
+}
+//#endregion
+//#region src/spec/schemas.ts
+/** `customer_tags` to `CustomerTags`. */
+function pascal(value) {
+	return value.replaceAll(/(^|[_\-.\s])(\w)/g, (_, _sep, char) => char.toUpperCase());
+}
+const schemaRef = (name) => ({ $ref: `#/components/schemas/${name}` });
+const tableDefs = /* @__PURE__ */ new WeakMap();
+/**
+* The 2020-12 `$defs` for every table (`customersRow`, `customersInsert`),
+* built once per metadata object and JSON column config.
+*/
+function tableSchemas(meta, json = {}) {
+	let byJson = tableDefs.get(meta);
+	if (!byJson) {
+		byJson = /* @__PURE__ */ new Map();
+		tableDefs.set(meta, byJson);
+	}
+	const key = JSON.stringify(json);
+	let defs = byJson.get(key);
+	if (!defs) {
+		defs = buildJsonSchema({
+			meta,
+			config: { json }
+		})["$defs"];
+		byJson.set(key, defs);
+	}
+	return defs;
+}
+const converted = /* @__PURE__ */ new WeakMap();
+function nameOf(schema) {
+	const id = schema["$id"] ?? schema["id"];
+	if (typeof id !== "string" || id === "") return;
+	return (id.split(/[/#]/u).findLast((part) => part !== "") ?? id).replace(/\.(?:schema\.)?json$/u, "");
+}
+/**
+* Converts a Standard Schema through Standard JSON Schema (2020-12), or
+* `undefined` when the library does not implement it. The schema's `$id`, `id`
+* and `$schema` are lifted out: the id becomes the component name.
+*/
+function convertStandard(schema, direction) {
+	let cache = converted.get(schema);
+	if (!cache) {
+		cache = /* @__PURE__ */ new Map();
+		converted.set(schema, cache);
+	}
+	const hit = cache.get(direction);
+	if (hit !== void 0) return hit ?? void 0;
+	const convert = schema["~standard"].jsonSchema?.[direction];
+	if (typeof convert !== "function") {
+		cache.set(direction, null);
+		return;
+	}
+	const raw = convert({ target: "draft-2020-12" });
+	const name = nameOf(raw);
+	const { $schema: _schema, $id: _id, id: _plainId, ...rest } = raw;
+	const result = {
+		schema: rest,
+		...name ? { name } : {}
+	};
+	cache.set(direction, result);
+	return result;
+}
+//#endregion
+//#region src/spec/presets.ts
+/** JSON Schema for RFC 9457 Problem Details as better-supabase sends them. */
+const PROBLEM_SCHEMA = {
+	type: "object",
+	required: [
+		"type",
+		"title",
+		"status"
+	],
+	properties: {
+		type: {
+			type: "string",
+			format: "uri-reference",
+			examples: [problemType("not_found").type]
+		},
+		title: { type: "string" },
+		status: {
+			type: "integer",
+			minimum: 100,
+			maximum: 599
+		},
+		detail: { type: "string" },
+		instance: { type: "string" },
+		kind: { type: "string" },
+		code: { type: "string" },
+		hint: { type: "string" },
+		constraint: { type: "string" },
+		column: { type: "string" },
+		columns: {
+			type: "array",
+			items: { type: "string" }
+		},
+		required: {
+			type: "string",
+			enum: ["aal1", "aal2"]
+		},
+		scopes: {
+			type: "array",
+			items: { type: "string" }
+		},
+		permission: { type: "string" },
+		approval: {
+			type: "object",
+			required: ["id"],
+			properties: { id: { type: "string" } }
+		},
+		issues: {
+			type: "array",
+			items: {
+				type: "object",
+				required: ["message"],
+				properties: {
+					message: { type: "string" },
+					path: {
+						type: "array",
+						items: { type: ["string", "integer"] }
+					}
+				}
+			}
+		}
+	}
+};
+/** The default error responses: today's Problem Details answers, 400 to 422. */
+const DEFAULT_ERRORS = [
+	{
+		name: "BadRequest",
+		status: 400,
+		description: "The request is invalid."
+	},
+	{
+		name: "Unauthorized",
+		status: 401,
+		description: "Missing or invalid credentials."
+	},
+	{
+		name: "Forbidden",
+		status: 403,
+		description: "Row-level security or a plugin denied the request."
+	},
+	{
+		name: "NotFound",
+		status: 404,
+		description: "No row matches."
+	},
+	{
+		name: "Conflict",
+		status: 409,
+		description: "A unique or foreign key constraint failed."
+	},
+	{
+		name: "Unprocessable",
+		status: 422,
+		description: "Validation or a check constraint failed."
+	}
+];
+/** Name of the shared 403 response of operations that declare a permission. */
+const PERMISSION_DENIED = "PermissionDenied";
+const problem = (code, detail, extra = {}) => ({ value: {
+	...problemType("forbidden"),
+	status: 403,
+	kind: "forbidden",
+	code,
+	detail,
+	...extra
+} });
+/** The 403 of an operation with a permission, with one example per problem code. */
+function permissionDeniedResponse() {
+	return {
+		description: "The authorizer denied the permission (`PERMISSION_DENIED`), the token lacks an OAuth scope (`INSUFFICIENT_SCOPE`), the action needs an approval (`APPROVAL_REQUIRED`), or row-level security denied the request.",
+		content: { [PROBLEM_CONTENT_TYPE]: {
+			schema: schemaRef("Problem"),
+			examples: {
+				permissionDenied: {
+					summary: "PERMISSION_DENIED",
+					...problem("PERMISSION_DENIED", "Permission invoices.update is required", { permission: "invoices.update" })
+				},
+				insufficientScope: {
+					summary: "INSUFFICIENT_SCOPE",
+					...problem("INSUFFICIENT_SCOPE", "The token lacks a required scope", { scopes: ["invoices.update"] })
+				},
+				approvalRequired: {
+					summary: "APPROVAL_REQUIRED",
+					...problem("APPROVAL_REQUIRED", "invoices.update needs an approval", {
+						permission: "invoices.update",
+						approval: { id: "apr_123" }
+					})
+				}
+			}
+		} }
+	};
+}
+function errorResponse(error) {
+	return {
+		description: error.description,
+		content: { [PROBLEM_CONTENT_TYPE]: { schema: schemaRef("Problem") } }
+	};
+}
+/** The scheme name of the `oauth2` preset. */
+const OAUTH_SCHEME = "supabaseOAuth";
+/** Security schemes and top-level requirements for the presets. */
+function resolveSecurity(presets, supabaseUrl, oauthScopes = {}) {
+	const schemes = {};
+	const requirements = [];
+	for (const preset of presets) {
+		if (typeof preset === "object") {
+			schemes[preset.name] = preset.scheme;
+			requirements.push({ [preset.name]: preset.scopes ?? [] });
+			continue;
+		}
+		switch (preset) {
+			case "bearer":
+				schemes["supabaseJwt"] = {
+					type: "http",
+					scheme: "bearer",
+					bearerFormat: "JWT",
+					description: "A Supabase access token. Requests run as that user under row-level security."
+				};
+				requirements.push({ supabaseJwt: [] });
+				break;
+			case "oauth2": {
+				if (!supabaseUrl) throw new TypeError("better-supabase/spec: oauth2 security needs supabaseUrl");
+				const origin = supabaseUrl.replace(/\/$/, "");
+				const auth = `${origin}/auth/v1`;
+				schemes[OAUTH_SCHEME] = {
+					type: "oauth2",
+					description: "The Supabase OAuth 2.1 server.",
+					flows: { authorizationCode: {
+						authorizationUrl: `${auth}/oauth/authorize`,
+						tokenUrl: `${auth}/oauth/token`,
+						scopes: oauthScopes
+					} },
+					metadataUrl: `${origin}/.well-known/oauth-authorization-server/auth/v1`
+				};
+				requirements.push({ [OAUTH_SCHEME]: [] });
+				break;
+			}
+			case "apiKey":
+				schemes["supabaseApiKey"] = {
+					type: "apiKey",
+					name: "apikey",
+					in: "header",
+					description: "The project's publishable key."
+				};
+				requirements.push({ supabaseApiKey: [] });
+				break;
+			default: throw new TypeError(`Unknown security preset "${String(preset)}"`);
+		}
+	}
+	return {
+		schemes,
+		requirements
+	};
+}
+//#endregion
+//#region src/spec/build-resource.ts
+const METHODS = /* @__PURE__ */ new Set([
+	"get",
+	"put",
+	"post",
+	"patch",
+	"delete",
+	"head",
+	"options",
+	"trace",
+	"query"
+]);
+function isMethod(value) {
+	return METHODS.has(value);
+}
+/** The error statuses each operation can answer with. */
+const OPERATION_STATUSES = {
+	list: [
+		400,
+		401,
+		403
+	],
+	create: [
+		400,
+		401,
+		403,
+		409,
+		422
+	],
+	get: [
+		401,
+		403,
+		404
+	],
+	update: [
+		400,
+		401,
+		403,
+		404,
+		409,
+		422
+	],
+	delete: [
+		401,
+		403,
+		404,
+		409
+	]
+};
+/** The error statuses each contract verb can answer with. */
+const VERB_STATUSES$1 = {
+	page: [
+		400,
+		401,
+		403
+	],
+	count: [
+		400,
+		401,
+		403
+	],
+	aggregate: [
+		400,
+		401,
+		403
+	],
+	upsert: [
+		400,
+		401,
+		403,
+		409,
+		422
+	]
+};
+/**
+* Statuses an operation only documents when it can answer with them; other
+* errors apply everywhere.
+*/
+const SCOPED_STATUSES = /* @__PURE__ */ new Set([
+	400,
+	401,
+	403,
+	404,
+	409,
+	422
+]);
+const JSON_TYPE = "application/json";
+function pageParameters(cursor, maxPageSize) {
+	return pageQuery(cursor, maxPageSize).map((p) => ({
+		name: p.name,
+		in: "query",
+		required: false,
+		description: p.description,
+		schema: p.schema
+	}));
+}
+function isParameter(value) {
+	return isPlainObject(value) && typeof value["name"] === "string" && typeof value["in"] === "string" && isPlainObject(value["schema"]);
+}
+function isPlanCarrier(input) {
+	return typeof input === "object" && "plan" in input;
+}
+/**
+* `description` and `deprecated` from comments, read structurally so older
+* metadata still works.
+*/
+function docsOf(value) {
+	if (!value) return {};
+	const description = "description" in value ? value.description : void 0;
+	const deprecated = "deprecated" in value ? value.deprecated : void 0;
+	return {
+		...typeof description === "string" && description !== "" ? { description } : {},
+		...deprecated === true ? { deprecated: true } : {}
+	};
+}
+function jsonContent(schema) {
+	return { [JSON_TYPE]: { schema } };
+}
+function jsonResponse(schema, description) {
+	return {
+		description,
+		content: jsonContent(schema)
+	};
+}
+function mutableProperties(schema) {
+	const properties = schema["properties"];
+	if (!isPlainObject(properties)) return;
+	const copy = {};
+	for (const [key, value] of Object.entries(properties)) if (isPlainObject(value)) copy[key] = { ...value };
+	schema["properties"] = copy;
+	return copy;
+}
+function createBuildContext(meta, options) {
+	const prefix = options.extensionPrefix ?? "x-better-supabase-";
+	const diagnostics = [];
+	const report = (diagnostic) => {
+		diagnostics.push(diagnostic);
+	};
+	const base = (options.basePath ?? "").replace(/\/$/, "");
+	const globalErrors = options.errors ?? DEFAULT_ERRORS;
+	const schemas = { Problem: structuredClone(PROBLEM_SCHEMA) };
+	const responses = {};
+	for (const error of globalErrors) responses[error.name] = errorResponse(error);
+	const operations = [];
+	const tags = [...options.tags ?? []];
+	const served = /* @__PURE__ */ new Map();
+	const { authorizer } = options;
+	const addTag = (name, description) => {
+		if (tags.some((tag) => tag.name === name)) return;
+		tags.push({
+			name,
+			...description ? { description } : {}
+		});
+	};
+	const addComponent = (name, schema) => {
+		const existing = schemas[name];
+		if (existing && JSON.stringify(existing) !== JSON.stringify(schema)) {
+			report({
+				code: "component-conflict",
+				severity: "error",
+				message: `Two different schemas are named "${name}"; the first one is kept`,
+				pointer: `/components/schemas/${pointerToken(name)}`
+			});
+			return;
+		}
+		schemas[name] = schema;
+	};
+	const keyOf = (ref, where) => {
+		if (authorizer) try {
+			return authorizer.key(ref);
+		} catch {
+			report({
+				code: "permission-unresolved",
+				severity: "error",
+				message: `${where}: the authorizer has no key for this permission`
+			});
+			return;
+		}
+		if (typeof ref === "string") return ref;
+		report({
+			code: "permission-unresolved",
+			severity: "error",
+			message: `${where}: a permission that is not a string needs an authorizer`
+		});
+	};
+	const converted = (standard, direction, where) => {
+		const result = convertStandard(standard, direction);
+		if (!result) report({
+			code: "schema-unconvertible",
+			severity: "warning",
+			message: `${where}: the schema does not implement Standard JSON Schema, so the spec allows any value`
+		});
+		return result;
+	};
+	const schemaOf = (standard, direction, role, operationId) => {
+		const result = converted(standard, direction, `${operationId} ${role}`);
+		if (!result) return {};
+		const name = options.componentName ? options.componentName({
+			kind: "schema",
+			id: result.name,
+			schema: result.schema,
+			role,
+			operationId
+		}) : result.name;
+		if (!name) return structuredClone(result.schema);
+		addComponent(name, structuredClone(result.schema));
+		return schemaRef(name);
+	};
+	const objectParameters = (standard, location, where) => {
+		const result = converted(standard, "input", where);
+		const properties = result?.schema["properties"];
+		if (!result || !isPlainObject(properties)) return [];
+		const required = result.schema["required"];
+		const requiredNames = Array.isArray(required) ? required : [];
+		return Object.entries(properties).flatMap(([name, schema]) => {
+			if (!isPlainObject(schema)) return [];
+			const description = schema["description"];
+			return [{
+				name,
+				in: location,
+				required: location === "path" || requiredNames.includes(name),
+				...typeof description === "string" ? { description } : {},
+				schema: structuredClone(schema)
+			}];
+		});
+	};
+	const usedErrors = (errors, statuses, permission) => {
+		const out = {};
+		for (const error of errors) {
+			if (SCOPED_STATUSES.has(error.status) && !statuses.includes(error.status)) continue;
+			const status = String(error.status);
+			if (Object.hasOwn(out, status)) continue;
+			if (error.status === 403 && permission) continue;
+			responses[error.name] ??= errorResponse(error);
+			out[status] = { ref: error.name };
+		}
+		if (permission) {
+			responses[PERMISSION_DENIED] ??= permissionDeniedResponse();
+			out["403"] = { ref: PERMISSION_DENIED };
+		}
+		return out;
+	};
+	const extendFor = (extend, name) => {
+		if (!extend) return;
+		const all = extend["*"];
+		const own = extend[name];
+		if (!all && !own) return;
+		return mergeJson(all ?? {}, own ?? {});
+	};
+	return {
+		meta,
+		options,
+		prefix,
+		base,
+		globalErrors,
+		diagnostics,
+		schemas,
+		responses,
+		operations,
+		tags,
+		served,
+		report,
+		addTag,
+		addComponent,
+		keyOf,
+		schemaOf,
+		objectParameters,
+		usedErrors,
+		extendFor
+	};
+}
+function resourceScope(ctx, key, input) {
+	const { meta, options, prefix, base, globalErrors, operations, served, report, addTag, addComponent, keyOf, schemaOf, usedErrors, extendFor } = ctx;
+	const { authorizer } = options;
+	let plan;
+	if (isPlanCarrier(input)) plan = input.plan;
+	else {
+		if (!meta.tables[key]) throw new TypeError(`better-supabase/spec: unknown table "${key}"`);
+		plan = planResource(meta, key, input === true ? {} : input, authorizer);
+	}
+	const tableKey = plan.table;
+	const table = plan.meta;
+	const description = plan.description;
+	const name = pascal(tableKey);
+	const tableDocs = docsOf(table);
+	const defs = tableSchemas(meta, options.json ?? {});
+	const componentFor = (variant) => {
+		const defaultName = `${name}${variant}`;
+		return options.componentName?.({
+			kind: "table",
+			table: tableKey,
+			variant,
+			defaultName
+		}) ?? defaultName;
+	};
+	const components = {};
+	for (const variant of [
+		"Row",
+		"Insert",
+		"Update"
+	]) {
+		const def = defs[`${tableKey}${variant}`];
+		if (!def) continue;
+		const schema = structuredClone(def);
+		if (tableDocs.description && schema["description"] === void 0) schema["description"] = tableDocs.description;
+		if (tableDocs.deprecated) schema["deprecated"] = true;
+		const properties = mutableProperties(schema);
+		for (const [column, property] of Object.entries(properties ?? {})) {
+			const docs = docsOf(table.columns[column]);
+			if (docs.description && property["description"] === void 0) property["description"] = docs.description;
+			if (docs.deprecated) property["deprecated"] = true;
+		}
+		const examples = options.examples?.[tableKey];
+		if (variant === "Row" && examples && examples.length > 0) schema["examples"] = structuredClone(examples);
+		const componentName = componentFor(variant);
+		components[variant] = componentName;
+		addComponent(componentName, schema);
+	}
+	const rowName = components.Row ?? componentFor("Row");
+	const cursor = plan.pagination === "cursor";
+	const pageName = componentFor("Page");
+	addComponent(pageName, pageSchema(schemaRef(rowName), cursor));
+	const tag = description.tag ?? tableKey;
+	addTag(tag, description.description ?? tableDocs.description);
+	const collection = `${base}${description.path ?? `/${tableKey}`}`;
+	const keyParam = plan.keyParam;
+	const rowProperties = defs[`${tableKey}Row`]?.["properties"];
+	const keySchema = keyParam && isPlainObject(rowProperties) ? rowProperties[keyParam] : void 0;
+	const idParameter = keyParam ? {
+		name: keyParam,
+		in: "path",
+		required: true,
+		schema: isPlainObject(keySchema) ? structuredClone(keySchema) : { type: "string" }
+	} : void 0;
+	const item = keyParam ? `${collection}/{${keyParam}}` : void 0;
+	const errors = description.errors ?? globalErrors;
+	const servedTable = {
+		table,
+		components,
+		operations: []
+	};
+	served.set(tableKey, servedTable);
+	const names = /* @__PURE__ */ new Set([
+		...plan.operations,
+		...plan.verbs,
+		...plan.actions.map((action) => action.name)
+	]);
+	for (const extendKey of Object.keys(description.extend ?? {})) if (extendKey !== "*" && !names.has(extendKey)) report({
+		code: "extend-unknown",
+		severity: "warning",
+		message: `${tableKey}.extend.${extendKey} names no operation or action of the resource`
+	});
+	const add = (opName, source, method, path, fields) => {
+		const defaultId = `${opName}${name}`;
+		const id = options.operationId?.({
+			source,
+			method,
+			path,
+			defaultId
+		}) ?? defaultId;
+		const ref = plan.permissions[opName];
+		const permission = ref === void 0 ? void 0 : keyOf(ref, `${tableKey}.${opName}`);
+		const extend = extendFor(description.extend, opName);
+		const { extensions, ...rest } = fields;
+		const operation = {
+			id,
+			method,
+			path,
+			tags: [tag],
+			source,
+			...rest,
+			extensions: {
+				[`${prefix}table`]: `${table.schema}.${table.name}`,
+				...extensions,
+				...permission === void 0 ? {} : { [`${prefix}permission`]: permission }
+			},
+			...permission === void 0 ? {} : { permission },
+			...description.security ? { security: description.security } : {},
+			...extend ? { extend } : {},
+			...tableDocs.deprecated ? { deprecated: true } : {}
+		};
+		operations.push(operation);
+		servedTable.operations.push(operation);
+	};
+	const outputOf = (operation, fallback) => {
+		const output = description.output?.[operation];
+		return output ? schemaOf(output, "output", "output", `${operation}${name}`) : fallback;
+	};
+	const resourceOp = (operation) => ({
+		kind: "resource",
+		table: tableKey,
+		operation
+	});
+	const errorsFor = (operation) => usedErrors(errors, OPERATION_STATUSES[operation], plan.permissions[operation] !== void 0);
+	const opExtension = (operation) => ({ [`${prefix}operation`]: operation });
+	return {
+		ctx,
+		plan,
+		tableKey,
+		name,
+		description,
+		components,
+		componentFor,
+		rowName,
+		pageName,
+		cursor,
+		collection,
+		item,
+		idParameter,
+		errors,
+		add,
+		outputOf,
+		resourceOp,
+		errorsFor,
+		opExtension
+	};
+}
+function addTableOperation(scope, operation) {
+	const { plan, tableKey, name, description, components, componentFor, rowName, pageName, cursor, collection, item, idParameter, add, outputOf, resourceOp, errorsFor, opExtension } = scope;
+	const { schemaOf } = scope.ctx;
+	switch (operation) {
+		case "list": {
+			const listOutput = description.output?.list;
+			const pageRef = listOutput ? pageSchema(schemaOf(listOutput, "output", "item", `list${name}`), cursor) : schemaRef(pageName);
+			add("list", resourceOp("list"), "get", collection, {
+				summary: `List ${tableKey}`,
+				extensions: opExtension("list"),
+				parameters: description.list ? description.list.openapi.filter(isParameter) : pageParameters(cursor, plan.maxPageSize),
+				responses: {
+					"200": jsonResponse(pageRef, `A page of ${tableKey}.`),
+					...errorsFor("list")
+				}
+			});
+			break;
+		}
+		case "create": {
+			const body = description.input?.create ? schemaOf(description.input.create, "input", "input", `create${name}`) : schemaRef(components.Insert ?? componentFor("Insert"));
+			add("create", resourceOp("create"), "post", collection, {
+				summary: `Create a ${tableKey} row`,
+				extensions: opExtension("create"),
+				parameters: [],
+				requestBody: {
+					required: true,
+					content: jsonContent(body)
+				},
+				responses: {
+					"201": jsonResponse(outputOf("create", schemaRef(rowName)), "Created."),
+					...errorsFor("create")
+				}
+			});
+			break;
+		}
+		case "get":
+			if (!item || !idParameter) break;
+			add("get", resourceOp("get"), "get", item, {
+				summary: `Get a ${tableKey} row`,
+				extensions: opExtension("get"),
+				parameters: [idParameter],
+				responses: {
+					"200": jsonResponse(outputOf("get", schemaRef(rowName)), "The row."),
+					...errorsFor("get")
+				}
+			});
+			break;
+		case "update": {
+			if (!item || !idParameter) break;
+			const body = description.input?.update ? schemaOf(description.input.update, "input", "input", `update${name}`) : schemaRef(components.Update ?? componentFor("Update"));
+			add("update", resourceOp("update"), "patch", item, {
+				summary: `Update a ${tableKey} row`,
+				extensions: opExtension("update"),
+				parameters: [idParameter],
+				requestBody: {
+					required: true,
+					content: jsonContent(body)
+				},
+				responses: {
+					"200": jsonResponse(outputOf("update", schemaRef(rowName)), "Updated."),
+					...errorsFor("update")
+				}
+			});
+			break;
+		}
+		case "delete":
+			if (!item || !idParameter) break;
+			add("delete", resourceOp("delete"), "delete", item, {
+				summary: `Delete a ${tableKey} row`,
+				extensions: opExtension("delete"),
+				parameters: [idParameter],
+				responses: {
+					"204": { description: "Deleted." },
+					...errorsFor("delete")
+				}
+			});
+			break;
+		default: throw new TypeError(`better-supabase/spec: unknown operation "${String(operation)}"`);
+	}
+}
+function addAction(scope, action) {
+	const { tableKey, name, idParameter, collection, errors, add } = scope;
+	const { prefix, schemaOf, objectParameters, usedErrors } = scope.ctx;
+	const method = action.method.toLowerCase();
+	if (!isMethod(method)) throw new TypeError(`${tableKey}.actions.${action.name}: unknown method`);
+	const operationId = `${action.name}${name}`;
+	const parameters = [...action.params.length > 0 && idParameter ? [idParameter] : [], ...action.query ? objectParameters(action.query, "query", `${operationId} query`) : []];
+	const status = String(action.status ?? (action.output ? 200 : 204));
+	const statuses = [
+		...action.input || action.query ? [400] : [],
+		401,
+		403,
+		...action.params.length > 0 ? [404] : [],
+		...action.input ? [422] : []
+	];
+	add(action.name, {
+		kind: "action",
+		table: tableKey,
+		action: action.name
+	}, method, `${collection}${action.path}`, {
+		...action.summary ? { summary: action.summary } : {},
+		...action.description ? { description: action.description } : {},
+		...action.deprecated ? { deprecated: true } : {},
+		extensions: {
+			[`${prefix}action`]: action.name,
+			...action.emits ? { [`${prefix}emits`]: [...action.emits] } : {}
+		},
+		parameters,
+		...action.input ? { requestBody: {
+			required: true,
+			content: jsonContent(schemaOf(action.input, "input", "input", operationId))
+		} } : {},
+		responses: {
+			[status]: action.output ? jsonResponse(schemaOf(action.output, "output", "output", operationId), action.summary ?? "Done.") : { description: action.summary ?? "Done." },
+			...usedErrors(errors, statuses, action.permission !== void 0)
+		}
+	});
+}
+const VERB_ARGUMENTS = {
+	page: "The page arguments of `db.<table>.page()`: `where`, `orderBy`, `size` with `page`, `offset` with `limit`, or `after`.",
+	count: "The arguments of `db.<table>.count()`, such as `where`.",
+	aggregate: "The arguments of `db.<table>.aggregate()`: the aggregates and `groupBy`.",
+	upsert: "A row to insert or update, or an array of rows."
+};
+function addVerb(scope, verb) {
+	const { plan, tableKey, components, componentFor, rowName, collection, errors, add } = scope;
+	const { prefix, usedErrors } = scope.ctx;
+	const row = schemaRef(rowName);
+	const insert = schemaRef(components.Insert ?? componentFor("Insert"));
+	const body = verb === "upsert" ? { oneOf: [insert, {
+		type: "array",
+		items: insert
+	}] } : { type: "object" };
+	const output = (() => {
+		switch (verb) {
+			case "page": return pageSchema(row, plan.pagination === "cursor");
+			case "count": return {
+				type: "integer",
+				minimum: 0
+			};
+			case "aggregate": return {};
+			case "upsert": return { oneOf: [row, {
+				type: "array",
+				items: row
+			}] };
+			default: throw new TypeError(`Unknown verb ${String(verb)}`);
+		}
+	})();
+	add(verb, {
+		kind: "verb",
+		owner: "table",
+		name: tableKey,
+		verb
+	}, "post", `${collection}/${verb}`, {
+		summary: `${verb[0].toUpperCase()}${verb.slice(1)} ${tableKey}`,
+		extensions: { [`${prefix}verb`]: verb },
+		parameters: [],
+		requestBody: {
+			required: verb === "upsert",
+			description: VERB_ARGUMENTS[verb],
+			content: jsonContent(body)
+		},
+		responses: {
+			"200": jsonResponse(output, "The result."),
+			...usedErrors(errors, VERB_STATUSES$1[verb], plan.permissions[verb] !== void 0)
+		}
+	});
+}
+/** Adds one resource's components, tag and operations to the build. */
+function buildResource(ctx, key, input) {
+	const scope = resourceScope(ctx, key, input);
+	for (const operation of scope.plan.operations) addTableOperation(scope, operation);
+	for (const verb of scope.plan.verbs) addVerb(scope, verb);
+	for (const action of scope.plan.actions) addAction(scope, action);
+}
+//#endregion
+//#region src/spec/build-blocks.ts
+/** The contract verbs that only read, so `requirePermissions` skips them. */
+const READ_VERBS = /* @__PURE__ */ new Set([
+	"list",
+	"page",
+	"get",
+	"count",
+	"aggregate"
+]);
+const VERB_STATUSES = [
+	400,
+	401,
+	403,
+	404,
+	409,
+	422
+];
+function isStandard(value) {
+	return isPlainObject(value) && isPlainObject(value["~standard"]);
+}
+/** Every verb of an instance: its methods, then `member.method`. */
+function instanceVerbs(surface) {
+	return [...surface.methods, ...Object.entries(surface.members).flatMap(([member, methods]) => methods.map((method) => `${member}.${method}`))];
+}
+/**
+* The body schema of `create` and `list` when the block has one entity with
+* that schema; any other verb takes its arguments as documented on the client.
+*/
+function inputOf(surface, verb) {
+	const field = verb === "create" ? "input" : verb === "list" ? "listFilter" : void 0;
+	if (field === void 0) return;
+	const found = Object.values(surface.schemas).flatMap((entity) => {
+		const schema = entity[field];
+		return isStandard(schema) ? [schema] : [];
+	});
+	return found.length === 1 ? found[0] : void 0;
+}
+/** The block instances `options.blocks` publishes, with their descriptions. */
+function publishedBlocks(source, input) {
+	if (input === false || source === void 0) return {};
+	if (input === void 0) return Object.fromEntries(source.instances.map((key) => [key, {}]));
+	return Object.fromEntries(Object.entries(input).map(([key, entry]) => [key, entry === true ? {} : entry]));
+}
+/** Adds `POST /<instance>/<verb>` for each published block instance. */
+function buildBlocks(ctx, source, input) {
+	if (source === void 0) return;
+	for (const [key, description] of Object.entries(publishedBlocks(source, input))) {
+		if (!source.instances.includes(key)) {
+			ctx.report({
+				code: "block-unknown",
+				severity: "error",
+				message: `blocks.${key} names no block instance of betterSupabase.blocks()`
+			});
+			continue;
+		}
+		const surface = source.describe?.(key);
+		if (!surface) {
+			ctx.report({
+				code: "block-undescribed",
+				severity: "warning",
+				message: `The ${key} block instance can't list its methods, so the API leaves it out`
+			});
+			continue;
+		}
+		buildInstance(ctx, key, surface, description);
+	}
+}
+function buildInstance(ctx, key, surface, description) {
+	const { options, prefix, base, globalErrors, operations, report, addTag, keyOf, schemaOf, usedErrors } = ctx;
+	const available = instanceVerbs(surface);
+	const verbs = description.verbs ?? available;
+	const tag = description.tag ?? key;
+	const property = instanceProperty(key);
+	const collection = `${base}${description.path ?? `/${key}`}`;
+	addTag(tag, description.description);
+	for (const verb of verbs) {
+		if (!available.includes(verb)) {
+			report({
+				code: "block-verb-unknown",
+				severity: "error",
+				message: `blocks.${key}.verbs: the ${surface.block} client has no ${verb} method`
+			});
+			continue;
+		}
+		const [first, second] = verb.split(".");
+		const member = second === void 0 ? void 0 : first;
+		const method = second ?? first ?? verb;
+		const source = {
+			kind: "verb",
+			owner: "block",
+			name: key,
+			...member === void 0 ? {} : { member },
+			verb: method
+		};
+		const path = `${collection}/${verb.replaceAll(".", "/")}`;
+		const defaultId = `${property}.${verb}`;
+		const id = options.operationId?.({
+			source,
+			method: "post",
+			path,
+			defaultId
+		}) ?? defaultId;
+		const ref = description.permissions?.[verb];
+		const permission = ref === void 0 ? void 0 : keyOf(ref, `blocks.${key}.${verb}`);
+		const standard = inputOf(surface, verb);
+		const body = standard ? schemaOf(standard, "input", "input", id) : {};
+		operations.push({
+			id,
+			method: "post",
+			path,
+			tags: [tag],
+			source,
+			summary: `${verb} (${key})`,
+			description: `Calls \`db.${property}.${verb}()\`. A method that takes more than one argument takes them as a JSON array.`,
+			parameters: [],
+			requestBody: {
+				required: false,
+				content: jsonContent(body)
+			},
+			responses: {
+				"200": jsonResponse({}, "What the method returns."),
+				...usedErrors(globalErrors, VERB_STATUSES, permission !== void 0)
+			},
+			extensions: {
+				[`${prefix}block`]: surface.block,
+				[`${prefix}instance`]: key,
+				[`${prefix}verb`]: verb,
+				...permission === void 0 ? {} : { [`${prefix}permission`]: permission }
+			},
+			...permission === void 0 ? {} : { permission },
+			...description.security ? { security: description.security } : {}
+		});
+	}
+}
+//#endregion
+//#region src/spec/data-api.ts
+const REST = "/rest/v1";
+const DEFAULT_TAG = "Data API";
+const ERROR = "DataApiError";
+/** The error body PostgREST answers with. */
+const ERROR_SCHEMA = {
+	type: "object",
+	required: ["message"],
+	properties: {
+		code: { type: "string" },
+		message: { type: "string" },
+		details: { type: ["string", "null"] },
+		hint: { type: ["string", "null"] }
+	}
+};
+/**
+* Query parameters PostgREST reserves, so a column with the name gets no
+* filter.
+*/
+const RESERVED = /* @__PURE__ */ new Set([
+	"select",
+	"order",
+	"limit",
+	"offset",
+	"columns",
+	"on_conflict",
+	"or",
+	"and",
+	"not"
+]);
+const INTEGER = /* @__PURE__ */ new Set([
+	"int2",
+	"int4",
+	"int8"
+]);
+const NUMBER = /* @__PURE__ */ new Set([
+	"float4",
+	"float8",
+	"numeric",
+	"oid",
+	"money"
+]);
+/** The scheme names the `apiKey` and `bearer` presets register. */
+const DATA_API_SECURITY = [{
+	supabaseApiKey: [],
+	supabaseJwt: []
+}, { supabaseApiKey: [] }];
+/** JSON Schema for a Postgres type as PostgREST writes it. */
+function typeSchema(meta, type) {
+	if (type.startsWith("_")) return {
+		type: "array",
+		items: typeSchema(meta, type.slice(1))
+	};
+	const values = meta.enums[type];
+	if (values) return {
+		type: "string",
+		enum: [...values]
+	};
+	if (INTEGER.has(type)) return { type: "integer" };
+	if (NUMBER.has(type)) return { type: "number" };
+	switch (type) {
+		case "bool": return { type: "boolean" };
+		case "uuid": return {
+			type: "string",
+			format: "uuid"
+		};
+		case "timestamptz": return {
+			type: "string",
+			format: "date-time"
+		};
+		case "date": return {
+			type: "string",
+			format: "date"
+		};
+		case "json":
+		case "jsonb":
+		case "record":
+		case "void": return {};
+		default: return { type: "string" };
+	}
+}
+/**
+* A table schema with database column names, as the Data API reads and writes
+* them.
+*/
+function databaseCased(schema, table) {
+	const dbName = (name) => table.columns[name]?.db ?? name;
+	const properties = schema["properties"];
+	const required = schema["required"];
+	return {
+		...schema,
+		...isPlainObject(properties) ? { properties: Object.fromEntries(Object.entries(properties).map(([name, value]) => [dbName(name), value])) } : {},
+		...Array.isArray(required) ? { required: required.map((name) => typeof name === "string" ? dbName(name) : name) } : {}
+	};
+}
+const qualified = (schema, name) => schema === "public" ? name : `${schema}.${name}`;
+const STRING = { type: "string" };
+const header = (name, description, schema, required = false) => ({
+	name,
+	in: "header",
+	required,
+	description,
+	schema: schema ?? STRING
+});
+const query = (name, description, schema) => ({
+	name,
+	in: "query",
+	required: false,
+	description,
+	schema: schema ?? STRING
+});
+/**
+* The `Accept-Profile` or `Content-Profile` header a table outside `public`
+* needs.
+*/
+function profile(schema, write) {
+	return schema === "public" ? [] : [header(write ? "Content-Profile" : "Accept-Profile", `The schema of the table, \`${schema}\`.`, {
+		type: "string",
+		enum: [schema]
+	}, true)];
+}
+const PREFER_WRITE = header("Prefer", "`return=representation` answers with the written rows; `return=minimal` (the default) answers without a body.");
+/**
+* Documents the Data API: table operations under `/rest/v1/<table>` and RPCs
+* under `/rest/v1/rpc/<name>`.
+*/
+function buildDataApi(ctx, dataApi) {
+	const { meta, options, operations, report, addTag, addComponent, responses } = ctx;
+	const tag = dataApi.tag ?? DEFAULT_TAG;
+	const origin = options.supabaseUrl?.replace(/\/$/, "");
+	if (!origin) report({
+		code: "data-api-server-missing",
+		severity: "warning",
+		message: "dataApi needs supabaseUrl: without it the /rest/v1 paths resolve against the document's servers"
+	});
+	const servers = origin ? [{
+		url: origin,
+		description: "The Supabase project."
+	}] : void 0;
+	const defs = tableSchemas(meta, options.json ?? {});
+	const tableKeys = /* @__PURE__ */ new Set();
+	const unknownTable = (key, where) => {
+		report({
+			code: "data-api-table-unknown",
+			severity: "error",
+			message: `${where}: no table or view "${key}"`
+		});
+	};
+	if (dataApi.tables === true) for (const key of Object.keys(meta.tables).toSorted()) tableKeys.add(key);
+	else for (const key of dataApi.tables ?? []) if (meta.tables[key]) tableKeys.add(key);
+	else unknownTable(key, "dataApi.tables");
+	for (const key of Object.keys(dataApi.operations ?? {})) if (!meta.tables[key]) unknownTable(key, "dataApi.operations");
+	else if (!tableKeys.has(key)) tableKeys.add(key);
+	const functionKeys = [];
+	if (dataApi.functions === true) functionKeys.push(...Object.keys(meta.functions).toSorted());
+	else for (const key of dataApi.functions ?? []) if (meta.functions[key]) functionKeys.push(key);
+	else report({
+		code: "data-api-function-unknown",
+		severity: "error",
+		message: `dataApi.functions: no function "${key}"`
+	});
+	if (tableKeys.size === 0 && functionKeys.length === 0) return;
+	addTag(tag, "The Supabase Data API (PostgREST). Every request runs under row-level security.");
+	addComponent(ERROR, structuredClone(ERROR_SCHEMA));
+	responses[ERROR] ??= {
+		description: "PostgREST rejected the request.",
+		content: jsonContent(schemaRef(ERROR))
+	};
+	const errors = { "4XX": { ref: ERROR } };
+	/**
+	* The database-cased component of a table variant, or `undefined` when the
+	* table has none.
+	*/
+	const component = (key, variant) => {
+		const table = meta.tables[key];
+		const schema = defs[`${key}${variant}`];
+		if (!table || !schema) return;
+		const name = `DataApi${pascal(table.schema === "public" ? "" : `${table.schema}_`)}${pascal(table.name)}${variant}`;
+		addComponent(name, databaseCased(structuredClone(schema), table));
+		return schemaRef(name);
+	};
+	const push = (draft) => {
+		const { defaultId, ...rest } = draft;
+		operations.push({
+			...rest,
+			id: options.operationId?.({
+				source: draft.source,
+				method: draft.method,
+				path: draft.path,
+				defaultId
+			}) ?? defaultId,
+			tags: [tag],
+			...servers ? { servers } : {},
+			security: DATA_API_SECURITY,
+			extensions: {}
+		});
+	};
+	for (const key of tableKeys) {
+		const table = meta.tables[key];
+		if (table) buildTable(key, table);
+	}
+	for (const key of functionKeys) {
+		const fn = meta.functions[key];
+		if (fn) buildFunction(key, fn);
+	}
+	function buildTable(key, table) {
+		const row = component(key, "Row") ?? {};
+		const insert = component(key, "Insert");
+		const update = component(key, "Update");
+		const rows = {
+			type: "array",
+			items: row
+		};
+		const path = `${REST}/${table.name}`;
+		const name = pascal(table.schema === "public" ? table.name : `${table.schema}_${table.name}`);
+		const label = qualified(table.schema, table.name);
+		const filters = Object.values(table.columns).filter((column) => !RESERVED.has(column.db)).map((column) => query(column.db, `Filters on \`${column.db}\` with an operator and a value: \`eq.<value>\`, \`in.(a,b)\`, \`is.null\`.`));
+		const viewOperations = ["select"];
+		if (insert) viewOperations.push("insert");
+		if (update) viewOperations.push("update", "delete");
+		const allowed = dataApi.operations?.[key] ?? (table.kind === "view" ? viewOperations : [
+			"select",
+			"insert",
+			"update",
+			"delete"
+		]);
+		const source = (operation) => ({
+			kind: "data-api",
+			table: key,
+			operation
+		});
+		const written = (status, description) => ({ [status]: jsonResponse(rows, `${description} The body holds the rows with \`Prefer: return=representation\`.`) });
+		for (const operation of allowed) switch (operation) {
+			case "select":
+				push({
+					defaultId: `dataApiSelect${name}`,
+					method: "get",
+					path,
+					summary: `Read rows of ${label}`,
+					parameters: [
+						query("select", "The columns to return, comma separated, and embedded relations as `relation(columns)`. Defaults to `*`."),
+						query("order", "Sort order, such as `created_at.desc,id`."),
+						query("limit", "The most rows to return.", {
+							type: "integer",
+							minimum: 0
+						}),
+						query("offset", "The rows to skip.", {
+							type: "integer",
+							minimum: 0
+						}),
+						...filters,
+						header("Range", "A row range, such as `0-24`."),
+						header("Prefer", "`count=exact`, `count=planned` or `count=estimated` adds the total to `Content-Range`."),
+						...profile(table.schema, false)
+					],
+					responses: {
+						"200": {
+							...jsonResponse(rows, "The rows."),
+							headers: { "Content-Range": {
+								description: "The returned range and the total, such as `0-24/100`.",
+								schema: { type: "string" }
+							} }
+						},
+						"206": jsonResponse(rows, "Part of the rows, for a `Range` request."),
+						...errors
+					},
+					source: source("select")
+				});
+				break;
+			case "insert":
+				push({
+					defaultId: `dataApiInsert${name}`,
+					method: "post",
+					path,
+					summary: `Insert rows into ${label}`,
+					parameters: [
+						query("columns", "The columns to read from the body, comma separated."),
+						query("on_conflict", "The unique columns an upsert matches on, comma separated."),
+						PREFER_WRITE,
+						...profile(table.schema, true)
+					],
+					requestBody: {
+						required: true,
+						content: jsonContent(insert ? { oneOf: [insert, {
+							type: "array",
+							items: insert
+						}] } : {})
+					},
+					responses: {
+						...written("201", "Created."),
+						...errors
+					},
+					source: source("insert")
+				});
+				break;
+			case "update":
+				push({
+					defaultId: `dataApiUpdate${name}`,
+					method: "patch",
+					path,
+					summary: `Update rows of ${label}`,
+					description: "Updates every row the filters match.",
+					parameters: [
+						...filters,
+						PREFER_WRITE,
+						...profile(table.schema, true)
+					],
+					requestBody: {
+						required: true,
+						content: jsonContent(update ?? {})
+					},
+					responses: {
+						...written("200", "Updated."),
+						"204": { description: "Updated, without a body." },
+						...errors
+					},
+					source: source("update")
+				});
+				break;
+			case "delete":
+				push({
+					defaultId: `dataApiDelete${name}`,
+					method: "delete",
+					path,
+					summary: `Delete rows of ${label}`,
+					description: "Deletes every row the filters match.",
+					parameters: [
+						...filters,
+						PREFER_WRITE,
+						...profile(table.schema, true)
+					],
+					responses: {
+						...written("200", "Deleted."),
+						"204": { description: "Deleted, without a body." },
+						...errors
+					},
+					source: source("delete")
+				});
+				break;
+			default: throw new TypeError(`Unknown Data API operation "${String(operation)}"`);
+		}
+	}
+	function argumentsSchema(signature) {
+		const required = signature.args.filter((arg) => arg.optional !== true).map((arg) => arg.name);
+		return {
+			type: "object",
+			properties: Object.fromEntries(signature.args.map((arg) => [arg.name, typeSchema(meta, arg.type)])),
+			...required.length > 0 ? { required } : {},
+			additionalProperties: false
+		};
+	}
+	function resultSchema(fn) {
+		const { result } = fn;
+		let one;
+		if (result && "table" in result) one = component(result.table, "Row") ?? {};
+		else if (result) one = {
+			type: "object",
+			properties: Object.fromEntries(result.columns.map((column) => [column.db, {}])),
+			required: result.columns.map((column) => column.db)
+		};
+		else {
+			const rowTable = Object.entries(meta.tables).find(([, table]) => table.name === fn.returns && table.schema === fn.schema);
+			one = rowTable ? component(rowTable[0], "Row") ?? {} : typeSchema(meta, fn.returns);
+		}
+		return fn.returnsSet ? {
+			type: "array",
+			items: one
+		} : one;
+	}
+	function buildFunction(key, fn) {
+		const signatures = fn.overloads ?? [fn];
+		const bodies = signatures.map(argumentsSchema);
+		const [only] = bodies;
+		const body = bodies.length === 1 && only ? only : { oneOf: bodies };
+		const takesArgs = signatures.some((signature) => signature.args.length > 0);
+		push({
+			defaultId: `dataApiRpc${pascal(fn.schema === "public" ? fn.name : `${fn.schema}_${fn.name}`)}`,
+			method: "post",
+			path: `${REST}/rpc/${fn.name}`,
+			summary: `Call ${qualified(fn.schema, fn.name)}`,
+			description: `A ${fn.volatility} function.${fn.volatility === "volatile" ? "" : " A GET with the arguments as query parameters calls it too."}`,
+			parameters: profile(fn.schema, true),
+			requestBody: {
+				required: takesArgs,
+				content: jsonContent(body)
+			},
+			responses: {
+				...fn.returns === "void" && !fn.returnsSet ? { "204": { description: "Done." } } : { "200": jsonResponse(resultSchema(fn), "The result.") },
+				...errors
+			},
+			source: {
+				kind: "data-api",
+				function: key,
+				operation: "rpc"
+			}
+		});
+	}
+}
+/** Adds the `apiKey` and `bearer` schemes the Data API operations require. */
+function withDataApiSchemes(security, operations, supabaseUrl) {
+	if (!operations.some((operation) => operation.source.kind === "data-api")) return security;
+	const { schemes } = resolveSecurity(["apiKey", "bearer"], supabaseUrl);
+	return {
+		schemes: {
+			...schemes,
+			...security.schemes
+		},
+		requirements: security.requirements
+	};
+}
+//#endregion
+//#region src/spec/events.ts
+/**
+* Whether a value is a `defineTopic()` result: a template string and the `sql`,
+* `trigger` and `subscribe` methods. `better-supabase upgrade` and `spec` use
+* the same check.
+*/
+function isTopicLike(value) {
+	return isRecord(value) && typeof value["template"] === "string" && typeof value["sql"] === "function" && typeof value["trigger"] === "function" && typeof value["subscribe"] === "function";
+}
+/**
+* The `defineTopic()` results in modules or arrays, for `events.topics`. A
+* module's topics are keyed by export name; a topic in an array by its `name`.
+* Other values are skipped, and a topic reached twice is kept once.
+*
+* ```ts
+* import * as topics from "../realtime/topics";
+* defineApi(betterSupabase, {
+*   info,
+*   events: { topics: topicsFrom(topics) },
+* });
+* ```
+*/
+function topicsFrom(...sources) {
+	const topics = {};
+	const seen = /* @__PURE__ */ new Set();
+	for (const source of sources) {
+		const entries = Array.isArray(source) ? source.map((value) => [void 0, value]) : Object.entries(source);
+		for (const [key, value] of entries) {
+			if (!isTopicLike(value) || seen.has(value)) continue;
+			seen.add(value);
+			topics[key ?? value.name ?? value.template] = value;
+		}
+	}
+	return topics;
+}
+const OPEN = { type: "object" };
+const DEFAULT_INTENTS = [
+	"insert",
+	"update",
+	"delete"
+];
+/** An id safe for AsyncAPI channel, operation and component keys. */
+function safeKey(value) {
+	return value.replaceAll(/[^A-Za-z0-9_-]/g, "_");
+}
+const keyPart = (value) => safeKey(pascal(value));
+/** The CloudEvents attributes in HTTP binary mode (`ce-*` headers). */
+const CLOUD_EVENT_TRAIT = {
+	description: "CloudEvents 1.0 attributes in HTTP binary mode.",
+	contentType: "application/json",
+	headers: {
+		type: "object",
+		properties: {
+			"ce-specversion": {
+				type: "string",
+				const: "1.0"
+			},
+			"ce-id": { type: "string" },
+			"ce-source": {
+				type: "string",
+				format: "uri-reference"
+			},
+			"ce-type": { type: "string" },
+			"ce-subject": { type: "string" },
+			"ce-time": {
+				type: "string",
+				format: "date-time"
+			},
+			"ce-dataschema": {
+				type: "string",
+				format: "uri"
+			},
+			"ce-partitionkey": { type: "string" }
+		}
+	}
+};
+function cloudEventHeaders(type, dataschema) {
+	return {
+		type: "object",
+		required: [
+			"ce-specversion",
+			"ce-id",
+			"ce-source",
+			"ce-type"
+		],
+		properties: {
+			"ce-type": {
+				type: "string",
+				const: type
+			},
+			...dataschema ? { "ce-dataschema": {
+				type: "string",
+				const: dataschema
+			} } : {}
+		}
+	};
+}
+function convert(schema, where, ctx) {
+	if (schema === true) return OPEN;
+	const converted = convertStandard(schema, "output");
+	if (converted) return converted.schema;
+	ctx.report({
+		code: "asyncapi-schema-opaque",
+		severity: "warning",
+		message: `${where}: the schema does not implement Standard JSON Schema; the payload is left open`
+	});
+	return OPEN;
+}
+function tableChannels(ctx, selection, channels, messages) {
+	if (selection === false) return;
+	const realtime = ctx.meta.realtime ?? {};
+	const keys = selection === true ? Object.keys(realtime) : selection;
+	for (const key of keys) {
+		const table = ctx.meta.tables[key];
+		const config = realtime[key];
+		if (!table || !config) {
+			ctx.report({
+				code: "asyncapi-table-unknown",
+				severity: "error",
+				message: `events.tables names "${key}", which is not in database.realtime.tables`
+			});
+			continue;
+		}
+		const id = `table${keyPart(key)}`;
+		const base = `bsb:t:${table.schema}.${table.name}`;
+		const address = config.user ? `${base}:u:{userId}` : config.tenant ? `${base}:{tenant}` : base;
+		const messageId = `${id}Change`;
+		messages[messageId] = {
+			id: messageId,
+			name: "change",
+			title: `${key} changed`,
+			summary: `A row of ${table.schema}.${table.name} was inserted, updated or deleted. Clients refetch through row-level security.`,
+			contentType: "application/json",
+			payload: {
+				type: "object",
+				required: [
+					"schema",
+					"table",
+					"operation"
+				],
+				properties: {
+					schema: {
+						type: "string",
+						const: table.schema
+					},
+					table: {
+						type: "string",
+						const: table.name
+					},
+					operation: {
+						type: "string",
+						enum: [
+							"INSERT",
+							"UPDATE",
+							"DELETE"
+						]
+					}
+				}
+			},
+			extensions: { [`${ctx.prefix}event`]: "change" }
+		};
+		channels.push({
+			id,
+			address,
+			title: `${key} changes`,
+			protocol: "ws",
+			...config.user ? { parameters: { userId: { description: "The signed-in user's id." } } } : config.tenant ? { parameters: { tenant: { description: `The row's \`${config.tenant}\` value.` } } } : {},
+			messages: [messageId],
+			operations: [{
+				id: `receive${keyPart(key)}Changes`,
+				action: "receive",
+				summary: `Change signals for ${key}`
+			}],
+			extensions: {
+				[`${ctx.prefix}table`]: `${table.schema}.${table.name}`,
+				[`${ctx.prefix}realtime-status`]: topicStatus({ private: true })
+			}
+		});
+	}
+}
+function topicChannels(ctx, topics, channels, messages) {
+	for (const [key, topic] of Object.entries(topics)) {
+		const id = `topic${keyPart(key)}`;
+		const ids = [];
+		const events = Object.entries(topic.events ?? {});
+		if (events.length === 0) {
+			ctx.report({
+				code: "asyncapi-topic-open",
+				severity: "info",
+				message: `Topic "${key}" lists no events; it is documented with one open message`
+			});
+			events.push(["*", true]);
+		}
+		for (const [event, schema] of events) {
+			const messageId = `${id}${event === "*" ? "Any" : keyPart(event)}`;
+			ids.push(messageId);
+			messages[messageId] = {
+				id: messageId,
+				...event === "*" ? {} : { name: event },
+				title: event === "*" ? `${key} broadcast` : `${key} ${event}`,
+				contentType: "application/json",
+				payload: convert(schema, `topics.${key}.events.${event}`, ctx),
+				extensions: { [`${ctx.prefix}event`]: event }
+			};
+		}
+		if (topic.presence) {
+			const messageId = `${id}Presence`;
+			ids.push(messageId);
+			messages[messageId] = {
+				id: messageId,
+				name: "presence",
+				title: `${key} presence`,
+				contentType: "application/json",
+				payload: topic.presenceSchema ? convert(topic.presenceSchema, `topics.${key}.presence`, ctx) : OPEN,
+				extensions: { [`${ctx.prefix}event`]: "presence" }
+			};
+		}
+		const permission = topic.permission === void 0 ? void 0 : ctx.keyOf(topic.permission, `topics.${key}`);
+		const extra = permission === void 0 ? {} : { permission };
+		const operations = [{
+			id: `receive${keyPart(key)}`,
+			action: "receive",
+			...topic.summary ? { summary: topic.summary } : {},
+			...extra
+		}];
+		if (topic.send === true || topic.clientSend === true || topic.presence) operations.push({
+			id: `send${keyPart(key)}`,
+			action: "send",
+			...extra
+		});
+		const params = [...topic.template.matchAll(/\{([^}]+)\}/g)].map((match) => match[1] ?? "");
+		channels.push({
+			id,
+			address: topic.template,
+			...topic.summary ? { summary: topic.summary } : {},
+			...topic.description ? { description: topic.description } : {},
+			title: topic.name ?? key,
+			...params.length > 0 ? { parameters: Object.fromEntries(params.map((name) => [name, {}])) } : {},
+			protocol: "ws",
+			messages: ids,
+			operations,
+			extensions: {
+				[`${ctx.prefix}private`]: topic.private ?? true,
+				[`${ctx.prefix}realtime-status`]: topic.status ?? topicStatus(topic)
+			}
+		});
+	}
+}
+function withActor(schema) {
+	const properties = schema["properties"];
+	if (!isPlainObject(properties) || "actorId" in properties) return schema;
+	return {
+		...schema,
+		properties: {
+			...properties,
+			actorId: {
+				type: "string",
+				description: "Who caused the event."
+			}
+		}
+	};
+}
+function cloudEventChannel(ctx, input, channels, messages) {
+	const ids = [];
+	const add = (messageId, type, title, payload, table) => {
+		const { dataschema } = dataschemaOf(input, {
+			type,
+			...table ? { table } : {}
+		});
+		ids.push(messageId);
+		messages[messageId] = {
+			id: messageId,
+			name: type,
+			title,
+			contentType: "application/json",
+			headers: cloudEventHeaders(type, dataschema),
+			payload,
+			traits: ["cloudEvent"],
+			extensions: {
+				[`${ctx.prefix}cloudevent-type`]: type,
+				...dataschema ? { [`${ctx.prefix}dataschema`]: dataschema } : {}
+			}
+		};
+	};
+	const rows = input.rows ?? false;
+	const rowTables = rows === true ? Object.keys(ctx.meta.tables) : rows === false ? [] : rows;
+	const defs = rowTables.length > 0 ? tableSchemas(ctx.meta, ctx.json) : {};
+	for (const table of rowTables) {
+		if (!ctx.meta.tables[table]) {
+			ctx.report({
+				code: "asyncapi-table-unknown",
+				severity: "error",
+				message: `events.cloudEvents.rows names an unknown table "${table}"`
+			});
+			continue;
+		}
+		const component = ctx.served.get(table)?.components.Row;
+		const row = component ? schemaRef(component) : defs[`${table}Row`] ?? OPEN;
+		for (const intent of input.intents ?? DEFAULT_INTENTS) {
+			const last = ROW_EVENT_TYPES[intent].split(".").at(-1) ?? intent;
+			const type = input.typePrefix ? `${input.typePrefix}.row.${last}` : ROW_EVENT_TYPES[intent];
+			add(`row${keyPart(table)}${keyPart(last)}`, type, `${table} ${last}`, {
+				type: "object",
+				required: ["table", "row"],
+				properties: {
+					table: {
+						type: "string",
+						const: table
+					},
+					row,
+					actorId: { type: "string" }
+				}
+			}, table);
+		}
+	}
+	for (const [event, schema] of Object.entries(input.blocks ?? {})) {
+		if (schema === void 0) continue;
+		const type = `${input.typePrefix ?? "dev.better-supabase"}.${event}`;
+		add(`block${keyPart(event)}`, type, event, withActor(convert(schema, `events.cloudEvents.blocks.${event}`, ctx)));
+	}
+	if (ids.length === 0) return false;
+	channels.push({
+		id: "cloudEvents",
+		address: input.address ?? "events",
+		title: "CloudEvents",
+		description: `CloudEvents from \`${input.source}\`, sent to the event sink.`,
+		protocol: "http",
+		messages: ids,
+		operations: [{
+			id: "sendCloudEvents",
+			action: "send"
+		}]
+	});
+	return true;
+}
+/**
+* The built channels and messages first, then the app's own (which win on an
+* id), and the workflows with every `WorkflowSource` run on `operations`.
+*/
+function eventParts(options, ctx, operations) {
+	const built = buildEvents(options.events, ctx);
+	return {
+		channels: [...built.channels, ...options.channels ?? []],
+		messages: {
+			...built.messages,
+			...options.messages
+		},
+		...Object.keys(built.messageTraits).length > 0 ? { messageTraits: built.messageTraits } : {},
+		workflows: (options.workflows ?? []).flatMap((workflow) => typeof workflow === "function" ? workflow(operations) : [workflow])
+	};
+}
+/** Channels and messages from the realtime tables, topics and CloudEvents. */
+function buildEvents(events, ctx) {
+	const channels = [];
+	const messages = {};
+	const messageTraits = {};
+	if (!events) return {
+		channels,
+		messages,
+		messageTraits
+	};
+	tableChannels(ctx, events.tables ?? true, channels, messages);
+	topicChannels(ctx, events.topics ?? {}, channels, messages);
+	if (events.cloudEvents && cloudEventChannel(ctx, events.cloudEvents, channels, messages)) messageTraits["cloudEvent"] = CLOUD_EVENT_TRAIT;
+	return {
+		channels,
+		messages,
+		messageTraits
+	};
+}
+//#endregion
+//#region src/spec/build.ts
+const READ_METHODS = /* @__PURE__ */ new Set([
+	"get",
+	"head",
+	"options",
+	"query"
+]);
+const modelCache = /* @__PURE__ */ new WeakMap();
+const NO_PLUGINS = [];
+const NO_BLOCKS = {};
+/** One `WeakMap` level of the model cache, created on first use. */
+function level(map, key, empty) {
+	let value = map.get(key);
+	if (value === void 0) {
+		value = empty();
+		map.set(key, value);
+	}
+	return value;
+}
+/**
+* Builds the version-neutral API model once per metadata, plugin list, block
+* set and options object. Formats lower it to each version; `defineApi` wraps
+* it.
+*/
+function buildApiModel(source, options) {
+	const plugins = source.plugins ?? NO_PLUGINS;
+	const blocks = source.options?.blocks;
+	return level(level(level(level(modelCache, source.meta, () => /* @__PURE__ */ new WeakMap()), plugins, () => /* @__PURE__ */ new WeakMap()), blocks ?? NO_BLOCKS, () => /* @__PURE__ */ new WeakMap()), options, () => build(source.meta, plugins, blocks, options));
+}
+/** The tables `options.resources` publishes: every table unless it says so. */
+function publishedResources(meta, options) {
+	if (options.resources === false) return {};
+	return options.resources ?? Object.fromEntries(Object.keys(meta.tables).map((key) => [key, true]));
+}
+function build(meta, plugins, blocks, options) {
+	const ctx = createBuildContext(meta, options);
+	for (const [key, input] of Object.entries(publishedResources(meta, options))) buildResource(ctx, key, input);
+	buildBlocks(ctx, blocks, options.blocks);
+	for (const [index, route] of (options.routes ?? []).entries()) buildRoute(ctx, route, index);
+	if (options.dataApi) buildDataApi(ctx, options.dataApi);
+	const security = withDataApiSchemes(buildSecurity(ctx), ctx.operations, options.supabaseUrl);
+	applyPlugins(ctx, plugins);
+	validateOperations(ctx);
+	return finalizeModel(ctx, security);
+}
+function buildRoute(ctx, route, index) {
+	const { options, base, globalErrors, operations, prefix, addTag, keyOf, schemaOf, objectParameters, usedErrors } = ctx;
+	const method = route.method.toLowerCase();
+	if (!isMethod(method)) throw new TypeError(`better-supabase/spec: routes[${index}] has an unknown method "${route.method}"`);
+	const path = `${base}${route.path}`;
+	const defaultId = `${method}${route.path.split("/").filter(Boolean).map((segment) => segment.replaceAll(/[{}]/g, "")).map(pascal).join("")}`;
+	const source = { kind: "route" };
+	const id = route.operationId ?? options.operationId?.({
+		source,
+		method,
+		path,
+		defaultId
+	}) ?? defaultId;
+	const declared = route.params ? objectParameters(route.params, "path", `${id} params`) : [];
+	const parameters = [];
+	for (const [, param] of path.matchAll(/\{(\w+)\}/g)) parameters.push(declared.find((entry) => entry.name === param) ?? {
+		name: param,
+		in: "path",
+		required: true,
+		schema: { type: "string" }
+	});
+	if (route.query) parameters.push(...objectParameters(route.query, "query", `${id} query`));
+	const permission = route.permission === void 0 ? void 0 : keyOf(route.permission, `routes[${index}]`);
+	const secured = route.security === void 0 || route.security.length > 0;
+	const status = String(route.status ?? (route.output || route.stream ? 200 : 204));
+	const success = route.stream ? {
+		description: route.summary ?? "A stream of events.",
+		content: { [route.stream.contentType ?? "text/event-stream"]: { itemSchema: schemaOf(route.stream.item, "output", "item", id) } }
+	} : route.output ? jsonResponse(schemaOf(route.output, "output", "output", id), route.summary ?? "OK.") : { description: route.summary ?? "Done." };
+	const routeTags = [...route.tags ?? []];
+	for (const tag of routeTags) addTag(tag);
+	operations.push({
+		id,
+		method,
+		path,
+		tags: routeTags,
+		source,
+		...route.summary ? { summary: route.summary } : {},
+		...route.description ? { description: route.description } : {},
+		...route.deprecated ? { deprecated: true } : {},
+		parameters,
+		...route.input ? { requestBody: {
+			required: true,
+			content: jsonContent(schemaOf(route.input, "input", "input", id))
+		} } : {},
+		responses: {
+			[status]: success,
+			...usedErrors(route.errors ?? globalErrors, [...route.input || route.query ? [400, 422] : [], ...secured ? [401, 403] : []], permission !== void 0)
+		},
+		...route.security ? { security: route.security } : {},
+		...permission === void 0 ? {} : { permission },
+		extensions: permission === void 0 ? {} : { [`${prefix}permission`]: permission },
+		...route.extend ? { extend: route.extend } : {}
+	});
+}
+function buildSecurity(ctx) {
+	const { options, operations } = ctx;
+	const oauthScopes = {};
+	if (options.permissionScopes === "keys") {
+		for (const operation of operations) if (operation.permission) oauthScopes[operation.permission] = `Permission ${operation.permission}.`;
+	}
+	const security = resolveSecurity(options.security ?? ["bearer"], options.supabaseUrl, oauthScopes);
+	if (options.permissionScopes === "keys") for (const operation of operations) {
+		const key = operation.permission;
+		if (!key || operation.security?.length === 0) continue;
+		operation.security = (operation.security ?? security.requirements).map((requirement) => {
+			const scopes = requirement[OAUTH_SCHEME];
+			return scopes ? {
+				...requirement,
+				[OAUTH_SCHEME]: [...scopes, key]
+			} : requirement;
+		});
+	}
+	return security;
+}
+function applyPlugins(ctx, plugins) {
+	const { meta, prefix, served, schemas, report } = ctx;
+	const describe = describeApi(meta, prefix, served, schemas);
+	for (const plugin of plugins) {
+		if (!plugin.describe) continue;
+		try {
+			plugin.describe(describe);
+		} catch (error) {
+			report({
+				code: "plugin-describe-failed",
+				severity: "warning",
+				message: `The ${plugin.name} plugin's describe() threw: ${error instanceof Error ? error.message : String(error)}`
+			});
+		}
+	}
+}
+/** Reports writes without a permission and duplicate operation ids. */
+function validateOperations(ctx) {
+	const { options, operations, report } = ctx;
+	if (options.requirePermissions) for (const operation of operations) {
+		if (operation.source.kind === "data-api") continue;
+		if ((operation.source.kind === "resource" ? operation.source.operation !== "list" && operation.source.operation !== "get" : operation.source.kind === "verb" ? !READ_VERBS.has(operation.source.verb) : !READ_METHODS.has(operation.method)) && operation.permission === void 0) report({
+			code: "permission-missing",
+			severity: "error",
+			message: `${operation.id} writes but declares no permission`,
+			pointer: `/operations/${pointerToken(operation.id)}`
+		});
+	}
+	const seen = /* @__PURE__ */ new Set();
+	for (const operation of operations) {
+		if (seen.has(operation.id)) report({
+			code: "operation-id-duplicate",
+			severity: "error",
+			message: `Two operations have the id "${operation.id}"`,
+			pointer: `/operations/${pointerToken(operation.id)}`
+		});
+		seen.add(operation.id);
+	}
+}
+function finalizeModel(ctx, security) {
+	const { meta, options, prefix, served, keyOf, report, schemas, operations, tags, responses, diagnostics } = ctx;
+	const { enrich } = options;
+	const finalSchemas = {};
+	for (const [name, schema] of Object.entries(schemas)) finalSchemas[name] = enrich?.schema?.(schema, { name }) ?? schema;
+	const finalOperations = operations.map((operation) => enrich?.operation?.(operation) ?? operation);
+	const { messageTraits, ...parts } = eventParts(options, {
+		meta,
+		json: options.json ?? {},
+		prefix,
+		served,
+		keyOf,
+		report
+	}, finalOperations);
+	const messages = {};
+	for (const [id, message] of Object.entries(parts.messages)) messages[id] = enrich?.message?.(message, { id }) ?? message;
+	return {
+		model: {
+			info: options.info,
+			...options.self ? { self: options.self } : {},
+			servers: options.servers ?? [],
+			tags,
+			operations: finalOperations,
+			schemas: finalSchemas,
+			responses,
+			securitySchemes: security.schemes,
+			security: security.requirements,
+			...options.securityProfileRequirements ? { securityProfileRequirements: options.securityProfileRequirements } : {},
+			channels: parts.channels.map((channel) => enrich?.channel?.(channel) ?? channel),
+			messages,
+			...messageTraits ? { messageTraits } : {},
+			webhooks: options.webhooks ?? [],
+			workflows: parts.workflows.map((workflow) => enrich?.workflow?.(workflow) ?? workflow),
+			fragments: options.fragments ?? [],
+			...options.realtimeUrl ? { realtimeUrl: options.realtimeUrl } : {},
+			extensionPrefix: prefix
+		},
+		diagnostics
+	};
+}
+/** An operation's name within its resource: the operation, verb or action. */
+function operationName(operation) {
+	switch (operation.source.kind) {
+		case "action": return operation.source.action;
+		case "resource": return operation.source.operation;
+		case "verb": return operation.source.verb;
+		case "data-api":
+		case "route":
+		case "fragment": return operation.id;
+		default: {
+			const unknown = operation.source;
+			throw new TypeError(`Unknown operation source ${String(unknown)}`);
+		}
+	}
+}
+function describeApi(meta, prefix, served, schemas) {
+	const columnSchemas = (table, column) => {
+		const entry = served.get(table);
+		if (!entry) return [];
+		return [
+			"Row",
+			"Insert",
+			"Update"
+		].flatMap((variant) => {
+			const name = entry.components[variant];
+			const schema = name ? schemas[name] : void 0;
+			const properties = schema?.["properties"];
+			if (!schema || !isPlainObject(properties)) return [];
+			const property = properties[column];
+			if (!isPlainObject(property)) return [];
+			return [{
+				variant,
+				schema,
+				properties,
+				property
+			}];
+		});
+	};
+	const replace = (schema, properties, column, property) => {
+		schema["properties"] = {
+			...properties,
+			[column]: property
+		};
+	};
+	return {
+		schema: meta,
+		extensionPrefix: prefix,
+		resources: [...served.values()].map((entry) => ({
+			table: entry.table,
+			operations: entry.operations.map(operationName)
+		})),
+		addParameter(table, parameter, names) {
+			for (const operation of served.get(table)?.operations ?? []) {
+				const name = operationName(operation);
+				if (names && !names.includes(name)) continue;
+				if (operation.parameters.some((entry) => entry.name === parameter.name && entry.in === parameter.in)) continue;
+				operation.parameters.push({ ...parameter });
+			}
+		},
+		markReadOnly(table, column, description) {
+			for (const { variant, schema, properties, property } of columnSchemas(table, column)) {
+				replace(schema, properties, column, {
+					...property,
+					readOnly: true,
+					...description && property["description"] === void 0 ? { description } : {}
+				});
+				const required = schema["required"];
+				if (variant !== "Row" && Array.isArray(required)) schema["required"] = required.filter((name) => name !== column);
+			}
+		},
+		describeColumn(table, column, patch) {
+			for (const { schema, properties, property } of columnSchemas(table, column)) replace(schema, properties, column, mergeJson(property, patch));
+		}
+	};
+}
+//#endregion
+export { topicsFrom as a, PROBLEM_SCHEMA as c, mergeJson as d, pointerToken as f, safeKey as i, convertStandard as l, publishedResources as n, publishedBlocks as o, CLOUD_EVENT_TRAIT as r, DEFAULT_ERRORS as s, buildApiModel as t, pascal as u };