better-supabase 0.5.0 → 0.6.0

package/dist/node/index.js

@@ -0,0 +1,210 @@
+import { i as toResponse, t as around } from "../shared-CBxosKK3.js";
+import { a as routeRefusal, n as guardedLocals, t as errorResponse } from "../refusal-CeJWxmkH.js";
+import { t as beforeRoute } from "../before-route-CnR0C0Jr.js";
+import { i as toWebHeaders, t as applyWebHeaders } from "../node-headers-C71zNQHe.js";
+import { n as toWebRequest, t as sendWebResponse } from "../http-Cv4T29xh.js";
+//#region src/node/index.ts
+/**
+* A `node:http` request listener running the entries around `handler`.
+* Response-phase entries see the handler's response, so refreshed cookies
+* and `withDbStats` totals reach the client.
+*
+* ```ts
+* createServer(toNodeHandler([withBetterSupabase(server)], (request, { db }) => db.notes.findMany()))
+* ```
+*/
+function toNodeHandler(entries, handler, options = {}) {
+	const run = around(entries);
+	return async (req, res) => {
+		const request = toWebRequest(req, options);
+		const response = await run(request, options.env?.(req), async (contributions) => toResponse(await handler(request, contributions)));
+		await sendWebResponse(res, response);
+	};
+}
+/** 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();
+}
+/**
+* Express middleware that puts every contribution on `res.locals`
+* (`res.locals.db`, `res.locals.bs`). Mount it before the routes.
+*
+* ```ts
+* app.use(toExpress([withBetterSupabase(server)]))
+* app.get('/notes', async (req, res) => res.json(await res.locals.db.notes.findMany().orThrow()))
+* ```
+*/
+function toExpress(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);
+		Object.assign(res.locals, outcome.contributions);
+		return true;
+	};
+	return (req, res, next) => {
+		continueWith(handle(req, res), next);
+	};
+}
+/**
+* Express route middleware that refuses callers outside `options`:
+* Problem Details, or a redirect to `signIn` or `mfa`. Runs after `toExpress`.
+*
+* ```ts
+* app.get('/admin', guard({ roles: ['admin'] }), handler)
+* ```
+*/
+function guard(options = {}) {
+	const handle = async (req, res) => {
+		const refused = await routeRefusal(guardedLocals(res.locals), toWebRequest(req, { body: false }), options);
+		if (!refused) return true;
+		await sendWebResponse(res, refused);
+		return false;
+	};
+	return (req, res, next) => {
+		continueWith(handle(req, res), next);
+	};
+}
+/**
+* An Express error handler that answers thrown `DbException`s (from
+* `.orThrow()`) with Problem Details and passes every other error on.
+* Register it after the routes.
+*/
+function problemErrorHandler(options = {}) {
+	return (error, req, res, next) => {
+		const response = errorResponse(error, toWebRequest(req, { body: false }), options);
+		if (!response || res.headersSent) {
+			next(error);
+			return;
+		}
+		continueWith(sendWebResponse(res, response).then(() => false), next);
+	};
+}
+function replyHeaders(reply) {
+	return {
+		getHeader: (name) => reply.getHeader(name),
+		setHeader: (name, value) => {
+			reply.header(name, typeof value === "number" ? String(value) : value);
+		}
+	};
+}
+async function sendReply(reply, response) {
+	applyWebHeaders(replyHeaders(reply), response.headers);
+	reply.code(response.status);
+	const body = response.body ? new Uint8Array(await response.arrayBuffer()) : void 0;
+	reply.send(body);
+}
+/**
+* A Fastify `onRequest` hook that puts every contribution on
+* `request.locals`. Declare `locals` with `app.decorateRequest('locals', null)`.
+*
+* ```ts
+* app.decorateRequest('locals', null)
+* app.addHook('onRequest', toFastify([withBetterSupabase(server)]))
+* app.get('/notes', (request) => request.locals.db.notes.findMany().orThrow())
+* ```
+*/
+function toFastify(entries, options = {}) {
+	const run = beforeRoute(entries);
+	return async (request, reply) => {
+		const web = toWebRequest(request.raw, {
+			...options,
+			body: false
+		});
+		const outcome = await run(web, options.env?.(request));
+		if (!outcome.reached) {
+			await sendReply(reply, outcome.response);
+			return;
+		}
+		applyWebHeaders(replyHeaders(reply), outcome.headers);
+		request.locals = {
+			...request.locals,
+			...outcome.contributions
+		};
+	};
+}
+/**
+* A Fastify `preHandler` hook that refuses callers outside `options`. Runs
+* after `toFastify`.
+*/
+function fastifyGuard(options = {}) {
+	return async (request, reply) => {
+		const refused = await routeRefusal(guardedLocals(request.locals ?? {}), toWebRequest(request.raw, { body: false }), options);
+		if (refused) await sendReply(reply, refused);
+	};
+}
+function koaHeaders(ctx) {
+	return {
+		getHeader: (name) => {
+			const value = ctx.response.get(name);
+			return value === "" ? void 0 : value;
+		},
+		setHeader: (name, value) => {
+			ctx.set(name, typeof value === "number" ? String(value) : value);
+		}
+	};
+}
+async function sendKoa(ctx, response) {
+	applyWebHeaders(koaHeaders(ctx), response.headers);
+	ctx.status = response.status;
+	ctx.body = response.body ? Buffer.from(await response.arrayBuffer()) : null;
+}
+/**
+* Koa middleware that puts every contribution on `ctx.state`, then awaits
+* the rest of the chain. Thrown `DbException`s become Problem Details.
+*
+* ```ts
+* app.use(toKoa([withBetterSupabase(server)]))
+* app.use(async (ctx) => { ctx.body = await ctx.state.db.notes.findMany().orThrow() })
+* ```
+*/
+function toKoa(entries, options = {}) {
+	const run = beforeRoute(entries);
+	return async (ctx, next) => {
+		const web = toWebRequest(ctx.req, {
+			...options,
+			body: false
+		});
+		const outcome = await run(web, options.env?.(ctx));
+		if (!outcome.reached) {
+			await sendKoa(ctx, outcome.response);
+			return;
+		}
+		applyWebHeaders(koaHeaders(ctx), outcome.headers);
+		Object.assign(ctx.state, outcome.contributions);
+		try {
+			await next();
+		} catch (error) {
+			const response = errorResponse(error, web, options);
+			if (!response) throw error;
+			await sendKoa(ctx, response);
+		}
+	};
+}
+/** Koa middleware that refuses callers outside `options`. Runs after `toKoa`. */
+function koaGuard(options = {}) {
+	return async (ctx, next) => {
+		const refused = await routeRefusal(guardedLocals(ctx.state), toWebRequest(ctx.req, { body: false }), options);
+		if (refused) {
+			await sendKoa(ctx, refused);
+			return;
+		}
+		await next();
+	};
+}
+//#endregion
+export { applyWebHeaders, fastifyGuard, guard, koaGuard, problemErrorHandler, sendWebResponse, toExpress, toFastify, toKoa, toNodeHandler, toWebHeaders, toWebRequest };

