better-supabase 0.12.0 → 0.14.0

package/dist/define-block-Dze77QTw.js

@@ -0,0 +1,56 @@
+//#region src/blocks/define-block.ts
+/** Where a block sits in the catalog and in presets, in catalog order. */
+const BLOCK_CATEGORIES = [
+	"identity",
+	"tenancy",
+	"collaboration",
+	"messaging",
+	"growth",
+	"crm",
+	"work",
+	"people",
+	"commerce",
+	"scheduling",
+	"content",
+	"ai",
+	"automation",
+	"developer",
+	"admin",
+	"database"
+];
+/** Describes a block with one manifest (ADR 0029). */
+function defineBlock(definition) {
+	const { create, consumes, provides, sections, ...rest } = definition;
+	return blockOf({
+		...rest,
+		consumes: consumes ?? {},
+		provides: provides ?? {},
+		sections: sections ?? {}
+	}, create, {});
+}
+function blockOf(parts, create, settings) {
+	return {
+		apiVersion: 1,
+		name: parts.name,
+		sql: parts.sql ?? [],
+		options: parts.options ?? {},
+		events: parts.events ?? { types: [] },
+		consumes: parts.consumes,
+		provides: parts.provides,
+		create,
+		client: parts.client,
+		category: parts.category,
+		recipes: parts.recipes ?? [],
+		schemas: parts.schemas ?? {},
+		invalidates: parts.invalidates ?? {},
+		sections: parts.sections,
+		settings,
+		with: (more) => blockOf(parts, create, {
+			...settings,
+			...more
+		}),
+		using: (next) => blockOf(parts, next, settings)
+	};
+}
+//#endregion
+export { defineBlock as n, BLOCK_CATEGORIES as t };

package/dist/delegation-CeXm9AJ3.js

