better-supabase 0.0.0 → 0.2.0

package/dist/read-set-4lI3W_gZ.js

@@ -0,0 +1,216 @@
+import { r as IrBuilder, u as tableMeta } from "./simplify-bwJpLnaS.js";
+import { n as touchedTables } from "./tables-rZxRxNPW.js";
+//#region src/core/spec.ts
+const READ_METHODS = [
+	"findMany",
+	"findFirst",
+	"findUnique",
+	"findById",
+	"count",
+	"aggregate",
+	"exists",
+	"paginate"
+];
+function createSpecs(meta) {
+	const specs = {};
+	for (const table of Object.keys(meta.tables)) {
+		const methods = {};
+		for (const method of READ_METHODS) methods[method] = (...args) => ({
+			v: 1,
+			table,
+			method,
+			args: trimUndefined(args)
+		});
+		specs[table] = methods;
+	}
+	return specs;
+}
+function trimUndefined(args) {
+	const out = [...args];
+	while (out.length > 0 && out.at(-1) === void 0) out.pop();
+	return out;
+}
+function isQuerySpec(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const spec = value;
+	return spec.v === 1 && typeof spec.table === "string" && READ_METHODS.includes(spec.method) && Array.isArray(spec.args);
+}
+/** The argument object of a spec's method (`findById` takes it second). */
+function specOptions(spec) {
+	const value = spec.method === "findById" ? spec.args[1] : spec.args[0];
+	return typeof value === "object" && value !== null ? value : void 0;
+}
+const builders = /* @__PURE__ */ new WeakMap();
+/**
+* App keys of every table a spec reads: its table, included relations and
+* relations used in `where`. Queries keyed by a spec go stale when any of
+* them changes. Invalid arguments yield just the spec's table; running the
+* spec reports the error.
+*/
+function specTables(meta, spec) {
+	try {
+		return readTables(meta, spec);
+	} catch {
+		return [spec.table];
+	}
+}
+function readTables(meta, spec) {
+	let builder = builders.get(meta);
+	if (!builder) {
+		builder = new IrBuilder(meta);
+		builders.set(meta, builder);
+	}
+	const table = tableMeta(meta, spec.table);
+	const args = specOptions(spec);
+	const counts = spec.method === "count" || spec.method === "exists" || spec.method === "aggregate";
+	return touchedTables({
+		kind: "select",
+		table,
+		selection: counts ? {
+			columns: [],
+			includes: []
+		} : builder.selection(table, args?.["select"], args?.["include"]),
+		where: builder.where(table, args?.["where"]),
+		orderBy: [],
+		limit: void 0,
+		offset: void 0,
+		count: void 0,
+		head: counts,
+		single: void 0
+	});
+}
+//#endregion
+//#region src/core/read-set.ts
+const NAME = /^[a-z][a-z0-9_]{0,59}$/;
+const PARAM = /^[a-z_][a-z0-9_]*$/i;
+const TYPE = /^(?:[a-z_][a-z0-9_]*\.)?[a-z_][a-z0-9_]*(?:\[\])?$/;
+/** `jsonb_build_object` takes at most 100 arguments. */
+const MAX_ENTRIES = 50;
+/** Placeholders are `NUL bs:<name> NUL`: no real parameter value holds a NUL. */
+const NUL = String.fromCharCode(0);
+const SENTINEL = new RegExp(`${NUL}bs:([a-z_][a-z0-9_]*)${NUL}`, "gi");
+const EXACT = new RegExp(`^${NUL}bs:([a-z_][a-z0-9_]*)${NUL}$`, "i");
+function sentinel(name) {
+	return `${NUL}bs:${name}${NUL}`;
+}
+/**
+* Registers reads that run as one round trip:
+*
+* ```ts
+* export const appChrome = defineReadSet(
+*   sb,
+*   'app_chrome',
+*   { params: { userId: 'uuid' } },
+*   (s, p) => ({
+*     unread: s.notifications.count({ where: { userId: p.userId, readAt: null } }),
+*     me: s.profiles.findFirst({ where: { id: p.userId } }),
+*   }),
+* );
+* ```
+*
+* `p` holds placeholders, not values: pass them straight into `where` (or
+* `in`), where the function reads them from its `p jsonb` argument.
+*/
+function defineReadSet(sb, name, options, build) {
+	if (!NAME.test(name)) throw new TypeError(`better-supabase: read set name "${name}" must be snake_case and at most 60 characters`);
+	const params = options.params ?? {};
+	const placeholders = {};
+	for (const [key, type] of Object.entries(params)) {
+		if (!PARAM.test(key)) throw new TypeError(`better-supabase: read set "${name}" has an invalid parameter name "${key}"`);
+		if (!TYPE.test(type)) throw new TypeError(`better-supabase: read set "${name}" parameter "${key}" has an invalid type "${type}"`);
+		placeholders[key] = type.endsWith("[]") ? [sentinel(key)] : sentinel(key);
+	}
+	const specs = build(sb.spec, placeholders);
+	const entries = Object.entries(specs);
+	if (entries.length === 0 || entries.length > MAX_ENTRIES) throw new TypeError(`better-supabase: read set "${name}" needs between 1 and ${MAX_ENTRIES} reads`);
+	for (const [key, spec] of entries) if (!isQuerySpec(spec)) throw new TypeError(`better-supabase: read set "${name}" entry "${key}" is not a spec from sb.spec`);
+	return {
+		kind: "read-set",
+		name,
+		functionName: `rs_${name}`,
+		params,
+		roles: options.roles ?? ["authenticated"],
+		specs,
+		definition: sb
+	};
+}
+function isReadSet(value) {
+	return typeof value === "object" && value !== null && value.kind === "read-set" && typeof value.name === "string";
+}
+/** A parameter a string or array carries, if it is exactly a placeholder. */
+function placeholderOf(value) {
+	if (typeof value === "string") {
+		const match = EXACT.exec(value);
+		return match ? {
+			name: match[1],
+			array: false
+		} : void 0;
+	}
+	if (Array.isArray(value) && value.length === 1) {
+		const inner = placeholderOf(value[0]);
+		return inner && !inner.array ? {
+			name: inner.name,
+			array: true
+		} : inner;
+	}
+}
+/** Splits a string around the placeholders inside it. */
+function splitPlaceholders(value) {
+	const parts = [];
+	let last = 0;
+	for (const match of value.matchAll(SENTINEL)) {
+		if (match.index > last) parts.push({ text: value.slice(last, match.index) });
+		parts.push({ param: match[1] });
+		last = match.index + match[0].length;
+	}
+	if (last < value.length) parts.push({ text: value.slice(last) });
+	return parts;
+}
+function hasPlaceholder(value) {
+	return value.includes(`${NUL}bs:`);
+}
+/** Whether any string inside `value` is (or holds) a placeholder. */
+function containsPlaceholder(value) {
+	if (typeof value === "string") return hasPlaceholder(value);
+	if (Array.isArray(value)) return value.some(containsPlaceholder);
+	if (typeof value === "object" && value !== null) return Object.values(value).some(containsPlaceholder);
+	return false;
+}
+/** Missing or wrongly typed parameters, as messages. */
+function checkParams(set, values) {
+	const problems = [];
+	for (const [key, type] of Object.entries(set.params)) {
+		const value = values?.[key];
+		if (value === void 0 || value === null) problems.push(`missing parameter "${key}"`);
+		else if (type.endsWith("[]") !== Array.isArray(value)) problems.push(`parameter "${key}" must be ${type.endsWith("[]") ? "an array" : "a single value"}`);
+	}
+	return problems;
+}
+/** The specs with every placeholder replaced by its value. */
+function bindParams(set, values) {
+	const bind = (value) => {
+		const placeholder = placeholderOf(value);
+		if (placeholder) return values[placeholder.name];
+		if (typeof value === "string") {
+			if (!hasPlaceholder(value)) return value;
+			return splitPlaceholders(value).map((part) => "text" in part ? part.text : String(values[part.param] ?? "")).join("");
+		}
+		if (Array.isArray(value)) return value.map(bind);
+		if (typeof value === "object" && value !== null) {
+			if (Object.getPrototypeOf(value) !== Object.prototype) return value;
+			return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, bind(entry)]));
+		}
+		return value;
+	};
+	return Object.fromEntries(Object.entries(set.specs).map(([key, spec]) => [key, {
+		...spec,
+		args: spec.args.map(bind)
+	}]));
+}
+/** App keys of every table the set reads. */
+function readSetTables(set, meta) {
+	const schema = meta ?? set.definition.meta;
+	return [...new Set(Object.values(set.specs).flatMap((spec) => specTables(schema, spec)))];
+}
+//#endregion
+export { hasPlaceholder as a, readSetTables as c, isQuerySpec as d, specTables as f, defineReadSet as i, splitPlaceholders as l, checkParams as n, isReadSet as o, containsPlaceholder as r, placeholderOf as s, bindParams as t, createSpecs as u };