package/dist/node-headers-AO06VhqH.d.ts

@@ -0,0 +1,24 @@
+//#region src/bridges/node-headers.d.ts
+/** Node's request headers: a string, an array of strings, or absent. */
+type NodeIncomingHeaders = Readonly<Record<string, string | readonly string[] | undefined>>;
+/** The part of a Node `IncomingMessage` a URL and headers need; no stream is read. */
+interface NodeRequestHead {
+  readonly method?: string | undefined;
+  readonly url?: string | undefined;
+  readonly headers: NodeIncomingHeaders;
+  readonly socket?: object | undefined;
+}
+/** Node's headers as `Headers`; HTTP/2 pseudo-headers (`:path`) are dropped. */
+declare function toWebHeaders(incoming: NodeIncomingHeaders): Headers;
+/** The part of a Node `ServerResponse` header writes need. */
+interface NodeHeaderTarget {
+  getHeader(name: string): number | string | readonly string[] | undefined;
+  setHeader(name: string, value: number | string | readonly string[]): unknown;
+}
+/**
+ * Copies a `Response`'s headers onto a Node response: `set-cookie` and
+ * `server-timing` are appended to what is already there, the rest replaced.
+ */
+declare function applyWebHeaders(target: NodeHeaderTarget, headers: Headers): void;
+//#endregion
+export { toWebHeaders as i, NodeRequestHead as n, applyWebHeaders as r, NodeHeaderTarget as t };

