better-supabase 0.3.0 → 0.5.0

package/dist/mcp/index.js

@@ -1,11 +1,11 @@
-import { n as dbError } from "../errors-Bl3rkOzo.js";
-import { t as base64ToText } from "../base64-CQeB1eSf.js";
-import { t as validate } from "../standard-FUi3Z3-7.js";
-import { o as toProblem } from "../problem-CGt1ADix.js";
+import { n as dbError } from "../errors-DtwXa6b8.js";
+import { t as base64ToText } from "../base64-D2gsioCY.js";
+import { t as validate } from "../standard-D7r6dMUu.js";
+import { a as problemResponse, o as toProblem } from "../problem-BW1KhzSG.js";
 import { t as SPEC_PINS } from "../spec-pins-C3oc-Tdp.js";
-import { t as buildJsonSchema } from "../json-schema--aOXAGfU.js";
-import { a as settle, c as withExtra, n as guard, o as createServer, s as extendServer, t as defaultExpose } from "../respond-C44EZAJo.js";
-import { t as defineResource } from "../resource-D30rp0GN.js";
+import { t as buildJsonSchema } from "../json-schema-m1fiwKgN.js";
+import { a as withExtra, d as guard, g as jsonResponse, h as jsonReplacer, m as settle, n as createServer, r as extendServer, u as defaultExpose } from "../server-Csx2sRjg.js";
+import { t as defineResource } from "../resource-CRxxwkQq.js";
 import { fromSupabaseUrl, unauthorizedResponse } from "@supabase/server/oauth-protected-resource";
 //#region src/mcp/mcp.ts
 const MCP_PROTOCOL_VERSION = SPEC_PINS.mcp;
