better-supabase 0.0.0 → 0.1.0

package/dist/openapi/index.js

@@ -0,0 +1,332 @@
+import { n as PROBLEM_TYPE_BASE, t as PROBLEM_CONTENT_TYPE } from "../problem-DPu6Fh-t.js";
+import { t as SPEC_PINS } from "../spec-pins-t6sPaHvl.js";
+import { t as buildJsonSchema } from "../json-schema-BbwO2mZg.js";
+//#region src/openapi/index.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" }
+		},
+		issues: {
+			type: "array",
+			items: {
+				type: "object",
+				required: ["message"],
+				properties: {
+					message: { type: "string" },
+					path: {
+						type: "array",
+						items: { type: ["string", "integer"] }
+					}
+				}
+			}
+		}
+	}
+};
+const ERRORS = [
+	[
+		"BadRequest",
+		400,
+		"The request is invalid."
+	],
+	[
+		"Unauthorized",
+		401,
+		"Missing or invalid credentials."
+	],
+	[
+		"Forbidden",
+		403,
+		"Row-level security or a plugin denied the request."
+	],
+	[
+		"NotFound",
+		404,
+		"No row matches."
+	],
+	[
+		"Conflict",
+		409,
+		"A unique or foreign key constraint failed."
+	],
+	[
+		"Unprocessable",
+		422,
+		"Validation or a check constraint failed."
+	]
+];
+const pascal = (value) => value.replace(/(^|[_-])(\w)/g, (_, _sep, char) => char.toUpperCase());
+const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
+const response = (name) => ({ $ref: `#/components/responses/${name}` });
+function errorResponses(codes) {
+	const out = {};
+	for (const [name, status] of ERRORS) if (codes.includes(status)) out[String(status)] = response(name);
+	return out;
+}
+function jsonBody(schema, description) {
+	return {
+		description,
+		content: { "application/json": { schema } }
+	};
+}
+function pageParameters() {
+	return [{
+		name: "page",
+		in: "query",
+		required: false,
+		description: "1-based page number.",
+		schema: {
+			type: "integer",
+			minimum: 1,
+			default: 1
+		}
+	}, {
+		name: "size",
+		in: "query",
+		required: false,
+		description: "Page size.",
+		schema: {
+			type: "integer",
+			minimum: 1,
+			maximum: 200,
+			default: 50
+		}
+	}];
+}
+/**
+* An OpenAPI 3.1 document for REST resources over your tables, with schemas
+* from the generated metadata, list-query parameters, Supabase security
+* schemes and Problem Details errors.
+*
+* ```ts
+* const doc = createOpenApi(sb, {
+*   info: { title: 'CRM API', version: '1.0.0' },
+*   resources: { customers: { list: customerList }, notes: { operations: ['list', 'get'] } },
+* });
+* ```
+*/
+function createOpenApi(sb, options) {
+	const defs = buildJsonSchema({
+		meta: sb.meta,
+		config: { json: options.json ?? {} }
+	})["$defs"];
+	const schemas = { Problem: PROBLEM_SCHEMA };
+	const paths = {};
+	const tags = [];
+	const base = (options.basePath ?? "").replace(/\/$/, "");
+	const security = options.security ?? ["bearer"];
+	for (const [key, raw] of Object.entries(options.resources)) {
+		const table = sb.meta.tables[key];
+		if (!table) throw new TypeError(`createOpenApi: unknown table "${key}"`);
+		const resource = raw === true ? {} : raw;
+		const operations = resource.operations ?? (table.kind === "view" ? ["list", "get"] : [
+			"list",
+			"get",
+			"create",
+			"update",
+			"delete"
+		]);
+		const name = pascal(key);
+		const tag = resource.tag ?? key;
+		if (!tags.some((entry) => entry.name === tag)) tags.push({
+			name: tag,
+			...resource.description ? { description: resource.description } : {}
+		});
+		const extensions = { "x-better-supabase-table": `${table.schema}.${table.name}` };
+		for (const variant of [
+			"Row",
+			"Insert",
+			"Update"
+		]) {
+			const schema = defs[`${key}${variant}`];
+			if (schema) schemas[`${name}${variant}`] = schema;
+		}
+		schemas[`${name}Page`] = {
+			type: "object",
+			required: ["items", "page"],
+			properties: {
+				items: {
+					type: "array",
+					items: ref(`${name}Row`)
+				},
+				page: {
+					type: "object",
+					required: [
+						"number",
+						"size",
+						"total",
+						"pages",
+						"hasMore"
+					],
+					properties: {
+						number: { type: "integer" },
+						size: { type: "integer" },
+						total: { type: ["integer", "null"] },
+						pages: { type: ["integer", "null"] },
+						hasMore: { type: "boolean" }
+					}
+				}
+			}
+		};
+		const collection = `${base}${resource.path ?? `/${key}`}`;
+		const keyColumn = table.primaryKey.length === 1 ? table.primaryKey[0] : void 0;
+		const idSchema = keyColumn ? (defs[`${key}Row`]?.["properties"])?.[keyColumn] ?? { type: "string" } : void 0;
+		const item = keyColumn ? `${collection}/{${keyColumn}}` : void 0;
+		const idParameter = keyColumn ? [{
+			name: keyColumn,
+			in: "path",
+			required: true,
+			schema: idSchema
+		}] : [];
+		const op = (operation, summary, body) => ({
+			operationId: `${operation}${name}`,
+			tags: [tag],
+			summary,
+			...extensions,
+			"x-better-supabase-operation": operation,
+			...body
+		});
+		for (const operation of operations) switch (operation) {
+			case "list":
+				(paths[collection] ??= {})["get"] = op("list", `List ${key}`, {
+					parameters: resource.list?.openapi ?? pageParameters(),
+					responses: {
+						"200": jsonBody(ref(`${name}Page`), `A page of ${key}.`),
+						...errorResponses([
+							400,
+							401,
+							403
+						])
+					}
+				});
+				break;
+			case "create":
+				(paths[collection] ??= {})["post"] = op("create", `Create a ${key} row`, {
+					requestBody: {
+						required: true,
+						content: { "application/json": { schema: ref(`${name}Insert`) } }
+					},
+					responses: {
+						"201": jsonBody(ref(`${name}Row`), "Created."),
+						...errorResponses([
+							400,
+							401,
+							403,
+							409,
+							422
+						])
+					}
+				});
+				break;
+			case "get":
+			case "update":
+			case "delete": {
+				if (!item) break;
+				const path = paths[item] ??= { parameters: idParameter };
+				if (operation === "get") path["get"] = op("get", `Get a ${key} row`, { responses: {
+					"200": jsonBody(ref(`${name}Row`), "The row."),
+					...errorResponses([
+						401,
+						403,
+						404
+					])
+				} });
+				else if (operation === "update") path["patch"] = op("update", `Update a ${key} row`, {
+					requestBody: {
+						required: true,
+						content: { "application/json": { schema: ref(`${name}Update`) } }
+					},
+					responses: {
+						"200": jsonBody(ref(`${name}Row`), "Updated."),
+						...errorResponses([
+							400,
+							401,
+							403,
+							404,
+							409,
+							422
+						])
+					}
+				});
+				else path["delete"] = op("delete", `Delete a ${key} row`, { responses: {
+					"204": { description: "Deleted." },
+					...errorResponses([
+						401,
+						403,
+						404,
+						409
+					])
+				} });
+				break;
+			}
+			default: throw new TypeError(`createOpenApi: unknown operation "${String(operation)}"`);
+		}
+	}
+	const securitySchemes = {};
+	if (security.includes("bearer")) securitySchemes["supabaseJwt"] = {
+		type: "http",
+		scheme: "bearer",
+		bearerFormat: "JWT",
+		description: "A Supabase access token. Requests run as that user under row-level security."
+	};
+	if (security.includes("oauth2")) {
+		if (!options.supabaseUrl) throw new TypeError("createOpenApi: oauth2 security needs supabaseUrl");
+		const auth = `${options.supabaseUrl.replace(/\/$/, "")}/auth/v1`;
+		securitySchemes["supabaseOAuth"] = {
+			type: "oauth2",
+			description: "The Supabase OAuth 2.1 server.",
+			flows: { authorizationCode: {
+				authorizationUrl: `${auth}/oauth/authorize`,
+				tokenUrl: `${auth}/oauth/token`,
+				scopes: {}
+			} }
+		};
+	}
+	const responses = {};
+	for (const [name, , description] of ERRORS) responses[name] = {
+		description,
+		content: { [PROBLEM_CONTENT_TYPE]: { schema: ref("Problem") } }
+	};
+	return {
+		openapi: SPEC_PINS.openapi,
+		info: options.info,
+		jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema",
+		...options.servers ? { servers: options.servers } : {},
+		tags,
+		paths,
+		components: {
+			schemas,
+			responses,
+			securitySchemes
+		},
+		security: Object.keys(securitySchemes).map((name) => ({ [name]: [] }))
+	};
+}
+//#endregion
+export { PROBLEM_SCHEMA, createOpenApi };