package/dist/realtime/index.d.ts

@@ -0,0 +1,4 @@
+import { x as PermdockTopicPolicy } from "../types-C83v5SQz.js";
+import { n as TemplateValues, t as TemplateParams } from "../template-mbvlysOo.js";
+import { C as defineTopic, S as TriggerOptions, _ as TopicEvent, a as LiveSource, b as TopicOptions, c as liveQuery, d as RealtimeClient, f as RowChange, g as Topic, h as SubscriptionStatus, i as LiveQueryOptions, l as liveTopic, m as Subscription, n as LiveCountOptions, o as LiveSubscription, p as SubscribeOptions, r as LiveCountSeed, s as liveCount, t as CountRunner, u as EventSchemas, v as TopicHandlers, w as rowChange, x as TopicPayload, y as TopicMessage } from "../live-DJyZMD6w.js";
+export { type CountRunner, EventSchemas, type LiveCountOptions, type LiveCountSeed, type LiveQueryOptions, type LiveSource, type LiveSubscription, type PermdockTopicPolicy, RealtimeClient, RowChange, SubscribeOptions, Subscription, SubscriptionStatus, type TemplateParams, type TemplateValues, Topic, TopicEvent, TopicHandlers, TopicMessage, TopicOptions, TopicPayload, TriggerOptions, defineTopic, liveCount, liveQuery, liveTopic, rowChange };