package/dist/node-headers-C71zNQHe.js

@@ -0,0 +1,55 @@
+//#region src/bridges/node-headers.ts
+function first(value) {
+	return typeof value === "string" ? value : value?.[0];
+}
+/** Node's headers as `Headers`; HTTP/2 pseudo-headers (`:path`) are dropped. */
+function toWebHeaders(incoming) {
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(incoming)) {
+		if (value === void 0 || name.startsWith(":")) continue;
+		if (typeof value === "string") headers.set(name, value);
+		else for (const item of value) headers.append(name, item);
+	}
+	return headers;
+}
+function originOf(req, trustProxy) {
+	const forwardedProto = trustProxy ? first(req.headers["x-forwarded-proto"])?.split(",")[0]?.trim() : void 0;
+	const socket = req.socket;
+	const encrypted = socket !== void 0 && "encrypted" in socket && socket.encrypted === true;
+	return `${forwardedProto ?? (encrypted ? "https" : "http")}://${(trustProxy ? first(req.headers["x-forwarded-host"])?.split(",")[0]?.trim() : void 0) ?? first(req.headers["host"]) ?? "localhost"}`;
+}
+/**
+* The absolute URL of a Node request. Express keeps the mounted path in
+* `originalUrl`; `x-forwarded-*` count only with `trustProxy`.
+*/
+function nodeRequestUrl(req, trustProxy = false) {
+	const path = "originalUrl" in req && typeof req.originalUrl === "string" ? req.originalUrl : req.url ?? "/";
+	return new URL(path, originOf(req, trustProxy));
+}
+/** A body-less `Request` with a Node request's method, URL and headers. */
+function headRequest(req, trustProxy = false) {
+	return new Request(nodeRequestUrl(req, trustProxy), {
+		method: req.method ?? "GET",
+		headers: toWebHeaders(req.headers)
+	});
+}
+/**
+* Copies a `Response`'s headers onto a Node response: `set-cookie` and
+* `server-timing` are appended to what is already there, the rest replaced.
+*/
+function applyWebHeaders(target, headers) {
+	const append = (name, values) => {
+		if (values.length === 0) return;
+		const existing = target.getHeader(name);
+		const before = existing === void 0 ? [] : typeof existing === "object" ? existing : [String(existing)];
+		target.setHeader(name, [...before, ...values]);
+	};
+	append("set-cookie", headers.getSetCookie());
+	for (const [name, value] of headers) {
+		if (name === "set-cookie") continue;
+		if (name === "server-timing") append(name, [value]);
+		else target.setHeader(name, value);
+	}
+}
+//#endregion
+export { toWebHeaders as i, headRequest as n, nodeRequestUrl as r, applyWebHeaders as t };

package/dist/nuxt/index.d.ts

