better-supabase 0.5.1 → 0.6.0

package/dist/nestjs/index.js

@@ -0,0 +1,164 @@
+import { a as routeRefusal, n as guardedLocals, t as errorResponse } from "../refusal-CeJWxmkH.js";
+import { t as beforeRoute } from "../before-route-CnR0C0Jr.js";
+import { t as applyWebHeaders } from "../node-headers-C71zNQHe.js";
+import { n as toWebRequest, t as sendWebResponse } from "../http-Cv4T29xh.js";
+import { createRequire } from "node:module";
+//#region src/nestjs/index.ts
+const contexts = /* @__PURE__ */ new WeakMap();
+/** The Node request under an Express request or a Fastify request (`request.raw`). */
+function rawOf(value) {
+	return "raw" in value && typeof value.raw === "object" && value.raw !== null ? value.raw : value;
+}
+function isServerResponse(value) {
+	return "setHeader" in value && typeof value.setHeader === "function" && "end" in value && typeof value.end === "function";
+}
+function responseOf(host) {
+	const raw = rawOf(host.switchToHttp().getResponse());
+	if (!isServerResponse(raw)) throw new TypeError("better-supabase: not an HTTP response");
+	return raw;
+}
+function requestOf(host) {
+	return rawOf(host.switchToHttp().getRequest());
+}
+/** The contributions `toNestMiddleware` stored for a request (Express or Fastify), if it ran. */
+function contextOf(request) {
+	return contexts.get(rawOf(request));
+}
+/** Calls `next()` when `step` resolves true and `next(error)` when it rejects. */
+async function continueWith(step, next) {
+	let proceed;
+	try {
+		proceed = await step;
+	} catch (error) {
+		next(error);
+		return;
+	}
+	if (proceed) next();
+}
+/**
+* Nest middleware that runs the entries before the route: a short circuit
+* (a 401, a CORS preflight) is the answer; otherwise the entries' cookies
+* go on the response and `@Ctx()` reads the contributions.
+*
+* ```ts title="src/app.module.ts"
+* export class AppModule implements NestModule {
+*   configure(consumer: MiddlewareConsumer) {
+*     consumer.apply(toNestMiddleware([withBetterSupabase(server)])).forRoutes('*')
+*   }
+* }
+* ```
+*/
+function toNestMiddleware(entries, options = {}) {
+	const run = beforeRoute(entries);
+	const handle = async (req, res) => {
+		const outcome = await run(toWebRequest(req, {
+			...options,
+			body: false
+		}), options.env?.(req));
+		if (!outcome.reached) {
+			await sendWebResponse(res, outcome.response);
+			return false;
+		}
+		applyWebHeaders(res, outcome.headers);
+		contexts.set(req, outcome.contributions);
+		return true;
+	};
+	return (req, res, next) => {
+		continueWith(handle(req, res), next);
+	};
+}
+function isNestCommon(value) {
+	return typeof value === "object" && value !== null && "createParamDecorator" in value && typeof value.createParamDecorator === "function" && "HttpException" in value && typeof value.HttpException === "function";
+}
+const NEST_COMMON = "@nestjs/common";
+let nest;
+/**
+* `@nestjs/common` is an optional peer, loaded on first use with a
+* variable specifier so apps on other frameworks never resolve it. It is
+* required synchronously because decorators run while the class is defined.
+*/
+function nestCommon() {
+	if (nest) return nest;
+	let loaded;
+	try {
+		loaded = createRequire(import.meta.url)(NEST_COMMON);
+	} catch (cause) {
+		throw new Error("better-supabase/nestjs needs @nestjs/common. Install it with `pnpm add @nestjs/common`.", { cause });
+	}
+	if (!isNestCommon(loaded)) throw new Error("better-supabase/nestjs: @nestjs/common has no createParamDecorator");
+	nest = loaded;
+	return nest;
+}
+let ctxDecorator;
+/**
+* A parameter decorator for the request's contributions, or one of them:
+* `@Ctx() ctx` or `@Ctx('db') db`.
+*
+* ```ts
+* @Get('notes')
+* list(@Ctx('db') db: Db) { return db.notes.findMany().orThrow() }
+* ```
+*/
+function Ctx(key) {
+	ctxDecorator ??= nestCommon().createParamDecorator((data, context) => {
+		const contributions = contextOf(context.switchToHttp().getRequest());
+		if (contributions === void 0) throw new Error("better-supabase: no request context; apply toNestMiddleware(...) for this route");
+		return typeof data === "string" ? contributions[data] : contributions;
+	});
+	return ctxDecorator(key);
+}
+/**
+* A guard instance that refuses callers outside `options`: Problem Details,
+* or a 303 to `signIn` or `mfa`, thrown as Nest's `HttpException`.
+*
+* ```ts
+* @UseGuards(guard({ roles: ['admin'] }))
+* ```
+*/
+function guard(options = {}) {
+	return { canActivate: async (context) => {
+		const req = requestOf(context);
+		const contributions = contexts.get(req);
+		if (contributions === void 0) throw new Error("better-supabase: no request context; apply toNestMiddleware(...) before the guard");
+		const refused = await routeRefusal(guardedLocals(contributions), toWebRequest(req, { body: false }), options);
+		if (!refused) return true;
+		const location = refused.headers.get("location");
+		if (location !== null) responseOf(context).setHeader("location", location);
+		const body = refused.body ? await refused.json() : {};
+		const { HttpException } = nestCommon();
+		throw new HttpException(typeof body === "object" && body !== null ? body : {}, refused.status);
+	} };
+}
+/**
+* An exception filter that answers thrown `DbException`s (from
+* `.orThrow()`) with Problem Details. Register it with `@Catch()` scope in
+* mind: other exceptions are answered the way Nest's base filter does.
+*/
+function problemFilter(options = {}) {
+	return { catch(exception, host) {
+		const req = requestOf(host);
+		const res = responseOf(host);
+		const response = errorResponse(exception, toWebRequest(req, { body: false }), options) ?? nestErrorResponse(exception);
+		if (res.headersSent) return;
+		sendWebResponse(res, response);
+	} };
+}
+function isHttpException(value) {
+	return typeof value === "object" && value !== null && "getStatus" in value && typeof value.getStatus === "function" && "getResponse" in value && typeof value.getResponse === "function";
+}
+function nestErrorResponse(exception) {
+	if (isHttpException(exception)) {
+		const status = exception.getStatus();
+		const body = exception.getResponse();
+		return Response.json(typeof body === "string" ? {
+			statusCode: status,
+			message: body
+		} : body, { status: typeof status === "number" ? status : 500 });
+	}
+	return Response.json({
+		statusCode: 500,
+		message: "Internal server error"
+	}, { status: 500 });
+}
+//#endregion
+export { Ctx, contextOf, guard, problemFilter, toNestMiddleware };

