better-supabase 0.7.0 → 0.8.0

package/dist/build-hPwk3_X5.js

@@ -0,0 +1,1296 @@
+import { r as isPlainObject } from "./clone-dN9XOL1K.js";
+import { n as PROBLEM_TYPE_BASE, t as PROBLEM_CONTENT_TYPE } from "./problem-CJvFeGu7.js";
+import { t as buildJsonSchema } from "./json-schema-CT4tvrkA.js";
+import { r as dataschemaOf } from "./cloud-event-CTh9Sr5w.js";
+import { n as planResource } from "./resource-BqNqlYg9.js";
+import { n as pageQuery, r as pageSchema } from "./resource-schemas-BJ518zFH.js";
+import { ROW_EVENT_TYPES } from "./events/index.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 void 0;
+	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/events.ts
+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 realtime.tables`
+			});
+			continue;
+		}
+		const id = `table${keyPart(key)}`;
+		const base = `bs: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}` }
+		});
+	}
+}
+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: 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 || 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 }
+		});
+	}
+}
+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 ?? {})) {
+		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/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: [`${PROBLEM_TYPE_BASE}not-found`]
+		},
+		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: {
+	type: `${PROBLEM_TYPE_BASE}forbidden`,
+	title: "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.ts
+const METHODS = /* @__PURE__ */ new Set([
+	"get",
+	"put",
+	"post",
+	"patch",
+	"delete",
+	"head",
+	"options",
+	"trace",
+	"query"
+]);
+function isMethod(value) {
+	return METHODS.has(value);
+}
+const READ_METHODS = /* @__PURE__ */ new Set([
+	"get",
+	"head",
+	"options",
+	"query"
+]);
+/** 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
+	]
+};
+/** 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 void 0;
+	const copy = {};
+	for (const [key, value] of Object.entries(properties)) if (isPlainObject(value)) copy[key] = { ...value };
+	schema["properties"] = copy;
+	return copy;
+}
+const modelCache = /* @__PURE__ */ new WeakMap();
+const NO_PLUGINS = [];
+/**
+* Builds the version-neutral API model once per metadata, plugin list and
+* options object. Formats lower it to each version; `defineApi` wraps it.
+*/
+function buildApiModel(source, options) {
+	const plugins = source.plugins ?? NO_PLUGINS;
+	let byPlugins = modelCache.get(source.meta);
+	if (!byPlugins) {
+		byPlugins = /* @__PURE__ */ new WeakMap();
+		modelCache.set(source.meta, byPlugins);
+	}
+	let byOptions = byPlugins.get(plugins);
+	if (!byOptions) {
+		byOptions = /* @__PURE__ */ new WeakMap();
+		byPlugins.set(plugins, byOptions);
+	}
+	let built = byOptions.get(options);
+	if (!built) {
+		built = build(source.meta, plugins, options);
+		byOptions.set(options, built);
+	}
+	return built;
+}
+function build(meta, plugins, 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 void 0;
+		const all = extend["*"];
+		const own = extend[name];
+		if (!all && !own) return void 0;
+		return mergeJson(all ?? {}, own ?? {});
+	};
+	for (const [key, input] of Object.entries(options.resources ?? {})) {
+		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.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 });
+		for (const operation of plan.operations) 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)}"`);
+		}
+		for (const action of plan.actions) {
+			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)
+				}
+			});
+		}
+	}
+	for (const [index, route] of (options.routes ?? []).entries()) {
+		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 } : {}
+		});
+	}
+	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;
+		});
+	}
+	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)}`
+			});
+		}
+	}
+	if (options.requirePermissions) {
+		for (const operation of operations) if ((operation.source.kind === "resource" ? operation.source.operation !== "list" && operation.source.operation !== "get" : !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);
+	}
+	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
+	};
+}
+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((operation) => operation.source.kind === "action" ? operation.source.action : operation.source.kind === "resource" ? operation.source.operation : operation.id)
+		})),
+		addParameter(table, parameter, names) {
+			for (const operation of served.get(table)?.operations ?? []) {
+				const name = operation.source.kind === "action" ? operation.source.action : operation.source.kind === "resource" ? operation.source.operation : operation.id;
+				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 { safeKey as a, mergeJson as c, CLOUD_EVENT_TRAIT as i, pointerToken as l, DEFAULT_ERRORS as n, convertStandard as o, PROBLEM_SCHEMA as r, pascal as s, buildApiModel as t };