package/dist/realtime/index.js

@@ -0,0 +1,268 @@
+import { n as dbError } from "../errors-Bl3rkOzo.js";
+import { i as ok, n as err, t as AsyncResult } from "../result-DWXatkd6.js";
+import { i as tenantClaimPaths } from "../claims-CoTobNC-.js";
+import { n as liveQuery, r as liveTopic, t as liveCount } from "../live-D8rV1Ldw.js";
+import { s as toApp } from "../shared-_6-uPL7E.js";
+import { a as sqlString, i as sqlIdent, n as parseTemplate, r as slug, t as permdockCheck } from "../permdock-sql-CghlHPuH.js";
+import { REALTIME_SUBSCRIBE_STATES } from "@supabase/supabase-js";
+//#region src/realtime/index.ts
+const VALUE = /^[\w.@+=-]+$/;
+function validateValue(_name, value) {
+	return VALUE.test(value) ? void 0 : "contains characters topics do not allow";
+}
+function claimSql(claim) {
+	const expressions = (typeof claim === "string" ? [claim] : claim).map((path) => {
+		const keys = path.split(".");
+		const last = keys.pop();
+		return `(select auth.jwt())${keys.map((key) => ` -> ${sqlString(key)}`).join("")} ->> ${sqlString(last)}`;
+	});
+	return expressions.length === 1 ? expressions[0] : `coalesce(${expressions.join(", ")})`;
+}
+async function validate(schema, value) {
+	if (!schema) return {
+		ok: true,
+		value
+	};
+	const result = await schema["~standard"].validate(value);
+	if (result.issues) return {
+		ok: false,
+		issues: result.issues.map((issue) => ({
+			message: issue.message,
+			...issue.path ? { path: issue.path.map((part) => typeof part === "object" ? part.key : part) } : {}
+		}))
+	};
+	return {
+		ok: true,
+		value: result.value
+	};
+}
+function sendError(status, message) {
+	if (status === 401) return dbError("unauthorized", message);
+	if (status === 403) return dbError("forbidden", message);
+	if (status === 429 || status >= 500 || status === 0) return dbError("network", message, status ? { status } : {});
+	return dbError("invalid_request", message, { status });
+}
+/**
+* A typed Realtime broadcast topic: names from a template, RLS policies for
+* private channels, row-change triggers, and disposable subscriptions.
+*
+* ```ts
+* export const notifications = defineTopic('org:{orgId}:notifications:{userId}', {
+*   events: { created: v.object({ id: v.string(), title: v.string() }) },
+* });
+* using sub = notifications.subscribe(supabase, { orgId, userId }, { created: (n) => toast(n.title) });
+* ```
+*/
+function defineTopic(template, options = {}) {
+	const parsed = parseTemplate(template, ":", validateValue);
+	const literal = template.replace(/\{[^}]+\}/g, " ");
+	const name = slug(options.name ?? literal) || "topic";
+	const isPrivate = options.private ?? true;
+	const schemas = options.events ?? {};
+	const segment = (param, kind) => {
+		const index = parsed.segmentOf(param);
+		if (index === void 0) throw new TypeError(`defineTopic: the ${kind} check needs {${param}} as a whole segment in "${template}"`);
+		return index;
+	};
+	const checks = [];
+	const permdock = options.permdock;
+	const tenantParam = options.tenant === false ? void 0 : options.tenant?.param ?? "orgId";
+	const permdockChecks = (() => {
+		if (!permdock) return void 0;
+		const where = `defineTopic(${template})`;
+		const id = permdock.scope === "global" ? void 0 : `split_part((select realtime.topic()), ':', ${String(permdock.segment ?? segment(tenantParam ?? "orgId", "PermDock"))})`;
+		const receive = permdockCheck(where, permdock, permdock.receive, id);
+		return {
+			receive,
+			send: permdock.send === void 0 ? receive : permdockCheck(where, permdock, permdock.send, id)
+		};
+	})();
+	if (!permdock && tenantParam && (options.tenant || parsed.params.includes(tenantParam))) {
+		const tenant = options.tenant === false ? {} : options.tenant ?? {};
+		const expression = tenant.sql ?? claimSql(tenant.claim ?? tenantClaimPaths());
+		checks.push(`split_part((select realtime.topic()), ':', ${String(segment(tenantParam, "tenant"))}) = (${expression})`);
+	}
+	const ownerParam = options.owner === false ? void 0 : options.owner?.param ?? "userId";
+	if (ownerParam && (options.owner || parsed.params.includes(ownerParam))) checks.push(`split_part((select realtime.topic()), ':', ${String(segment(ownerParam, "owner"))}) = (select auth.uid())::text`);
+	const topicOf = (values) => parsed.build(values);
+	return {
+		template,
+		name,
+		params: parsed.params,
+		private: isPrivate,
+		topic: topicOf,
+		match: (topic) => parsed.match(topic),
+		sql() {
+			const extensions = options.presence ? "('broadcast', 'presence')" : "('broadcast')";
+			const condition = (extra) => [
+				`(select realtime.topic()) ~ ${sqlString(parsed.sqlPattern)}`,
+				`realtime.messages.extension in ${extensions}`,
+				...checks,
+				...extra === void 0 ? [] : [extra]
+			].join("\n    and ");
+			const lines = [`-- better-supabase: topic ${template}`];
+			const policies = [[
+				"receive",
+				"select",
+				"using",
+				condition(permdockChecks?.receive)
+			]];
+			if (options.send || options.presence || permdock?.send !== void 0) policies.push([
+				"send",
+				"insert",
+				"with check",
+				condition(permdockChecks?.send)
+			]);
+			for (const [suffix, command, clause, check] of policies) {
+				const policy = sqlIdent(`bs_topic_${name}_${suffix}`);
+				lines.push(`drop policy if exists ${policy} on realtime.messages;`, `create policy ${policy} on realtime.messages for ${command} to authenticated\n  ${clause} (\n    ${check}\n  );`);
+			}
+			return `${lines.join("\n")}\n`;
+		},
+		triggerSql(sb, table, trigger) {
+			const meta = sb.meta.tables[table];
+			if (!meta) throw new TypeError(`defineTopic: unknown table "${table}"`);
+			const values = trigger.values;
+			const parts = template.split(/(\{[^}]+\})/).filter(Boolean).map((part) => {
+				const param = /^\{(.+)\}$/.exec(part)?.[1];
+				if (param === void 0) return sqlString(part);
+				const column = values[param];
+				const db = column === void 0 ? void 0 : meta.columns[column]?.db;
+				if (!db) throw new TypeError(`defineTopic: no column for {${param}} on "${table}"`);
+				return `rec.${sqlIdent(db)}::text`;
+			});
+			const schema = trigger.functionSchema ?? "public";
+			const fn = `${sqlIdent(schema)}.${sqlIdent(`bs_broadcast_${name}_${slug(meta.name)}`)}`;
+			const triggerName = sqlIdent(`bs_broadcast_${name}`);
+			const target = `${sqlIdent(meta.schema)}.${sqlIdent(meta.name)}`;
+			const events = (trigger.events ?? [
+				"insert",
+				"update",
+				"delete"
+			]).join(" or ");
+			return [
+				`-- better-supabase: broadcast ${meta.name} changes to ${template}`,
+				`create or replace function ${fn}()`,
+				"returns trigger",
+				"language plpgsql",
+				"security definer",
+				"set search_path = ''",
+				"as $$",
+				"declare",
+				"  rec record;",
+				"begin",
+				"  if tg_op = 'DELETE' then rec := old; else rec := new; end if;",
+				"  perform realtime.broadcast_changes(",
+				`    ${parts.join(" || ")},`,
+				"    tg_op, tg_op, tg_table_name, tg_table_schema, new, old",
+				"  );",
+				"  return null;",
+				"end;",
+				"$$;",
+				`revoke execute on function ${fn}() from public, anon, authenticated;`,
+				"",
+				`drop trigger if exists ${triggerName} on ${target};`,
+				`create trigger ${triggerName} after ${events} on ${target}`,
+				`  for each row execute function ${fn}();`,
+				""
+			].join("\n");
+		},
+		subscribe(client, values, handlers, subscribeOptions = {}) {
+			const topic = topicOf(values);
+			const channel = client.channel(topic, { config: {
+				private: isPrivate,
+				broadcast: { self: subscribeOptions.self ?? false }
+			} });
+			const table = handlers;
+			channel.on("broadcast", { event: "*" }, (raw) => {
+				const message = {
+					event: raw.event,
+					payload: raw["payload"],
+					topic
+				};
+				const handler = table[message.event] ?? table["*"];
+				if (!handler) return;
+				validate(schemas[message.event], message.payload).then((checked) => {
+					if (checked.ok) handler(checked.value, message);
+					else subscribeOptions.onInvalid?.(message, checked.issues);
+				});
+			});
+			let closed = false;
+			subscribeOptions.onStatus?.("joining");
+			const ready = (async () => {
+				if (isPrivate) await client.realtime.setAuth();
+				if (closed) return;
+				await new Promise((resolve, reject) => {
+					channel.subscribe((status, error) => {
+						switch (status) {
+							case REALTIME_SUBSCRIBE_STATES.SUBSCRIBED:
+								subscribeOptions.onStatus?.("subscribed");
+								resolve();
+								return;
+							case REALTIME_SUBSCRIBE_STATES.CLOSED:
+								subscribeOptions.onStatus?.("closed");
+								resolve();
+								return;
+							case REALTIME_SUBSCRIBE_STATES.CHANNEL_ERROR:
+							case REALTIME_SUBSCRIBE_STATES.TIMED_OUT: {
+								const failure = error ?? /* @__PURE__ */ new Error(`Realtime ${status.toLowerCase()} on ${topic}`);
+								subscribeOptions.onStatus?.("error", failure);
+								reject(failure);
+								return;
+							}
+							default: reject(/* @__PURE__ */ new Error(`Unknown realtime status ${String(status)}`));
+						}
+					});
+				});
+			})();
+			ready.catch(() => void 0);
+			const unsubscribe = async () => {
+				if (closed) return;
+				closed = true;
+				await client.removeChannel(channel);
+			};
+			return {
+				topic,
+				channel,
+				ready,
+				unsubscribe,
+				[Symbol.dispose]: () => void unsubscribe(),
+				[Symbol.asyncDispose]: unsubscribe
+			};
+		},
+		send(client, values, event, payload) {
+			return AsyncResult.from(async () => {
+				const topic = topicOf(values);
+				const checked = await validate(schemas[event], payload);
+				if (!checked.ok) return err(dbError("validation", `Invalid payload for ${event}`, { issues: checked.issues }));
+				if (isPrivate) await client.realtime.setAuth();
+				const channel = client.channel(topic, { config: { private: isPrivate } });
+				try {
+					const response = await channel.httpSend(event, checked.value);
+					return response.success ? ok(void 0) : err(sendError(response.status, response.error));
+				} finally {
+					await client.removeChannel(channel);
+				}
+			});
+		}
+	};
+}
+/**
+* Reads a `realtime.broadcast_changes` message as an app-cased row change.
+* Returns `null` for messages about other tables.
+*/
+function rowChange(sb, table, message) {
+	const meta = sb.meta.tables[table];
+	const payload = message.payload;
+	if (!meta || !payload || payload.table !== meta.name || payload.schema && payload.schema !== meta.schema) return null;
+	const operation = payload.operation ?? message.event;
+	if (operation !== "INSERT" && operation !== "UPDATE" && operation !== "DELETE") return null;
+	return {
+		operation,
+		table,
+		record: payload.record ? toApp(meta, payload.record) : null,
+		oldRecord: payload.old_record ? toApp(meta, payload.old_record) : null
+	};
+}
+//#endregion
+export { defineTopic, liveCount, liveQuery, liveTopic, rowChange };