package/dist/next/client/index.d.ts

@@ -0,0 +1,35 @@
+//#region src/next/client/index.d.ts
+/** The `push` and `refresh` `useSessionChange` needs; next-intl's router fits. */
+export interface SessionChangeRouter {
+  push(href: string): void;
+  refresh(): void;
+}
+/** The part of a supabase-js client `refreshToken` calls, e.g. `useSupabase()`. */
+export interface TokenRefresher {
+  readonly auth: {
+    refreshSession(): Promise<{
+      readonly error: Error | null;
+    }>;
+  };
+}
+export interface SessionChangeOptions {
+  /**
+   * Refresh the browser's access token first, so the server reads the new
+   * claims (an organization switch, a new membership) from the cookie.
+   */
+  readonly refreshToken?: TokenRefresher;
+}
+/**
+ * After a session change, expire the server cache (`changed`), navigate,
+ * then refresh the client router. `refresh()` in a Server Action leaves
+ * prefetched private App Shells, so `router.push` alone shows the old
+ * session. Pass a next-intl (or other) router when `push` must keep the
+ * locale prefix.
+ *
+ * ```ts
+ * const switched = useSessionChange(sessionChanged, router, { refreshToken: useSupabase() });
+ * await switched('/dashboard');
+ * ```
+ */
+export declare function useSessionChange(changed: () => Promise<void>, router?: SessionChangeRouter, options?: SessionChangeOptions): (to?: string) => Promise<void>;
+//#endregion

package/dist/next/client/index.js

