better-supabase 0.12.0 → 0.14.0

package/dist/orpc/index.js

@@ -1,24 +1,29 @@
-import { r as dbErrorOf } from "../errors-BV1SKTVs.js";
-import { c as toProblem } from "../problem-JRCohp1j.js";
-import { i as claimsOf } from "../claims-PqzCxaTD.js";
-import { t as tenantOf } from "../tenant-B-fiItlJ.js";
-import { c as extendServer, n as flushEvents, s as createServer, x as refreshFor } from "../adapter-CRNH2aX_.js";
-import { n as toSession } from "../view-CYX1wsgp.js";
-import { o as settle, r as guard, t as defaultExpose } from "../respond-Bhp3G__q.js";
-import { t as authorizeCaller } from "../kit-LTbHrWWD.js";
-import { t as rateLimitGate } from "../rate-limit-DVZ7qIzW.js";
+import { r as dbErrorOf } from "../errors-03ysrOt4.js";
+import { c as toProblem } from "../problem-BWElIgIb.js";
+import { i as claimsOf } from "../claims-Bp9My7XP.js";
+import { t as callWithInput } from "../block-method-Bvsao626.js";
+import { t as tenantOf } from "../tenant-DnMqeNIM.js";
+import { c as extendServer, n as flushEvents, s as createServer, x as refreshFor } from "../adapter-BCFAg58A.js";
+import { n as toSession } from "../view-BtgqxQLM.js";
+import { o as settle, r as guard, t as defaultExpose } from "../respond-z_yfyitp.js";
+import { t as authorizeCaller } from "../kit-Ct4Z6GIO.js";
+import { t as rateLimitGate } from "../rate-limit-B_U12PdL.js";
 import { bufferRequest, pipeline, seedContext } from "@supabase/middleware";
 import { COMMON_ERROR_STATUS_MAP, ORPCError, os } from "@orpc/server";
 //#region src/bridges/orpc.ts
 /**
 * 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.
+* 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' }) }
+* const os = implement(contract).$context<{ request: Request; db: Db }>();
+* export default {
+*   fetch: toOrpc([withBetterSupabase(server)], new RPCHandler(router), {
+*     prefix: "/rpc",
+*   }),
+* };
 * ```
 */
 function toOrpc(entries, handler, options = {}) {
@@ -37,7 +42,7 @@ function toOrpc(entries, handler, options = {}) {
 //#endregion
 //#region src/orpc/index.ts
 const CODES = /* @__PURE__ */ new Map(Object.entries(COMMON_ERROR_STATUS_MAP).map(([code, status]) => [status, code]));
-/** oRPC code for a `DbError`, from its HTTP status. */
+/** ORPC code for a `DbError`, from its HTTP status. */
 function orpcCode(error) {
 	return CODES.get(error.status) ?? (error.status >= 500 ? "INTERNAL_SERVER_ERROR" : "BAD_REQUEST");
 }
@@ -47,7 +52,7 @@ function withHeaders(response, headers) {
 	for (const [name, value] of headers) copy.headers.set(name, value);
 	return copy;
 }
-/** oRPC integration: middleware adding the caller's repositories to `context`. */
+/** ORPC integration: middleware adding the caller's repositories to `context`. */
 function createOrpc(betterSupabase, options = {}) {
 	const server = createServer(betterSupabase, options);
 	const expose = options.exposeErrors ?? defaultExpose();
@@ -61,7 +66,7 @@ function createOrpc(betterSupabase, options = {}) {
 			data: problem
 		});
 	};
-	const middleware = (middlewareOptions = {}) => os.$context().middleware(async ({ context, next }) => {
+	const middleware = (middlewareOptions = {}) => os.$context().middleware(async ({ context, next }, input) => {
 		const refresh = refreshFor(middlewareOptions.refresh, context.request) ?? false;
 		const known = contexts.get(context.request);
 		const ctx = known && (known.refresh || !refresh) ? known.ctx : await server.context(context.request, { refresh });
@@ -71,7 +76,7 @@ function createOrpc(betterSupabase, options = {}) {
 		});
 		const denied = guard(ctx.auth, middlewareOptions.allow, middlewareOptions.aal, middlewareOptions.scopes);
 		if (denied) throw toOrpcError(denied);
-		const caller = await authorizeCaller(ctx.auth, middlewareOptions, void 0, tenantOf(toSession(ctx.auth), tenantClaim), options.authorizer);
+		const caller = await authorizeCaller(ctx.auth, middlewareOptions, input, tenantOf(toSession(ctx.auth), tenantClaim), options.authorizer, ctx);
 		if ("kind" in caller) throw toOrpcError(caller);
 		try {
 			return await next({ context: {
@@ -127,6 +132,36 @@ function createOrpc(betterSupabase, options = {}) {
 			const settled = await settle(() => value);
 			if (!settled.ok) throw toOrpcError(settled.error);
 			return settled.data;
+		},
+		blockRouter(client, routerOptions) {
+			const procedures = {};
+			const routes = [];
+			const schemas = routerOptions.schemas ?? {};
+			for (const name of routerOptions.methods) {
+				const route = {
+					method: "POST",
+					path: `/${routerOptions.name}/${name}`,
+					operationId: `${routerOptions.name}.${name}`
+				};
+				const schema = schemas[name];
+				const base = os.$context().use(middleware(routerOptions.guard));
+				const routed = routerOptions.meta ? base.meta(routerOptions.meta(route)) : base;
+				const call = async ({ input, context }) => {
+					const settled = await settle(() => callWithInput(client(context.bs), name, input));
+					if (!settled.ok) throw toOrpcError(settled.error);
+					return settled.data;
+				};
+				procedures[name] = schema ? routed.input(schema).handler(call) : routed.handler(call);
+				routes.push({
+					...route,
+					...schema ? { input: schema } : {},
+					...routerOptions.tags ? { tags: routerOptions.tags } : {}
+				});
+			}
+			return {
+				procedures,
+				routes
+			};
 		}
 	});
 }

package/dist/otel/index.d.ts

@@ -1,6 +1,6 @@
-import { o as EventHub } from "../events-P3raDX2E.js";
-import { d as Plugin } from "../plugin-D-95Q0w0.js";
-import { t as SPEC_PINS } from "../spec-pins-Dqpml2dZ.js";
+import { o as EventHub } from "../events-DbLjvxDX.js";
+import { d as Plugin } from "../plugin-Ar5546xh.js";
+import { t as SPEC_PINS } from "../spec-pins-CZ2CL8YZ.js";
 import { Attributes, Meter, Tracer } from "@opentelemetry/api";
 //#region src/otel/index.d.ts
 export declare const INSTRUMENTATION_NAME = "better-supabase";
@@ -14,20 +14,23 @@ export interface OtelOptions {
   /** Set `false` to skip the duration histogram. */
   readonly metrics?: boolean;
   /**
-   * The database name in `db.namespace` (`{database}|{schema}`). Supabase
-   * names it `postgres`, the default for Postgres executors.
+   * The database name in `db.namespace` (`{database}|{schema}`). Supabase names
+   * it `postgres`, the default for Postgres executors.
    */
   readonly database?: string;
-  /** `server.address` and `server.port` on spans and metrics, e.g. the project host. */
+  /**
+   * `server.address` and `server.port` on spans and metrics, e.g. the project
+   * host.
+   */
   readonly server?: {
     readonly address: string;
     readonly port?: number;
   };
 }
 /**
- * Database client spans and metrics for every repository operation, using
- * the OpenTelemetry database conventions. Filter values and row data are
- * never recorded; `db.query.summary` is `SELECT customers`.
+ * Database client spans and metrics for every repository operation, using the
+ * OpenTelemetry database conventions. Filter values and row data are never
+ * recorded; `db.query.summary` is `SELECT customers`.
  *
  * ```ts
  * const betterSupabase = defineSupabase(schema).use(otel());
@@ -35,8 +38,8 @@ export interface OtelOptions {
  */
 export declare function otel(options?: OtelOptions): Plugin<"otel">;
 /**
- * Spans for auth resolution and session refreshes, from `betterSupabase.events`.
- * Returns a function that stops listening.
+ * Spans for auth resolution and session refreshes, from
+ * `betterSupabase.events`. Returns a function that stops listening.
  */
 export declare function traceAuth(betterSupabase: {
   readonly events: EventHub;
@@ -44,16 +47,16 @@ export declare function traceAuth(betterSupabase: {
 /**
  * Records block events (`support.started`, `webhook.failed`, ...) with the
  * `BLOCK_ATTRIBUTES` names: as an event on the active span, or as a short
- * `block <type>` span when there is none. Failures (`*.failed`, `*.denied`)
- * set an error status. Returns a function that stops listening.
+ * `block <type>` span when there is none. Failures (`*.failed`, `*.denied`) set
+ * an error status. Returns a function that stops listening.
  */
 export declare function traceBlockEvents(betterSupabase: {
   readonly events: EventHub;
 }, options?: Pick<OtelOptions, "tracer" | "attributes">): () => void;
 /**
- * A `fetch` that adds W3C `traceparent`/`tracestate` from the active
- * context. Pass it to `createClient(url, key, { global: { fetch } })` so
- * PostgREST, Auth and Storage calls join the trace.
+ * A `fetch` that adds W3C `traceparent`/`tracestate` from the active context.
+ * Pass it to `createClient(url, key, { global: { fetch } })` so PostgREST, Auth
+ * and Storage calls join the trace.
  */
 export declare function tracedFetch(base?: typeof fetch): typeof fetch;
 //#endregion

package/dist/otel/index.js

@@ -1,8 +1,8 @@
-import { r as definePlugin } from "../plugin-tfXW1-qO.js";
-import { t as SPEC_PINS } from "../spec-pins-S4PymRxp.js";
-import "../version-DSWxci83.js";
-import { i as blockEventAttributes } from "../block-events-DD9Q_NUz.js";
+import { r as definePlugin } from "../plugin-D9bYbYli.js";
+import { t as SPEC_PINS } from "../spec-pins-D3Tm6HJi.js";
+import { i as blockEventAttributes } from "../block-events-pBXPzwnW.js";
 import { SpanKind, SpanStatusCode, context, metrics, propagation, trace } from "@opentelemetry/api";
+//#endregion
 //#region src/otel/index.ts
 const INSTRUMENTATION_NAME = "better-supabase";
 /** OpenTelemetry semantic conventions version the attributes follow. */
@@ -31,18 +31,18 @@ function systemOf(executor) {
 	return executor.name === "postgrest" || executor.name === "postgres" ? "postgresql" : executor.name;
 }
 /**
-* Database client spans and metrics for every repository operation, using
-* the OpenTelemetry database conventions. Filter values and row data are
-* never recorded; `db.query.summary` is `SELECT customers`.
+* Database client spans and metrics for every repository operation, using the
+* OpenTelemetry database conventions. Filter values and row data are never
+* recorded; `db.query.summary` is `SELECT customers`.
 *
 * ```ts
 * const betterSupabase = defineSupabase(schema).use(otel());
 * ```
 */
 function otel(options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.12.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.14.0");
 	let histogram;
-	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.12.0")).createHistogram("db.client.operation.duration", {
+	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.14.0")).createHistogram("db.client.operation.duration", {
 		unit: "s",
 		description: "Duration of database client operations.",
 		advice: { explicitBucketBoundaries: [
@@ -149,7 +149,10 @@ function otel(options = {}) {
 			};
 			const rpc = executor.rpc?.bind(executor);
 			const batch = executor.batch?.bind(executor);
-			/** Semantic conventions name a batch `BATCH <operation>` when every operation shares it. */
+			/**
+			* Semantic conventions name a batch `BATCH <operation>` when every
+			* operation shares it.
+			*/
 			const describeBatch = (ops) => {
 				const [only, ...others] = new Set(ops.map(operationName));
 				const operation = only && others.length === 0 ? `BATCH ${only}` : "BATCH";
@@ -212,11 +215,11 @@ function otel(options = {}) {
 	});
 }
 /**
-* Spans for auth resolution and session refreshes, from `betterSupabase.events`.
-* Returns a function that stops listening.
+* Spans for auth resolution and session refreshes, from
+* `betterSupabase.events`. Returns a function that stops listening.
 */
 function traceAuth(betterSupabase, options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.12.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.14.0");
 	const offAuth = betterSupabase.events.on("auth", (event) => {
 		const span = tracer.startSpan("auth.resolve", {
 			kind: SpanKind.INTERNAL,
@@ -250,11 +253,11 @@ function traceAuth(betterSupabase, options = {}) {
 /**
 * Records block events (`support.started`, `webhook.failed`, ...) with the
 * `BLOCK_ATTRIBUTES` names: as an event on the active span, or as a short
-* `block <type>` span when there is none. Failures (`*.failed`, `*.denied`)
-* set an error status. Returns a function that stops listening.
+* `block <type>` span when there is none. Failures (`*.failed`, `*.denied`) set
+* an error status. Returns a function that stops listening.
 */
 function traceBlockEvents(betterSupabase, options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.12.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.14.0");
 	return betterSupabase.events.on("block", (event) => {
 		const attributes = {
 			...options.attributes,
@@ -275,9 +278,9 @@ function traceBlockEvents(betterSupabase, options = {}) {
 	});
 }
 /**
-* A `fetch` that adds W3C `traceparent`/`tracestate` from the active
-* context. Pass it to `createClient(url, key, { global: { fetch } })` so
-* PostgREST, Auth and Storage calls join the trace.
+* A `fetch` that adds W3C `traceparent`/`tracestate` from the active context.
+* Pass it to `createClient(url, key, { global: { fetch } })` so PostgREST, Auth
+* and Storage calls join the trace.
 */
 function tracedFetch(base = fetch) {
 	return (input, init) => {

package/dist/outbox-CsF_iKjx.d.ts

@@ -0,0 +1,199 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, t as AsyncResult } from "./result-C6jDfedy.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { i as CursorPageOptions, n as BlockOptions } from "./block-helpers-BaugZlJV.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { t as BlockProblemOptions } from "./problem-DpHB7tWl.js";
+import { i as EventSink, t as CloudEvent } from "./cloud-event-SPyXMdcd.js";
+import { g as SubscriberPolicy, i as AuthorizationHooks } from "./authorization-hooks-dLmUO_PZ.js";
+//#region src/blocks/outbox/outbox.d.ts
+/** One row of the outbox, as `outbox_claim` and `outbox_history` return it. */
+interface OutboxEvent {
+  /** The cursor value: increases with every event. */
+  readonly position: number;
+  readonly id: string;
+  readonly type: string;
+  readonly payload: unknown;
+  /**
+   * The module or function that wrote it, e.g.
+   * `better-supabase/blocks/organizations`.
+   */
+  readonly source: string | null;
+  readonly subject: string | null;
+  readonly tenant: string | null;
+  readonly key: string | null;
+  readonly actorId: string | null;
+  readonly createdAt: Temporal.Instant;
+}
+interface EmitOptions {
+  readonly subject?: string;
+  readonly tenant?: string;
+  /** With a key, emitting again (per tenant) returns the first event. */
+  readonly key?: string;
+  readonly source?: string;
+}
+/**
+ * `transport` writes (`emit`) and reads (`history`); `service`, which defaults
+ * to `transport`, runs the consumer calls (`register`, `relay`, `consume`,
+ * `deadLetters`, `purge`), which need the service role.
+ */
+interface OutboxOptions extends BlockOptions {
+  /** CloudEvents `source` of the relayed events, e.g. `https://crm.example.com`. */
+  readonly source: string;
+  /**
+   * Prepended to each type with a dot when relaying, e.g. `com.example`.
+   * Defaults to `dev.better-supabase`.
+   */
+  readonly typePrefix?: string;
+  /**
+   * Decides, per event, whether a consumer gets it. The consumer is the
+   * subscriber `{ principal: <consumer name>, kind: "service" }`. An event it
+   * leaves out is skipped and the cursor moves past it; a throw counts as a
+   * failed attempt. Defaults to `authorization.delivery.subscribers`.
+   */
+  readonly subscribers?: SubscriberPolicy;
+  /** `server.authorization`, for its `delivery.subscribers` policy. */
+  readonly authorization?: Pick<AuthorizationHooks, "delivery">;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Outbox>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface RegisterOptions {
+  /**
+   * Type patterns such as `organization.*` or `invoice.paid`. Defaults to every
+   * event.
+   */
+  readonly types?: readonly string[];
+  /** Start at the first kept event instead of after the latest one. */
+  readonly fromStart?: boolean;
+}
+interface RelayOptions {
+  /** Events per claim and per `sink.send`. Defaults to 100. */
+  readonly batch?: number;
+  /** How long a claim holds the consumer. Defaults to `1 minute`. */
+  readonly lease?: string;
+  /** Stops claiming after this many milliseconds. */
+  readonly budgetMs?: number;
+  /** Identifies this worker in the lease. Defaults to a random id. */
+  readonly owner?: string;
+  /**
+   * Failures in a row before the event that keeps failing goes to the dead
+   * letters and the cursor moves past it. Defaults to 10.
+   */
+  readonly maxAttempts?: number;
+  /** The longest wait between failed attempts. Defaults to `10 minutes`. */
+  readonly maxBackoff?: string;
+}
+interface RelayResult {
+  /** Events handed to the sink or handler. */
+  readonly delivered: number;
+  /**
+   * Events the `subscribers` policy kept from the consumer, when there were
+   * any.
+   */
+  readonly refused?: number;
+  /**
+   * Set when the sink threw: the consumer backs off and retries the batch one
+   * event at a time.
+   */
+  readonly error?: DbError;
+  /** 1 when this run moved the failing event to the dead letters. */
+  readonly deadLettered?: number;
+}
+/** An event a consumer skipped after `maxAttempts` failures. */
+interface OutboxDeadLetter {
+  readonly consumer: string;
+  readonly event: OutboxEvent;
+  readonly attempts: number;
+  readonly error: string | null;
+  readonly deadAt: Temporal.Instant;
+}
+interface OutboxPurgeOptions {
+  /**
+   * A consumer that hasn't claimed for this long (a Postgres interval such as
+   * `30 days`) no longer holds events back. Defaults to waiting for every
+   * consumer.
+   */
+  readonly ignoreIdle?: string;
+}
+/**
+ * Takes a batch of outbox rows, with the actor and tenant that CloudEvents
+ * leave out. Throwing counts a failed attempt: the consumer backs off, then
+ * retries one event at a time until the event that fails goes to the dead
+ * letters.
+ */
+type OutboxHandler = (events: readonly OutboxEvent[]) => unknown;
+interface OutboxRouteOptions extends Omit<RelayOptions, "owner">, BlockProblemOptions {
+  /** The bearer secret, such as `process.env.CRON_SECRET`. */
+  readonly secret: string | undefined;
+  /**
+   * Consumer name to the sink its events go to, or a handler that takes the
+   * rows.
+   */
+  readonly consumers: Readonly<Record<string, EventSink | OutboxHandler>>;
+  readonly onError?: (error: DbError, consumer: string) => void;
+}
+interface OutboxRouteResult {
+  readonly consumers: Readonly<Record<string, RelayResult>>;
+  readonly budgetExhausted: boolean;
+}
+interface HistoryFilter extends CursorPageOptions<number> {
+  readonly subject?: string;
+  readonly type?: string;
+  /** Only events after this position. */
+  readonly cursor?: number;
+  readonly limit?: number;
+}
+interface Outbox {
+  /** Writes an event in the current transaction and returns its id. */
+  emit(type: string, payload?: unknown, options?: EmitOptions): AsyncResult<string>;
+  /** Creates the consumer, or changes its types. Returns its cursor position. */
+  register(consumer: string, options?: RegisterOptions): AsyncResult<number>;
+  /** Removes the consumer, so purges stop waiting for it. */
+  unregister(consumer: string): AsyncResult<boolean>;
+  /**
+   * Claims the consumer's next events, sends them to `sink` as CloudEvents and
+   * moves the cursor, until none are left or the budget runs out. A sink that
+   * throws leaves the batch for a later run with backoff, so delivery is at
+   * least once; an event that fails `maxAttempts` times goes to the dead
+   * letters.
+   */
+  relay(consumer: string, sink: EventSink, options?: RelayOptions): Promise<RelayResult>;
+  /**
+   * Like `relay`, but hands `handler` the outbox rows themselves, with
+   * `actorId`, `tenant` and `key`, for consumers inside the app (search
+   * indexing, notifications) that need the actor.
+   */
+  consume(consumer: string, handler: OutboxHandler, options?: RelayOptions): Promise<RelayResult>;
+  /**
+   * A `GET`/`POST` handler for a cron that relays every consumer at once,
+   * within one budget.
+   */
+  relayRoute(options: OutboxRouteOptions): (request: Request) => Promise<Response>;
+  history(filter?: HistoryFilter): AsyncResult<readonly OutboxEvent[]>;
+  /** The consumer's dead letters, newest first (default 100, at most 1000). */
+  deadLetters(consumer: string, limit?: number): AsyncResult<readonly OutboxDeadLetter[]>;
+  /**
+   * Deletes up to `batch` events (default 10,000) older than `olderThan` that
+   * every consumer has passed, and dead letters older than `olderThan`. Call it
+   * again while it returns `batch`.
+   */
+  purge(olderThan?: string, batch?: number, options?: OutboxPurgeOptions): AsyncResult<number>;
+}
+/**
+ * The CloudEvent for an outbox row: the row id as `id` (stable, so receivers
+ * can deduplicate), the payload as `data`, the tenant as `partitionkey` and the
+ * writing module as `producer`. The actor stays out of the context attributes,
+ * which must not carry personal data.
+ */
+declare function outboxCloudEvent(event: OutboxEvent, options: Pick<OutboxOptions, "source" | "typePrefix">): CloudEvent;
+/**
+ * The outbox over a `BlockTransport`: `sqlTransport(postgres)` on a server
+ * connection, where `emit` joins the caller's transaction, or
+ * `rpcTransport(serviceClient)` for apps that reach the database only through
+ * the Data API, where `emit` writes in its own transaction.
+ */
+declare function createOutbox(options: OutboxOptions): Outbox;
+//#endregion
+export { OutboxEvent as a, OutboxPurgeOptions as c, RegisterOptions as d, RelayOptions as f, outboxCloudEvent as h, OutboxDeadLetter as i, OutboxRouteOptions as l, createOutbox as m, HistoryFilter as n, OutboxHandler as o, RelayResult as p, Outbox as r, OutboxOptions as s, EmitOptions as t, OutboxRouteResult as u };