package/dist/orpc/index.d.ts

@@ -0,0 +1,46 @@
+import { n as AnyModels, t as AnyFunctions } from "../types-C2fslP1z.js";
+import { o as Result, p as DbError } from "../result-CTkCZ6JA.js";
+import { t as BetterSupabase } from "../define-CTfWw-SS.js";
+import { r as AuthState } from "../resolve-DW8h9NPm.js";
+import { d as ServerContext, f as ServerOptions, l as BetterServer, n as GuardOptions } from "../respond-PoTpy5DT.js";
+import { r as ProblemDetails } from "../problem-DlgB0lYl.js";
+import { DecoratedMiddleware, ORPCError } from "@orpc/server";
+//#region src/orpc/index.d.ts
+/** Initial context: pass `{ context: { request } }` to the oRPC handler. */
+export interface OrpcRequestContext {
+  readonly request: Request;
+}
+/** What `middleware()` adds to `context`. */
+export interface OrpcContext<M extends AnyModels, F extends AnyFunctions, E> {
+  readonly bs: ServerContext<M, F, E>;
+  readonly db: ServerContext<M, F, E>["db"];
+  readonly auth: AuthState;
+}
+export interface OrpcOptions extends ServerOptions {
+  /** Include internal error messages. Defaults to `NODE_ENV === 'development'`. */
+  readonly exposeErrors?: boolean;
+}
+export interface MiddlewareOptions extends GuardOptions {
+  /** Refresh an expired cookie session. Pair with `ctx.bs.resolution.apply` in the handler adapter. */
+  readonly refresh?: boolean;
+}
+export type OrpcMiddleware<M extends AnyModels, F extends AnyFunctions, E> = DecoratedMiddleware<OrpcRequestContext, OrpcContext<M, F, E>, unknown, unknown, Record<never, never>>;
+export interface BetterOrpc<M extends AnyModels, F extends AnyFunctions, E> extends BetterServer<M, F, E> {
+  /**
+   * Resolves the caller, enforces `allow` and adds `context.db`, `context.auth`
+   * and `context.bs`. Thrown `DbException`s, and errors caused by a
+   * `DbError`, become `ORPCError`s.
+   */
+  middleware(options?: MiddlewareOptions): OrpcMiddleware<M, F, E>;
+  /** A `Result` (or `AsyncResult`) as data, throwing an `ORPCError` on failure. */
+  unwrap<T>(value: Result<T> | PromiseLike<Result<T>>): Promise<T>;
+  /** Plain values pass through; thrown `DbException`s become `ORPCError`s. */
+  unwrap<T>(value: T | PromiseLike<T>): Promise<T>;
+  toORPCError(error: DbError): ORPCError<string, ProblemDetails>;
+}
+/** oRPC code for a `DbError`, from its HTTP status. */
+export declare function orpcCode(error: DbError): string;
+/** oRPC integration: middleware adding the caller's repositories to `context`. */
+export declare function createOrpc<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, options?: OrpcOptions): BetterOrpc<M, F, E>;
+//#endregion
+export type { GuardOptions };