@@ -0,0 +1,146 @@
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { n as actorOf } from "./actor-hNajGNEK.js";
+import { n as impersonatorClaim, t as actClaim } from "./impersonation-CZD9AOAk.js";
+//#region src/auth/delegation.ts
+/**
+* The claim `forContext({ permissions })` sets: the permission keys the work
+* may use. `better_supabase.cap_allows` refuses every other key, and a job
+* queued under a cap keeps it.
+*/
+const PERMISSION_CAP_CLAIM = "bs_permission_cap";
+/**
+* The claims a delegated token adds; `contextClaims` never takes them from
+* `claimsFor`.
+*/
+const DELEGATION_CLAIMS = [
+	"act",
+	"client_id",
+	"scope",
+	"authorization_details",
+	PERMISSION_CAP_CLAIM
+];
+/**
+* `*` grants every key and `prefix.*` every key under prefix, as
+* `permission_matches` in SQL.
+*/
+function permissionMatches(granted, wanted) {
+	return granted === "*" || granted === wanted || granted.endsWith(".*") && wanted.startsWith(granted.slice(0, -1));
+}
+/**
+* The permission cap in `claims`: `undefined` without one, `false` for a cap
+* that is not a list of strings.
+*/
+function permissionCapOf(claims) {
+	const cap = claims[PERMISSION_CAP_CLAIM];
+	if (cap === void 0) return;
+	return Array.isArray(cap) && cap.every((key) => typeof key === "string") ? cap : false;
+}
+/**
+* The keys of `wanted` that `inherited` allows, so a cap only ever narrows.
+* Either side alone is the cap; neither is no cap.
+*/
+function narrowCap(inherited, wanted) {
+	if (wanted === void 0) return inherited;
+	if (inherited === void 0) return wanted;
+	return wanted.filter((key) => inherited.some((granted) => permissionMatches(granted, key)));
+}
+const INVALID = {
+	ok: false,
+	reason: "invalid-delegation"
+};
+function isDetail(value) {
+	return isRecord(value) && typeof value["type"] === "string" && value["type"] !== "";
+}
+function scopeOf(value) {
+	if (value === void 0) return;
+	const scopes = typeof value === "string" ? value.split(/\s+/u) : Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
+	if (scopes === void 0) return false;
+	const joined = scopes.filter(Boolean).join(" ");
+	return joined === "" ? void 0 : joined;
+}
+/**
+* The delegation in `claims`, for a token an OAuth client or agent acts with: a
+* `client_id`, or an `act` chain that is not a support or impersonation level.
+* `{ ok: true }` without `delegation` for any other session. An invalid `act`
+* chain, a `client_id` that is not a non-empty string, a `scope` that is
+* neither a string nor a list of strings, and `authorization_details` that are
+* not objects with a `type` are `{ ok: false }`: the work must not run as the
+* user alone.
+*/
+function delegatedClaims(claims) {
+	const outcome = actorOf(claims);
+	if (!outcome.ok) return {
+		ok: false,
+		reason: "invalid-chain"
+	};
+	const client = claims["client_id"];
+	if (client !== void 0 && (typeof client !== "string" || client === "")) return INVALID;
+	const actor = outcome.actor;
+	const chain = actor?.kind === "oauth-client" || actor?.kind === "agent" ? actor.chain : void 0;
+	if (client === void 0 && chain === void 0) return { ok: true };
+	const scope = scopeOf(claims["scope"]);
+	if (scope === false) return INVALID;
+	const details = claims["authorization_details"];
+	if (details !== void 0 && !(Array.isArray(details) && details.every(isDetail))) return INVALID;
+	return {
+		ok: true,
+		delegation: {
+			...client === void 0 ? {} : { client_id: client },
+			...scope === void 0 ? {} : { scope },
+			...details === void 0 ? {} : { authorization_details: details },
+			...chain === void 0 ? {} : { act: chain }
+		}
+	};
+}
+/**
+* The SQL claims for the user in a recorded context: the user as
+* `authenticated`, the tenant as `tenant_id`, and the context's delegation, so
+* the access functions (through `cap_allows`), `token_scope_allows` and the
+* TypeScript scope checks narrow the work to what the queuing token held, and
+* to its permission cap. The `act` claim is the support session, else the OAuth
+* client chain, else the impersonating admin.
+*/
+function contextClaims(context, options = {}) {
+	const { actor, tenant } = context;
+	if (actor?.kind !== "user") return {
+		ok: false,
+		message: `forContext needs a user actor, got ${actor ? actor.kind : "none"}: use admin() for service work`
+	};
+	const claims = context.claims ?? {};
+	const recorded = actorOf(claims);
+	const delegated = delegatedClaims(claims);
+	const inherited = permissionCapOf(claims);
+	if (inherited === false) return {
+		ok: false,
+		message: "forContext got an invalid permission cap"
+	};
+	const cap = narrowCap(inherited, options.permissions);
+	if (!recorded.ok || !delegated.ok) return {
+		ok: false,
+		message: !recorded.ok || !delegated.ok && delegated.reason === "invalid-chain" ? "forContext got an invalid act claim" : "forContext got invalid delegation claims"
+	};
+	const support = recorded.actor?.kind === "support" ? recorded.actor : void 0;
+	const delegation = delegated.delegation ?? {};
+	const act = support ? impersonatorClaim(support) : delegation.act ?? (actor.impersonator ? actClaim({
+		actor: actor.impersonator,
+		reason: options.reason ?? "job"
+	}) : void 0);
+	const extra = Object.fromEntries(Object.entries(options.extra ?? {}).filter(([key]) => !DELEGATION_CLAIMS.includes(key)));
+	const impersonator = support?.id ?? actor.impersonator;
+	return {
+		ok: true,
+		claims: {
+			...extra,
+			role: "authenticated",
+			sub: actor.id,
+			...tenant === void 0 ? {} : { tenant_id: tenant },
+			...delegation,
+			...act === void 0 ? {} : { act },
+			...cap === void 0 ? {} : { [PERMISSION_CAP_CLAIM]: cap }
+		},
+		...impersonator === void 0 ? {} : { impersonator },
+		...support?.readOnly ? { readOnly: true } : {}
+	};
+}
+//#endregion
+export { narrowCap as a, delegatedClaims as i, PERMISSION_CAP_CLAIM as n, permissionCapOf as o, contextClaims as r, DELEGATION_CLAIMS as t };

