better-supabase 0.1.0 → 0.3.0

package/dist/{define-QGkq04oe.js → define-DF341GDj.js}

@@ -1,11 +1,14 @@
 import { n as dbError, t as DbException } from "./errors-Bl3rkOzo.js";
-import { a as invalidRequest, c as needsDecoding, o as decodeRows, r as IrBuilder, s as encodeValue } from "./simplify-oHiDKRVQ.js";
-import { i as or, t as and } from "./types-6cYK9pbJ.js";
+import { a as invalidRequest, c as needsDecoding, o as decodeRows, r as IrBuilder, s as encodeValue } from "./simplify-LakqK1vH.js";
+import { n as nowInstant } from "./temporal-BwshQk0W.js";
+import { i as or, n as column, r as not, t as and } from "./types-6cYK9pbJ.js";
 import { i as ok, n as err, o as toDbError, s as withErrorMapper, t as AsyncResult } from "./result-DWXatkd6.js";
-import { t as invalidationTargets } from "./tables-rZxRxNPW.js";
+import { t as invalidationTargets } from "./tables-Dhha3BXM.js";
+import { t as consoleLogger } from "./logger-glM28NVN.js";
 import { r as orderPlugins } from "./plugin-BqR6wKMB.js";
-import { a as postgrestExecutor, n as StatsRecorder, r as recordStats } from "./stats-3iy8u3_P.js";
-import { d as isQuerySpec, f as specTables, n as checkParams, o as isReadSet, r as containsPlaceholder, t as bindParams, u as createSpecs } from "./read-set-DhX2d04c.js";
+import { a as postgrestExecutor, n as StatsRecorder, r as recordStats } from "./stats-D78UQ8Yu.js";
+import { d as isQuerySpec, f as specTables, n as checkParams, o as isReadSet, r as containsPlaceholder, t as bindParams, u as createSpecs } from "./read-set-D0qBcboM.js";
+import { a as toBase64Url, t as base64ToText } from "./base64-CQeB1eSf.js";
 import { t as validate } from "./standard-FUi3Z3-7.js";
 //#region src/core/batch.ts
 /**
@@ -91,26 +94,6 @@ function memoryCache() {
 	};
 }
 //#endregion
-//#region src/core/logger.ts
-const log = (method) => (message, fields) => {
-	if (fields === void 0) console[method](`better-supabase: ${message}`);
-	else console[method](`better-supabase: ${message}`, fields);
-};
-/** The default: `console`, with a `better-supabase:` prefix. */
-const consoleLogger = {
-	debug: log("debug"),
-	info: log("info"),
-	warn: log("warn"),
-	error: log("error")
-};
-const noop = () => {};
-const silentLogger = {
-	debug: noop,
-	info: noop,
-	warn: noop,
-	error: noop
-};
-//#endregion
 //#region src/core/events.ts
 /**
 * Observers only: a handler that throws is reported to the logger and never
@@ -148,27 +131,13 @@ var EventHub = class {
 };
 //#endregion
 //#region src/core/cursor.ts
-const encoder = new TextEncoder();
-const decoder = new TextDecoder();
-function toBase64Url(bytes) {
-	let binary = "";
-	for (const byte of bytes) binary += String.fromCharCode(byte);
-	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function fromBase64Url(text) {
-	const base64 = text.replace(/-/g, "+").replace(/_/g, "/");
-	const binary = atob(base64 + "=".repeat((4 - base64.length % 4) % 4));
-	const bytes = new Uint8Array(binary.length);
-	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
-	return bytes;
-}
 /** Opaque, URL-safe keyset cursor. */
 function encodeCursor(values) {
-	return toBase64Url(encoder.encode(JSON.stringify(values)));
+	return toBase64Url(JSON.stringify(values));
 }
 function decodeCursor(cursor) {
 	try {
-		const parsed = JSON.parse(decoder.decode(fromBase64Url(cursor)));
+		const parsed = JSON.parse(base64ToText(cursor));
 		return Array.isArray(parsed) ? parsed : void 0;
 	} catch {
 		return;
@@ -208,7 +177,7 @@ function optionsOf(args) {
 	return options;
 }
 function signalOf(args) {
-	const signal = args?.signal;
+	const signal = args?.["signal"];
 	return signal instanceof AbortSignal ? signal : void 0;
 }
 function mutationKind(op) {
@@ -252,10 +221,16 @@ var OperationRunner = class {
 		} : { errorMappers: runtime.errorMappers };
 		const executed = await runtime.executor.execute(current, context);
 		const selection = current.kind === "select" ? current.selection : current.returning;
-		const result = executed.ok && selection && needsDecoding(selection) ? ok({
-			...executed.data,
-			rows: decodeRows(selection, executed.data.rows)
-		}) : executed;
+		let result = executed;
+		if (executed.ok && selection && needsDecoding(selection)) try {
+			result = ok({
+				...executed.data,
+				rows: decodeRows(selection, executed.data.rows)
+			});
+		} catch (cause) {
+			if (cause instanceof DbException) return this.fail(op.table, cause.error);
+			throw cause;
+		}
 		const rows = result.ok ? result.data.rows.length : 0;
 		const truncated = current.kind === "select" && current.limit === void 0 && current.single === void 0 && !current.head && rows >= runtime.maxRows;
 		if (truncated && !runtime.truncatedTables.has(op.table.key)) {
@@ -315,21 +290,21 @@ var OperationRunner = class {
 /** Creates the runtime repository object for one table. */
 function createRepository(runner, table) {
 	const { builder } = runner.runtime;
-	const selection = (args) => builder.selection(table, args?.select, args?.include);
+	const selection = (args) => builder.selection(table, args?.["select"], args?.["include"]);
 	const selectOp = (args, patch = {}) => ({
 		kind: "select",
 		table,
 		selection: selection(args),
-		where: builder.where(table, args?.where),
-		orderBy: builder.orderBy(table, args?.orderBy),
-		limit: typeof args?.limit === "number" ? args.limit : void 0,
-		offset: typeof args?.offset === "number" ? args.offset : void 0,
+		where: builder.where(table, args?.["where"]),
+		orderBy: builder.orderBy(table, args?.["orderBy"]),
+		limit: typeof args?.["limit"] === "number" ? args["limit"] : void 0,
+		offset: typeof args?.["offset"] === "number" ? args["offset"] : void 0,
 		count: void 0,
 		head: false,
 		single: void 0,
 		...patch
 	});
-	const returning = (args) => args?.returning === false ? void 0 : selection(args);
+	const returning = (args) => args?.["returning"] === false ? void 0 : selection(args);
 	const run = (op, args) => runner.run(op, optionsOf(args), signalOf(args));
 	const notFound = () => runner.fail(table, dbError("not_found", `No ${table.key} row matched`));
 	const base = {
@@ -358,7 +333,7 @@ function createRepository(runner, table) {
 		findUnique(args) {
 			return AsyncResult.from(async () => {
 				const op = selectOp(args, {
-					where: builder.uniqueKey(table, args.where),
+					where: builder.uniqueKey(table, args["where"]),
 					limit: 1
 				});
 				const result = await run(op, args);
@@ -379,8 +354,8 @@ function createRepository(runner, table) {
 		},
 		count(args) {
 			return AsyncResult.from(async () => {
-				const mode = args?.mode;
-				const op = selectOp({ where: args?.where }, {
+				const mode = args?.["mode"];
+				const op = selectOp({ where: args?.["where"] }, {
 					selection: {
 						columns: [],
 						includes: []
@@ -395,28 +370,28 @@ function createRepository(runner, table) {
 		aggregate(args) {
 			return AsyncResult.from(async () => {
 				const aggregation = builder.aggregation(table, args);
-				const orderBy = builder.orderBy(table, args.orderBy);
+				const orderBy = builder.orderBy(table, args["orderBy"]);
 				const grouped = new Set(aggregation.columns.map((c) => c.column));
 				const loose = orderBy.find((term) => !grouped.has(term.column));
 				if (loose) return runner.fail(table, dbError("invalid_request", `aggregate on "${table.key}" can only sort by groupBy columns, not "${loose.column}"`));
 				const op = selectOp({
-					where: args.where,
-					limit: args.limit,
-					offset: args.offset
+					where: args["where"],
+					limit: args["limit"],
+					offset: args["offset"]
 				}, {
 					selection: aggregation,
 					orderBy
 				});
 				const result = await run(op, args);
 				if (!result.ok) return result;
-				if (args.groupBy !== void 0) return ok(result.data.rows);
+				if (args["groupBy"] !== void 0) return ok(result.data.rows);
 				return ok(result.data.rows[0] ?? decodeRows(aggregation, [{}])[0] ?? {});
 			});
 		},
 		exists(args) {
 			return AsyncResult.from(async () => {
 				const columns = table.primaryKey.slice(0, 1).map((alias) => builder.selectColumn(table, alias));
-				const op = selectOp({ where: args?.where }, {
+				const op = selectOp({ where: args?.["where"] }, {
 					selection: {
 						columns,
 						includes: []
@@ -435,21 +410,21 @@ function createRepository(runner, table) {
 				const op = insertOp([data], args, void 0);
 				const result = await run(op, args);
 				if (!result.ok) return result;
-				return ok(args?.returning === false ? null : result.data.rows[0] ?? null);
+				return ok(args?.["returning"] === false ? null : result.data.rows[0] ?? null);
 			});
 		},
 		createMany(rows, args) {
 			return AsyncResult.from(async () => {
-				if (rows.length === 0) return ok(args?.returning === false ? { count: 0 } : []);
+				if (rows.length === 0) return ok(args?.["returning"] === false ? { count: 0 } : []);
 				const result = await run(insertOp(rows, args, void 0), args);
 				if (!result.ok) return result;
-				return ok(args?.returning === false ? { count: result.data.count ?? rows.length } : result.data.rows);
+				return ok(args?.["returning"] === false ? { count: result.data.count ?? rows.length } : result.data.rows);
 			});
 		},
 		update(id, patch, args) {
 			return AsyncResult.from(async () => {
 				const key = builder.primaryKey(table, id);
-				const expect = args?.expect ? builder.where(table, args.expect) : void 0;
+				const expect = args?.["expect"] ? builder.where(table, args["expect"]) : void 0;
 				const op = {
 					kind: "update",
 					table,
@@ -481,8 +456,8 @@ function createRepository(runner, table) {
 				const op = {
 					kind: "update",
 					table,
-					set: builder.row(table, args.data, "update"),
-					where: builder.where(table, args.where),
+					set: builder.row(table, args["data"], "update"),
+					where: builder.where(table, args["where"]),
 					returning: void 0
 				};
 				const result = await run(op, args);
@@ -491,19 +466,19 @@ function createRepository(runner, table) {
 		},
 		upsert(data, args) {
 			return AsyncResult.from(async () => {
-				const op = insertOp([data], args, conflictColumns(args?.onConflict));
+				const op = insertOp([data], args, conflictColumns(args?.["onConflict"]));
 				const result = await run(op, args);
 				if (!result.ok) return result;
-				return ok(args?.returning === false ? null : result.data.rows[0] ?? null);
+				return ok(args?.["returning"] === false ? null : result.data.rows[0] ?? null);
 			});
 		},
 		upsertMany(rows, args) {
 			return AsyncResult.from(async () => {
-				if (rows.length === 0) return ok(args?.returning === false ? { count: 0 } : []);
-				const op = insertOp(rows, args, conflictColumns(args?.onConflict));
+				if (rows.length === 0) return ok(args?.["returning"] === false ? { count: 0 } : []);
+				const op = insertOp(rows, args, conflictColumns(args?.["onConflict"]));
 				const result = await run(op, args);
 				if (!result.ok) return result;
-				return ok(args?.returning === false ? { count: result.data.count ?? rows.length } : result.data.rows);
+				return ok(args?.["returning"] === false ? { count: result.data.count ?? rows.length } : result.data.rows);
 			});
 		},
 		delete(id, args) {
@@ -521,7 +496,7 @@ function createRepository(runner, table) {
 		},
 		deleteMany(args) {
 			return AsyncResult.from(async () => {
-				const where = builder.where(table, args.where);
+				const where = builder.where(table, args["where"]);
 				if (!where) return runner.fail(table, dbError("invalid_request", "deleteMany needs a non-empty \"where\""));
 				const result = await run({
 					kind: "delete",
@@ -534,14 +509,15 @@ function createRepository(runner, table) {
 		}
 	};
 	function insertOp(rows, args, conflict) {
+		const built = rows.map((row) => builder.row(table, row));
 		return {
 			kind: "insert",
 			table,
-			rows: rows.map((row) => builder.row(table, row)),
+			rows: conflict && built.length > 1 ? byKey(built, conflict) : built,
 			returning: returning(args),
 			onConflict: conflict ? {
 				columns: conflict,
-				action: args?.ignoreDuplicates === true ? "ignore" : "update"
+				action: args?.["ignoreDuplicates"] === true ? "ignore" : "update"
 			} : void 0,
 			defaultToNull: false
 		};
@@ -557,11 +533,11 @@ function createRepository(runner, table) {
 		return invalidRequest(`Invalid onConflict on "${table.key}"`, table.key);
 	}
 	async function offsetPage(args) {
-		const size = Number(args.size);
+		const size = Number(args["size"]);
 		if (!Number.isInteger(size) || size < 1) return runner.fail(table, dbError("invalid_request", "\"size\" must be a positive integer"));
-		const number = args.page === void 0 ? 1 : Number(args.page);
+		const number = args["page"] === void 0 ? 1 : Number(args["page"]);
 		if (!Number.isInteger(number) || number < 1) return runner.fail(table, dbError("invalid_request", "\"page\" must be a positive integer"));
-		const count = args.count;
+		const count = args["count"];
 		const op = selectOp(args, {
 			limit: size + 1,
 			offset: (number - 1) * size,
@@ -583,19 +559,19 @@ function createRepository(runner, table) {
 		});
 	}
 	async function cursorPage(args) {
-		const size = Number(args.size);
+		const size = Number(args["size"]);
 		if (!Number.isInteger(size) || size < 1) return runner.fail(table, dbError("invalid_request", "\"size\" must be a positive integer"));
-		const orderBy = withTieBreaker(builder.orderBy(table, args.orderBy));
+		const orderBy = withTieBreaker(builder.orderBy(table, args["orderBy"]));
 		const { selection: withSort, added } = ensureColumns(selection(args), orderBy);
 		let after;
-		if (typeof args.after === "string") {
-			const values = decodeCursor(args.after);
+		if (typeof args["after"] === "string") {
+			const values = decodeCursor(args["after"]);
 			if (!values || values.length !== orderBy.length) return runner.fail(table, dbError("invalid_request", "Invalid cursor"));
-			after = keysetCondition(orderBy, values);
+			after = keysetCondition(orderBy, values, (name) => Object.values(table.columns).find((meta) => meta.db === name)?.nullable ?? true);
 		}
 		const op = selectOp(args, {
 			selection: withSort,
-			where: and(builder.where(table, args.where), after),
+			where: and(builder.where(table, args["where"]), after),
 			orderBy,
 			limit: size + 1,
 			offset: void 0
@@ -653,24 +629,47 @@ function strip(row, keys) {
 	for (const key of keys) delete copy[key];
 	return copy;
 }
-/** `(a, b) > (x, y)` for mixed directions, as an OR of ANDs. */
-function keysetCondition(orderBy, values) {
-	const branches = orderBy.map((term, index) => {
-		const equal = orderBy.slice(0, index).map((prev, prevIndex) => ({
-			kind: "column",
-			column: prev.column,
-			op: "eq",
-			value: values[prevIndex]
-		}));
-		const step = {
-			kind: "column",
-			column: term.column,
-			op: term.direction === "asc" ? "gt" : "lt",
-			value: values[index]
-		};
-		return and(...equal, step) ?? step;
+/**
+* Rows in conflict-key order, so concurrent upserts lock the same rows in
+* the same order instead of deadlocking.
+*/
+function byKey(rows, columns) {
+	const compare = (left, right) => {
+		if (left === right) return 0;
+		if (left === null || left === void 0) return 1;
+		if (right === null || right === void 0) return -1;
+		if (typeof left === "number" && typeof right === "number") return left - right;
+		if (typeof left === "bigint" && typeof right === "bigint") return left < right ? -1 : 1;
+		const a = String(left);
+		const b = String(right);
+		return a < b ? -1 : a > b ? 1 : 0;
+	};
+	return [...rows].sort((left, right) => {
+		for (const column of columns) {
+			const order = compare(left[column], right[column]);
+			if (order !== 0) return order;
+		}
+		return 0;
+	});
+}
+/**
+* The rows after the cursor `values` in `orderBy` order, as an OR of ANDs:
+* `a > x or (a = x and b > y)`. The SQL compiler sends that shape as the row
+* comparison `(a, b) > (x, y)`. Nulls sort where Postgres puts them: last
+* for `asc`, first for `desc`, unless the term says otherwise.
+*/
+function keysetCondition(orderBy, values, nullable) {
+	const isNull = (name) => column(name, "is", null);
+	const branches = orderBy.flatMap((term, index) => {
+		const value = values[index];
+		const nullsFirst = (term.nulls ?? (term.direction === "desc" ? "first" : "last")) === "first";
+		const after = column(term.column, term.direction === "asc" ? "gt" : "lt", value);
+		const step = value === null ? nullsFirst ? not(isNull(term.column)) : void 0 : nullsFirst || !nullable(term.column) ? after : or(after, isNull(term.column));
+		if (!step) return [];
+		const equal = orderBy.slice(0, index).map((prev, prevIndex) => values[prevIndex] === null ? isNull(prev.column) : column(prev.column, "eq", values[prevIndex]));
+		return [and(...equal, step) ?? step];
 	});
-	return or(...branches);
+	return branches.length > 0 ? or(...branches) : column(orderBy[0]?.column ?? "", "in", []);
 }
 //#endregion
 //#region src/core/search.ts
@@ -707,6 +706,10 @@ var BetterSupabase = class BetterSupabase {
 	get claimsSchema() {
 		return this.options.claims;
 	}
+	/** The schema set by `userMetadata()`; its output types `session.profile`. */
+	get userMetadataSchema() {
+		return this.options.userMetadata;
+	}
 	/**
 	* Returns a new instance whose servers validate verified JWT claims (custom
 	* access token hook output) with `schema`, and whose sessions are typed by it.
@@ -723,6 +726,24 @@ var BetterSupabase = class BetterSupabase {
 		}, this.events);
 	}
 	/**
+	* Returns a new instance whose sessions parse `user_metadata` with
+	* `schema` into a typed `session.profile`. Users can change their metadata
+	* with `auth.updateUser()`, so a failure only leaves `profile` undefined
+	* (with one warning), and no authorization code reads it. It is for
+	* display only: roles, memberships, the tenant and entitlements come from
+	* the verified claims, never from `profile`.
+	*
+	* ```ts
+	* const sb = defineSupabase(schema).userMetadata(z.object({ display_name: z.string() }));
+	* ```
+	*/
+	userMetadata(schema) {
+		return new BetterSupabase(this.schema, this.plugins, {
+			...this.options,
+			userMetadata: schema
+		}, this.events);
+	}
+	/**
 	* Returns a new instance whose `.orThrow()` throws `mapper(error)` instead
 	* of a `DbException`, and whose results `toBetterResult` maps the same way.
 	* Results themselves keep their `DbError`.
@@ -793,7 +814,9 @@ var BetterSupabase = class BetterSupabase {
 		const invalidate = (target) => {
 			try {
 				const pending = adapter.invalidate(target);
-				if (pending) pending.catch((cause) => report(cause, target.table));
+				if (pending) pending.catch((cause) => {
+					report(cause, target.table);
+				});
 			} catch (cause) {
 				report(cause, target.table);
 			}
@@ -828,7 +851,7 @@ var BetterSupabase = class BetterSupabase {
 			context,
 			events,
 			errorMappers,
-			now: this.options.now ?? (() => /* @__PURE__ */ new Date()),
+			now: this.options.now ?? nowInstant,
 			maxRows: this.options.maxRows ?? 1e3,
 			truncatedTables: this.#truncatedTables
 		});
@@ -982,15 +1005,15 @@ var BetterSupabase = class BetterSupabase {
 			const rows = entry.rows ?? [];
 			const result = await runSpec(this.#db(client, {
 				name: "read-set",
-				execute: async (op) => {
+				execute: (op) => {
 					if (op.kind === "select" && op.single) {
-						if (rows.length > 1) return err(dbError("multiple_rows", `Expected one ${op.table.key} row`));
-						if (rows.length === 0 && op.single === "one") return err(dbError("not_found", `No ${op.table.key} row matched`));
+						if (rows.length > 1) return Promise.resolve(err(dbError("multiple_rows", `Expected one ${op.table.key} row`)));
+						if (rows.length === 0 && op.single === "one") return Promise.resolve(err(dbError("not_found", `No ${op.table.key} row matched`)));
 					}
-					return ok({
+					return Promise.resolve(ok({
 						rows,
 						count: entry.count ?? null
-					});
+					}));
 				}
 			}, context, [], new StatsRecorder(), new EventHub(this.events.logger)), spec, void 0);
 			if (!result.ok) return result;
@@ -1011,7 +1034,7 @@ var BetterSupabase = class BetterSupabase {
 				repository[name] = method;
 			}
 		}
-		repository.extend = (build) => ({
+		repository["extend"] = (build) => ({
 			...repository,
 			...build(repository)
 		});
@@ -1065,4 +1088,4 @@ function defineSupabase(schema, options) {
 	return new BetterSupabase(schema, [], options);
 }
 //#endregion
-export { EventHub as a, cacheTargetOf as c, rpcCacheTargets as d, encodeCursor as i, memoryCache as l, defineSupabase as n, consoleLogger as o, decodeCursor as r, silentLogger as s, BetterSupabase as t, rowKey as u };
+export { EventHub as a, rowKey as c, encodeCursor as i, rpcCacheTargets as l, defineSupabase as n, cacheTargetOf as o, decodeCursor as r, memoryCache as s, BetterSupabase as t };

package/dist/{define-CTfWw-SS.d.ts → define-DUbydmJa.d.ts}

@@ -1,10 +1,11 @@
-import { A as TableMeta, C as Relations, D as Simplify, E as SchemaMeta, M as UniqueKeyName, N as UniqueWhere, P as Update, S as RelationShape, T as Schema, h as Insert, k as TableKey, n as AnyModels, t as AnyFunctions, w as Row, y as PrimaryKeyValue } from "./types-C2fslP1z.js";
-import { g as Operation, l as CountMode, r as Executor } from "./executor-Bazhgsgq.js";
-import { p as DbError, s as ThrowMapper, t as AsyncResult, v as ErrorMapper } from "./result-CTkCZ6JA.js";
-import { a as EventHub, f as Logger, i as EventHandler, o as EventName, s as MutationNotice, u as RpcNotice } from "./events-2OJsVG_d.js";
-import { a as ExtensionOf, g as WithExtension, h as RequestContext, n as AnyPlugin, r as ApplyExtension } from "./plugin-HvGqCurB.js";
-import { t as StandardSchemaV1 } from "./standard-CyhRzctb.js";
-import { i as PostgrestPlan } from "./postgrest-Dm-vhY6R.js";
+/// <reference lib="esnext.temporal" />
+import { A as SchemaMeta, C as PrimaryKeyValue, D as Relations, E as RelationTypes, I as UniqueKeyName, L as UniqueWhere, N as TableKey, O as Row, P as TableMeta, R as Update, g as Insert, j as Simplify, k as Schema, n as AnyModels, t as AnyFunctions } from "./types-DONv9SHN.js";
+import { g as Operation, l as CountMode, r as Executor } from "./executor-DynmIWhq.js";
+import { p as DbError, s as ThrowMapper, t as AsyncResult, v as ErrorMapper } from "./result-c2OYgCV2.js";
+import { a as EventHub, f as Logger, i as EventHandler, o as EventName, s as MutationNotice, u as RpcNotice } from "./events-Do8jXh4D.js";
+import { a as ExtensionOf, g as WithExtension, h as RequestContext, n as AnyPlugin, r as ApplyExtension } from "./plugin-DVRB8qNE.js";
+import { t as StandardSchemaV1 } from "./standard-eudBiRk1.js";
+import { i as PostgrestPlan } from "./postgrest-DmBlevh-.js";
 //#region src/ir/args.d.ts
 interface BaseOps<V> {
   readonly eq?: V;
@@ -147,7 +148,7 @@ interface AggregateArgs<M extends AnyModels, T extends keyof M> {
 type SelectPart<M extends AnyModels, T extends keyof M, A> = A extends {
   readonly select: readonly (infer K)[];
 } ? Pick<Row<M, T>, Extract<K, keyof Row<M, T>>> : Row<M, T>;
-type RelationPayload<M extends AnyModels, R, V> = R extends RelationShape ? R["kind"] extends "many" ? Payload<M, Extract<R["table"], keyof M>, V extends true ? unknown : V>[] : R["nullable"] extends true ? Payload<M, Extract<R["table"], keyof M>, V extends true ? unknown : V> | null : Payload<M, Extract<R["table"], keyof M>, V extends true ? unknown : V> : never;
+type RelationPayload<M extends AnyModels, R, V> = R extends RelationTypes ? R["kind"] extends "many" ? Payload<M, Extract<R["table"], keyof M>, V extends true ? unknown : V>[] : R["nullable"] extends true ? Payload<M, Extract<R["table"], keyof M>, V extends true ? unknown : V> | null : Payload<M, Extract<R["table"], keyof M>, V extends true ? unknown : V> : never;
 type IncludePart<M extends AnyModels, T extends keyof M, A> = A extends {
   readonly include: infer I;
 } ? { -readonly [R in keyof I & keyof Relations<M, T>]: RelationPayload<M, Relations<M, T>[R], I[R]>; } & CountPart<I> & ([keyof I & MeasureKey] extends [never] ? unknown : RelationMeasures<M, T, I>) : unknown;
@@ -551,7 +552,7 @@ declare function explainPostgrest(op: Operation): PostgrestPlan;
 //#region src/core/define.d.ts
 interface DefineSupabaseOptions {
   /** Clock used by plugins (timestamps, soft delete). */
-  readonly now?: () => Date;
+  readonly now?: () => Temporal.Instant;
   /** Extra error mappers, run before plugin mappers. */
   readonly errors?: readonly ErrorMapper[];
   /** Receives errors from event handlers, hooks and cache adapters. Defaults to `console`. */
@@ -562,6 +563,8 @@ interface DefineSupabaseOptions {
   readonly throwAs?: ThrowMapper;
   /** Validates verified JWT claims on the server. Prefer `sb.claims()`, which also types them. */
   readonly claims?: StandardSchemaV1;
+  /** Parses `user_metadata` into `session.profile`. Prefer `sb.userMetadata()`, which also types it. */
+  readonly userMetadata?: StandardSchemaV1;
   /**
    * PostgREST's `db-max-rows`: the most rows one read returns. An unbounded
    * `findMany` that returns this many sets `truncated` on the `query` event
@@ -586,7 +589,7 @@ interface RpcDefinition {
  * The isomorphic definition of your data layer: schema plus plugins. Holds no
  * secrets and no connection; `connect()` binds it to a client per request.
  */
-declare class BetterSupabase<M extends AnyModels = AnyModels, D = unknown, F extends AnyFunctions = AnyFunctions, E = unknown, C = unknown> {
+declare class BetterSupabase<M extends AnyModels = AnyModels, D = unknown, F extends AnyFunctions = AnyFunctions, E = unknown, C = unknown, P = unknown> {
   #private;
   readonly schema: Schema<M, D, F>;
   readonly plugins: readonly AnyPlugin[];
@@ -596,6 +599,8 @@ declare class BetterSupabase<M extends AnyModels = AnyModels, D = unknown, F ext
   get meta(): SchemaMeta;
   /** The schema set by `claims()`; its output types `session.claims`. */
   get claimsSchema(): StandardSchemaV1<unknown, C> | undefined;
+  /** The schema set by `userMetadata()`; its output types `session.profile`. */
+  get userMetadataSchema(): StandardSchemaV1<unknown, P> | undefined;
   /**
    * Returns a new instance whose servers validate verified JWT claims (custom
    * access token hook output) with `schema`, and whose sessions are typed by it.
@@ -605,7 +610,20 @@ declare class BetterSupabase<M extends AnyModels = AnyModels, D = unknown, F ext
    * const sb = defineSupabase(schema).claims(z.object({ tenant_id: z.uuid() }));
    * ```
    */
-  claims<S extends StandardSchemaV1>(schema: S): BetterSupabase<M, D, F, E, StandardSchemaV1.InferOutput<S>>;
+  claims<S extends StandardSchemaV1>(schema: S): BetterSupabase<M, D, F, E, StandardSchemaV1.InferOutput<S>, P>;
+  /**
+   * Returns a new instance whose sessions parse `user_metadata` with
+   * `schema` into a typed `session.profile`. Users can change their metadata
+   * with `auth.updateUser()`, so a failure only leaves `profile` undefined
+   * (with one warning), and no authorization code reads it. It is for
+   * display only: roles, memberships, the tenant and entitlements come from
+   * the verified claims, never from `profile`.
+   *
+   * ```ts
+   * const sb = defineSupabase(schema).userMetadata(z.object({ display_name: z.string() }));
+   * ```
+   */
+  userMetadata<S extends StandardSchemaV1>(schema: S): BetterSupabase<M, D, F, E, C, StandardSchemaV1.InferOutput<S>>;
   /**
    * Returns a new instance whose `.orThrow()` throws `mapper(error)` instead
    * of a `DbException`, and whose results `toBetterResult` maps the same way.
@@ -615,7 +633,7 @@ declare class BetterSupabase<M extends AnyModels = AnyModels, D = unknown, F ext
    * const sb = defineSupabase(schema).mapError((error) => new AppError(error));
    * ```
    */
-  mapError(mapper: (error: DbError) => unknown): BetterSupabase<M, D, F, E, C>;
+  mapError(mapper: (error: DbError) => unknown): BetterSupabase<M, D, F, E, C, P>;
   /**
    * Builds serializable `QuerySpec`s with the same arguments and result types
    * as the repository: `sb.spec.customers.findMany({ select: ['id'] })`.
@@ -624,7 +642,7 @@ declare class BetterSupabase<M extends AnyModels = AnyModels, D = unknown, F ext
   /** App keys of every table a spec reads; mutations of any of them make it stale. */
   tablesOf(spec: QuerySpec): string[];
   /** Returns a new instance with the plugin appended. */
-  use<P extends AnyPlugin>(plugin: P): BetterSupabase<M, D, F, WithExtension<E, ExtensionOf<P>>, C>;
+  use<Q extends AnyPlugin>(plugin: Q): BetterSupabase<M, D, F, WithExtension<E, ExtensionOf<Q>>, C, P>;
   /**
    * Declares the tables an RPC writes, so cache adapters and live queries
    * invalidate them after it succeeds.
@@ -635,7 +653,7 @@ declare class BetterSupabase<M extends AnyModels = AnyModels, D = unknown, F ext
    */
   defineRpc(name: Extract<keyof F, string>, options: {
     readonly invalidates: readonly TableKey<M>[];
-  }): BetterSupabase<M, D, F, E, C>;
+  }): BetterSupabase<M, D, F, E, C, P>;
   /** Observes queries, mutations, errors, auth and refreshes. */
   on<K extends EventName>(name: K, handler: EventHandler<K>): () => void;
   /**

package/dist/edge/index.d.ts

@@ -1,7 +1,7 @@
-import { k as TableKey, n as AnyModels, t as AnyFunctions } from "../types-C2fslP1z.js";
-import { t as BetterSupabase } from "../define-CTfWw-SS.js";
-import { d as ServerContext, f as ServerOptions, l as BetterServer, n as GuardOptions } from "../respond-PoTpy5DT.js";
-import { i as ResourceRouteOptions } from "../resource-SkPTRJDD.js";
+import { N as TableKey, n as AnyModels, t as AnyFunctions } from "../types-DONv9SHN.js";
+import { t as BetterSupabase } from "../define-DUbydmJa.js";
+import { d as ServerContext, f as ServerOptions, l as BetterServer, n as GuardOptions } from "../respond-DAkPIdTH.js";
+import { a as ResourceRouteOptions } from "../resource-CwVgiI5q.js";
 //#region src/edge/index.d.ts
 export interface CorsOptions {
   /** Allowed origins, or `*`. Defaults to `*`. */

package/dist/edge/index.js

@@ -1,7 +1,7 @@
 import { n as dbError } from "../errors-Bl3rkOzo.js";
-import { a as problemResponse } from "../problem-DPu6Fh-t.js";
-import { i as respond, n as guard, o as createServer, s as extendServer, t as defaultExpose } from "../respond-4-dhoV7x.js";
-import { t as defineResource } from "../resource-CYiu6Ygi.js";
+import { a as problemResponse } from "../problem-CGt1ADix.js";
+import { i as respond, n as guard, o as createServer, s as extendServer, t as defaultExpose } from "../respond-C44EZAJo.js";
+import { t as defineResource } from "../resource-D30rp0GN.js";
 //#region src/edge/index.ts
 const SUPABASE_CORS_HEADERS = [
 	"authorization",
@@ -54,7 +54,7 @@ function createEdge(sb, options = {}) {
 			});
 			const ctx = await server.context(request, { refresh: handlerOptions.refresh ?? false });
 			const instance = new URL(request.url).pathname;
-			const denied = guard(ctx.auth, handlerOptions.allow, handlerOptions.aal);
+			const denied = guard(ctx.auth, handlerOptions.allow, handlerOptions.aal, handlerOptions.scopes);
 			let response;
 			try {
 				response = denied ? problemResponse(denied, {

package/dist/entitlements-CTEBm7IB.js

@@ -0,0 +1,20 @@
+//#region src/auth/entitlements.ts
+/**
+* Whether the session's plan-features claim grants `key` in `tenantId`.
+* `claim` is `config.claims.features` (default `features`), the claim
+* `better_supabase.feature_claims()` fills. The claim is as fresh as the
+* token: enforce it in RLS with `better_supabase.has_entitlement()`, and
+* refresh the session after checkout.
+*/
+function hasEntitlement(session, tenantId, key, claim = "features") {
+	if (session.kind !== "user") return false;
+	const claims = session.claims;
+	if (!isRecord(claims)) return false;
+	const features = claims[claim];
+	if (!isRecord(features) || !Object.hasOwn(features, tenantId)) return false;
+	const keys = features[tenantId];
+	return Array.isArray(keys) && keys.includes(key);
+}
+const isRecord = (value) => typeof value === "object" && value !== null;
+//#endregion
+export { hasEntitlement as t };