better-supabase 0.2.0 → 0.4.0

package/dist/{react-C83BdBGt.js → react-CQHMaESR.js}

@@ -1,66 +1,66 @@
-import { i as tenantClaimPaths, n as claimAt, r as claimsOf } from "./claims-CoTobNC-.js";
-import { t as invalidateTables } from "./invalidate-DbxuL2jL.js";
-import { n as liveQuery, t as liveCount } from "./live-D8rV1Ldw.js";
-import { n as useSession } from "./session-CqEwzVup.js";
+import { i as tenantClaimPaths, n as claimAt, r as claimsOf } from "./claims-BAf6c7is.js";
+import { t as invalidateTables } from "./invalidate-CgxmRamI.js";
+import { n as liveQuery, t as liveCount } from "./live-CdJBOc4f.js";
+import { useSession } from "./react/session.js";
 import { createContext, createElement, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-//#region src/react/index.ts
-const BrowserContext = createContext(null);
+//#region src/react/hooks.ts
+const ClientContext = createContext(null);
 const LOADING = {
 	status: "loading",
 	user: null,
 	claims: null
 };
-/** Provides the browser client to the hooks. */
+/** Provides the better-supabase client to the hooks. */
 function BetterSupabaseProvider(props) {
-	const { browser, queryClient } = props;
+	const { client, queryClient } = props;
 	const user = useRef(void 0);
-	useEffect(() => browser.auth.subscribe(() => {
-		const snapshot = browser.auth.current();
+	useEffect(() => client.auth.subscribe(() => {
+		const snapshot = client.auth.current();
 		if (snapshot.status === "loading") return;
 		const id = snapshot.user?.id ?? null;
 		if (user.current !== void 0 && user.current !== id) queryClient?.removeQueries({ queryKey: ["bs"] });
 		user.current = id;
-	}), [browser, queryClient]);
+	}), [client, queryClient]);
 	const value = useMemo(() => ({
-		browser,
+		client,
 		queryClient
-	}), [browser, queryClient]);
-	return createElement(BrowserContext.Provider, { value }, props.children);
+	}), [client, queryClient]);
+	return createElement(ClientContext.Provider, { value }, props.children);
 }