package/dist/delivery-Bm0jxmzI.js

@@ -0,0 +1,29 @@
+//#region src/blocks/notifications/delivery.ts
+/**
+* The headers automated mail carries: `Auto-Submitted: auto-generated` (RFC 3834)
+* on every message, so auto-responders stay quiet, and on `notification` mail
+* with an unsubscribe target, `List-Unsubscribe` (RFC 2369).
+* `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058) needs the
+* `https:` URL, so a `mailto:`-only target leaves it out. Throws a `TypeError`
+* for a URL that isn't `https:` or an address that isn't `mailto:`.
+*/
+function mailHeaders(category, unsubscribe) {
+	const headers = { "Auto-Submitted": "auto-generated" };
+	if (category !== "notification" || unsubscribe === void 0) return headers;
+	const targets = [];
+	if (unsubscribe.url !== void 0) {
+		if (!URL.canParse(unsubscribe.url)) throw new TypeError(`The unsubscribe URL "${unsubscribe.url}" is not a URL`);
+		if (new URL(unsubscribe.url).protocol !== "https:") throw new TypeError(`The unsubscribe URL "${unsubscribe.url}" must use https (RFC 8058)`);
+		targets.push(`<${unsubscribe.url}>`);
+	}
+	if (unsubscribe.mailto !== void 0) {
+		if (!/^mailto:[^\s<>]+$/i.test(unsubscribe.mailto)) throw new TypeError(`The unsubscribe address "${unsubscribe.mailto}" must be a mailto: URI`);
+		targets.push(`<${unsubscribe.mailto}>`);
+	}
+	if (targets.length === 0) return headers;
+	headers["List-Unsubscribe"] = targets.join(", ");
+	if (unsubscribe.url !== void 0) headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
+	return headers;
+}
+//#endregion
+export { mailHeaders as t };

package/dist/delivery-n6lZGuGx.d.ts