@@ -215,7 +215,7 @@ function textResult(value, isError = false) {
 	return {
 		content: [{
 			type: "text",
-			text: typeof value === "string" ? value : JSON.stringify(value ?? null)
+			text: typeof value === "string" ? value : JSON.stringify(value ?? null, jsonReplacer)
 		}],
 		...structured ? { structuredContent: structured } : {},
 		...isError ? { isError: true } : {}
@@ -231,17 +231,19 @@ function canonical(request) {
 * through RLS. Answers 401 with RFC 9728 metadata so clients can sign in with
 * Supabase Auth's OAuth server.
 */
-function createMcp(sb, options) {
-	const server = createServer(sb, options);
+function createMcp(betterSupabase, options) {
+	const server = createServer(betterSupabase, options);
 	const expose = options.exposeErrors ?? defaultExpose();
 	const defs = buildJsonSchema({
-		meta: sb.meta,
+		meta: betterSupabase.meta,
 		config: { json: options.json ?? {} }
 	})["$defs"];
 	const registry = /* @__PURE__ */ new Map();
+	let allTools;
 	const register = (entry) => {
 		if (registry.has(entry.info.name)) throw new TypeError(`Duplicate MCP tool "${entry.info.name}"`);
 		registry.set(entry.info.name, entry);
+		allTools = void 0;
 	};
 	const failure = (error) => textResult(toProblem(error, { expose }), true);
 	const refused = async (tool, args, ctx) => {
@@ -256,11 +258,14 @@ function createMcp(sb, options) {
 	const isVisible = async (tool, ctx) => !options.visible || options.visible(ctx, tool);
 	for (const [table, raw] of Object.entries(options.resources ?? {})) {
 		if (!raw) continue;
-		const resource = defineResource(sb, table, raw === true ? {} : raw);
+		const key = table;
+		const entry = raw;
+		const { meta, ...route } = entry === true ? {} : entry;
+		const resource = defineResource(betterSupabase, key, route);
 		for (const { info, operation } of tableTools(resource, defs)) {
 			const ref = {
 				info,
-				meta: void 0
+				meta: meta?.[operation]
 			};
 			register({
 				...ref,
@@ -302,8 +307,11 @@ function createMcp(sb, options) {
 		});
 	};
 	for (const tool of options.tools ?? []) addTool(tool);
-	const listTools = () => [...registry.values()].map((entry) => entry.info);
-	const visibleTools = async (ctx) => {
+	const listTools = () => allTools ??= [...registry.values()].map((entry) => entry.info);
+	/** Without a `visible` hook every caller sees the same list, built once. */
+	const visibleTools = async (context) => {
+		if (!options.visible) return listTools();
+		const ctx = context();
 		const entries = [...registry.values()];
 		const shown = await Promise.all(entries.map((entry) => isVisible(entry, ctx)));
 		return entries.filter((_, index) => shown[index]).map((e) => e.info);
@@ -333,7 +341,7 @@ function createMcp(sb, options) {
 		const outcome = await invoke(name, args, ctx);
 		return isRefusal(outcome) ? failure(dbError("forbidden", outcome.refusal)) : outcome;
 	};
-	const scopes = (options.scopes ?? []).filter((scope) => scope !== "offline_access");
+	const scopes = (options.advertisedScopes ?? options.scopes ?? []).filter((scope) => scope !== "offline_access");
 	const serverInfo = {
 		name: options.name,
 		version: options.version,
@@ -357,6 +365,12 @@ function createMcp(sb, options) {
 		response.headers.set("www-authenticate", challenge);
 		return response;
 	};
+	/** A missing second factor is no scope problem, and an outage is not the caller's fault. */
+	const refuse = (request, denied) => {
+		if (denied.kind === "unauthorized") return unauthorized(request);
+		if (denied.kind !== "forbidden") return problemResponse(denied, { expose });
+		return denied.code === "INSUFFICIENT_AAL" ? rpcError(null, INVALID_REQUEST, denied.message, 403) : forbidden(request, denied.message, denied.scopes);
+	};
 	const unsupportedVersion = (id, requested) => rpcError(id, UNSUPPORTED_PROTOCOL_VERSION, "Unsupported protocol version", 400, {
 		supported: [...SUPPORTED_VERSIONS],
 		requested
@@ -376,7 +390,7 @@ function createMcp(sb, options) {
 			if (sent === null || headerName(sent) !== name) return mismatch(`Mcp-Name must be ${name}`);
 		}
 	};
-	const handler = async (request) => {
+	const endpoint = async (request) => {
 		const origin = request.headers.get("origin");
 		if (origin && options.allowedOrigins && !options.allowedOrigins.includes(origin)) return rpcError(null, INVALID_REQUEST, "Origin not allowed", 403);
 		if (options.allowedHosts && !hostAllowed(request, options.allowedHosts)) return rpcError(null, INVALID_REQUEST, "Host not allowed", 403);
@@ -386,9 +400,9 @@ function createMcp(sb, options) {
 		});
 		const header = request.headers.get("mcp-protocol-version");
 		if (header && !SUPPORTED_VERSIONS.includes(header)) return unsupportedVersion(null, header);
-		const ctx = await server.context(request);
-		const denied = guard(ctx.auth, options.allow, options.aal);
-		if (denied) return denied.kind === "unauthorized" ? unauthorized(request) : forbidden(request, denied.message);
+		const ctx = await server.context(request, { cookies: false });
+		const denied = guard(ctx.auth, options.allow, options.aal, options.requiredScopes);
+		if (denied) return refuse(request, denied);
 		let message;
 		try {
 			message = await request.json();
@@ -407,7 +421,7 @@ function createMcp(sb, options) {
 			request,
 			signal: request.signal
 		});
-		const reply = (result) => Response.json({
+		const reply = (result) => jsonResponse({
 			jsonrpc: "2.0",
 			id: message.id,
 			result: modern ? {
@@ -437,7 +451,7 @@ function createMcp(sb, options) {
 			}
 			case "ping": return modern ? notFound() : reply({});
 			case "tools/list": return reply({
-				tools: await visibleTools(toolContext()),
+				tools: await visibleTools(toolContext),
 				...modern ? {
 					ttlMs: LIST_TTL_MS,
 					cacheScope: "private"
@@ -465,14 +479,14 @@ function createMcp(sb, options) {
 	}, { headers: { "access-control-allow-origin": "*" } });
 	const mcp = extendServer(server, {
 		get tools() {
-			return listTools();
+			return [...listTools()];
 		},
 		tool(definition) {
 			addTool(defineTool(definition));
 			return mcp;
 		},
 		call,
-		handler,
+		endpoint,
 		metadata,
 		fetch(request) {
 			const { pathname } = new URL(request.url);
@@ -483,7 +497,7 @@ function createMcp(sb, options) {
 					"access-control-allow-methods": "GET"
 				}
 			}) : metadata(request));
-			return handler(request);
+			return endpoint(request);
 		}
 	});
 	return mcp;

package/dist/{mfa-x3V3vGh-.d.ts → mfa-CusDgPaD.d.ts}

@@ -1,9 +1,13 @@
-import { p as DbError } from "./result-c2OYgCV2.js";
+import { _ as DbError } from "./executor-BunPOO-k.js";
 //#region src/auth/impersonation.d.ts
 /** The admin acting as the user, from the RFC 8693 `act` claim. */
 interface Impersonator {
   readonly id: string;
   readonly reason?: string;
+  /** The support session, when the admin started one (`act.session_id`). */
+  readonly sessionId?: string;
+  /** Whether the support session blocks writes (`act.read_only`). */
+  readonly readOnly?: boolean;
 }
 /** `actingAs(userId, claims, { actor, reason })`: who acts, and why (recorded by the audit module). */
 interface ImpersonationOptions {

package/dist/next/image/index.js

@@ -21,13 +21,16 @@ const clamp = (value, min, max) => Math.min(max, Math.max(min, Math.round(value)
 */
 function createImageLoader(options) {
 	const storage = `${options.url.replace(/\/+$/, "")}/storage/v1`;
-	const publicPrefixes = [`${storage}/object/public/`, `${storage}/render/image/public/`];
+	const publicPrefixes = [`${storage}/object/public/`, `${storage}/render/image/public/`].map((prefix) => ({
+		prefix,
+		length: new URL(prefix).pathname.length
+	}));
 	const fallback = options.fallback ?? (({ src }) => src);
 	return (props) => {
-		const prefix = publicPrefixes.find((candidate) => props.src.startsWith(candidate));
+		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(new URL(prefix).pathname.length);
+		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)));

package/dist/next/index.d.ts

@@ -1,12 +1,13 @@
-import { n as AnyModels, t as AnyFunctions } from "../types-DONv9SHN.js";
-import { p as DbError } from "../result-c2OYgCV2.js";
-import { B as ReadSet, P as DbStats, Z as QuerySpec, l as CacheAdapter, t as BetterSupabase } from "../define-DUbydmJa.js";
-import { n as AmrEntry, s as Impersonator, t as Aal } from "../mfa-x3V3vGh-.js";
-import { r as AuthState } from "../resolve-BRciX2jK.js";
-import { d as ServerContext, f as ServerOptions, l as BetterServer, n as GuardOptions, t as AuthKind } from "../respond-DAkPIdTH.js";
-import { n as toSession, t as AuthSession } from "../view-3Po_PVlr.js";
-import { r as LiveCountSeed, t as CountRunner } from "../live-QE3UPbGm.js";
-import { n as MembershipClaim, r as hasEntitlement, t as EntitlementKey } from "../entitlements-DvJXoI02.js";
+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 { r as AuthState } from "../resolve-C15TJq77.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-D2OQl62-.js";
+import { n as AmrEntry, s as Impersonator, t as Aal } from "../mfa-CusDgPaD.js";
+import { n as toSession, t as AuthSession } from "../view-BEf0diC5.js";
+import { r as LiveCountSeed, t as CountRunner } from "../live-D9W2M5aO.js";
+import { n as supportOf, t as SupportView } from "../support-view-Da5peKFg.js";
+import { n as MembershipClaim, r as hasEntitlement, t as EntitlementKey } from "../entitlements-DUxU4oHe.js";
 import { NextRequest } from "next/server.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/next/collector.d.ts
@@ -33,12 +34,12 @@ interface NextDebugOptions {
   readonly header?: string;
   /** Warns in development when one render goes over it. */
   readonly budget?: DbBudget;
-  /** Where `next.debugRoute()` is mounted. Defaults to `/api/bs-stats`. */
+  /** Where `bs.debugRoute()` is mounted. Defaults to `/api/bs-stats`. */
   readonly route?: string;
 }
-/** Response header with the URL of the request's totals on `next.debugRoute()`. */
+/** Response header with the URL of the request's totals on `bs.debugRoute()`. */
 export declare const STATS_URL_HEADER = "x-bs-stats";
-interface ProxyOptions<C = unknown, U = unknown> {
+interface ProxyOptions<C = unknown, P = unknown> {
   /**
    * Another middleware to compose with, such as next-intl's. It runs on the
    * original request, alongside auth; its rewrite, redirect or request
@@ -46,9 +47,9 @@ interface ProxyOptions<C = unknown, U = 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, U>, request: NextRequest) => Response | undefined | Promise<Response | undefined>;
+  readonly protect?: (auth: AuthState<C, P>, request: NextRequest) => Response | undefined | Promise<Response | undefined>;
   /** Post-processes the final response; return a new one to replace it. */
-  readonly after?: (response: Response, auth: AuthState<C, U>) => Response | undefined | void | Promise<Response | undefined | void>;
+  readonly after?: (response: Response, auth: AuthState<C, P>) => Response | undefined | void | Promise<Response | undefined | void>;
   /**
    * Adds `Server-Timing: bs-proxy;dur=..., bs-verify;dur=...` (ms): the whole
    * proxy, and resolving the session (a local verify, or a refresh).
@@ -76,25 +77,28 @@ type Unwrapped<T> = T extends {
 } | {
   readonly ok: false;
 } ? D : T;
-interface BetterNext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, U = unknown> extends BetterServer<M, F, E, C, U> {
+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, U>): Promise<Response>;
-  /** Server Components and actions: the caller's context, memoized per request. */
-  server(): Promise<ServerContext<M, F, E, C, U>>;
+  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.
+   */
+  context(request?: Request, 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
    * Components and pass the promise to `<SessionProvider>`.
    */
-  session(): Promise<AuthSession<C, U>>;
+  session(): Promise<AuthSession<C, P>>;
   /**
    * The context for a session and its token, without reading the request.
    * The token is verified again (memoized, no network call); a token for
    * another user than `session` gives an `invalid` context.
    */
-  serverFor(session: AuthSession<C, U>, options: {
+  contextForSession(session: AuthSession<C, P>, options: {
     readonly token: string | null;
-  }): Promise<ServerContext<M, F, E, C, U>>;
+  }): Promise<ServerContext<M, F, E, C, P>>;
   /**
    * First statement of an app-authored `'use cache: private'` function: sets
    * `cacheLife` from the session's expiry (`sessionStale`, capped by
@@ -104,14 +108,14 @@ interface BetterNext<M extends AnyModels, F extends AnyFunctions, E, C = unknown
    * ```ts
    * async function getCustomers() {
    *   'use cache: private';
-   *   const { db } = await next.cached();
+   *   const { db } = await bs.cached();
    *   return db.customers.findMany().orThrow();
    * }
    * ```
    */
-  cached(options?: CachedOptions): Promise<CachedContext<M, F, E, C, U>>;
+  cached(options?: CachedOptions): Promise<CachedContext<M, F, E, C, P>>;
   /**
-   * Drops every `next.cached()` entry of a user, e.g. after a role change,
+   * 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)`).
    */
   invalidateSession(userId: string, options?: {
@@ -121,18 +125,18 @@ interface BetterNext<M extends AnyModels, F extends AnyFunctions, E, C = unknown
    * Counts on the server and returns a serializable seed for
    * `useLiveCount(seed)`, so the badge renders with a number and the client
    * only refetches on changes. Pass `db` inside `'use cache: private'`
-   * (from `next.cached()`); otherwise it uses `next.server()`. A failed
+   * (from `bs.cached()`); otherwise it uses `bs.context()`. A failed
    * count gives `count: null` instead of throwing.
    */
   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<P = Record<string, string | string[]>>(handler: (request: NextRequest, ctx: ServerContext<M, F, E, C, U> & {
-    readonly params: P;
+  route<Params = Record<string, string | string[]>>(handler: (request: NextRequest, ctx: ServerContext<M, F, E, C, P> & {
+    readonly params: Params;
   }) => unknown, options?: GuardOptions): (request: NextRequest, segment: {
-    readonly params: Promise<P>;
+    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, U>) => Promise<T> | T): (input: ActionInput<S>) => Promise<ActionResult<Unwrapped<Awaited<T>>>>;
+  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;
   /**
@@ -146,7 +150,27 @@ interface BetterNext<M extends AnyModels, F extends AnyFunctions, E, C = unknown
    * `expectDbBudget`. Answers 404 unless `debug` is on.
    */
   debugRoute(): (request: Request) => Promise<Response>;
+  /**
+   * Starts a support session for the signed-in admin and sets its cookie,
+   * so the admin's next requests render as the target. Call it from a
+   * server action.
+   */
+  startSupport(request: SupportStartRequest): Promise<ActionResult<SupportStarted>>;
+  /** Ends the admin's support session and clears its cookie. Call it from a server action. */
+  stopSupport(): Promise<ActionResult<{
+    readonly ended: boolean;
+  }>>;
+}
+/** What `startSupport` returns: plain data, safe across the action boundary. */
+interface SupportStarted {
+  readonly sessionId: string;
+  readonly targetUserId: string;
+  readonly readOnly: boolean;
+  /** ISO 8601. */
+  readonly expiresAt: string;
 }
+/** 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. */
   readonly min?: number;
@@ -172,10 +196,10 @@ interface CachedOptions {
   /** More `cacheTag`s for the entry, e.g. `snapshotTag(sub)` or `org:<id>`. */
   readonly tags?: readonly string[];
 }
-type CachedContext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, U = unknown> = ServerContext<M, F, E, C, U> & {
-  readonly session: AuthSession<C, U>;
+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 `next.cached()` puts on a user's entries. */
+/** 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;
@@ -202,7 +226,7 @@ interface RequireAalOptions {
  * combine it with your sign-in redirect.
  *
  * ```ts
- * next.proxy(request, {
+ * bs.proxy(request, {
  *   protect: requireAal('aal2', { redirect: '/mfa', match: (path) => path.startsWith('/settings') }),
  * });
  * ```
@@ -215,9 +239,9 @@ export declare function shouldRefresh(request: Request): boolean;
  * actions and cache tags, on top of `createServer`.
  *
  * ```ts
- * export const next = createNext(sb);
+ * export const bs = createNext(betterSupabase);
  * ```
  */
-export declare function createNext<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, U = unknown>(sb: BetterSupabase<M, D, F, E, C, U>, options?: NextOptions): BetterNext<M, F, E, C, U>;
+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 AmrEntry, type AuthKind, type AuthSession, type BetterNext, type CachedContext, type CachedOptions, type DbBudget, type DbStats, type EntitlementKey, type GuardOptions, type Impersonator, type MembershipClaim, type NextDebugOptions, type NextOptions, type ProxyOptions, type RequireAalOptions, type SessionStaleOptions, hasEntitlement, toSession };
+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 };