package/dist/orpc/index.js

@@ -0,0 +1,50 @@
+import { r as dbErrorOf } from "../errors-Bl3rkOzo.js";
+import { o as toProblem } from "../problem-DPu6Fh-t.js";
+import { a as settle, n as guard, o as createServer, s as extendServer, t as defaultExpose } from "../respond-4-dhoV7x.js";
+import { COMMON_ERROR_STATUS_MAP, ORPCError, os } from "@orpc/server";
+//#region src/orpc/index.ts
+const CODES = new Map(Object.entries(COMMON_ERROR_STATUS_MAP).map(([code, status]) => [status, code]));
+/** oRPC code for a `DbError`, from its HTTP status. */
+function orpcCode(error) {
+	return CODES.get(error.status) ?? (error.status >= 500 ? "INTERNAL_SERVER_ERROR" : "BAD_REQUEST");
+}
+/** oRPC integration: middleware adding the caller's repositories to `context`. */
+function createOrpc(sb, options = {}) {
+	const server = createServer(sb, options);
+	const expose = options.exposeErrors ?? defaultExpose();
+	const toORPCError = (error) => {
+		const problem = toProblem(error, { expose });
+		return new ORPCError(orpcCode(error), {
+			message: problem.detail ?? problem.title,
+			data: problem
+		});
+	};
+	return extendServer(server, {
+		toORPCError,
+		middleware(middlewareOptions = {}) {
+			return os.$context().middleware(async ({ context, next }) => {
+				const ctx = await server.context(context.request, { refresh: middlewareOptions.refresh ?? false });
+				const denied = guard(ctx.auth, middlewareOptions.allow, middlewareOptions.aal);
+				if (denied) throw toORPCError(denied);
+				try {
+					return await next({ context: {
+						bs: ctx,
+						db: ctx.db,
+						auth: ctx.auth
+					} });
+				} catch (cause) {
+					const thrown = dbErrorOf(cause);
+					if (thrown) throw toORPCError(thrown);
+					throw cause;
+				}
+			});
+		},
+		async unwrap(value) {
+			const settled = await settle(() => value);
+			if (!settled.ok) throw toORPCError(settled.error);
+			return settled.data;
+		}
+	});
+}
+//#endregion
+export { createOrpc, orpcCode };