@@ -0,0 +1,60 @@
+//#region src/nuxt/index.d.ts
+/** `betterSupabase` in `nuxt.config.ts`, or the module's inline options. */
+export interface NuxtModuleOptions {
+  /**
+   * The server module whose default export is the entry array, e.g.
+   * `'~~/server/better-supabase'` exporting `[withBetterSupabase(server)]`.
+   * Without it the module registers no server middleware.
+   */
+  readonly server?: string;
+  /** Auto-import the `better-supabase/vue` composables. Defaults to true. */
+  readonly composables?: boolean;
+}
+/** A Nitro handler registration. */
+export interface NitroHandlerLike {
+  readonly handler: string;
+  readonly middleware?: boolean;
+  readonly route?: string;
+}
+/** An auto-import registration. */
+export interface NuxtImportLike {
+  readonly name: string;
+  readonly from: string;
+}
+/** The part of the Nuxt instance the module writes, typed structurally. */
+export interface NuxtLike {
+  readonly options: {
+    readonly betterSupabase?: NuxtModuleOptions | undefined;
+    nitro: {
+      virtual?: Record<string, string | (() => string)>;
+      handlers?: NitroHandlerLike[];
+    };
+  };
+  hook(name: "imports:extend", fn: (imports: NuxtImportLike[]) => void): void;
+}
+/** The composables `better-supabase/vue` exports, auto-imported in components. */
+export declare const VUE_COMPOSABLES: readonly string[];
+/** The virtual Nitro middleware: the app's entries through `toH3V1`. */
+export declare function middlewareSource(server: string): string;
+/** A Nuxt module, typed structurally so the package does not import `@nuxt/kit`. */
+export interface BetterSupabaseNuxtModule {
+  (inline: NuxtModuleOptions | undefined, nuxt: NuxtLike): void;
+  getMeta(): Promise<{
+    readonly name: string;
+    readonly configKey: string;
+  }>;
+}
+/**
+ * Registers the app's entries as Nitro server middleware (every
+ * contribution on `event.context`) and auto-imports the Vue composables.
+ *
+ * ```ts title="nuxt.config.ts"
+ * export default defineNuxtConfig({
+ *   modules: ['better-supabase/nuxt'],
+ *   betterSupabase: { server: '~~/server/better-supabase' },
+ * })
+ * ```
+ */
+declare const betterSupabaseNuxt: BetterSupabaseNuxtModule;
+//#endregion
+export { betterSupabaseNuxt as default };

package/dist/nuxt/index.js

@@ -0,0 +1,64 @@
+//#region src/nuxt/index.ts
+/** The composables `better-supabase/vue` exports, auto-imported in components. */
+const VUE_COMPOSABLES = [
+	"useAuth",
+	"useSupabase",
+	"useSession",
+	"useSupportSession",
+	"provideSession",
+	"useLiveQuery",
+	"useLiveCount",
+	"useBroadcast",
+	"usePresence",
+	"useAction"
+];
+const MIDDLEWARE_ID = "#better-supabase/middleware";
+/** The virtual Nitro middleware: the app's entries through `toH3V1`. */
+function middlewareSource(server) {
+	return [
+		`import { defineEventHandler } from "h3";`,
+		`import { toH3V1 } from "better-supabase/h3/v1";`,
+		`import entries from ${JSON.stringify(server)};`,
+		`export default defineEventHandler(toH3V1(entries));`
+	].join("\n");
+}
+function setup(inline, nuxt) {
+	const options = {
+		...nuxt.options.betterSupabase,
+		...inline
+	};
+	if (options.server !== void 0) {
+		const nitro = nuxt.options.nitro;
+		nitro.virtual = {
+			...nitro.virtual,
+			[MIDDLEWARE_ID]: middlewareSource(options.server)
+		};
+		nitro.handlers = [...nitro.handlers ?? [], {
+			handler: MIDDLEWARE_ID,
+			middleware: true
+		}];
+	}
+	if (options.composables ?? true) nuxt.hook("imports:extend", (imports) => {
+		for (const name of VUE_COMPOSABLES) imports.push({
+			name,
+			from: "better-supabase/vue"
+		});
+	});
+}
+/**
+* Registers the app's entries as Nitro server middleware (every
+* contribution on `event.context`) and auto-imports the Vue composables.
+*
+* ```ts title="nuxt.config.ts"
+* export default defineNuxtConfig({
+*   modules: ['better-supabase/nuxt'],
+*   betterSupabase: { server: '~~/server/better-supabase' },
+* })
+* ```
+*/
+const betterSupabaseNuxt = Object.assign(setup, { getMeta: () => Promise.resolve({
+	name: "better-supabase",
+	configKey: "betterSupabase"
+}) });
+//#endregion
+export { VUE_COMPOSABLES, betterSupabaseNuxt as default, middlewareSource };

package/dist/onboarding-BZGHYJks.d.ts

