better-supabase 0.7.1 → 0.9.0

package/dist/asyncapi/index.js

@@ -0,0 +1,569 @@
+import { r as isPlainObject } from "../clone-dN9XOL1K.js";
+import { t as SPEC_PINS } from "../spec-pins-S4PymRxp.js";
+import { o as defineDocumentFormat, t as defineApi } from "../api-CFjuYKFY.js";
+import { c as pascal, i as topicsFrom, n as CLOUD_EVENT_TRAIT, r as safeKey, u as pointerToken } from "../build-Cm0T5MVG.js";
+import { t as ASYNCAPI_FILE_NAME } from "../types-BRTSpOIh.js";
+//#region src/asyncapi/format.ts
+const ASYNCAPI_FIELD = {
+	"3.0": SPEC_PINS.asyncapi30,
+	"3.1": SPEC_PINS.asyncapi31
+};
+const SCHEMA_PREFIX = "#/components/schemas/";
+const KEY = /^[A-Za-z0-9_-]+$/;
+const PARAM = /\{([^}]+)\}/g;
+/** JSON Schema 2020-12 keywords the AsyncAPI Schema Object (draft-07) lacks. */
+const KEYWORDS_2020 = /* @__PURE__ */ new Set([
+	"$defs",
+	"$anchor",
+	"$dynamicRef",
+	"$dynamicAnchor",
+	"prefixItems",
+	"dependentSchemas",
+	"dependentRequired",
+	"unevaluatedProperties",
+	"unevaluatedItems"
+]);
+/** The query Supabase Realtime reads on the websocket upgrade. */
+const WS_BINDING = { ws: {
+	method: "GET",
+	query: {
+		type: "object",
+		required: ["apikey"],
+		properties: {
+			apikey: {
+				type: "string",
+				description: "The project's publishable (anon) key."
+			},
+			vsn: {
+				type: "string",
+				description: "Realtime protocol version."
+			}
+		}
+	},
+	bindingVersion: "0.1.0"
+} };
+const STANDARD_WEBHOOK_HEADERS = {
+	type: "object",
+	required: [
+		"webhook-id",
+		"webhook-timestamp",
+		"webhook-signature"
+	],
+	properties: {
+		"webhook-id": {
+			type: "string",
+			description: "Unique message id; the same on every retry."
+		},
+		"webhook-timestamp": {
+			type: "string",
+			pattern: "^[0-9]+$",
+			description: "Unix time in seconds when the message was sent."
+		},
+		"webhook-signature": {
+			type: "string",
+			description: "Space-separated signatures of `id.timestamp.body`, each `v1,<base64>`."
+		}
+	}
+};
+const omitUndefined = (value) => Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== void 0));
+function collectRefs(value, out) {
+	if (Array.isArray(value)) for (const item of value) collectRefs(item, out);
+	else if (isPlainObject(value)) for (const [key, item] of Object.entries(value)) if (key === "$ref" && typeof item === "string") out.add(item);
+	else collectRefs(item, out);
+}
+function uses2020(value) {
+	if (Array.isArray(value)) return value.some(uses2020);
+	if (!isPlainObject(value)) return false;
+	return Object.entries(value).some(([key, item]) => KEYWORDS_2020.has(key) || uses2020(item));
+}
+/** Component names a set of values references, with everything they reference. */
+function referencedSchemas(model, roots) {
+	const out = {};
+	const pending = [];
+	const visit = (value) => {
+		const refs = /* @__PURE__ */ new Set();
+		collectRefs(value, refs);
+		for (const ref of refs) {
+			if (!ref.startsWith(SCHEMA_PREFIX)) continue;
+			const name = ref.slice(21).replaceAll("~1", "/").replaceAll("~0", "~");
+			if (name in out || !model.schemas[name]) continue;
+			out[name] = model.schemas[name];
+			pending.push(name);
+		}
+	};
+	for (const root of roots) visit(root);
+	while (pending.length > 0) {
+		const name = pending.pop();
+		if (name !== void 0) visit(out[name]);
+	}
+	const sorted = {};
+	for (const name of Object.keys(out).toSorted()) {
+		const schema = out[name];
+		if (schema) sorted[name] = structuredClone(schema);
+	}
+	return sorted;
+}
+function lowerScheme(name, scheme, ctx) {
+	switch (scheme.type) {
+		case "http": return omitUndefined({ ...scheme });
+		case "apiKey": return omitUndefined({
+			type: "httpApiKey",
+			name: scheme.name,
+			in: scheme.in,
+			description: scheme.description
+		});
+		case "openIdConnect": return omitUndefined({ ...scheme });
+		case "oauth2": {
+			const flows = {};
+			for (const [flow, value] of Object.entries(scheme.flows)) {
+				const { scopes, ...rest } = value;
+				flows[flow] = omitUndefined({
+					...rest,
+					availableScopes: { ...scopes }
+				});
+			}
+			return omitUndefined({
+				type: "oauth2",
+				description: scheme.description,
+				flows
+			});
+		}
+		case "profile":
+			ctx.report({
+				code: "asyncapi-security-unsupported",
+				severity: "info",
+				message: `Security scheme "${name}" uses Security Profiles, which AsyncAPI cannot describe; it is left out`,
+				pointer: `/components/securitySchemes/${pointerToken(name)}`
+			});
+			return;
+		default: return scheme;
+	}
+}
+function lowerMessage(message, prefix) {
+	return omitUndefined({
+		name: message.name,
+		title: message.title,
+		summary: message.summary,
+		description: message.description,
+		contentType: message.contentType,
+		headers: message.headers ? structuredClone(message.headers) : void 0,
+		payload: structuredClone(message.payload),
+		correlationId: message.correlationId ? { location: message.correlationId } : void 0,
+		traits: message.traits?.map((trait) => ({ $ref: `#/components/messageTraits/${safeKey(trait)}` })),
+		...Object.fromEntries(Object.entries(message.extensions ?? {}).map(([key, value]) => [key.startsWith("x-") ? key : `${prefix}${key}`, value]))
+	});
+}
+function lowerTrait(trait) {
+	return omitUndefined({
+		...trait,
+		headers: trait.headers ? structuredClone(trait.headers) : void 0
+	});
+}
+function webhookMessage(webhook) {
+	return {
+		id: `webhook${safeKey(pascal(webhook.id))}`,
+		name: webhook.id,
+		title: webhook.id,
+		...webhook.summary ? { summary: webhook.summary } : {},
+		...webhook.description ? { description: webhook.description } : {},
+		contentType: "application/json",
+		...webhook.standardWebhooks ? { headers: STANDARD_WEBHOOK_HEADERS } : {},
+		payload: webhook.payload
+	};
+}
+/** A server from a URL: `host` and `pathname` split, the scheme as protocol. */
+function serverFrom(url, fields, wsDefault) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return;
+	}
+	const scheme = parsed.protocol.slice(0, -1);
+	const protocol = wsDefault ? scheme === "http" || scheme === "ws" ? "ws" : "wss" : scheme;
+	const pathname = parsed.pathname === "/" ? void 0 : parsed.pathname;
+	return omitUndefined({
+		host: parsed.host,
+		protocol,
+		pathname,
+		...fields
+	});
+}
+function lowerAsyncApi(model, version, ctx) {
+	const prefix = model.extensionPrefix;
+	const keyOf = (id, where) => {
+		if (KEY.test(id)) return id;
+		const key = safeKey(id);
+		ctx.report({
+			code: "asyncapi-key-invalid",
+			severity: "info",
+			message: `${where} "${id}" is written as "${key}"; AsyncAPI keys allow letters, digits, "_" and "-"`
+		});
+		return key;
+	};
+	const securitySchemes = {};
+	for (const [name, scheme] of Object.entries(model.securitySchemes)) {
+		const lowered = lowerScheme(name, scheme, ctx);
+		if (lowered) securitySchemes[safeKey(name)] = lowered;
+	}
+	const security = [];
+	for (const requirement of model.security) {
+		const names = Object.keys(requirement);
+		if (names.length > 1) ctx.report({
+			code: "asyncapi-security-combined",
+			severity: "info",
+			message: `A requirement that needs ${names.join(" and ")} together is listed as alternatives; AsyncAPI security lists have no AND`,
+			pointer: "/security"
+		});
+		for (const name of names) {
+			const key = safeKey(name);
+			if (key in securitySchemes && !security.some((entry) => entry["$ref"] === `#/components/securitySchemes/${key}`)) security.push({ $ref: `#/components/securitySchemes/${key}` });
+		}
+	}
+	const webhookMessages = model.webhooks.map(webhookMessage);
+	const allMessages = { ...model.messages };
+	for (const message of webhookMessages) allMessages[message.id] = message;
+	const channels = [...model.channels];
+	if (webhookMessages.length > 0) channels.push({
+		id: "webhooks",
+		address: "",
+		title: "Outgoing webhooks",
+		description: "Webhooks the app sends to each receiver's URL, signed per Standard Webhooks when the headers are listed.",
+		protocol: "http",
+		messages: webhookMessages.map((message) => message.id),
+		operations: model.webhooks.map((webhook, index) => ({
+			id: `send${safeKey(pascal(webhook.id))}Webhook`,
+			action: "send",
+			...webhook.summary ? { summary: webhook.summary } : {},
+			messages: [webhookMessages[index]?.id ?? webhook.id]
+		}))
+	});
+	const servers = {};
+	const wsServers = [];
+	const httpServers = [];
+	const hasWs = channels.some((channel) => channel.protocol === "ws");
+	const hasHttp = channels.some((channel) => channel.protocol === "http");
+	if (hasWs && model.realtimeUrl) {
+		const server = serverFrom(model.realtimeUrl, {
+			title: "Supabase Realtime",
+			description: "The Realtime websocket. Private channels need the user's access token.",
+			security: security.length > 0 ? security : void 0
+		}, true);
+		if (server) {
+			servers["realtime"] = server;
+			wsServers.push({ $ref: "#/servers/realtime" });
+		} else ctx.report({
+			code: "asyncapi-realtime-url-invalid",
+			severity: "error",
+			message: `realtimeUrl "${model.realtimeUrl}" is not an absolute URL`,
+			pointer: "/servers/realtime"
+		});
+	} else if (hasWs) ctx.report({
+		code: "asyncapi-server-missing",
+		severity: "warning",
+		message: "Realtime channels are described without a server; set realtimeUrl to add the Realtime websocket",
+		pointer: "/servers"
+	});
+	if (hasHttp) model.servers.forEach((entry, index) => {
+		const key = safeKey(entry.name ?? (index === 0 ? "api" : `api${String(index + 1)}`));
+		const server = serverFrom(entry.url, omitUndefined({ description: entry.description }), false);
+		if (!server || key in servers) return;
+		servers[key] = server;
+		httpServers.push({ $ref: `#/servers/${key}` });
+	});
+	const messageKeys = /* @__PURE__ */ new Map();
+	const messages = {};
+	for (const [id, message] of Object.entries(allMessages)) {
+		const key = keyOf(id, "Message");
+		messageKeys.set(id, key);
+		messages[key] = lowerMessage(message, prefix);
+		if (uses2020(message.payload) || uses2020(message.headers)) ctx.report({
+			code: "asyncapi-schema-dialect",
+			severity: "warning",
+			message: `Message "${id}" uses JSON Schema 2020-12 keywords that the AsyncAPI Schema Object (draft-07) does not define`,
+			pointer: `/components/messages/${pointerToken(key)}`
+		});
+	}
+	const channelObjects = {};
+	const operations = {};
+	const placed = [];
+	const addOperation = (key, operation, pointer) => {
+		if (key in operations) {
+			ctx.report({
+				code: "asyncapi-operation-id-duplicate",
+				severity: "error",
+				message: `Two operations have the id "${key}"; the first one is kept`,
+				pointer
+			});
+			return;
+		}
+		operations[key] = operation;
+	};
+	for (const channel of channels) {
+		const key = keyOf(channel.id, "Channel");
+		if (key in channelObjects) {
+			ctx.report({
+				code: "asyncapi-channel-id-duplicate",
+				severity: "error",
+				message: `Two channels have the id "${key}"; the first one is kept`,
+				pointer: `/channels/${pointerToken(key)}`
+			});
+			continue;
+		}
+		placed.push({
+			key,
+			channel
+		});
+		const channelMessages = {};
+		for (const id of channel.messages) {
+			const messageKey = messageKeys.get(id);
+			if (messageKey === void 0) {
+				ctx.report({
+					code: "asyncapi-message-unknown",
+					severity: "error",
+					message: `Channel "${channel.id}" lists an unknown message "${id}"`,
+					pointer: `/channels/${pointerToken(key)}/messages`
+				});
+				continue;
+			}
+			channelMessages[messageKey] = { $ref: `#/components/messages/${messageKey}` };
+		}
+		const names = [...channel.address.matchAll(PARAM)].map((match) => match[1] ?? "");
+		const parameters = names.length > 0 ? Object.fromEntries(names.map((name) => [name, omitUndefined({ ...channel.parameters?.[name] })])) : void 0;
+		const serverRefs = channel.protocol === "ws" ? wsServers : httpServers;
+		channelObjects[key] = omitUndefined({
+			address: channel.address === "" ? null : channel.address,
+			title: channel.title,
+			summary: channel.summary,
+			description: channel.description,
+			servers: serverRefs.length > 0 ? serverRefs.map((ref) => ({ ...ref })) : void 0,
+			parameters,
+			messages: channelMessages,
+			bindings: channel.protocol === "ws" ? structuredClone(WS_BINDING) : void 0,
+			...channel.extensions
+		});
+		for (const operation of channel.operations) {
+			const operationKey = keyOf(operation.id, "Operation");
+			const refs = [];
+			for (const id of operation.messages ?? []) {
+				const messageKey = messageKeys.get(id);
+				if (messageKey === void 0 || !channel.messages.includes(id)) {
+					ctx.report({
+						code: "asyncapi-operation-message-unknown",
+						severity: "error",
+						message: `Operation "${operation.id}" lists "${id}", which is not a message of channel "${channel.id}"`,
+						pointer: `/operations/${pointerToken(operationKey)}`
+					});
+					continue;
+				}
+				refs.push({ $ref: `#/channels/${key}/messages/${messageKey}` });
+			}
+			addOperation(operationKey, omitUndefined({
+				action: operation.action,
+				channel: { $ref: `#/channels/${key}` },
+				summary: operation.summary,
+				description: operation.description,
+				messages: operation.messages ? refs : void 0,
+				[`${prefix}permission`]: operation.permission,
+				...operation.extensions
+			}), `/operations/${pointerToken(operationKey)}`);
+		}
+	}
+	for (const operation of model.operations) {
+		const emits = operation.extensions[`${prefix}emits`];
+		if (!Array.isArray(emits)) continue;
+		const byChannel = /* @__PURE__ */ new Map();
+		for (const event of emits) {
+			if (typeof event !== "string") continue;
+			const target = placed.find(({ channel }) => channel.messages.some((id) => {
+				const message = allMessages[id];
+				return id === event || message?.name === event || message?.name?.endsWith(`.${event}`) === true;
+			}));
+			const id = target?.channel.messages.find((candidate) => {
+				const message = allMessages[candidate];
+				return candidate === event || message?.name === event || message?.name?.endsWith(`.${event}`) === true;
+			});
+			if (!target || id === void 0) {
+				ctx.report({
+					code: "asyncapi-emits-unknown",
+					severity: "warning",
+					message: `Operation "${operation.id}" emits "${event}", which no message describes`,
+					pointer: `/operations/${pointerToken(operation.id)}`
+				});
+				continue;
+			}
+			const list = byChannel.get(target.key) ?? [];
+			list.push(messageKeys.get(id) ?? id);
+			byChannel.set(target.key, list);
+		}
+		const many = byChannel.size > 1;
+		for (const [channelKey, keys] of byChannel) {
+			const operationKey = safeKey(many ? `${operation.id}Emits${pascal(channelKey)}` : `${operation.id}Emits`);
+			addOperation(operationKey, {
+				action: "send",
+				channel: { $ref: `#/channels/${channelKey}` },
+				summary: `Events sent by ${operation.method.toUpperCase()} ${operation.path}`,
+				messages: [...new Set(keys)].map((messageKey) => ({ $ref: `#/channels/${channelKey}/messages/${messageKey}` })),
+				[`${prefix}operation`]: operation.id
+			}, `/operations/${pointerToken(operationKey)}`);
+		}
+	}
+	const traits = {};
+	for (const [name, trait] of Object.entries(model.messageTraits ?? {})) traits[safeKey(name)] = lowerTrait(trait);
+	const schemas = referencedSchemas(model, [Object.values(messages), Object.values(traits)]);
+	const { info } = model;
+	const document = omitUndefined({
+		asyncapi: ASYNCAPI_FIELD[version],
+		info: omitUndefined({
+			title: info.title,
+			version: info.version,
+			description: info.description ?? info.summary,
+			termsOfService: info.termsOfService,
+			contact: info.contact ? omitUndefined({ ...info.contact }) : void 0,
+			license: info.license ? omitUndefined({
+				name: info.license.name,
+				url: info.license.url
+			}) : void 0
+		}),
+		defaultContentType: "application/json",
+		servers: Object.keys(servers).length > 0 ? servers : void 0,
+		channels: channelObjects,
+		operations,
+		components: omitUndefined({
+			schemas: Object.keys(schemas).length > 0 ? schemas : void 0,
+			messages: Object.keys(messages).length > 0 ? messages : void 0,
+			messageTraits: Object.keys(traits).length > 0 ? traits : void 0,
+			securitySchemes: Object.keys(securitySchemes).length > 0 ? securitySchemes : void 0
+		})
+	});
+	if (!isAsyncApiDocument(document)) throw new TypeError("better-supabase/asyncapi: lowering lost a required field");
+	return document;
+}
+function isAsyncApiDocument(value) {
+	return typeof value["asyncapi"] === "string" && isPlainObject(value["info"]) && isPlainObject(value["channels"]) && isPlainObject(value["operations"]) && isPlainObject(value["components"]);
+}
+function resolve(document, ref) {
+	if (!ref.startsWith("#/")) return;
+	let node = document;
+	for (const raw of ref.slice(2).split("/")) {
+		const key = raw.replaceAll("~1", "/").replaceAll("~0", "~");
+		if (!isPlainObject(node)) return;
+		node = node[key];
+	}
+	return node;
+}
+function refOf(value) {
+	return isPlainObject(value) && typeof value["$ref"] === "string" ? value["$ref"] : void 0;
+}
+function lintAsyncApi(document) {
+	const diagnostics = [];
+	const refs = /* @__PURE__ */ new Set();
+	collectRefs(document, refs);
+	for (const ref of refs) if (ref.startsWith("#") && resolve(document, ref) === void 0) diagnostics.push({
+		code: "asyncapi-ref-unresolved",
+		severity: "error",
+		message: `$ref "${ref}" does not resolve inside the document`
+	});
+	for (const [key, channel] of Object.entries(document.channels)) {
+		const pointer = `/channels/${pointerToken(key)}`;
+		if (!KEY.test(key)) diagnostics.push({
+			code: "asyncapi-key-invalid",
+			severity: "error",
+			message: `Channel id "${key}" has characters AsyncAPI keys do not allow`,
+			pointer
+		});
+		const address = channel["address"];
+		const names = new Set(typeof address === "string" ? [...address.matchAll(PARAM)].map((match) => match[1] ?? "") : []);
+		const parameters = isPlainObject(channel["parameters"]) ? Object.keys(channel["parameters"]) : [];
+		for (const name of parameters) if (!names.has(name)) diagnostics.push({
+			code: "asyncapi-parameter-unknown",
+			severity: "error",
+			message: `Parameter "${name}" is not in the address of channel "${key}"`,
+			pointer: `${pointer}/parameters`
+		});
+		for (const name of names) if (!parameters.includes(name)) diagnostics.push({
+			code: "asyncapi-parameter-missing",
+			severity: "error",
+			message: `Address expression "{${name}}" of channel "${key}" has no parameter`,
+			pointer: `${pointer}/parameters`
+		});
+	}
+	for (const [key, operation] of Object.entries(document.operations)) {
+		const pointer = `/operations/${pointerToken(key)}`;
+		const channelRef = refOf(operation["channel"]);
+		if (!channelRef?.startsWith("#/channels/")) {
+			diagnostics.push({
+				code: "asyncapi-operation-channel-unknown",
+				severity: "error",
+				message: `Operation "${key}" does not reference a root channel`,
+				pointer: `${pointer}/channel`
+			});
+			continue;
+		}
+		const list = Array.isArray(operation["messages"]) ? operation["messages"] : [];
+		for (const entry of list) if (!refOf(entry)?.startsWith(`${channelRef}/messages/`)) diagnostics.push({
+			code: "asyncapi-operation-message-unknown",
+			severity: "error",
+			message: `Operation "${key}" lists a message outside its channel`,
+			pointer: `${pointer}/messages`
+		});
+	}
+	return diagnostics;
+}
+/**
+* AsyncAPI as a `DocumentFormat`, for the events the API model describes:
+* Realtime table change signals and broadcast topics on the Supabase
+* Realtime websocket (`ws` bindings), CloudEvents (headers as the
+* `cloudEvent` message trait), outgoing webhooks over HTTP and the events
+* HTTP operations emit. 3.0 is the default; 3.1 only adds `ros2` bindings,
+* so the two documents differ in the `asyncapi` field.
+*/
+const asyncapiFormat = defineDocumentFormat({
+	id: "asyncapi",
+	versions: {
+		"3.0": {
+			pin: SPEC_PINS.asyncapi30,
+			status: "stable"
+		},
+		"3.1": {
+			pin: SPEC_PINS.asyncapi31,
+			status: "stable"
+		}
+	},
+	defaultVersion: "3.0",
+	lower: lowerAsyncApi,
+	lint: lintAsyncApi,
+	fileName: () => ASYNCAPI_FILE_NAME
+});
+//#endregion
+//#region src/asyncapi/index.ts
+/**
+* An AsyncAPI document for the app's events: Realtime table change signals
+* and broadcast topics, CloudEvents for row and block events, outgoing
+* webhooks and the events HTTP operations emit. Pass `events` (and
+* `realtimeUrl` for the websocket server). Throws when building or checking
+* the document finds an error; use `defineApi(...).render(asyncapiFormat)`
+* to read every finding instead.
+*
+* ```ts
+* const doc = createAsyncApi(betterSupabase, {
+*   info: { title: "CRM events", version: "1.0.0" },
+*   realtimeUrl: "wss://example.supabase.co/realtime/v1/websocket",
+*   events: { tables: ["customers"], cloudEvents: { source: "/crm", blocks: { "support.started": true } } },
+* });
+* ```
+*/
+function createAsyncApi(betterSupabase, options) {
+	const { version, transform, overlays, onDiagnostic, ...apiOptions } = options;
+	const result = defineApi(betterSupabase, apiOptions).render(asyncapiFormat, {
+		...version === void 0 ? {} : { version },
+		...transform === void 0 ? {} : { transform: (rendered) => transform(rendered) },
+		...overlays === void 0 ? {} : { overlays }
+	});
+	const errors = result.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+	if (errors.length > 0) throw new TypeError(`createAsyncApi: ${errors.map((error) => `${error.code}: ${error.message}${error.pointer ? ` (${error.pointer})` : ""}`).join("; ")}`);
+	if (onDiagnostic) for (const diagnostic of result.diagnostics) onDiagnostic(diagnostic);
+	return result.document;
+}
+//#endregion
+export { ASYNCAPI_FILE_NAME, CLOUD_EVENT_TRAIT, asyncapiFormat, createAsyncApi, topicsFrom };