package/dist/otel/index.d.ts

@@ -0,0 +1,40 @@
+import { a as EventHub } from "../events-2OJsVG_d.js";
+import { f as Plugin } from "../plugin-HvGqCurB.js";
+import { t as SPEC_PINS } from "../spec-pins-CJPVghHy.js";
+import { Attributes, Meter, Tracer } from "@opentelemetry/api";
+//#region src/otel/index.d.ts
+export declare const INSTRUMENTATION_NAME = "better-supabase";
+/** OpenTelemetry semantic conventions version the attributes follow. */
+export declare const SEMCONV_VERSION: typeof SPEC_PINS.otelSemconv;
+export interface OtelOptions {
+  readonly tracer?: Tracer;
+  readonly meter?: Meter;
+  /** Extra attributes on every span, e.g. `{ 'service.namespace': 'crm' }`. */
+  readonly attributes?: Attributes;
+  /** Set `false` to skip the duration histogram. */
+  readonly metrics?: boolean;
+}
+/**
+ * Database client spans and metrics for every repository operation, using
+ * the OpenTelemetry database conventions. Filter values and row data are
+ * never recorded; `db.query.summary` is `SELECT customers`.
+ *
+ * ```ts
+ * const sb = defineSupabase(schema).use(otel());
+ * ```
+ */
+export declare function otel(options?: OtelOptions): Plugin<"otel">;
+/**
+ * Spans for auth resolution and session refreshes, from `sb.events`.
+ * Returns a function that stops listening.
+ */
+export declare function traceAuth(sb: {
+  readonly events: EventHub;
+}, options?: Pick<OtelOptions, "tracer" | "attributes">): () => void;
+/**
+ * A `fetch` that adds W3C `traceparent`/`tracestate` from the active
+ * context. Pass it to `createClient(url, key, { global: { fetch } })` so
+ * PostgREST, Auth and Storage calls join the trace.
+ */
+export declare function tracedFetch(base?: typeof fetch): typeof fetch;
+//#endregion