@@ -0,0 +1,62 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "./result-D7y2fT87.js";
+import { t as BlockTransport } from "./block-transport-DvaoPuZ9.js";
+import { r as BlockTemporalOptions } from "./block-helpers-CKtbFcRv.js";
+//#region src/blocks/onboarding/onboarding.d.ts
+type ChecklistScope = "user" | "organization";
+/** One step. `events` completes it when the outbox records one of those types. */
+interface ChecklistStep<Id extends string = string> {
+  readonly id: Id;
+  readonly title?: string;
+  readonly description?: string;
+  /** Where the step is done in the app, for a "Start" link. */
+  readonly href?: string;
+  readonly events?: readonly string[];
+}
+interface ChecklistSpec<Id extends string, Scope extends ChecklistScope> {
+  readonly id: string;
+  /** `user` tracks each user; `organization` tracks each tenant. */
+  readonly scope: Scope;
+  readonly steps: readonly ChecklistStep<Id>[];
+}
+interface ChecklistConnectOptions extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /** The module schema (`sql.modules.onboarding.schema`), default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** A step with the subject's progress. */
+interface StepProgress<Id extends string> extends ChecklistStep<Id> {
+  readonly completed: boolean;
+  readonly completedAt: Temporal.Instant | undefined;
+  readonly completedBy: string | undefined;
+}
+interface ChecklistProgress<Id extends string> {
+  readonly steps: readonly StepProgress<Id>[];
+  readonly completed: number;
+  readonly total: number;
+  /** Every step is complete. */
+  readonly done: boolean;
+  /** The first step not done yet. */
+  readonly next: StepProgress<Id> | undefined;
+}
+/** The organization for an organization checklist; nothing for a user one. */
+type ChecklistSubject<Scope extends ChecklistScope> = Scope extends "organization" ? [organizationId: string] : [];
+interface ChecklistClient<Id extends string, Scope extends ChecklistScope> {
+  progress(...subject: ChecklistSubject<Scope>): AsyncResult<ChecklistProgress<Id>>;
+  /** Marks a step done; `false` when it already was. */
+  complete(step: Id, ...subject: ChecklistSubject<Scope>): AsyncResult<boolean>;
+  /** Marks a step not done; `false` when it wasn't. */
+  reset(step: Id, ...subject: ChecklistSubject<Scope>): AsyncResult<boolean>;
+}
+interface Checklist<Id extends string, Scope extends ChecklistScope> extends ChecklistSpec<Id, Scope> {
+  connect(options: ChecklistConnectOptions): ChecklistClient<Id, Scope>;
+}
+/**
+ * Declares an onboarding checklist. Pass the result to
+ * `sql.modules.onboarding.options.checklists` so the database knows its
+ * steps, and `connect` it to read and complete them.
+ */
+declare function defineChecklist<const Id extends string, const Scope extends ChecklistScope>(spec: ChecklistSpec<Id, Scope>): Checklist<Id, Scope>;
+//#endregion
+export { ChecklistScope as a, ChecklistSubject as c, ChecklistProgress as i, StepProgress as l, ChecklistClient as n, ChecklistSpec as o, ChecklistConnectOptions as r, ChecklistStep as s, Checklist as t, defineChecklist as u };

package/dist/openapi/index.d.ts

@@ -1,2 +1,2 @@
-import { a as ResourceOptions, i as ResourceOperation, n as OpenApiOptions, o as createOpenApi, r as PROBLEM_SCHEMA, t as OpenApiDocument } from "../index-C7f8cOBM.js";
+import { a as ResourceOptions, i as ResourceOperation, n as OpenApiOptions, o as createOpenApi, r as PROBLEM_SCHEMA, t as OpenApiDocument } from "../index-Bxih3l0u.js";
 export { OpenApiDocument, OpenApiOptions, PROBLEM_SCHEMA, ResourceOperation, ResourceOptions, createOpenApi };

package/dist/openapi/index.js