@@ -0,0 +1,36 @@
+"use client";
+import { useCallback } from "react";
+import { useRouter } from "next/navigation.js";
+//#region src/next/client/index.ts
+/**
+* After a session change, expire the server cache (`changed`), navigate,
+* then refresh the client router. `refresh()` in a Server Action leaves
+* prefetched private App Shells, so `router.push` alone shows the old
+* session. Pass a next-intl (or other) router when `push` must keep the
+* locale prefix.
+*
+* ```ts
+* const switched = useSessionChange(sessionChanged, router, { refreshToken: useSupabase() });
+* await switched('/dashboard');
+* ```
+*/
+function useSessionChange(changed, router, options = {}) {
+	const nextRouter = useRouter();
+	const used = router ?? nextRouter;
+	const refresher = options.refreshToken;
+	return useCallback(async (to) => {
+		if (refresher) {
+			const { error } = await refresher.auth.refreshSession();
+			if (error) throw error;
+		}
+		await changed();
+		if (to !== void 0) used.push(to);
+		used.refresh();
+	}, [
+		changed,
+		used,
+		refresher
+	]);
+}
+//#endregion
+export { useSessionChange };

package/dist/next/image/index.js

@@ -1,11 +1,5 @@
+import { t as storageImageUrl } from "../../image-url-pIVlO6R1.js";
 //#region src/next/image/index.ts
-/** Storage's image transformation limits. */
-const MAX_WIDTH = 2500;
-const QUALITY = {
-	min: 20,
-	max: 100
-};
-const clamp = (value, min, max) => Math.min(max, Math.max(min, Math.round(value)));
 /**
 * A `next/image` loader that serves public Storage objects through
 * Supabase image transformations (`/render/image/public`), so Next.js does
@@ -20,24 +14,9 @@ const clamp = (value, min, max) => Math.min(max, Math.max(min, Math.round(value)
 * were signed with, so sign them with `renderUrl()` at the size you render.
 */
 function createImageLoader(options) {
-	const storage = `${options.url.replace(/\/+$/, "")}/storage/v1`;
-	const publicPrefixes = [`${storage}/object/public/`, `${storage}/render/image/public/`].map((prefix) => ({
-		prefix,
-		length: new URL(prefix).pathname.length
-	}));
+	const imageUrl = storageImageUrl(options);
 	const fallback = options.fallback ?? (({ src }) => src);
-	return (props) => {
-		const prefix = publicPrefixes.find((candidate) => props.src.startsWith(candidate.prefix));
-		if (prefix === void 0) return fallback(props);
-		const source = new URL(props.src);
-		const object = source.pathname.slice(prefix.length);
-		const target = new URL(`${storage}/render/image/public/${object}`);
-		for (const [key, value] of source.searchParams) target.searchParams.set(key, value);
-		target.searchParams.set("width", String(clamp(props.width, 1, MAX_WIDTH)));
-		if (props.quality !== void 0) target.searchParams.set("quality", String(clamp(props.quality, QUALITY.min, QUALITY.max)));
-		if (options.resize) target.searchParams.set("resize", options.resize);
-		return target.toString();
-	};
+	return (props) => imageUrl(props.src, props) ?? fallback(props);
 }
 //#endregion
 export { createImageLoader };

package/dist/next/index.d.ts

@@ -1,13 +1,16 @@
-import { n as AnyFunctions, r as AnyModels } from "../types-Dnf_wRDz.js";
-import { _ as DbError } from "../executor-BunPOO-k.js";
-import { B as ReadSet, P as DbStats, Z as QuerySpec, l as CacheAdapter, t as BetterSupabase } from "../define-Bp_BZa5h.js";
-import { n as Impersonator, o as AuthState } from "../impersonation-BmePsuxz.js";
-import { C as SupportOptions, D as supportSessions, E as SupportStartRequest, T as SupportSessions, b as ActiveSupport, d as ContextOptions, f as ServerContext, n as GuardOptions, p as ServerOptions, t as AuthKind, u as BetterServer, w as SupportPolicy } from "../respond-BR1fJWOB.js";
-import { n as AmrEntry, t as Aal } from "../mfa-Cu96oJdw.js";
-import { n as toSession, t as AuthSession } from "../view-CbgObAeb.js";
-import { r as LiveCountSeed, t as CountRunner } from "../live-D9W2M5aO.js";
-import { n as supportOf, t as SupportView } from "../support-view-B8SlToQX.js";
-import { n as MembershipClaim, r as hasEntitlement, t as EntitlementKey } from "../entitlements-BiJZ4t49.js";
+import { a as AnyModels, i as AnyFunctions } from "../types-6BdhkmZe.js";
+import { r as AuthState } from "../resolve-KW8nCeL6.js";
+import { B as DbStats, K as ReadSet, it as QuerySpec, t as BetterSupabase, u as CacheAdapter } from "../define-CJJkkr1-.js";
+import { C as SupportOptions, D as supportSessions, E as SupportStartRequest, T as SupportSessions, b as ActiveSupport, i as ServerContext, n as ContextOptions, o as ServerOptions, t as BetterServer, w as SupportPolicy } from "../server-CeVeeXwz.js";
+import { n as AmrEntry, s as Impersonator, t as Aal } from "../mfa-Daak8ukG.js";
+import { t as tenantOf } from "../tenant-icPeuUBN.js";
+import { n as toSession, t as AuthSession } from "../view-DbxLNu8L.js";
+import { n as AuthKind, r as GuardOptions } from "../respond-DoBijysA.js";
+import { a as AuthorizedContext, c as Unwrapped, i as AuthorizeOptions, n as ActionParsed, r as ActionResult, t as ActionInput } from "../kit-B5tid-q5.js";
+import { r as LiveCountSeed, t as CountRunner } from "../index-DunNRdnT.js";
+import { r as MembershipClaim } from "../entitlements-DHrY2UDZ.js";
+import { i as tagFor, t as TagOptions } from "../tags-Cx-LnIQP.js";
+import { n as supportOf, t as SupportView } from "../support-view-33Oi07TT.js";
 import { NextRequest } from "next/server.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/next/collector.d.ts