package/dist/otel/index.js

@@ -0,0 +1,168 @@
+import { n as definePlugin } from "../plugin-BqR6wKMB.js";
+import { t as SPEC_PINS } from "../spec-pins-t6sPaHvl.js";
+import "../version-Cqq1m3UY.js";
+import { SpanKind, SpanStatusCode, context, metrics, propagation, trace } from "@opentelemetry/api";
+//#region src/otel/index.ts
+const INSTRUMENTATION_NAME = "better-supabase";
+/** OpenTelemetry semantic conventions version the attributes follow. */
+const SEMCONV_VERSION = SPEC_PINS.otelSemconv;
+const OPERATION_NAME = {
+	select: "SELECT",
+	insert: "INSERT",
+	update: "UPDATE",
+	delete: "DELETE"
+};
+function operationName(op) {
+	if (op.kind === "insert" && op.onConflict?.action === "update") return "UPSERT";
+	if (op.kind === "select" && op.head) return "COUNT";
+	return OPERATION_NAME[op.kind];
+}
+function systemOf(executor) {
+	return executor.name === "postgrest" || executor.name === "postgres" ? "postgresql" : executor.name;
+}
+/**
+* Database client spans and metrics for every repository operation, using
+* the OpenTelemetry database conventions. Filter values and row data are
+* never recorded; `db.query.summary` is `SELECT customers`.
+*
+* ```ts
+* const sb = defineSupabase(schema).use(otel());
+* ```
+*/
+function otel(options = {}) {
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.0.0");
+	let histogram;
+	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.0.0")).createHistogram("db.client.operation.duration", {
+		unit: "s",
+		description: "Duration of database client operations.",
+		advice: { explicitBucketBoundaries: [
+			.001,
+			.005,
+			.01,
+			.05,
+			.1,
+			.5,
+			1,
+			5,
+			10
+		] }
+	});
+	return definePlugin({
+		name: "otel",
+		enforce: "post",
+		wrapExecutor: (executor) => ({
+			...executor,
+			name: executor.name,
+			execute(op, executeContext) {
+				const operation = operationName(op);
+				const summary = `${operation} ${op.table.name}`;
+				const attributes = {
+					...options.attributes,
+					"db.system.name": systemOf(executor),
+					"db.namespace": op.table.schema,
+					"db.collection.name": op.table.name,
+					"db.operation.name": operation,
+					"db.query.summary": summary,
+					"better_supabase.executor": executor.name
+				};
+				const started = performance.now();
+				return tracer.startActiveSpan(summary, {
+					kind: SpanKind.CLIENT,
+					attributes
+				}, async (span) => {
+					const finish = (errorType) => {
+						const metricAttributes = {
+							"db.system.name": attributes["db.system.name"],
+							"db.collection.name": op.table.name,
+							"db.operation.name": operation,
+							...errorType ? { "error.type": errorType } : {}
+						};
+						histogram?.record((performance.now() - started) / 1e3, metricAttributes);
+						span.end();
+					};
+					try {
+						const result = await executor.execute(op, executeContext);
+						if (result.ok) {
+							span.setAttribute("db.response.returned_rows", result.data.rows.length);
+							finish();
+						} else {
+							span.setAttributes({
+								"error.type": result.error.kind,
+								...result.error.code ? { "db.response.status_code": result.error.code } : {}
+							});
+							span.setStatus({
+								code: SpanStatusCode.ERROR,
+								message: result.error.message
+							});
+							finish(result.error.kind);
+						}
+						return result;
+					} catch (cause) {
+						const error = cause instanceof Error ? cause : new Error(String(cause));
+						span.recordException(error);
+						span.setAttribute("error.type", error.name);
+						span.setStatus({
+							code: SpanStatusCode.ERROR,
+							message: error.message
+						});
+						finish(error.name);
+						throw cause;
+					}
+				});
+			}
+		})
+	});
+}
+/**
+* Spans for auth resolution and session refreshes, from `sb.events`.
+* Returns a function that stops listening.
+*/
+function traceAuth(sb, options = {}) {
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.0.0");
+	const offAuth = sb.events.on("auth", (event) => {
+		const span = tracer.startSpan("auth.resolve", {
+			kind: SpanKind.INTERNAL,
+			attributes: {
+				...options.attributes,
+				"better_supabase.auth.source": event.source,
+				...event.userId ? { "enduser.id": event.userId } : {}
+			}
+		});
+		if (!event.ok) span.setStatus({ code: SpanStatusCode.ERROR });
+		span.end();
+	});
+	const offRefresh = sb.events.on("refresh", (event) => {
+		const end = Date.now();
+		const span = tracer.startSpan("auth.refresh", {
+			kind: SpanKind.CLIENT,
+			startTime: end - event.durationMs,
+			attributes: {
+				...options.attributes,
+				"better_supabase.refresh.shared": event.shared
+			}
+		});
+		if (!event.ok) span.setStatus({ code: SpanStatusCode.ERROR });
+		span.end(end);
+	});
+	return () => {
+		offAuth();
+		offRefresh();
+	};
+}
+/**
+* A `fetch` that adds W3C `traceparent`/`tracestate` from the active
+* context. Pass it to `createClient(url, key, { global: { fetch } })` so
+* PostgREST, Auth and Storage calls join the trace.
+*/
+function tracedFetch(base = fetch) {
+	return (input, init) => {
+		const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : void 0));
+		propagation.inject(context.active(), headers, { set: (carrier, key, value) => carrier.set(key, value) });
+		return base(input, {
+			...init,
+			headers
+		});
+	};
+}
+//#endregion
+export { INSTRUMENTATION_NAME, SEMCONV_VERSION, otel, traceAuth, tracedFetch };