-function useBrowserContext() {
-	const value = useContext(BrowserContext);
-	if (!value) throw new Error("better-supabase: wrap your app in <BetterSupabaseProvider browser={browser}>");
+function useClientContext() {
+	const value = useContext(ClientContext);
+	if (!value) throw new Error("better-supabase: wrap your app in <BetterSupabaseProvider client={bs}>");
 	return value;
 }
-function useBrowser() {
-	return useBrowserContext().browser;
+function useClient() {
+	return useClientContext().client;
 }
 /** The session state for UI: `loading`, `signed-out` or `signed-in` with the user and claims. */
 function useAuth() {
-	const browser = useBrowser();
-	return useSyncExternalStore(browser.auth.subscribe, browser.auth.current, () => LOADING);
+	const client = useClient();
+	return useSyncExternalStore(client.auth.subscribe, client.auth.current, () => LOADING);
 }
 function useSupabase() {
-	return useBrowser().supabase;
+	return useClient().supabase;
 }
 /**
 * Hooks typed for your schema.
 *
 * ```ts
-* export const { useDb, useQueries, useAuth } = createHooks<typeof browser>();
+* export const { useDb, useQueries, useAuth } = createHooks<typeof bs>();
 * ```
 */
 function createHooks() {
 	return {
 		useDb() {
-			const browser = useBrowser();
+			const client = useClient();
 			useAuth();
-			return browser.db;
+			return client.db;
 		},
 		useQueries() {
-			const browser = useBrowser();
+			const client = useClient();
 			useAuth();
-			return browser.queries;
+			return client.queries;
 		},
 		useSupabase,
 		useAuth,
@@ -76,7 +76,7 @@ function createHooks() {
 * ```
 */
 function useBroadcast(topic, values, handlers, options) {
-	const { browser, queryClient } = useBrowserContext();
+	const { client, queryClient } = useClientContext();
 	const auth = useAuth();
 	const [status, setStatus] = useState("closed");
 	const latest = useRef({
@@ -91,9 +91,9 @@ function useBroadcast(topic, values, handlers, options) {
 	const userId = auth.user?.id ?? null;
 	if (options?.invalidate && !queryClient) throw new Error("better-supabase: useBroadcast({ invalidate }) needs <BetterSupabaseProvider queryClient={...}>");
 	useEffect(() => {
-		if (!name || auth.status === "loading") return void 0;
+		if (!name || auth.status === "loading") return;
 		const matched = topic.match(name);
-		if (!matched) return void 0;
+		if (!matched) return;
 		const forward = (payload, message) => {
 			const current = latest.current;
 			const table = current.handlers;
@@ -106,7 +106,7 @@ function useBroadcast(topic, values, handlers, options) {
 			}
 			for (const queryKey of invalidate(message)) queryClient.invalidateQueries({ queryKey });
 		};
-		const subscription = topic.subscribe(browser.supabase, matched, { "*": forward }, {
+		const subscription = topic.subscribe(client.supabase, matched, { "*": forward }, {
 			...latest.current.options?.self === void 0 ? {} : { self: latest.current.options.self },
 			onStatus: setStatus,
 			onInvalid: (message, issues) => latest.current.options?.onInvalid?.(message, issues)
@@ -116,7 +116,7 @@ function useBroadcast(topic, values, handlers, options) {
 			setStatus("closed");
 		};
 	}, [
-		browser,
+		client,
 		topic,
 		name,
 		userId,
@@ -138,23 +138,23 @@ function claimedTenant(auth, meta) {
 * resubscribes when the spec, tenant or user changes.
 *
 * ```ts
-* const spec = sb.spec.customers.findMany({ include: { notes: true } });
+* const spec = betterSupabase.spec.customers.findMany({ include: { notes: true } });
 * const { data } = useQuery(q.$spec(spec));
 * useLiveQuery(spec);
 * ```
 */
 function useLiveQuery(spec, options = {}) {
-	const { browser, queryClient } = useBrowserContext();
+	const { client, queryClient } = useClientContext();
 	const auth = useAuth();
 	const [status, setStatus] = useState("closed");
 	if (spec && !queryClient) throw new Error("better-supabase: useLiveQuery needs <BetterSupabaseProvider queryClient={...}>");
 	const key = spec ? JSON.stringify(spec) : null;
-	const tenant = options.tenant ?? claimedTenant(auth, browser.sb.meta);
+	const tenant = options.tenant ?? claimedTenant(auth, client.betterSupabase.meta);
 	const userId = auth.user?.id ?? null;
 	const debounceMs = options.debounceMs;
 	useEffect(() => {
-		if (!key || !queryClient || auth.status === "loading") return void 0;
-		const live = liveQuery(browser.sb, browser.supabase, JSON.parse(key), {
+		if (!key || !queryClient || auth.status === "loading") return;
+		const live = liveQuery(client.betterSupabase, client.supabase, JSON.parse(key), {
 			onChange: (tables) => void invalidateTables(queryClient, tables),
 			onStatus: setStatus,
 			...tenant === void 0 ? {} : { tenant },
@@ -164,7 +164,7 @@ function useLiveQuery(spec, options = {}) {
 			live.unsubscribe();
 		};
 	}, [
-		browser,
+		client,
 		queryClient,
 		key,
 		tenant,
@@ -177,15 +177,15 @@ function useLiveQuery(spec, options = {}) {
 /**
 * A count that stays current: refetches only the `count` spec (a HEAD
 * request) after each debounced change to a table it reads, and after the
-* channel rejoins. Takes a spec or a `next.liveCount()` seed; pass `null` to
+* channel rejoins. Takes a spec or a `bs.liveCount()` seed; pass `null` to
 * pause. Doesn't need a `QueryClient`.
 *
 * ```tsx
-* const { count } = useLiveCount(seed); // seed = await next.liveCount(spec)
+* const { count } = useLiveCount(seed); // seed = await bs.liveCount(spec)
 * ```
 */
 function useLiveCount(source, options = {}) {
-	const { browser } = useBrowserContext();
+	const { client } = useClientContext();
 	const auth = useAuth();
 	const seed = source && "spec" in source ? source : void 0;
 	const spec = seed ? seed.spec : source;
@@ -197,24 +197,28 @@ function useLiveCount(source, options = {}) {
 	});
 	const [status, setStatus] = useState("closed");
 	const key = spec ? JSON.stringify(spec) : null;
-	const tenant = options.tenant ?? claimedTenant(auth, browser.sb.meta);
+	const tenant = options.tenant ?? claimedTenant(auth, client.betterSupabase.meta);
 	const userId = auth.user?.id ?? null;
 	const debounceMs = options.debounceMs;
 	const hasInitial = initial !== void 0;
 	useEffect(() => {
-		if (!key || auth.status === "loading") return void 0;
-		const live = liveCount(browser.sb, browser.supabase, browser.db, JSON.parse(key), {
+		if (!key || auth.status === "loading") return;
+		const live = liveCount(client.betterSupabase, client.supabase, client.db, JSON.parse(key), {
 			immediate: !hasInitial,
-			onCount: (count) => setState({
-				key,
-				count,
-				error: void 0
-			}),
-			onError: (error) => setState((previous) => ({
-				key,
-				count: previous.key === key ? previous.count : void 0,
-				error
-			})),
+			onCount: (count) => {
+				setState({
+					key,
+					count,
+					error: void 0
+				});
+			},
+			onError: (error) => {
+				setState((previous) => ({
+					key,
+					count: previous.key === key ? previous.count : void 0,
+					error
+				}));
+			},
 			onStatus: setStatus,
 			...tenant === void 0 ? {} : { tenant },
 			...debounceMs === void 0 ? {} : { debounceMs }
@@ -223,7 +227,7 @@ function useLiveCount(source, options = {}) {
 			live.unsubscribe();
 		};
 	}, [
-		browser,
+		client,
 		key,
 		tenant,
 		userId,

package/dist/{read-set-4lI3W_gZ.js → read-set-FWK8qQ58.js}

@@ -1,5 +1,5 @@
-import { r as IrBuilder, u as tableMeta } from "./simplify-bwJpLnaS.js";
-import { n as touchedTables } from "./tables-rZxRxNPW.js";
+import { r as builderFor, u as tableMeta } from "./simplify-Cqvfr9dj.js";
+import { n as touchedTables } from "./tables-Cb-3_VWc.js";
 //#region src/core/spec.ts
 const READ_METHODS = [
 	"findMany",
@@ -40,7 +40,6 @@ 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
@@ -48,18 +47,54 @@ const builders = /* @__PURE__ */ new WeakMap();
 * spec reports the error.
 */
 function specTables(meta, spec) {
+	const table = meta.tables[spec.table];
+	const args = specOptions(spec);
+	if (table && args?.["include"] === void 0 && !touchesRelations(table, args?.["where"])) return [spec.table];
+	const key = specKey(spec);
+	let byKey = tablesByMeta.get(meta);
+	if (!byKey) {
+		byKey = /* @__PURE__ */ new Map();
+		tablesByMeta.set(meta, byKey);
+	}
+	const known = key === void 0 ? void 0 : byKey.get(key);
+	if (known) return [...known];
+	let tables;
 	try {
-		return readTables(meta, spec);
+		tables = readTables(meta, spec);
 	} catch {
-		return [spec.table];
+		tables = [spec.table];
+	}
+	if (key !== void 0) {
+		if (byKey.size >= SPEC_CACHE_SIZE) byKey.clear();
+		byKey.set(key, tables);
 	}
+	return [...tables];
 }
-function readTables(meta, spec) {
-	let builder = builders.get(meta);
-	if (!builder) {
-		builder = new IrBuilder(meta);
-		builders.set(meta, builder);
+const SPEC_CACHE_SIZE = 500;
+const tablesByMeta = /* @__PURE__ */ new WeakMap();
+/** A text key for the spec, or `undefined` when its arguments do not serialize. */
+function specKey(spec) {
+	try {
+		return JSON.stringify([
+			spec.table,
+			spec.method,
+			spec.args
+		], (_key, value) => typeof value === "bigint" ? `${value}n` : value);
+	} catch {
+		return;
 	}
+}
+function touchesRelations(table, where) {
+	if (typeof where !== "object" || where === null) return false;
+	if (Array.isArray(where)) return where.some((item) => touchesRelations(table, item));
+	for (const [key, value] of Object.entries(where)) {
+		if (key in table.relations) return true;
+		if ((key === "AND" || key === "OR" || key === "NOT") && touchesRelations(table, value)) return true;
+	}
+	return false;
+}
+function readTables(meta, spec) {
+	const builder = builderFor(meta);
 	const table = tableMeta(meta, spec.table);
 	const args = specOptions(spec);
 	const counts = spec.method === "count" || spec.method === "exists" || spec.method === "aggregate";
@@ -87,7 +122,7 @@ 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 NUL = "\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) {
@@ -98,7 +133,7 @@ function sentinel(name) {
 *
 * ```ts
 * export const appChrome = defineReadSet(
-*   sb,
+*   betterSupabase,
 *   'app_chrome',
 *   { params: { userId: 'uuid' } },
 *   (s, p) => ({
@@ -111,7 +146,7 @@ function sentinel(name) {
 * `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) {
+function defineReadSet(betterSupabase, 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 = {};
@@ -120,10 +155,10 @@ function defineReadSet(sb, name, options, build) {
 		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 specs = build(betterSupabase.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`);
+	for (const [key, spec] of entries) if (!isQuerySpec(spec)) throw new TypeError(`better-supabase: read set "${name}" entry "${key}" is not a spec from betterSupabase.spec`);
 	return {
 		kind: "read-set",
 		name,
@@ -131,7 +166,7 @@ function defineReadSet(sb, name, options, build) {
 		params,
 		roles: options.roles ?? ["authenticated"],
 		specs,
-		definition: sb
+		definition: betterSupabase
 	};
 }
 function isReadSet(value) {

package/dist/realtime/index.d.ts

@@ -1,4 +1,5 @@
-import { x as PermdockTopicPolicy } from "../types-C83v5SQz.js";
+import { x as PermdockTopicPolicy } from "../types-DONv9SHN.js";
+import { t as PermdockCatalog } from "../permdock-sql-DImJULY-.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 };
+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-BHakSWWo.js";
+export { type CountRunner, type EventSchemas, type LiveCountOptions, type LiveCountSeed, type LiveQueryOptions, type LiveSource, type LiveSubscription, type PermdockCatalog, type PermdockTopicPolicy, type RealtimeClient, type RowChange, type SubscribeOptions, type Subscription, type SubscriptionStatus, type TemplateParams, type TemplateValues, type Topic, type TopicEvent, type TopicHandlers, type TopicMessage, type TopicOptions, type TopicPayload, type TriggerOptions, defineTopic, liveCount, liveQuery, liveTopic, rowChange };

package/dist/realtime/index.js

@@ -1,11 +1,11 @@
-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 { n as dbError } from "../errors-L0xK41y_.js";
+import { i as ok, n as err, t as AsyncResult } from "../result-Bj6yt33D.js";
+import { i as tenantClaimPaths } from "../claims-BAf6c7is.js";
+import { n as liveQuery, r as liveTopic, t as liveCount } from "../live-CdJBOc4f.js";
+import { s as toApp } from "../shared-DnoCdMDr.js";
+import { a as sqlIdent, i as slug, o as sqlString, r as parseTemplate, t as permdockCheck } from "../permdock-sql-C4KFzLc9.js";
 import { REALTIME_SUBSCRIBE_STATES } from "@supabase/supabase-js";
-//#region src/realtime/index.ts
+//#region src/realtime/topic.ts
 const VALUE = /^[\w.@+=-]+$/;
 function validateValue(_name, value) {
 	return VALUE.test(value) ? void 0 : "contains characters topics do not allow";
@@ -55,7 +55,7 @@ function sendError(status, message) {
 */
 function defineTopic(template, options = {}) {
 	const parsed = parseTemplate(template, ":", validateValue);
-	const literal = template.replace(/\{[^}]+\}/g, " ");
+	const literal = template.replaceAll(/\{[^}]+\}/g, " ");
 	const name = slug(options.name ?? literal) || "topic";
 	const isPrivate = options.private ?? true;
 	const schemas = options.events ?? {};
@@ -71,10 +71,10 @@ function defineTopic(template, options = {}) {
 		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);
+		const receive = permdockCheck(where, permdock, permdock.receive, id, options.catalog);
 		return {
 			receive,
-			send: permdock.send === void 0 ? receive : permdockCheck(where, permdock, permdock.send, id)
+			send: permdock.send === void 0 ? receive : permdockCheck(where, permdock, permdock.send, id, options.catalog)
 		};
 	})();
 	if (!permdock && tenantParam && (options.tenant || parsed.params.includes(tenantParam))) {
@@ -119,8 +119,8 @@ function defineTopic(template, options = {}) {
 			}
 			return `${lines.join("\n")}\n`;
 		},
-		triggerSql(sb, table, trigger) {
-			const meta = sb.meta.tables[table];
+		triggerSql(betterSupabase, table, trigger) {
+			const meta = betterSupabase.meta.tables[table];
 			if (!meta) throw new TypeError(`defineTopic: unknown table "${table}"`);
 			const values = trigger.values;
 			const parts = template.split(/(\{[^}]+\})/).filter(Boolean).map((part) => {
@@ -131,7 +131,7 @@ function defineTopic(template, options = {}) {
 				if (!db) throw new TypeError(`defineTopic: no column for {${param}} on "${table}"`);
 				return `rec.${sqlIdent(db)}::text`;
 			});
-			const schema = trigger.functionSchema ?? "public";
+			const schema = trigger.functionSchema ?? "better_supabase";
 			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)}`;
@@ -142,6 +142,7 @@ function defineTopic(template, options = {}) {
 			]).join(" or ");
 			return [
 				`-- better-supabase: broadcast ${meta.name} changes to ${template}`,
+				`create schema if not exists ${sqlIdent(schema)};`,
 				`create or replace function ${fn}()`,
 				"returns trigger",
 				"language plpgsql",
@@ -235,13 +236,14 @@ function defineTopic(template, options = {}) {
 				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 open = client.getChannels().some((existing) => existing.topic === `realtime:${topic}`);
+				if (isPrivate && !open) 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);
+					if (!open) await client.removeChannel(channel);
 				}
 			});
 		}
@@ -251,8 +253,8 @@ function defineTopic(template, options = {}) {
 * 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];
+function rowChange(betterSupabase, table, message) {
+	const meta = betterSupabase.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;

package/dist/{index-CG69s15v.d.ts → refresh-BwYkyNOQ.d.ts}

@@ -1,6 +1,4 @@
-import { m as StoredSession } from "./resolve-CjHILk2w.js";
-import "./view-D1s0wa0T.js";
-import "./entitlements-Dng-ctuT.js";
+import { m as StoredSession } from "./resolve-BAqQcwMW.js";
 //#region src/auth/refresh.d.ts
 interface RefreshOptions {
   readonly url: string;
@@ -14,6 +12,12 @@ interface RefreshOptions {
     readonly secretKey: string;
   };
   readonly fetch?: typeof fetch;
+  /**
+   * Milliseconds before a refresh counts as a network failure (the session is
+   * kept). 5000 by default.
+   */
+  readonly timeoutMs?: number;
+  /** Epoch milliseconds, the unit JWT `exp` and `iat` math needs. */
   readonly now?: () => number;
 }
 type RefreshOutcome = {

package/dist/{resolve-CjHILk2w.d.ts → resolve-BAqQcwMW.d.ts}

@@ -1,7 +1,7 @@
-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 { p as DbError } from "./result-CqEsbgYs.js";
+import { f as Logger, l as RefreshEvent } from "./events-B21UOhvP.js";
+import { h as RequestContext } from "./plugin-bNhvJwRh.js";
+import { t as StandardSchemaV1 } from "./standard-BsaCYQJc.js";
 import { t as BetterSupabaseEnv } from "./index-Dy6kuF0P.js";
 import { CookieOptions } from "@supabase/ssr";
 import { JWTClaims, SupabaseEnv, UserClaims } from "@supabase/server";
@@ -46,9 +46,9 @@ declare function applyCookieWrites(cookies: readonly CookieRecord[], writes: rea
 //#endregion
 //#region src/auth/resolve.d.ts
 /**
- * Who is calling. `C` is the claims type from `sb.claims(schema)`; the
+ * Who is calling. `C` is the claims type from `betterSupabase.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)`.
+ * is the `user_metadata` type from `betterSupabase.userMetadata(schema)`.
  */
 type AuthState<C = unknown, P = unknown> = {
   readonly kind: "user";
@@ -59,7 +59,7 @@ type AuthState<C = unknown, P = unknown> = {
   /** Seconds since epoch, from the token's `exp`. */
   readonly expiresAt: number | null;
   /**
-   * `user_metadata` parsed by `sb.userMetadata(schema)`; `undefined`
+   * `user_metadata` parsed by `betterSupabase.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.
    */
@@ -76,7 +76,7 @@ type AuthState<C = unknown, P = unknown> = {
   readonly reason: InvalidReason;
   readonly error: DbError;
 };
-type InvalidReason = "token" | "claims";
+type InvalidReason = "token" | "claims" | "actor";
 /**
  * What an `AuthResolver` returns. `reason` may be left out of an `invalid`
  * state; it then counts as `token`.
@@ -101,8 +101,13 @@ 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. */
+  /**
+   * With `refresh`, refresh when the token expires within this many seconds.
+   * Defaults to 60. Without `refresh` a token stays valid until its `exp`.
+   */
   readonly leeway?: number;
+  /** Milliseconds before a refresh counts as a network failure. Defaults to 5000. */
+  readonly refreshTimeoutMs?: number;
   /**
    * Accept `sb_secret_` keys (`apikey` header) as service callers: `true` for
    * any configured key, or the key names allowed (`['cron']`). Defaults to false.
@@ -117,12 +122,12 @@ interface ResolveAuthOptions {
   /** 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
+   * Validates the verified claims (`betterSupabase.claims(schema)` sets it). A failure
    * resolves to `{ kind: 'invalid', reason: 'claims' }`.
    */
   readonly claims?: StandardSchemaV1;
   /**
-   * Parses `user_metadata` into `profile` (`sb.userMetadata(schema)` sets
+   * Parses `user_metadata` into `profile` (`betterSupabase.userMetadata(schema)` sets
    * it). A failure leaves `profile` undefined and warns once; the session
    * stays valid.
    */
@@ -140,6 +145,7 @@ interface ResolveAuthOptions {
   /** Called after every refresh attempt (metrics, logging). */
   readonly onRefresh?: (event: RefreshEvent) => void;
   readonly fetch?: typeof fetch;
+  /** Epoch milliseconds, the unit JWT `exp` and `iat` math needs. */
   readonly now?: () => number;
 }
 interface AuthResolution<C = unknown, P = unknown> {

package/dist/{resource-CgZa3YG_.d.ts → resource-BJcaIfxi.d.ts}

@@ -1,13 +1,14 @@
-import { N as TableKey, P as TableMeta, R as Update, _ as Insert, n as AnyModels, t as AnyFunctions } from "./types-C83v5SQz.js";
-import { b as ValidationIssue, o as Result } from "./result-CTkCZ6JA.js";
-import { t as BetterSupabase, xt as SelectArg } from "./define-e3zI4_4g.js";
-import { r as RespondOptions } from "./respond-Dne1ARSa.js";
-import { i as ResourceOperation } from "./index-DbxFr7XG.js";
+import { N as TableKey, P as TableMeta, R as Update, g as Insert, n as AnyModels, t as AnyFunctions } from "./types-DONv9SHN.js";
+import { b as ValidationIssue, o as Result } from "./result-CqEsbgYs.js";
+import { t as BetterSupabase, xt as SelectArg } from "./define-CRS2MRV3.js";
+import { i as RespondOptions } from "./respond-DgIbdrt8.js";
+import { i as ResourceOperation } from "./index-BhHEC04r.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/server/resource.d.ts
 /** What a resource needs from `defineListQuery`. */
 interface ResourceList {
   readonly table: string;
+  readonly pagination?: ResourcePagination;
   readonly openapi: readonly unknown[];
   readonly jsonSchema: Readonly<Record<string, unknown>>;
   parse(input: never): {
@@ -31,9 +32,16 @@ interface ResourceRouteOptions<M extends AnyModels, T extends TableKey<M>> {
     readonly create?: StandardSchemaV1<unknown, Insert<M, T>>;
     readonly update?: StandardSchemaV1<unknown, Update<M, T>>;
   };
-  /** Largest page for the default `page`/`size` list. Defaults to 200. */
+  /**
+   * Paging of the default list: `offset` (`page` and `size`) or `cursor`
+   * (`after` and `size`, keyset). A `list` query brings its own. Defaults
+   * to `offset`.
+   */
+  readonly pagination?: ResourcePagination;
+  /** Largest page for the default list. Defaults to 200. */
   readonly maxPageSize?: number;
 }
+type ResourcePagination = "offset" | "cursor";
 interface ResourceInput {
   /** Primary key value; strings are converted for integer keys. */
   readonly id?: unknown;
@@ -49,6 +57,7 @@ interface ResourceHandler {
   /** Name of the key parameter, or `undefined` for tables without a single-column key. */
   readonly keyParam: string | undefined;
   readonly list: ResourceList | undefined;
+  readonly pagination: ResourcePagination;
   readonly maxPageSize: number;
   /** Runs one operation as whoever `db` is bound to. Resolves to a `Result`. */
   execute(db: object, operation: ResourceOperation, input?: ResourceInput): Promise<Result<unknown>>;
@@ -60,6 +69,6 @@ interface ResourceHandler {
  * `createOpenApi`: `GET/POST /<table>` and `GET/PATCH/DELETE /<table>/{id}`.
  * Shared by the HTTP adapters and the MCP table tools.
  */
-declare function defineResource<M extends AnyModels, D, F extends AnyFunctions, E, T extends TableKey<M>>(sb: BetterSupabase<M, D, F, E>, table: T, options?: ResourceRouteOptions<M, T>): ResourceHandler;
+declare function defineResource<M extends AnyModels, D, F extends AnyFunctions, E, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, F, E>, table: T, options?: ResourceRouteOptions<M, T>): ResourceHandler;
 //#endregion
-export { defineResource as a, ResourceRouteOptions as i, ResourceInput as n, ResourceList as r, ResourceHandler as t };
+export { ResourceRouteOptions as a, ResourcePagination as i, ResourceInput as n, defineResource as o, ResourceList as r, ResourceHandler as t };