@@ -48,6 +51,21 @@ interface ProxyOptions<C = unknown, P = unknown> {
   readonly before?: (request: NextRequest) => Response | undefined | Promise<Response | undefined>;
   /** Answer before rendering, e.g. redirect signed-out users. Refreshed cookies are kept. */
   readonly protect?: (auth: AuthState<C, P>, request: NextRequest) => Response | undefined | Promise<Response | undefined>;
+  /**
+   * A prefetch never refreshes, so a session cookie whose token expired
+   * resolves to `{ kind: 'anon', reason: 'expired' }` there. `'protect'`
+   * (the default) passes that to `protect` like any other caller.
+   * `'render'` skips `protect` for it, so the prefetch renders signed out
+   * instead of caching a redirect to sign-in; `sessionStale` keeps that view
+   * out of the App Shell, and the navigation itself refreshes the session.
+   */
+  readonly expiredPrefetch?: "protect" | "render";
+  /**
+   * Methods that run `protect`. Defaults to `GET` and `HEAD`, so a Server
+   * Action POST is not redirected before the action runs. Set `true` to
+   * include mutations, or pass the methods yourself.
+   */
+  readonly protectMethods?: true | readonly string[];
   /** Post-processes the final response; return a new one to replace it. */
   readonly after?: (response: Response, auth: AuthState<C, P>) => Response | undefined | void | Promise<Response | undefined | void>;
   /**
@@ -55,36 +73,57 @@ interface ProxyOptions<C = unknown, P = unknown> {
    * proxy, and resolving the session (a local verify, or a refresh).
    */
   readonly serverTiming?: boolean;
+  readonly endedSession?: true | EndedSessionOptions;
 }