@@ -0,0 +1,71 @@
+//#region src/blocks/notifications/delivery.d.ts
+/**
+ * What a message is for. `security` (sign-in codes, password resets, new-device
+ * alerts) and `approval` (a request waiting on the reader) mail never carries
+ * an unsubscribe link: the reader can't opt out of it.
+ */
+type MailCategory = "notification" | "security" | "approval";
+/** One email, ready for a provider. */
+interface EmailMessage {
+  readonly from: string;
+  readonly to: string;
+  readonly subject: string;
+  readonly text?: string;
+  readonly html?: string;
+  readonly replyTo?: string;
+  readonly category: MailCategory;
+  /**
+   * Headers the provider sends as given: `Auto-Submitted` on every message, and
+   * `List-Unsubscribe` with `List-Unsubscribe-Post` on notification mail that
+   * has an unsubscribe address.
+   */
+  readonly headers: Readonly<Record<string, string>>;
+}
+/** The message each channel's transport sends. */
+interface DeliveryMessages {
+  readonly email: EmailMessage;
+}
+type DeliveryChannel = keyof DeliveryMessages;
+interface DeliverySendOptions {
+  /**
+   * The delivery id. A provider that dedupes by key sends a retried delivery
+   * once; pass it as the provider's idempotency key.
+   */
+  readonly idempotencyKey: string;
+}
+interface DeliveryReceipt {
+  /** The provider's id for the message, kept for support and webhooks. */
+  readonly providerMessageId?: string;
+}
+/**
+ * Sends one message through a provider (Resend, Postmark, SES, SMTP). A throw
+ * retries the delivery after its lease, with the same idempotency key.
+ */
+interface DeliveryTransport<C extends DeliveryChannel = DeliveryChannel> {
+  readonly apiVersion: 1;
+  readonly channel: C;
+  /** Stored on the delivery, e.g. `resend`. */
+  readonly provider: string;
+  send(message: DeliveryMessages[C], options: DeliverySendOptions): DeliveryReceipt | void | Promise<DeliveryReceipt | void>;
+}
+/**
+ * Where a reader unsubscribes: an `https:` URL for one-click, a `mailto:`
+ * address, or both.
+ */
+interface UnsubscribeTarget {
+  /** Receives the RFC 8058 one-click `POST`; must be `https:`. */
+  readonly url?: string;
+  /** `mailto:` address, with an optional `?subject=`. */
+  readonly mailto?: string;
+}
+/**
+ * The headers automated mail carries: `Auto-Submitted: auto-generated` (RFC 3834)
+ * on every message, so auto-responders stay quiet, and on `notification` mail
+ * with an unsubscribe target, `List-Unsubscribe` (RFC 2369).
+ * `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058) needs the
+ * `https:` URL, so a `mailto:`-only target leaves it out. Throws a `TypeError`
+ * for a URL that isn't `https:` or an address that isn't `mailto:`.
+ */
+declare function mailHeaders(category: MailCategory, unsubscribe?: UnsubscribeTarget): Record<string, string>;
+//#endregion
+export { DeliveryTransport as a, UnsubscribeTarget as c, DeliverySendOptions as i, mailHeaders as l, DeliveryMessages as n, EmailMessage as o, DeliveryReceipt as r, MailCategory as s, DeliveryChannel as t };

package/dist/documents-kgDOHUfn.d.ts

