better-supabase 0.8.0 → 0.9.0

package/dist/resource-C8r5xGqY.js

@@ -0,0 +1,463 @@
+import { n as dbError, o as isDbError } from "./errors-8i6tSICm.js";
+import { a as ok, r as err, s as toDbError } from "./result-BlgnMB0H.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { n as validate } from "./standard-B5fe2gnW.js";
+import { a as methodNotAllowed } from "./problem-pIiL3WbE.js";
+import { a as respond, i as isResult } from "./respond-DdhZ9Wbn.js";
+import { n as checkPermission, t as checkEach } from "./authorizer-DH7DjkL3.js";
+import { n as planResource, t as matchAction } from "./resource-DO4gbVi5.js";
+//#region src/server/resource-execute.ts
+async function settled(value) {
+	return await value;
+}
+function failure(cause, message) {
+	if (isDbError(cause)) return err(cause);
+	const error = toDbError(cause);
+	return err(error.kind === "unexpected" ? dbError("unexpected", message) : error);
+}
+/** Runs a hook: its `Result` passes through, anything else is an `unexpected` error. */
+async function runHook(name, call) {
+	try {
+		const value = await call();
+		if (!isResult(value)) return err(dbError("unexpected", `The ${name} hook must return a Result`));
+		return value.ok ? ok(value.data) : failure(value.error, `The ${name} hook failed`);
+	} catch (cause) {
+		return failure(cause, `The ${name} hook failed`);
+	}
+}
+/** Runs an action handler: a `Result` unwraps, a plain value is the data. */
+async function runHandler(name, call) {
+	try {
+		const value = await call();
+		if (!isResult(value)) return ok(value);
+		return value.ok ? ok(value.data) : failure(value.error, `The ${name} action failed`);
+	} catch (cause) {
+		return failure(cause, `The ${name} action failed`);
+	}
+}
+/** Defines an action and types its handler's `data` and `query` from the schemas. */
+function defineAction(action) {
+	return action;
+}
+//#endregion
+//#region src/server/resource-http.ts
+const INTEGER = /* @__PURE__ */ new Set([
+	"int2",
+	"int4",
+	"int8"
+]);
+function keyValue(table, raw) {
+	const invalid = err(dbError("invalid_input", `${JSON.stringify(raw)} is not a valid ${table.key} key`));
+	const column = table.columns[table.primaryKey[0]];
+	if (column && INTEGER.has(column.type)) {
+		const value = typeof raw === "string" ? Number(raw) : raw;
+		return typeof value === "number" && Number.isSafeInteger(value) ? ok(value) : invalid;
+	}
+	return typeof raw === "string" && raw !== "" ? ok(raw) : invalid;
+}
+/**
+* A cross-site browser request that needed no CORS preflight: a form post
+* riding on the session cookie. Bearer requests and JSON bodies (which need a
+* preflight) pass, as do requests without an `Origin` (not a browser).
+*/
+function crossSiteSimpleRequest(request) {
+	if (request.method === "GET" || request.method === "HEAD") return false;
+	if (request.headers.has("authorization")) return false;
+	const origin = request.headers.get("origin");
+	if (!origin || origin === new URL(request.url).origin) return false;
+	if (request.headers.get("sec-fetch-site") === "same-origin") return false;
+	const type = request.headers.get("content-type") ?? "";
+	return !/^application\/(?:[\w.+-]+\+)?json\b/iu.test(type);
+}
+async function readBody(request) {
+	try {
+		const body = await request.json();
+		if (typeof body === "object" && body !== null && !Array.isArray(body)) return ok(body);
+	} catch {}
+	return err(dbError("invalid_input", "The request body must be a JSON object"));
+}
+/** Any JSON body; an empty body is `undefined`. */
+async function readJson(request) {
+	const text = await request.text();
+	if (text.trim() === "") return ok(void 0);
+	try {
+		return ok(JSON.parse(text));
+	} catch {
+		return err(dbError("invalid_input", "The request body must be JSON"));
+	}
+}
+/** URL parameters as an object; a repeated name becomes an array. */
+function queryObject(query) {
+	if (!(query instanceof URLSearchParams)) return query ?? {};
+	const values = {};
+	for (const [name, value] of query) {
+		const seen = values[name];
+		values[name] = seen === void 0 ? value : [...Array.isArray(seen) ? seen : [seen], value];
+	}
+	return values;
+}
+function pageArgs(query, max, pagination) {
+	const raw = (name) => {
+		const value = query instanceof URLSearchParams ? query.get(name) : query?.[name];
+		return value === null || value === "" ? void 0 : value;
+	};
+	const read = (name, fallback) => {
+		const value = raw(name);
+		if (value === void 0) return fallback;
+		const number = Number(value);
+		return Number.isSafeInteger(number) && number >= 1 ? number : void 0;
+	};
+	const issues = [];
+	const size = read("size", 50);
+	if (size === void 0 || size > max) issues.push({
+		message: `Must be between 1 and ${max}`,
+		path: ["size"]
+	});
+	const [used, unused] = pagination === "cursor" ? ["after", "page"] : ["page", "after"];
+	if (raw(unused) !== void 0) issues.push({
+		message: `This list pages with \`${used}\``,
+		path: [unused]
+	});
+	const page = read("page", 1);
+	if (pagination === "offset" && page === void 0) issues.push({
+		message: "Must be a positive integer",
+		path: ["page"]
+	});
+	const after = raw("after");
+	if (pagination === "cursor" && after !== void 0 && typeof after !== "string") issues.push({
+		message: "Must be text",
+		path: ["after"]
+	});
+	if (issues.length > 0 || size === void 0) return err(dbError("validation", "Invalid page parameters", { issues }));
+	return pagination === "cursor" ? ok({
+		after: typeof after === "string" ? after : null,
+		size
+	}) : ok({
+		page: page ?? 1,
+		size
+	});
+}
+function asObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? ok(value) : err(dbError("invalid_input", "Expected an object of column values"));
+}
+function splitPath(subpath) {
+	if (typeof subpath !== "string") return ok(subpath);
+	try {
+		return ok(subpath.split("/").filter((segment) => segment !== "").map((segment) => decodeURIComponent(segment)));
+	} catch {
+		return err(dbError("invalid_input", `Malformed path ${subpath}`));
+	}
+}
+function contextOf(db) {
+	const value = "$context" in db ? db.$context : void 0;
+	return isRecord(value) ? value : {};
+}
+/** Whether an action's path fits these segments, whatever the method. */
+function actionFits(action, segments) {
+	return action.segments.length === segments.length && action.segments.every((segment, index) => segment.startsWith("{") ? segments[index] !== "" : segment === segments[index]);
+}
+//#endregion
+//#region src/server/resource.ts
+/**
+* Operations over one table, matching the paths and responses of the API
+* model: `GET/POST /<table>`, `GET/PATCH/DELETE /<table>/{id}` and each
+* action's path. Shared by the HTTP adapters and the MCP table tools.
+*
+* With permissions, the authorizer decides before the repository runs:
+* `get`, `update` and `delete` fetch the row first (under RLS) and pass it
+* as the resource's properties, and `list` keeps only the rows it grants.
+*/
+function defineResource(betterSupabase, table, options = {}, authorizer) {
+	if (options.list && options.list.table !== table) throw new TypeError(`The list query is for "${options.list.table}", not "${table}"`);
+	const plan = planResource(betterSupabase.meta, table, options, authorizer);
+	const { meta, operations, keyParam, pagination, maxPageSize } = plan;
+	const has = (operation) => operations.includes(operation);
+	const extra = options.select === void 0 ? {} : { select: options.select };
+	const list = options.list;
+	const hooks = options.hooks ?? {};
+	const resourceOf = (id, row) => ({
+		type: table,
+		...id === void 0 ? {} : { id: String(id) },
+		...isRecord(row) ? { properties: row } : {}
+	});
+	const permit = (name, db, resource) => {
+		const permission = plan.permissions[name];
+		if (permission === void 0) return ok(void 0);
+		return checkPermission({
+			authorizer,
+			permission,
+			resource,
+			context: contextOf(db)
+		});
+	};
+	const ctxOf = (db, input) => ({
+		db,
+		table,
+		request: input.request,
+		context: contextOf(db)
+	});
+	const after = async (name, ctx, result) => {
+		const run = hooks[name];
+		if (!run || !result.ok) return result;
+		return runHook(name, () => run.call(hooks, ctx, result.data));
+	};
+	const authorize = async (ctx, operation, target) => hooks.authorize ? runHook("authorize", () => hooks.authorize(ctx, operation, target)) : ok(void 0);
+	const repositoryOf = (db) => {
+		const repository = db[table];
+		if (!repository) throw new TypeError(`The db has no "${table}" repository`);
+		return repository;
+	};
+	const key = (raw) => keyParam ? keyValue(meta, raw) : err(dbError("invalid_request", `${table} has no single-column key`));
+	/** Fetches the row a permission decision reads, under the caller's RLS. */
+	const rowFor = async (name, db, id) => {
+		if (plan.permissions[name] === void 0) return ok(void 0);
+		return settled(repositoryOf(db).findById(id));
+	};
+	const filterRows = async (db, result) => {
+		const permission = plan.permissions["list"];
+		if (permission === void 0 || !result.ok) return result;
+		if (!authorizer) {
+			const denied = await checkPermission({
+				authorizer,
+				permission,
+				resource: { type: table },
+				context: contextOf(db)
+			});
+			if (!denied.ok) return denied;
+		}
+		const page = result.data;
+		if (!isRecord(page) || !Array.isArray(page["items"])) return result;
+		const items = page["items"];
+		const granted = await checkEach(authorizer, permission, items.map((row) => resourceOf(keyParam && isRecord(row) ? row[keyParam] : void 0, row)), contextOf(db));
+		return ok({
+			...page,
+			items: items.filter((_, index) => granted[index])
+		});
+	};
+	const execute = async (db, operation, input = {}) => {
+		const repository = repositoryOf(db);
+		if (!has(operation)) return err(dbError("forbidden", `${operation} is not enabled for ${table}`));
+		const ctx = ctxOf(db, input);
+		switch (operation) {
+			case "list": {
+				let run;
+				let query = input.query;
+				if (list) {
+					const parsed = list.parse(input.query ?? {});
+					if (!parsed.ok) return err(dbError("validation", "Invalid list query", { issues: parsed.issues }));
+					query = parsed.value;
+					run = () => settled(list.run(db, parsed.value, extra));
+				} else {
+					const page = pageArgs(input.query, maxPageSize, pagination);
+					if (!page.ok) return page;
+					query = page.data;
+					run = () => settled(repository.paginate({
+						...extra,
+						...page.data,
+						..."page" in page.data ? { count: "exact" } : {}
+					}));
+				}
+				const allowed = await authorize(ctx, "list", { query });
+				if (!allowed.ok) return allowed;
+				return after("afterList", ctx, await filterRows(db, await run()));
+			}
+			case "get": {
+				const id = key(input.id);
+				if (!id.ok) return id;
+				const row = await settled(repository.findById(id.data, extra));
+				if (!row.ok) return row;
+				const permitted = await permit("get", db, resourceOf(id.data, row.data));
+				if (!permitted.ok) return permitted;
+				const allowed = await authorize(ctx, "get", {
+					id: id.data,
+					row: row.data
+				});
+				if (!allowed.ok) return allowed;
+				return after("afterGet", ctx, row);
+			}
+			case "create": {
+				const body = asObject(input.data);
+				if (!body.ok) return body;
+				const data = options.input?.create ? await validate(options.input.create, body.data, "data") : body;
+				if (!data.ok) return data;
+				const permitted = await permit("create", db, resourceOf(void 0, data.data));
+				if (!permitted.ok) return permitted;
+				const allowed = await authorize(ctx, "create", { data: data.data });
+				if (!allowed.ok) return allowed;
+				const values = hooks.beforeCreate ? await runHook("beforeCreate", () => hooks.beforeCreate(ctx, data.data)) : data;
+				if (!values.ok) return values;
+				const created = await settled(repository.create(values.data, extra));
+				return after("afterCreate", ctx, created);
+			}
+			case "update": {
+				const id = key(input.id);
+				if (!id.ok) return id;
+				const body = asObject(input.data);
+				if (!body.ok) return body;
+				const data = options.input?.update ? await validate(options.input.update, body.data, "data") : body;
+				if (!data.ok) return data;
+				const row = await rowFor("update", db, id.data);
+				if (!row.ok) return row;
+				const permitted = await permit("update", db, resourceOf(id.data, row.data));
+				if (!permitted.ok) return permitted;
+				const target = {
+					id: id.data,
+					data: data.data,
+					...row.data === void 0 ? {} : { row: row.data }
+				};
+				const allowed = await authorize(ctx, "update", target);
+				if (!allowed.ok) return allowed;
+				const values = hooks.beforeUpdate ? await runHook("beforeUpdate", () => hooks.beforeUpdate(ctx, data.data, target)) : data;
+				if (!values.ok) return values;
+				const updated = await settled(repository.update(id.data, values.data, extra));
+				return after("afterUpdate", ctx, updated);
+			}
+			case "delete": {
+				const id = key(input.id);
+				if (!id.ok) return id;
+				const row = await rowFor("delete", db, id.data);
+				if (!row.ok) return row;
+				const permitted = await permit("delete", db, resourceOf(id.data, row.data));
+				if (!permitted.ok) return permitted;
+				const target = {
+					id: id.data,
+					...row.data === void 0 ? {} : { row: row.data }
+				};
+				const allowed = await authorize(ctx, "delete", target);
+				if (!allowed.ok) return allowed;
+				if (hooks.beforeDelete) {
+					const before = await runHook("beforeDelete", () => hooks.beforeDelete(ctx, target));
+					if (!before.ok) return before;
+				}
+				return settled(repository.delete(id.data));
+			}
+			default: throw new TypeError(`Unknown operation ${String(operation)}`);
+		}
+	};
+	const action = async (db, name, input = {}) => {
+		const planned = plan.actions.find((candidate) => candidate.name === name);
+		const definition = options.actions?.[name];
+		if (!planned || !definition) return err(dbError("not_found", `${table} has no action ${name}`));
+		let id;
+		if (planned.params.length > 0) {
+			const parsed = key(input.id);
+			if (!parsed.ok) return parsed;
+			id = parsed.data;
+		}
+		let data = input.data;
+		if (planned.input) {
+			const parsed = await validate(planned.input, data, "data");
+			if (!parsed.ok) return parsed;
+			data = parsed.data;
+		}
+		let query = queryObject(input.query);
+		if (planned.query) {
+			const parsed = await validate(planned.query, query, "query");
+			if (!parsed.ok) return parsed;
+			query = parsed.data;
+		}
+		const row = id === void 0 ? ok(void 0) : await rowFor(name, db, id);
+		if (!row.ok) return row;
+		const permitted = await permit(name, db, resourceOf(id, row.data ?? data));
+		if (!permitted.ok) return permitted;
+		const ctx = ctxOf(db, input);
+		const allowed = await authorize(ctx, name, {
+			id,
+			data,
+			query,
+			...row.data === void 0 ? {} : { row: row.data }
+		});
+		if (!allowed.ok) return allowed;
+		return runHandler(name, () => definition.handler(ctx, {
+			id,
+			data,
+			query
+		}));
+	};
+	const collectionMethods = [...has("list") ? ["GET"] : [], ...has("create") ? ["POST"] : []];
+	const itemMethods = [
+		...has("get") ? ["GET"] : [],
+		...has("update") ? ["PATCH"] : [],
+		...has("delete") ? ["DELETE"] : []
+	];
+	const route = async (request, db, segments, actions) => {
+		if (crossSiteSimpleRequest(request)) return [err(dbError("forbidden", "Cross-site requests need Content-Type: application/json or a bearer token", { code: "CROSS_SITE_REQUEST" }))];
+		if (actions && segments.length > 0) {
+			const method = request.method === "HEAD" ? "GET" : request.method;
+			const found = matchAction(plan, method, segments);
+			if (found === "method") return [methodNotAllowed(plan.actions.filter((candidate) => actionFits(candidate, segments)).map((candidate) => candidate.method))];
+			if (found) {
+				const body = method === "GET" ? ok(void 0) : await readJson(request);
+				if (!body.ok) return [body];
+				const id = keyParam ? found.params[keyParam] : void 0;
+				return [await action(db, found.action.name, {
+					id,
+					data: body.data,
+					query: new URL(request.url).searchParams,
+					request
+				}), found.action.status ?? 200];
+			}
+		}
+		if (segments.length === 0) {
+			if (request.method === "GET" && has("list")) return [await execute(db, "list", {
+				query: new URL(request.url).searchParams,
+				request
+			})];
+			if (request.method === "POST" && has("create")) {
+				const body = await readBody(request);
+				return [body.ok ? await execute(db, "create", {
+					data: body.data,
+					request
+				}) : body, 201];
+			}
+			return [methodNotAllowed(collectionMethods)];
+		}
+		if (segments.length > 1 || !keyParam) return [new Response(null, { status: 404 })];
+		const id = segments[0];
+		if (request.method === "GET" && has("get")) return [await execute(db, "get", {
+			id,
+			request
+		})];
+		if (request.method === "PATCH" && has("update")) {
+			const body = await readBody(request);
+			return [body.ok ? await execute(db, "update", {
+				id,
+				data: body.data,
+				request
+			}) : body];
+		}
+		if (request.method === "DELETE" && has("delete")) return [await execute(db, "delete", {
+			id,
+			request
+		})];
+		return [methodNotAllowed(itemMethods)];
+	};
+	const reply = async (routed, respondOptions) => {
+		const [value, status] = await routed();
+		return respond(() => value, status === void 0 ? respondOptions : {
+			...respondOptions,
+			status
+		});
+	};
+	return {
+		table,
+		meta,
+		operations,
+		keyParam,
+		list,
+		pagination,
+		maxPageSize,
+		plan,
+		execute,
+		action,
+		handle(request, db, id, respondOptions = {}) {
+			return reply(() => route(request, db, id === void 0 ? [] : [id], false), respondOptions);
+		},
+		serve(request, db, subpath, respondOptions = {}) {
+			const segments = splitPath(subpath);
+			return reply(async () => segments.ok ? route(request, db, segments.data, true) : [segments], respondOptions);
+		}
+	};
+}
+//#endregion
+export { actionFits as n, defineAction as r, defineResource as t };