package/dist/path-Cv__-OTj.d.ts

@@ -0,0 +1,17 @@
+//#region src/storage/path.d.ts
+declare const bucketOf: unique symbol;
+/**
+ * An object path in bucket `B`, e.g. `org-1/cust-1/logo/3.webp`. Returned by
+ * `bucket.path()` and `upload()`, and the type of columns listed in the
+ * `storagePaths` config. Store paths, not URLs: signed URLs expire and public
+ * URLs pin the project host.
+ */
+type StoragePath<B extends string = string> = string & {
+  readonly [bucketOf]: B;
+};
+/** A plain string or a `StoragePath` of bucket `B`; paths of other buckets are rejected. */
+type PathIn<B extends string> = string & {
+  readonly [bucketOf]?: B;
+};
+//#endregion
+export { StoragePath as n, PathIn as t };

package/dist/plugin-BqR6wKMB.js

@@ -0,0 +1,23 @@
+//#region src/core/plugin.ts
+const PLUGIN_API_VERSION = 1;
+const RANK = {
+	pre: 0,
+	normal: 1,
+	post: 2
+};
+/** Plugins in hook order: `pre`, then unmarked in `use()` order, then `post`. */
+function orderPlugins(plugins) {
+	return plugins.map((plugin, index) => ({
+		plugin,
+		index
+	})).sort((a, b) => RANK[a.plugin.enforce ?? "normal"] - RANK[b.plugin.enforce ?? "normal"] || a.index - b.index).map(({ plugin }) => plugin);
+}
+/** Identity helper that fixes `apiVersion` and infers the plugin types. */
+function definePlugin(plugin) {
+	return {
+		...plugin,
+		apiVersion: 1
+	};
+}
+//#endregion
+export { definePlugin as n, orderPlugins as r, PLUGIN_API_VERSION as t };