@@ -0,0 +1,152 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-C6jDfedy.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { r as BlockTemporalOptions } from "./block-helpers-BaugZlJV.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+//#region src/blocks/documents/documents.d.ts
+interface DocumentsOptions extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`.
+   */
+  readonly schema?: string;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Documents>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** Which document to open: one per subject and name. */
+interface DocumentRef {
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  /** Default: `body`. */
+  readonly name?: string;
+}
+/** A Yjs update and its place in the document's log. */
+interface DocumentUpdate {
+  readonly seq: number;
+  readonly update: Uint8Array;
+}
+interface DocumentInfo {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly name: string;
+  /** The private realtime topic for updates and presence. */
+  readonly topic: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** What a client needs to rebuild the document. */
+interface DocumentState {
+  /** The compacted state; unset before the first compaction. */
+  readonly snapshot?: Uint8Array;
+  /** The last update the snapshot contains, `0` without one. */
+  readonly snapshotSeq: number;
+  /** The updates after the snapshot, oldest first. */
+  readonly updates: readonly DocumentUpdate[];
+}
+interface OpenedDocument extends DocumentInfo, DocumentState {
+  /** Whether the caller may push updates. */
+  readonly canWrite: boolean;
+  /**
+   * Whether the caller may suggest changes: editors, and readers who hold
+   * `documents.suggest`.
+   */
+  readonly canSuggest: boolean;
+}
+interface DocumentVersion {
+  readonly id: string;
+  readonly number: number;
+  /** The version's name; a named version is kept out of retention. */
+  readonly label?: string;
+  /** `manual` for a saved version, `auto` for one the app took. */
+  readonly source: string;
+  /** A frozen version keeps its name. */
+  readonly frozen: boolean;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+}
+type DocumentSuggestionStatus = "open" | "accepted" | "rejected" | "withdrawn";
+/** A suggested change: a Yjs update that is not in the log yet. */
+interface DocumentSuggestion {
+  readonly id: string;
+  readonly documentId: string;
+  readonly update: Uint8Array;
+  readonly summary?: string;
+  readonly status: DocumentSuggestionStatus;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly decidedBy?: string;
+  readonly decidedAt?: Temporal.Instant;
+  readonly note?: string;
+}
+interface DecidedSuggestion extends DocumentSuggestion {
+  /** The update's place in the log, when the suggestion was accepted. */
+  readonly seq?: number;
+}
+type SuggestionDecision = "accepted" | "rejected" | "withdrawn";
+interface Documents {
+  /** The document's state; creates it on first open for an editor. */
+  open(ref: DocumentRef): AsyncResult<OpenedDocument>;
+  /** Appends an update and returns its sequence number. */
+  push(documentId: string, update: Uint8Array): AsyncResult<number>;
+  /**
+   * Updates after `afterSeq`. When compaction dropped some of them, the result
+   * carries the snapshot to start from instead.
+   */
+  pull(documentId: string, afterSeq: number): AsyncResult<DocumentState>;
+  /**
+   * Stores `state` as the snapshot through `throughSeq` and drops those
+   * updates. Returns false when a newer snapshot exists. The service role or
+   * `documents.manage`.
+   */
+  compact(documentId: string, state: Uint8Array, throughSeq: number): AsyncResult<boolean>;
+  /** Saves the merged state as a version; needs the versions module. */
+  saveVersion(documentId: string, state: Uint8Array, label?: string): AsyncResult<{
+    readonly id: string;
+    readonly number: number;
+  }>;
+  /**
+   * Newest first; needs the versions module. `named: true` keeps the versions
+   * with a name.
+   */
+  versions(documentId: string, options?: {
+    readonly named?: boolean;
+  }): AsyncResult<readonly DocumentVersion[]>;
+  /**
+   * Names a version, or removes its name with `null`. A named version is kept
+   * out of retention. Editors; needs the versions module.
+   */
+  nameVersion(documentId: string, versionId: string, label: string | null): AsyncResult<boolean>;
+  /**
+   * Stores an update as a suggestion instead of appending it. Editors, and
+   * readers who hold `documents.suggest`.
+   */
+  suggest(documentId: string, update: Uint8Array, summary?: string): AsyncResult<DocumentSuggestion>;
+  /** Oldest first. Default status: `open`. */
+  suggestions(documentId: string, options?: {
+    readonly status?: DocumentSuggestionStatus | "all";
+  }): AsyncResult<readonly DocumentSuggestion[]>;
+  /**
+   * Accepts or rejects a suggestion (editors), or withdraws it (its author).
+   * Accepting appends the update to the log.
+   */
+  decideSuggestion(suggestionId: string, decision: SuggestionDecision, note?: string): AsyncResult<DecidedSuggestion>;
+  /** A saved state; needs the versions module. */
+  version(documentId: string, versionId: string): AsyncResult<Uint8Array>;
+  /** Documents with at least `minUpdates` uncompacted updates. Service role. */
+  toCompact(options?: {
+    readonly minUpdates?: number;
+    readonly limit?: number;
+  }): AsyncResult<readonly string[]>;
+}
+/** The `documents` SQL module as typed calls, with updates as bytes. */
+declare function createDocuments(options: DocumentsOptions): Documents;
+//#endregion
+export { DocumentSuggestion as a, DocumentVersion as c, OpenedDocument as d, SuggestionDecision as f, DocumentState as i, Documents as l, DocumentInfo as n, DocumentSuggestionStatus as o, createDocuments as p, DocumentRef as r, DocumentUpdate as s, DecidedSuggestion as t, DocumentsOptions as u };

package/dist/edge/index.d.ts

@@ -1,25 +1,28 @@
-import { f as Result } from "../result-BREt7qOh.js";
-import { a as AnyModels, i as AnyFunctions } from "../types-BrpW5ixT.js";
-import { t as StandardSchemaV1 } from "../standard-BcUQuUgu.js";
-import { s as PermissionRef, t as AnyAuthorizer } from "../authorizer-eiOjo-3l.js";
-import { t as BetterSupabase } from "../define-DYZnvAbs.js";
-import { a as ServerContext, c as ServerOptions, n as BetterServer } from "../server-types-fLdep4gb.js";
-import { t as AuthSession } from "../view-KQhe6eNc.js";
-import { i as MiddlewareOptions, r as GuardOptions } from "../respond-BSL36dQp.js";
-import { s as BlockRequireOptions } from "../kit-De-EVRhw.js";
-import { n as FunctionContract, t as DescribedFunction } from "../function-contract-DWqFl_QO.js";
-import { t as Validated } from "../shared-DDSjEGDR.js";
+import { f as Result } from "../result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "../standard-DbQsD2xZ.js";
+import { M as AnyFunctions, N as AnyModels } from "../executor-CPyrQdjh.js";
+import { s as PermissionRef, t as AnyAuthorizer } from "../authorizer-DFP3gHv8.js";
+import { t as BetterSupabase } from "../define-Dw7pRO4h.js";
+import { t as AuthSession } from "../view-2_I-2ukO.js";
+import { a as ServerContext, c as ServerOptions, n as BetterServer } from "../server-types-BOs-eFpo.js";
+import { i as MiddlewareOptions, r as GuardOptions } from "../respond-CZYibxUx.js";
+import { c as ResourceLoaderContext, s as BlockRequireOptions } from "../kit-DKfbNTAA.js";
+import { n as FunctionContract, t as DescribedFunction } from "../function-contract-vPqwt1j4.js";
+import { t as Validated } from "../shared-CRRfQAKG.js";
 import { n as SUPABASE_CORS_HEADERS, r as corsConfig, t as CorsOptions } from "../cors-kLq6VM06.js";
-import { i as ResourceContext, l as ResourceRouteOptions, o as ResourceHooks, r as ResourceAction, t as ActionArgs } from "../resource-types-LW1i5-h3.js";
-import { t as ResourceMap } from "../resources-D3_FAz_H.js";
-import { t as defineAction } from "../resource-execute-Bxvgmx-n.js";
+import { i as ResourceContext, l as ResourceRouteOptions, o as ResourceHooks, r as ResourceAction, t as ActionArgs } from "../resource-types-Bzt_bpR5.js";
+import { t as ResourceMap } from "../resources-Du5wcL3f.js";
+import { t as defineAction } from "../resource-execute-bT9ltHVT.js";
 import { AnyEntry, Contributions } from "@supabase/middleware";
 //#region src/bridges/edge.d.ts
 /** The platform context Workers pass as the third `fetch` argument. */
 interface EdgeExecutionContext {
   waitUntil(promise: Promise<unknown>): void;
 }
-/** `Deno.serve` passes `(request, info)`, Workers `fetch` passes `(request, env, ctx)`. */
+/**
+ * `Deno.serve` passes `(request, info)`, Workers `fetch` passes `(request, env,
+ * ctx)`.
+ */
 type EdgeHandler = (request: Request, env?: unknown, executionContext?: EdgeExecutionContext) => Promise<Response>;
 /**
  * Runs an entry array around `handler` as a fetch handler for Supabase Edge
@@ -27,14 +30,20 @@ type EdgeHandler = (request: Request, env?: unknown, executionContext?: EdgeExec
  * context, so on Workers `getEnv` inside the entries reads the bindings.
  *
  * ```ts