package/dist/resource-DO4gbVi5.js

@@ -0,0 +1,91 @@
+//#region src/spec/resource.ts
+const ACTION_NAME = /^[A-Za-z][A-Za-z0-9_]*$/u;
+const RESERVED = /* @__PURE__ */ new Set([
+	"list",
+	"get",
+	"create",
+	"update",
+	"delete"
+]);
+function planAction(table, name, action, keyParam) {
+	if (!ACTION_NAME.test(name) || RESERVED.has(name)) throw new TypeError(`${table}.actions.${name}: use a name of letters, digits and "_" that is not an operation`);
+	if (!action.path.startsWith("/") || action.path === "/") throw new TypeError(`${table}.actions.${name}: the path must start with "/" and name a segment, e.g. "/{id}/send"`);
+	const segments = action.path.slice(1).split("/");
+	const params = [];
+	for (const segment of segments) {
+		const match = /^\{(\w+)\}$/u.exec(segment);
+		if (match) params.push(match[1]);
+		else if (segment === "" || /[{}]/u.test(segment)) throw new TypeError(`${table}.actions.${name}: "${action.path}" has an invalid segment`);
+	}
+	if (params.some((param) => param !== keyParam)) throw new TypeError(`${table}.actions.${name}: the only path parameter is the key ${keyParam ? `"{${keyParam}}"` : "(this table has none)"}`);
+	return {
+		...action,
+		name,
+		params,
+		segments
+	};
+}
+/**
+* Resolves what a resource serves: the operations, the key, paging,
+* actions and permissions. Shared by `defineResource` and the API model.
+*/
+function planResource(schema, table, description = {}, authorizer) {
+	const meta = schema.tables[table];
+	if (!meta) throw new TypeError(`Unknown table "${table}"`);
+	const operations = description.operations ?? (meta.kind === "view" ? ["list", "get"] : [
+		"list",
+		"get",
+		"create",
+		"update",
+		"delete"
+	]);
+	const keyParam = meta.primaryKey.length === 1 ? meta.primaryKey[0] : void 0;
+	const pagination = description.list ? description.list.pagination ?? "cursor" : description.pagination ?? (meta.primaryKey.length > 0 ? "cursor" : "offset");
+	const actions = Object.entries(description.actions ?? {}).map(([name, action]) => planAction(table, name, action, keyParam));
+	const permissions = {};
+	if (description.permissions === true) {
+		if (!authorizer?.forOperation) throw new TypeError(`${table}: permissions: true needs an authorizer with forOperation()`);
+		for (const operation of operations) {
+			const ref = authorizer.forOperation(table, operation);
+			if (ref !== void 0) permissions[operation] = ref;
+		}
+	} else if (description.permissions) {
+		for (const [operation, ref] of Object.entries(description.permissions)) if (ref !== void 0) permissions[operation] = ref;
+	}
+	for (const action of actions) if (action.permission !== void 0) permissions[action.name] = action.permission;
+	return {
+		table,
+		meta,
+		operations,
+		keyParam,
+		pagination,
+		maxPageSize: description.maxPageSize ?? 200,
+		description,
+		actions,
+		permissions
+	};
+}
+/** The action whose method and segments match, with its params. */
+function matchAction(plan, method, segments) {
+	let wrongMethod = false;
+	for (const action of plan.actions) {
+		if (action.segments.length !== segments.length) continue;
+		const params = {};
+		if (!action.segments.every((segment, index) => {
+			const value = segments[index];
+			if (segment.startsWith("{")) {
+				params[segment.slice(1, -1)] = value;
+				return value !== "";
+			}
+			return segment === value;
+		})) continue;
+		if (action.method === method) return {
+			action,
+			params
+		};
+		wrongMethod = true;
+	}
+	return wrongMethod ? "method" : void 0;
+}
+//#endregion
+export { planResource as n, matchAction as t };

package/dist/resource-execute-D0yQ-8WR.d.ts

@@ -0,0 +1,12 @@
+import { n as ResourceActionSpec } from "./resource-B4ka8dDH.js";
+import { i as ResourceContext, n as Parsed, r as ResourceAction, t as ActionArgs } from "./resource-types-D2vEQVXI.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/server/resource-execute.d.ts
+/** Defines an action and types its handler's `data` and `query` from the schemas. */
+declare function defineAction<DbT = unknown, Ref = string, I extends StandardSchemaV1 | undefined = undefined, Q extends StandardSchemaV1 | undefined = undefined>(action: Omit<ResourceActionSpec<Ref>, "input" | "query"> & {
+  readonly input?: I;
+  readonly query?: Q;
+  handler(ctx: ResourceContext<DbT>, args: ActionArgs<Parsed<I>, Parsed<Q>>): unknown;
+}): ResourceAction<Ref, DbT>;
+//#endregion
+export { defineAction as t };