@@ -1,6 +1,6 @@
-import { n as PROBLEM_TYPE_BASE, t as PROBLEM_CONTENT_TYPE } from "../problem-BW1KhzSG.js";
-import { t as SPEC_PINS } from "../spec-pins-C3oc-Tdp.js";
-import { t as buildJsonSchema } from "../json-schema-m1fiwKgN.js";
+import { n as PROBLEM_TYPE_BASE, t as PROBLEM_CONTENT_TYPE } from "../problem-BreOl8b8.js";
+import { t as SPEC_PINS } from "../spec-pins--j6mTok4.js";
+import { t as buildJsonSchema } from "../json-schema-CvER4kgT.js";
 //#region src/openapi/index.ts
 /** JSON Schema for RFC 9457 Problem Details as better-supabase sends them. */
 const PROBLEM_SCHEMA = {

package/dist/orpc/index.d.ts

@@ -1,10 +1,44 @@
-import { n as AnyFunctions, r as AnyModels } from "../types-Dnf_wRDz.js";
-import { _ as DbError, u as Result } from "../executor-BunPOO-k.js";
-import { t as BetterSupabase } from "../define-Bp_BZa5h.js";
-import { r as AuthState } from "../resolve-C15TJq77.js";
-import { f as ServerContext, n as GuardOptions, p as ServerOptions, r as MiddlewareOptions, u as BetterServer } from "../respond-D2OQl62-.js";
-import { r as ProblemDetails } from "../problem-Blxe8S31.js";
-import { DecoratedMiddleware, ORPCError } from "@orpc/server";
+import { b as DbError, f as Result } from "../result-D7y2fT87.js";
+import { a as AnyModels, i as AnyFunctions } from "../types-6BdhkmZe.js";
+import { r as AuthState } from "../resolve-KW8nCeL6.js";
+import { i as ProblemDetails } from "../problem-DD8LZFjc.js";
+import { t as BetterSupabase } from "../define-CJJkkr1-.js";
+import { i as ServerContext, o as ServerOptions, t as BetterServer } from "../server-CeVeeXwz.js";
+import { i as MiddlewareOptions, r as GuardOptions } from "../respond-DoBijysA.js";
+import { s as BlockRequireOptions } from "../kit-B5tid-q5.js";
+import { t as Validated } from "../shared-DDSjEGDR.js";
+import { AnyEntry, Contributions } from "@supabase/middleware";
+import { BuilderWithMiddlewares, DecoratedMiddleware, ORPCError } from "@orpc/server";
+//#region src/bridges/orpc.d.ts
+/** The part of an oRPC fetch handler (`RPCHandler`, `OpenAPIHandler`) a bridge calls. */
+interface OrpcHandlerLike<Context> {
+  handle(request: Request, options: {
+    readonly prefix?: `/${string}`;
+    readonly context: Context;
+  }): Promise<{
+    readonly matched: boolean;
+    readonly response?: Response | undefined;
+  }>;
+}
+interface ToOrpcOptions {
+  /** Path prefix the router is mounted under, e.g. `/rpc`. */
+  readonly prefix?: `/${string}`;
+}
+/**
+ * Runs an entry array around an oRPC fetch handler. The procedures' initial
+ * context is `{ request }` plus every contributed key, and the response
+ * passes back through the entries, so refreshed cookies and response-phase
+ * headers reach it. A request no procedure matched answers 404.
+ *
+ * ```ts
+ * const os = implement(contract).$context<{ request: Request; db: Db }>()
+ * export default { fetch: toOrpc([withBetterSupabase(server)], new RPCHandler(router), { prefix: '/rpc' }) }
+ * ```
+ */
+export declare function toOrpc<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, handler: OrpcHandlerLike<{
+  readonly request: Request;
+} & Contributions<Entries>>, options?: ToOrpcOptions): (request: Request, env?: unknown) => Promise<Response>;
+//#endregion
 //#region src/orpc/index.d.ts
 /** Initial context: pass `{ context: { request } }` to the oRPC handler. */
 export interface OrpcRequestContext {
@@ -19,6 +53,11 @@ export interface OrpcContext<M extends AnyModels, F extends AnyFunctions, E, C =
 export interface OrpcOptions extends ServerOptions {
   /** Include internal error messages. Defaults to `NODE_ENV === 'development'`. */
   readonly exposeErrors?: boolean;
+  /**
+   * Keeps the invocation alive for event sink sends a procedure started,
+   * e.g. `EdgeRuntime.waitUntil` or Next's `after`. `fetchHandler` calls it.
+   */
+  readonly waitUntil?: (promise: Promise<unknown>) => void;
 }
 /** The part of an oRPC fetch handler (`RPCHandler`, `OpenAPIHandler`) `fetchHandler` calls. */
 export interface OrpcFetchHandler {
@@ -35,6 +74,14 @@ export interface OrpcFetchOptions {
   readonly prefix?: `/${string}`;
 }
 export type OrpcMiddleware<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> = DecoratedMiddleware<OrpcRequestContext, OrpcContext<M, F, E, C, P>, unknown, unknown, Record<never, never>>;
+/** Guard and authorize options of `middleware()` and `authed()`. */
+export interface OrpcGuardOptions<C = unknown, P = unknown> extends MiddlewareOptions, BlockRequireOptions<C, P> {}
+/** `os` with the caller's context: `bs.authed().handler(({ context }) => ...)`. */
+export type OrpcAuthed<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> = BuilderWithMiddlewares<OrpcRequestContext, OrpcContext<M, F, E, C, P>, Record<never, never>>;
+/** The Workers execution context, typed structurally. */
+export interface OrpcExecutionContext {
+  waitUntil(promise: Promise<unknown>): void;
+}
 export interface BetterOrpc<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends BetterServer<M, F, E, C, P> {
   /**
    * Resolves the caller, enforces `allow` and adds `context.db`, `context.auth`
@@ -42,13 +89,25 @@ export interface BetterOrpc<M extends AnyModels, F extends AnyFunctions, E, C =
    * `DbError`, become `ORPCError`s. Serve the router with `fetchHandler` so
    * refreshed session cookies and `bs-primary-until` reach the response.
    */
-  middleware(options?: MiddlewareOptions): OrpcMiddleware<M, F, E, C, P>;
+  middleware(options?: OrpcGuardOptions<C, P>): OrpcMiddleware<M, F, E, C, P>;
+  /**
+   * A procedure builder behind `middleware(options)`, so each procedure
+   * starts from the caller's context instead of repeating `.use()`:
+   *
+   * ```ts
+   * export const list = bs.authed({ requireTenant: true })
+   *   .handler(({ context }) => bs.unwrap(context.db.customers.findMany()))
+   * ```
+   */
+  authed(options?: OrpcGuardOptions<C, P>): OrpcAuthed<M, F, E, C, P>;
   /**
    * A fetch handler for an oRPC handler: passes `{ request }` as the initial
    * context, answers 404 when no procedure matched, and applies the cookies
-   * of the request's context (`ctx.apply`).
+   * of the request's context (`ctx.apply`). On Workers, pending event sends
+   * go to the `ctx.waitUntil` of `fetch(request, env, ctx)` when
+   * `OrpcOptions.waitUntil` is unset.
    */
-  fetchHandler(handler: OrpcFetchHandler, options?: OrpcFetchOptions): (request: Request) => Promise<Response>;
+  fetchHandler(handler: OrpcFetchHandler, options?: OrpcFetchOptions): (request: Request, env?: unknown, executionContext?: OrpcExecutionContext) => Promise<Response>;
   /** A `Result` (or `AsyncResult`) as data, throwing an `ORPCError` on failure. */
   unwrap<T>(value: Result<T> | PromiseLike<Result<T>>): Promise<T>;
   /** Plain values pass through; thrown `DbException`s become `ORPCError`s. */
@@ -60,4 +119,4 @@ export declare function orpcCode(error: DbError): string;
 /** oRPC integration: middleware adding the caller's repositories to `context`. */
 export declare function createOrpc<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, options?: OrpcOptions): BetterOrpc<M, F, E, C, P>;
 //#endregion
-export type { GuardOptions, MiddlewareOptions };
+export type { GuardOptions, MiddlewareOptions, OrpcHandlerLike, ToOrpcOptions };