- * Deno.serve(toEdge([withBetterSupabase(server)], async (req, ctx) =>
- *   Response.json(await ctx.db.notes.findMany().orThrow())))
+ * Deno.serve(
+ *   toEdge([withBetterSupabase(server)], async (req, ctx) =>
+ *     Response.json(await ctx.db.notes.findMany().orThrow()),
+ *   ),
+ * );
  * ```
  */
 export declare function toEdge<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, handler: (request: Request, ctx: Contributions<Entries>, executionContext: EdgeExecutionContext | undefined, env: unknown) => Response | Promise<Response>): EdgeHandler;
 //#endregion
 //#region src/edge/function.d.ts
-/** A fetch handler that carries its contract in its type and its schemas at runtime. */
+/**
+ * A fetch handler that carries its contract in its type and its schemas at
+ * runtime.
+ */
 type TypedFunction<In, Out> = EdgeHandler & DescribedFunction & {
   /** Type-only: never set at runtime. */
   readonly "~contract"?: FunctionContract<In, Out>;
@@ -53,7 +62,10 @@ interface FunctionDefinition<I extends StandardSchemaV1, Out, M extends AnyModel
    * answers 500, so a function never sends data its contract doesn't promise.
    */
   readonly output?: StandardSchemaV1<unknown, Out>;
-  /** A one-line summary for the operation `functionRoute` describes in `better-supabase/spec`. */
+  /**
+   * A one-line summary for the operation `functionRoute` describes in
+   * `better-supabase/spec`.
+   */
   readonly summary?: string;
   /** Runs as the caller with the parsed input. Returns data or a `Result`. */
   readonly handler: (input: StandardSchemaV1.InferOutput<I>, ctx: ServerContext<M, F, E, C, P, B> & {
@@ -81,7 +93,10 @@ export declare function defineFunction<I extends StandardSchemaV1, Out, M extend
 export interface EdgeOptions extends ServerOptions {
   /** Answer preflights and add CORS headers. `true` uses Supabase's defaults. */
   readonly cors?: boolean | CorsOptions;
-  /** Include error details in problem responses. Defaults to `NODE_ENV === 'development'`. */
+  /**
+   * Include error details in problem responses. Defaults to `NODE_ENV ===
+   * 'development'`.
+   */
   readonly exposeErrors?: boolean;
   /**
    * Keeps the invocation alive for event sink sends a handler started, e.g.
@@ -96,9 +111,9 @@ export interface ResourcesOptions extends MiddlewareOptions {
 }
 type ParamNames<K extends string> = K extends `${string}:${infer Name}/${infer Rest}` ? Name | ParamNames<Rest> : K extends `${string}:${infer Name}` ? Name : never;
 /**
- * The params a route key declares: one per `:name` segment, and `*` for a
- * final wildcard. `RouteParams<"GET /orgs/:org/files/*">` is
- * `{ org: string; "*": string }`.
+ * The params a route key declares: one per `:name` segment, and `*` for a final
+ * wildcard. `RouteParams<"GET /orgs/:org/files/*">` is `{ org: string; "*":
+ * string }`.
  */
 export type RouteParams<K extends string> = { readonly [N in ParamNames<K> | (K extends `${string}/*` ? "*" : never)]: string; };
 /** A route handler: the request, the caller's context and the path params. */