-type ActionResult<T> = {
-  readonly ok: true;
-  readonly data: T;
-  readonly error: null;
-} | {
-  readonly ok: false;
-  readonly data: null;
-  readonly error: DbError;
-};
-interface ActionOptions<S extends StandardSchemaV1 | undefined> extends GuardOptions {
+interface EndedSessionOptions {
+  readonly paths?: readonly string[];
+  readonly redirect?: string;
+}
+interface ActionOptions<S extends StandardSchemaV1 | undefined, C = unknown, P = unknown, R extends boolean = boolean> extends GuardOptions, AuthorizeOptions<ActionParsed<S>, C, P, R> {
   /** Validates the input (plain object or `FormData`) with any Standard Schema. */
   readonly input?: S;
+  /**
+   * The active tenant for the action's context, from the validated input,
+   * instead of `NextOptions.tenant`. It is checked the same way: the
+   * `tenant()` plugin and `current_tenant_id()` only honor a tenant the
+   * caller belongs to.
+   */
+  readonly tenant?: (input: ActionParsed<S>) => string | undefined;
+}
+interface RouteOptions<C = unknown, P = unknown, R extends boolean = boolean> extends GuardOptions, AuthorizeOptions<NextRequest, C, P, R> {
+  /**
+   * Refresh an expired session cookie in the route and send the new cookies
+   * with its response. For routes the proxy's matcher skips; off by default
+   * because the proxy refreshes everything it matches.
+   */
+  readonly refresh?: boolean;
+}
+interface RequireOptions<C = unknown, P = unknown, R extends boolean = boolean> extends GuardOptions, AuthorizeOptions<undefined, C, P, R> {
+  /** The active tenant, as for `bs.context({ tenant })`. */
+  readonly tenant?: string;
+}
+interface ScopeOptions {
+  /**
+   * The active tenant, e.g. from route params, instead of `NextOptions.tenant`
+   * (whose request has the incoming headers but no URL here). It goes where
+   * the resolver's result goes, so it gets the same checks: the `tenant()`
+   * plugin and `current_tenant_id()` only honor a tenant the caller belongs to.
+   */
+  readonly tenant?: string;
 }
-type ActionInput<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferInput<S> | FormData : unknown;
-type ActionParsed<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : unknown;
-type Unwrapped<T> = T extends {
-  readonly ok: true;
-  readonly data: infer D;
-} | {
-  readonly ok: false;
-} ? D : T;
 interface BetterNext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends BetterServer<M, F, E, C, P> {
   /** `proxy.ts`: refreshes sessions for page loads and server actions. */
   proxy(request: NextRequest, options?: ProxyOptions<C, P>): Promise<Response>;
   /**
    * The caller's context. Without a request (Server Components, actions) it
-   * reads the incoming headers and is memoized per request.
+   * reads the incoming headers and is memoized per request and tenant.
+   *
+   * ```ts
+   * const { db } = await bs.context({ tenant: organizationId });
+   * ```
    */
-  context(request?: Request, options?: ContextOptions): Promise<ServerContext<M, F, E, C, P>>;
+  context(options?: ScopeOptions): Promise<ServerContext<M, F, E, C, P>>;
+  context(request: Request | undefined, options?: ContextOptions): Promise<ServerContext<M, F, E, C, P>>;
   /**
    * The verified caller as serializable data (no token, no clients), memoized
    * per request. Wrap it in a `'use cache: private'` function with Cache
@@ -113,10 +152,14 @@ interface BetterNext<M extends AnyModels, F extends AnyFunctions, E, C = unknown
    * }
    * ```
    */
-  cached(options?: CachedOptions): Promise<CachedContext<M, F, E, C, P>>;
+  cached(options?: CachedOptions<Extract<keyof M, string>>): Promise<CachedContext<M, F, E, C, P>>;
   /**
    * Drops every `bs.cached()` entry of a user, e.g. after a role change,
-   * and the entries tagged with `tags` (such as PermDock's `snapshotTag(userId)`).
+   * and the entries tagged with `tags` (such as a permission snapshot's tag).
+   * In a Server Action it also re-renders the caller's page, so no
+   * `refresh()` is needed. It reaches server caches and the caller's router
+   * only: another user's browser keeps its `'use cache: private'` entries
+   * until they go stale or that user's token changes.
    */
   invalidateSession(userId: string, options?: {
     readonly tags?: readonly string[];
@@ -130,21 +173,44 @@ interface BetterNext<M extends AnyModels, F extends AnyFunctions, E, C = unknown
    */
   liveCount<T extends Extract<keyof M, string>>(spec: QuerySpec<T, "count", number>, db?: CountRunner): Promise<LiveCountSeed<T>>;
   /** Route handler with auth, Result unwrapping and Problem Details errors. */
-  route<Params = Record<string, string | string[]>>(handler: (request: NextRequest, ctx: ServerContext<M, F, E, C, P> & {
+  route<Params = Record<string, string | string[]>, R extends boolean = false>(handler: (request: NextRequest, ctx: ServerContext<M, F, E, C, P> & AuthorizedContext<C, P, R> & {
     readonly params: Params;
-  }) => unknown, options?: GuardOptions): (request: NextRequest, segment: {
+  }) => unknown, options?: RouteOptions<C, P, R>): (request: NextRequest, segment: {
     readonly params: Promise<Params>;
   }) => Promise<Response>;
-  /** Server action returning a serializable `ActionResult`. */
-  action<S extends StandardSchemaV1 | undefined, T>(options: ActionOptions<S>, fn: (input: ActionParsed<S>, ctx: ServerContext<M, F, E, C, P>) => Promise<T> | T): (input: ActionInput<S>) => Promise<ActionResult<Unwrapped<Awaited<T>>>>;
-  /** Tags the current `"use cache"` scope with a table (and row) tag. */
-  cacheTag(table: Extract<keyof M, string>, id?: string | number): void;
+  /**
+   * Server action returning a serializable `ActionResult`.
+   *
+   * ```ts
+   * export const invite = bs.action(
+   *   { input: Invite, requireTenant: true, roles: ['admin'] },
+   *   async (input, { db, tenant }) => db.invitations.create({ ...input, organizationId: tenant }),
+   * );
+   * ```
+   */
+  action<S extends StandardSchemaV1 | undefined, T, R extends boolean = false>(options: ActionOptions<S, C, P, R>, fn: (input: ActionParsed<S>, ctx: ServerContext<M, F, E, C, P> & AuthorizedContext<C, P, R>) => Promise<T> | T): (input: ActionInput<S>) => Promise<ActionResult<Unwrapped<Awaited<T>>>>;
+  /**
+   * For Server Components: the caller's context, or the Next.js interrupt
+   * for a refused caller. `unauthorized` calls `unauthorized()`, `forbidden`
+   * calls `forbidden()` (both need `experimental.authInterrupts`, else
+   * `notFound()`), and `not_found` calls `notFound()`.
+   *
+   * ```ts
+   * const { db, tenant } = await bs.require({ requireTenant: true, roles: ['admin'] });
+   * ```
+   */
+  require<R extends boolean = false>(options?: RequireOptions<C, P, R>): Promise<ServerContext<M, F, E, C, P> & AuthorizedContext<C, P, R>>;
+  /**
+   * Tags the current `"use cache"` scope with a table (and row) tag. With a
+   * `tenant`, mutations in other tenants leave the entry cached.
+   */
+  cacheTag(table: Extract<keyof M, string>, id?: string | number, options?: TagOptions): void;
   /**
    * Tags the current `"use cache"` scope with every table the specs (or a
    * read set) read, plus the row of each `findById`, so any mutation that
    * changes one revalidates it.
    */
-  cacheTags(target: QuerySpec<Extract<keyof M, string>> | readonly QuerySpec<Extract<keyof M, string>>[] | ReadSet): void;
+  cacheTags(target: QuerySpec<Extract<keyof M, string>> | readonly QuerySpec<Extract<keyof M, string>>[] | ReadSet, options?: TagOptions): void;
   /**
    * GET handler serving a request's database totals (`?id=<request id>`) for
    * `expectDbBudget`. Answers 404 unless `debug` is on.
@@ -172,20 +238,34 @@ interface SupportStarted {
 /** The tag `bs.cached()` adds to entries rendered in a support session. */
 export declare function supportTag(sessionId: string): string;
 interface SessionStaleOptions {
-  /** Below this, the result would not be prefetched anyway. Defaults to 30. */
+  /**
+   * With fewer seconds left on the token, the view is not reused at all (0):
+   * Next.js would not prefetch it anyway. Defaults to 30, and values below
+   * 30 count as 30: the client router keeps any entry for at least 30
+   * seconds, so a shorter stale time would outlive the token.
+   */
   readonly min?: number;
   /** 300 (5 minutes) joins the route's App Shell. Defaults to 300. */
   readonly max?: number;
 }
 /**
  * `cacheLife` `stale` seconds for a view of `session`: `max`, but never past
- * the token's expiry, and at least `min`.
+ * the token's expiry, and 0 once fewer than `min` seconds are left. A
+ * signed-out view that a refresh would change (an `expired` or
+ * `refresh_failed` cookie, or an `invalid` token) is 0 as well, so it never
+ * joins the App Shell.
  */
 export declare function sessionStale(session: AuthSession, options?: SessionStaleOptions, now?: number): number;
-interface CachedOptions {
+interface CachedOptions<T extends string = string> extends ScopeOptions {
+  /**
+   * The active tenant, as for `bs.context({ tenant })`. Next.js keys the
+   * private cache on your function's arguments, so take the tenant as an
+   * argument and pass it through; never read it from anywhere else.
+   */
+  readonly tenant?: string;
   /**
    * `cacheLife` for the entry. `stale` is `sessionStale`, and never more than
-   * `stale` when it is set: pass PermDock's `cacheLifeFor(snapshot)` so the
+   * `stale` when it is set: pass a permission snapshot's lifetime so the
    * entry goes stale with the snapshot too.
    */
   readonly life?: SessionStaleOptions & {
@@ -193,22 +273,40 @@ interface CachedOptions {
     readonly revalidate?: number;
     readonly expire?: number;
   };
-  /** More `cacheTag`s for the entry, e.g. `snapshotTag(sub)` or `org:<id>`. */
+  /** More `cacheTag`s for the entry, e.g. `snapshotTag(sub)` or `organization:<id>`. */
   readonly tags?: readonly string[];
+  /**
+   * Tables the entry reads, so the `updateTag` after a mutation drops it:
+   * `bs:<table>`, or with an active tenant `bs:<table>@<tenant>` and
+   * `bs:<table>@*`, so other tenants' writes leave it cached.
+   */
+  readonly tables?: readonly T[];
+  /** With `tables`, also tags the row `bs:<first table>:<id>`. */
+  readonly id?: string | number;
 }
 type CachedContext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> = ServerContext<M, F, E, C, P> & {
   readonly session: AuthSession<C, P>;
 };
 /** The tag `bs.cached()` puts on a user's entries. */
 export declare function sessionTag(userId: string): string;
-/** `bs:<table>` or `bs:<table>:<id>`. Mutations invalidate both. */
-export declare function tagFor(table: string, id?: string | number): string;
+interface NextCacheOptions {
+  /**
+   * How a mutation outside a Server Action (a route handler, a webhook)
+   * expires its tags with `revalidateTag`. Defaults to `{ expire: 0 }`, so
+   * the next read waits for fresh data; `'max'` serves the stale entry
+   * while it revalidates.
+   */
+  readonly revalidate?: string | {
+    readonly expire?: number;
+  };
+}
 /**
- * Invalidates `bs:<table>` for every table in the target and
- * `bs:<table>:<id>` for the changed rows. `createNext` attaches it unless
- * `cacheTags: false`.
+ * Invalidates `bs:<table>` for every table in the target, the tenant's
+ * `bs:<table>@<tenant>` (every tenant's `bs:<table>@*` when the mutation has
+ * no tenant) and `bs:<table>:<id>` for the changed rows. Reads another tenant
+ * tagged stay cached. `createNext` attaches it unless `cacheTags: false`.
  */
-export declare function nextCache(): CacheAdapter;
+export declare function nextCache(options?: NextCacheOptions): CacheAdapter;
 interface RequireAalOptions {
   /**
    * Page that enrolls or challenges a second factor. Signed-in users below
@@ -232,6 +330,7 @@ interface RequireAalOptions {
  * ```
  */
 export declare function requireAal(level: Aal, options?: RequireAalOptions): (auth: AuthState, request: NextRequest) => Response | undefined;
+export declare function shouldCheckSession(request: NextRequest, options?: EndedSessionOptions): boolean;
 /** Page loads, client navigations and server actions; never prefetches or assets. */
 export declare function shouldRefresh(request: Request): boolean;
 /**
@@ -244,4 +343,4 @@ export declare function shouldRefresh(request: Request): boolean;
  */
 export declare function createNext<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, options?: NextOptions): BetterNext<M, F, E, C, P>;
 //#endregion
-export { type Aal, type ActionOptions, type ActionResult, type ActiveSupport, type AmrEntry, type AuthKind, type AuthSession, type BetterNext, type CachedContext, type CachedOptions, type DbBudget, type DbStats, type EntitlementKey, type GuardOptions, type Impersonator, type LiveCountSeed, type MembershipClaim, type NextDebugOptions, type NextOptions, type ProxyOptions, type RequireAalOptions, type SessionStaleOptions, type SupportOptions, type SupportPolicy, type SupportSessions, type SupportStartRequest, type SupportStarted, type SupportView, hasEntitlement, supportOf, supportSessions, toSession };
+export { type Aal, type ActionOptions, type ActionResult, type ActiveSupport, type AmrEntry, type AuthKind, type AuthSession, type AuthorizeOptions, type AuthorizedContext, type BetterNext, type CachedContext, type CachedOptions, type DbBudget, type DbStats, type EndedSessionOptions, type GuardOptions, type Impersonator, type LiveCountSeed, type MembershipClaim, type NextCacheOptions, type NextDebugOptions, type NextOptions, type ProxyOptions, type RequireAalOptions, type RequireOptions, type RouteOptions, type ScopeOptions, type SessionStaleOptions, type SupportOptions, type SupportPolicy, type SupportSessions, type SupportStartRequest, type SupportStarted, type SupportView, type TagOptions, supportOf, supportSessions, tagFor, tenantOf, toSession };