package/dist/resolve-CjHILk2w.d.ts

@@ -0,0 +1,170 @@
+import { p as DbError } from "./result-CTkCZ6JA.js";
+import { f as Logger, l as RefreshEvent } from "./events-DOt3nSO-.js";
+import { h as RequestContext } from "./plugin-C4TR9J0Z.js";
+import { t as StandardSchemaV1 } from "./standard-CyhRzctb.js";
+import { t as BetterSupabaseEnv } from "./index-Dy6kuF0P.js";
+import { CookieOptions } from "@supabase/ssr";
+import { JWTClaims, SupabaseEnv, UserClaims } from "@supabase/server";
+//#region src/auth/session.d.ts
+/** The session object auth-js persists (`sb-<ref>-auth-token`). */
+interface StoredSession {
+  readonly access_token: string;
+  readonly refresh_token: string;
+  readonly expires_at?: number;
+  readonly expires_in?: number;
+  readonly token_type?: string;
+  readonly user?: unknown;
+  readonly [key: string]: unknown;
+}
+interface CookieRecord {
+  readonly name: string;
+  readonly value: string;
+}
+interface CookieWrite {
+  readonly name: string;
+  readonly value: string;
+  readonly options: CookieOptions;
+}
+/** Headers that keep responses carrying session cookies out of shared caches. */
+declare const AUTH_CACHE_HEADERS: Readonly<Record<string, string>>;
+/** `sb-<first label of the hostname>-auth-token`, the supabase-js default. */
+declare function sessionCookieName(url: string): string;
+declare function parseCookies(header: string | null | undefined): CookieRecord[];
+declare function serializeCookie(write: CookieWrite): string;
+/**
+ * Reads the session written by `@supabase/ssr` (plain or `base64-`, whole or
+ * chunked). Mismatched chunks from a partial write read as no session.
+ */
+declare function readSession(cookies: readonly CookieRecord[], name: string): StoredSession | null;
+/**
+ * Cookie writes that store `session` (or clear it with `null`) exactly like
+ * `@supabase/ssr`, and expire chunks the new value no longer uses.
+ */
+declare function writeSession(existing: readonly CookieRecord[], name: string, session: StoredSession | null, options?: CookieOptions): CookieWrite[];
+/** Applies cookie writes to a cookie list, as the next request would see it. */
+declare function applyCookieWrites(cookies: readonly CookieRecord[], writes: readonly CookieWrite[]): CookieRecord[];
+//#endregion
+//#region src/auth/resolve.d.ts
+/**
+ * Who is calling. `C` is the claims type from `sb.claims(schema)`; the
+ * verified payload keeps every JWT claim and adds the schema's output. `P`
+ * is the `user_metadata` type from `sb.userMetadata(schema)`.
+ */
+type AuthState<C = unknown, P = unknown> = {
+  readonly kind: "user";
+  readonly token: string;
+  readonly claims: JWTClaims & C;
+  readonly user: UserClaims;
+  readonly source: "bearer" | "cookie" | (string & {});
+  /** Seconds since epoch, from the token's `exp`. */
+  readonly expiresAt: number | null;
+  /**
+   * `user_metadata` parsed by `sb.userMetadata(schema)`; `undefined`
+   * without a schema or when the metadata fails it. Users can write this
+   * data themselves: use it for display, never for access.
+   */
+  readonly profile?: P;
+} | {
+  readonly kind: "service";
+  readonly keyName: string;
+} | {
+  readonly kind: "anon";
+  /** `expired`: the cookie session needs a refresh that was not allowed here (run the proxy). */
+  readonly reason: "none" | "expired" | "signed_out" | "refresh_failed";
+} | {
+  readonly kind: "invalid";
+  readonly reason: InvalidReason;
+  readonly error: DbError;
+};
+type InvalidReason = "token" | "claims";
+/**
+ * What an `AuthResolver` returns. `reason` may be left out of an `invalid`
+ * state; it then counts as `token`.
+ */
+type ResolvedState = Exclude<AuthState, {
+  kind: "invalid";
+}> | {
+  readonly kind: "invalid";
+  readonly reason?: InvalidReason;
+  readonly error: DbError;
+};
+/**
+ * Extension point for other credentials (API keys, third-party auth, custom
+ * tokens). Return `undefined` when the request carries nothing this resolver
+ * understands; the built-in Bearer and cookie resolution runs next.
+ */
+interface AuthResolver {
+  readonly name: string;
+  resolve(request: Request): Promise<ResolvedState | undefined> | ResolvedState | undefined;
+}
+interface ResolveAuthOptions {
+  readonly env: BetterSupabaseEnv;
+  /** Allow refreshing an expiring cookie session. Only where cookies can be written (proxy). */
+  readonly refresh?: boolean;
+  /** Refresh when the token expires within this many seconds. Defaults to 60. */
+  readonly leeway?: number;
+  /**
+   * Accept `sb_secret_` keys (`apikey` header) as service callers: `true` for
+   * any configured key, or the key names allowed (`['cron']`). Defaults to false.
+   */
+  readonly secret?: boolean | readonly string[];
+  readonly audience?: string | string[];
+  readonly issuer?: string | string[];
+  readonly cookie?: {
+    readonly name?: string;
+    readonly options?: CookieOptions;
+  };
+  /** Inline JWKS instead of fetching `env.jwksUrl` (tests, air-gapped). */
+  readonly jwks?: SupabaseEnv["jwks"];
+  /**
+   * Validates the verified claims (`sb.claims(schema)` sets it). A failure
+   * resolves to `{ kind: 'invalid', reason: 'claims' }`.
+   */
+  readonly claims?: StandardSchemaV1;
+  /**
+   * Parses `user_metadata` into `profile` (`sb.userMetadata(schema)` sets
+   * it). A failure leaves `profile` undefined and warns once; the session
+   * stays valid.
+   */
+  readonly userMetadata?: StandardSchemaV1;
+  /** Receives the `userMetadata` warning. Defaults to `console`. */
+  readonly logger?: Logger;
+  readonly resolvers?: readonly AuthResolver[];
+  /**
+   * The caller's IP, sent to Auth as `Sb-Forwarded-For` on refreshes so its
+   * per-IP rate limit counts users, not your server. Only with a secret key
+   * (`env.secretKey`), which Auth requires for the header. Defaults to
+   * `clientIp` (the first `x-forwarded-for` hop); `false` turns it off.
+   */
+  readonly clientIp?: ((request: Request) => string | undefined) | false;
+  /** Called after every refresh attempt (metrics, logging). */
+  readonly onRefresh?: (event: RefreshEvent) => void;
+  readonly fetch?: typeof fetch;
+  readonly now?: () => number;
+}
+interface AuthResolution<C = unknown, P = unknown> {
+  readonly auth: AuthState<C, P>;
+  /** Cookie writes for the response. Empty unless the session was refreshed or cleared. */
+  readonly cookies: readonly CookieWrite[];
+  /** No-store headers, set whenever `cookies` is not empty. */
+  readonly headers: Readonly<Record<string, string>>;
+  /** Cookies the rest of this request should see, including a refreshed session. */
+  readonly requestCookies: readonly CookieRecord[];
+  /** Adds `cookies` and `headers` to a response. */
+  apply(response: Response): Response;
+}
+/** The first `x-forwarded-for` hop, the client as your edge saw it. */
+declare function clientIp(request: Request): string | undefined;
+/**
+ * Resolves who is calling: custom resolvers, then `Authorization: Bearer`
+ * (APIs, MCP, mobile), then the `@supabase/ssr` session cookie (browsers).
+ *
+ * A valid token costs no network call: it is verified locally against the
+ * cached JWKS. An expiring cookie session is refreshed only when `refresh` is
+ * set, through a single-flight request, and only then are cookies written.
+ */
+declare function resolveAuth(request: Request, options: ResolveAuthOptions): Promise<AuthResolution>;
+/** The repository context (`actor`, `claims`) for an auth state. */
+declare function authContext(auth: AuthState): RequestContext;
+//#endregion
+export { readSession as _, ResolveAuthOptions as a, writeSession as b, clientIp as c, CookieOptions as d, CookieRecord as f, parseCookies as g, applyCookieWrites as h, InvalidReason as i, resolveAuth as l, StoredSession as m, AuthResolver as n, ResolvedState as o, CookieWrite as p, AuthState as r, authContext as s, AuthResolution as t, AUTH_CACHE_HEADERS as u, serializeCookie as v, sessionCookieName as y };