@@ -107,15 +122,18 @@ export type EdgeRouteHandler<M extends AnyModels, F extends AnyFunctions, E, C =
   readonly session: AuthSession<C, P>;
   readonly tenant: string | undefined;
 }) => unknown;
-/** A route with its own guard: `allow`, `aal`, `scopes`, `requireTenant`, `authorize`. */
-export interface EdgeRoute<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, Params = Readonly<Record<string, string>>, B = unknown> extends BlockRequireOptions<C, P> {
+/**
+ * A route with its own guard: `allow`, `aal`, `scopes`, `requireTenant`,
+ * `authorize`.
+ */
+export interface EdgeRoute<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, Params = Readonly<Record<string, string>>, B = unknown, Ref = unknown> extends BlockRequireOptions<C, P, boolean, Ref, ServerContext<M, F, E, C, P, B> & ResourceLoaderContext<C, P>> {
   readonly handler: EdgeRouteHandler<M, F, E, C, P, Params, B>;
 }
 /**
- * Routes by `"METHOD /path"` (or `"/path"` for every method). `:name`
- * segments are params, a final `*` matches the rest of the path.
+ * Routes by `"METHOD /path"` (or `"/path"` for every method). `:name` segments
+ * are params, a final `*` matches the rest of the path.
  */
-export type EdgeRoutes<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, B = unknown> = Readonly<Record<string, EdgeRouteHandler<M, F, E, C, P, Readonly<Record<string, string>>, B> | EdgeRoute<M, F, E, C, P, Readonly<Record<string, string>>, B>>>;
+export type EdgeRoutes<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, B = unknown, Ref = unknown> = Readonly<Record<string, EdgeRouteHandler<M, F, E, C, P, Readonly<Record<string, string>>, B> | EdgeRoute<M, F, E, C, P, Readonly<Record<string, string>>, B, Ref>>>;
 export interface BetterEdge<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, Ref = string, B = unknown> extends BetterServer<M, F, E, C, P, B> {
   /**
    * A fetch handler (`Deno.serve`, Workers `fetch`) running as the caller.
@@ -124,23 +142,32 @@ export interface BetterEdge<M extends AnyModels, F extends AnyFunctions, E, C =
   handler(fn: (request: Request, ctx: ServerContext<M, F, E, C, P, B>) => unknown, options?: MiddlewareOptions): EdgeHandler;
   /**
    * A router: each route runs as the caller, behind the shared guard in
-   * `options` and its own. An unknown path answers 404 and a known path
-   * with another method 405, both before auth resolves. `ctx.params` is
-   * typed from the key: `"GET /customers/:id"` gets `params.id`.
+   * `options` and its own. An unknown path answers 404 and a known path with
+   * another method 405, both before auth resolves. `ctx.params` is typed from
+   * the key: `"GET /customers/:id"` gets `params.id`.
    *
    * ```ts
-   * Deno.serve(bs.routes({
-   *   'GET /customers': (req, ctx) => ctx.db.customers.findMany(),
-   *   'GET /customers/:id': (req, ctx) => ctx.db.customers.find(ctx.params.id),
-   *   'POST /invites': { requireTenant: true, handler: (req, ctx) => invite(req, ctx) },
-   * }, { basePath: '/api' }))
+   * Deno.serve(
+   *   bs.routes(
+   *     {
+   *       "GET /customers": (req, ctx) => ctx.db.customers.findMany(),
+   *       "GET /customers/:id": (req, ctx) =>
+   *         ctx.db.customers.find(ctx.params.id),
+   *       "POST /invites": {
+   *         requireTenant: true,
+   *         handler: (req, ctx) => invite(req, ctx),
+   *       },
+   *     },
+   *     { basePath: "/api" },
+   *   ),
+   * );
    * ```
    */
-  routes<K extends string>(routes: { readonly [Key in K]: EdgeRouteHandler<M, F, E, C, P, RouteParams<Key>, B> | EdgeRoute<M, F, E, C, P, RouteParams<Key>, B>; }, options?: ResourcesOptions): EdgeHandler;
+  routes<K extends string>(routes: { readonly [Key in K]: EdgeRouteHandler<M, F, E, C, P, RouteParams<Key>, B> | EdgeRoute<M, F, E, C, P, RouteParams<Key>, B, Ref>; }, options?: ResourcesOptions): EdgeHandler;
   /**
-   * REST resources matching the API model, e.g.
-   * `Deno.serve(bs.resources({ customers: true }))`: collection, item and
-   * action paths. An unknown path answers 404 before auth resolves.
+   * REST resources matching the API model, e.g. `Deno.serve(bs.resources({
+   * customers: true }))`: collection, item and action paths. An unknown path
+   * answers 404 before auth resolves.
    */
   resources(map: ResourceMap<M, Ref, ServerContext<M, F, E, C, P, B>["db"]>, options?: ResourcesOptions): EdgeHandler;
 }