better-supabase 0.4.0 → 0.5.0

package/dist/jobs/index.js

@@ -1,19 +1,168 @@
-import { c as mapDbError, n as dbError, t as DbException } from "../errors-L0xK41y_.js";
-import { n as nowInstant } from "../temporal-BwshQk0W.js";
-import { t as temporal } from "../temporal-required-CBNHT6ni.js";
-import { i as ok, n as err, o as toDbError, t as AsyncResult } from "../result-Bj6yt33D.js";
-import { t as validate } from "../standard-BRyBGTtp.js";
-import { a as problemResponse } from "../problem-BihjPR0t.js";
-import { t as fromPgError } from "../executor-CVt6dD0B.js";
-import { c as verifyWebhook } from "../webhooks-Bh_Jf_-l.js";
-//#region src/jobs/jobs.ts
+import { c as mapDbError, n as dbError, t as DbException } from "../errors-DtwXa6b8.js";
+import { n as nowInstant } from "../temporal-CVlIV2DZ.js";
+import { t as temporal } from "../temporal-required-CAt4Dc9Z.js";
+import { i as ok, n as err, o as toDbError, t as AsyncResult } from "../result-BKiliPY7.js";
+import { n as allTenantsContext, s as tenantOf } from "../plugin-DwARMuQp.js";
+import { t as validate } from "../standard-D7r6dMUu.js";
+import { a as problemResponse } from "../problem-BW1KhzSG.js";
+import { i as tenantClaimPaths, n as claimAt } from "../claims-BAf6c7is.js";
+import { r as sqlIdent } from "../template-TxrGI5jR.js";
+import { t as fromPgError } from "../executor-XycESQPH.js";
+import { c as verifyWebhook, s as verifySharedSecret } from "../verify-Ce49ETPz.js";
+//#region src/jobs/cron.ts
+const MACROS = {
+	"@yearly": "0 0 1 1 *",
+	"@annually": "0 0 1 1 *",
+	"@monthly": "0 0 1 * *",
+	"@weekly": "0 0 * * 0",
+	"@daily": "0 0 * * *",
+	"@midnight": "0 0 * * *",
+	"@hourly": "0 * * * *"
+};
+const MONTHS = [
+	"jan",
+	"feb",
+	"mar",
+	"apr",
+	"may",
+	"jun",
+	"jul",
+	"aug",
+	"sep",
+	"oct",
+	"nov",
+	"dec"
+];
+const WEEKDAYS = [
+	"sun",
+	"mon",
+	"tue",
+	"wed",
+	"thu",
+	"fri",
+	"sat"
+];
+/** Replaces `JAN` or `MON` style names with their numbers. */
+function named(text, names, first) {
+	return text.replaceAll(/[a-z]{3}/gi, (name) => {
+		const index = names.indexOf(name.toLowerCase());
+		return index === -1 ? name : String(index + first);
+	});
+}
+const INTERVAL = /^(\d+)\s+(second|minute|hour)s?$/i;
+/** Gives up when no minute matches within this many days (`0 0 30 2 *`). */
+const SEARCH_DAYS = 1830;
+function invalid(expression, reason) {
+	return /* @__PURE__ */ new TypeError(`Invalid cron "${expression}": ${reason}`);
+}
+function field(expression, text, min, max) {
+	const values = /* @__PURE__ */ new Set();
+	for (const part of text.split(",")) {
+		const match = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(part);
+		if (!match) throw invalid(expression, `"${part}" is not a cron field`);
+		const [, range = "", stepText] = match;
+		const step = stepText === void 0 ? 1 : Number(stepText);
+		let from = min;
+		let to = max;
+		if (range !== "*") {
+			const [start = "", end] = range.split("-");
+			from = Number(start);
+			to = end === void 0 ? stepText === void 0 ? from : max : Number(end);
+		}
+		if (step < 1 || from < min || to > max || from > to) throw invalid(expression, `"${part}" is outside ${String(min)}-${String(max)}`);
+		for (let value = from; value <= to; value += step) values.add(value);
+	}
+	return [...values].toSorted((a, b) => a - b);
+}
+function parse(expression) {
+	const parts = (MACROS[expression.trim().toLowerCase()] ?? expression).trim().split(/\s+/);
+	if (parts.length !== 5) throw invalid(expression, "expected 5 fields (minute hour day month weekday)");
+	const [minute = "", hour = "", day = "", monthText = "", weekdayText = ""] = parts;
+	const month = named(monthText, MONTHS, 1);
+	const weekday = named(weekdayText, WEEKDAYS, 0);
+	return {
+		minutes: field(expression, minute, 0, 59),
+		hours: field(expression, hour, 0, 23),
+		days: new Set(field(expression, day, 1, 31)),
+		months: new Set(field(expression, month, 1, 12)),
+		weekdays: new Set(field(expression, weekday, 0, 7).map((value) => value === 0 ? 7 : value)),
+		daysRestricted: day !== "*",
+		weekdaysRestricted: weekday !== "*"
+	};
+}
+function dayMatches(fields, date) {
+	if (!fields.months.has(date.month)) return false;
+	const day = fields.days.has(date.day);
+	const weekday = fields.weekdays.has(date.dayOfWeek);
+	if (fields.daysRestricted && fields.weekdaysRestricted) return day || weekday;
+	if (fields.daysRestricted) return day;
+	if (fields.weekdaysRestricted) return weekday;
+	return true;
+}
+/** The first matching minute of `date` after `after`, from `start` on its first day. */
+function firstRunOn(fields, date, start, timeZone, after) {
+	for (const hour of fields.hours) {
+		if (start && hour < start.hour) continue;
+		for (const minute of fields.minutes) {
+			if (hour === start?.hour && minute < start.minute) continue;
+			const instant = date.toPlainDateTime({
+				hour,
+				minute
+			}).toZonedDateTime(timeZone, { disambiguation: "compatible" }).toInstant();
+			if (temporal().Instant.compare(instant, after) > 0) return instant;
+		}
+	}
+}
+/**
+* Throws a `TypeError` unless `expression` is a schedule `nextCronRun`
+* understands: five cron fields, a macro such as `@daily`, or an interval
+* such as `30 seconds`.
+*/
+function assertCron(expression) {
+	if (!INTERVAL.test(expression.trim())) parse(expression);
+}
+/**
+* The first run of `expression` after `after`, in `timeZone`.
+*
+* Accepts five cron fields (lists, ranges and steps; a restricted day of
+* month and day of week match either, as in cron), the macros `@hourly`,
+* `@daily`, `@weekly`, `@monthly` and `@yearly`, and intervals such as
+* `30 seconds`, `5 minutes` or `2 hours`, counted from `after`. A local time
+* that a DST change skips runs at the same offset after the gap.
+*/
+function nextCronRun(expression, timeZone, after) {
+	const interval = INTERVAL.exec(expression.trim());
+	if (interval) {
+		const amount = Number(interval[1]);
+		if (amount < 1) throw invalid(expression, "the interval must be positive");
+		const unit = interval[2].toLowerCase();
+		return after.add(unit === "second" ? { seconds: amount } : unit === "minute" ? { minutes: amount } : { hours: amount });
+	}
+	const fields = parse(expression);
+	const start = after.toZonedDateTimeISO(timeZone).toPlainDateTime().round({
+		smallestUnit: "minute",
+		roundingMode: "floor"
+	}).add({ minutes: 1 });
+	let date = start.toPlainDate();
+	for (let offset = 0; offset < SEARCH_DAYS; offset += 1) {
+		const found = dayMatches(fields, date) && firstRunOn(fields, date, offset === 0 ? start : void 0, timeZone, after);
+		if (found) return found;
+		date = date.add({ days: 1 });
+	}
+	throw invalid(expression, "it never matches a date");
+}
+//#endregion
+//#region src/jobs/shared.ts
+function asDbError(cause) {
+	const raw = fromPgError(cause);
+	return raw ? mapDbError(raw) : toDbError(cause);
+}
 function run(fn) {
 	return AsyncResult.from(async () => {
 		try {
 			return ok(await fn());
 		} catch (cause) {
-			const raw = fromPgError(cause);
-			return err(raw ? mapDbError(raw) : toDbError(cause));
+			return err(asDbError(cause));
 		}
 	});
 }
@@ -36,9 +185,425 @@ const sleep = (ms, signal) => new Promise((resolve) => {
 	}
 	signal?.addEventListener("abort", done, { once: true });
 });
-function sqlTransport(sql) {
+/** pgmq and the inbox return `timestamptz` as text over RPC and as `Date` from `pg`. */
+const toInstant = (value) => value instanceof Date ? temporal().Instant.fromEpochMilliseconds(value.getTime()) : temporal().Instant.from(value);
+function errorText(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "object" && error !== null && "message" in error) return String(error.message);
+	return String(error);
+}
+//#endregion
+//#region src/jobs/jobs.ts
+async function sha256(text) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+const AUTH_COOKIE = /^sb-.+-auth-token(?:\.\d+)?$/;
+/** A hash of the credentials the request carries, or `''` without any. */
+async function callerScope(request) {
+	const authorization = request.headers.get("authorization");
+	const cookies = (request.headers.get("cookie") ?? "").split(";").map((pair) => pair.trim()).filter((pair) => AUTH_COOKIE.test(pair.split("=", 1)[0] ?? "")).sort();
+	const credential = authorization ?? cookies.join(";");
+	return credential === "" ? "" : `caller:${await sha256(credential)}`;
+}
+/** HTTP idempotency keys (IETF `Idempotency-Key` header) over the `idempotency` SQL kit module. */
+function createIdempotency(sql, options = {}) {
+	const headerName = options.header ?? "idempotency-key";
+	const ttl = seconds(options.ttl ?? "24 hours");
+	const lock = seconds(options.lock ?? "1 minute");
+	const begin = (key, fingerprint, scope = "") => run(async () => {
+		const [row] = await sql.queryRaw("select * from better_supabase.begin_idempotent($1, $2, $3, $4::interval, $5::interval)", [
+			scope,
+			key,
+			fingerprint,
+			ttl,
+			lock
+		]);
+		return {
+			state: row.state,
+			status: row.status_code,
+			body: row.response
+		};
+	});
+	const complete = (key, status, body, scope = "") => run(async () => {
+		await sql.queryRaw("select better_supabase.complete_idempotent($1, $2, $3, $4)", [
+			scope,
+			key,
+			status,
+			JSON.stringify(body)
+		]);
+	});
+	const release = (key, scope = "") => run(async () => {
+		await sql.queryRaw("select better_supabase.release_idempotent($1, $2)", [scope, key]);
+	});
+	return {
+		begin,
+		complete,
+		release,
+		async handle(request, handler) {
+			const key = request.headers.get(headerName);
+			const instance = new URL(request.url).pathname;
+			if (!key) return options.required ? problemResponse(dbError("invalid_request", `The ${headerName} header is required`, { code: "IDEMPOTENCY_KEY_MISSING" }), { instance }) : handler(request);
+			if (key.length > 255) return problemResponse(dbError("invalid_request", `The ${headerName} header is too long`, { code: "IDEMPOTENCY_KEY_INVALID" }), { instance });
+			const scope = typeof options.scope === "function" ? options.scope(request) : options.scope ?? await callerScope(request);
+			const body = await request.clone().text();
+			const fingerprint = await sha256(`${request.method} ${instance}\n${body}`);
+			const started = await begin(key, fingerprint, scope);
+			if (!started.ok) return problemResponse(started.error, { instance });
+			const { state } = started.data;
+			switch (state) {
+				case "replay": {
+					const stored = started.data.body;
+					return new Response(stored.body, {
+						status: started.data.status ?? 200,
+						headers: {
+							...stored.contentType ? { "content-type": stored.contentType } : {},
+							"idempotency-replayed": "true"
+						}
+					});
+				}
+				case "running": return problemResponse(dbError("conflict", "A request with this idempotency key is still running", { code: "IDEMPOTENCY_KEY_IN_USE" }), {
+					instance,
+					headers: { "retry-after": "1" }
+				});
+				case "mismatch": return problemResponse(dbError("validation", "This idempotency key was used for a different request", {
+					code: "IDEMPOTENCY_KEY_REUSED",
+					issues: [{
+						message: "Use a new key for a new request",
+						path: [headerName]
+					}]
+				}), { instance });
+				case "started": break;
+				default: throw new TypeError(`Unknown idempotency state ${String(state)}`);
+			}
+			let response;
+			try {
+				response = await handler(request);
+			} catch (cause) {
+				await release(key, scope);
+				throw cause;
+			}
+			if (response.status >= 500) {
+				await release(key, scope);
+				return response;
+			}
+			const stored = {
+				body: await response.clone().text(),
+				contentType: response.headers.get("content-type")
+			};
+			await complete(key, response.status, stored, scope);
+			return response;
+		}
+	};
+}
+function defaultType(payload) {
+	if (typeof payload !== "object" || payload === null) return null;
+	const type = payload.type;
+	return typeof type === "string" ? type : null;
+}
+/** Store-then-process webhooks: acknowledge fast, process with retries, never twice. */
+function createInbox(sql, options) {
+	const worker = options.worker ?? workerId();
+	if (!options.secrets && !options.verify) throw new TypeError("createInbox needs `secrets` (Standard Webhooks) or `verify`");
+	const verified = async (request) => {
+		if (options.verify) return options.verify(request, await request.clone().text());
+		const result = await verifyWebhook(request, options.secrets);
+		return result.ok ? ok({
+			id: result.data.id,
+			payload: result.data.payload
+		}) : result;
+	};
+	return {
+		async receive(request) {
+			const instance = new URL(request.url).pathname;
+			if (request.method !== "POST") return new Response(null, {
+				status: 405,
+				headers: { allow: "POST" }
+			});
+			const message = await verified(request);
+			if (!message.ok) return problemResponse(message.error, { instance });
+			const headers = Object.fromEntries((options.keepHeaders ?? []).flatMap((name) => {
+				const value = request.headers.get(name);
+				return value === null ? [] : [[name.toLowerCase(), value]];
+			}));
+			const stored = await run(() => sql.queryRaw("select * from better_supabase.receive_webhook($1, $2, $3, $4, $5)", [
+				options.source,
+				message.data.id,
+				(options.typeOf ?? defaultType)(message.data.payload),
+				JSON.stringify(message.data.payload),
+				JSON.stringify(headers)
+			]));
+			if (!stored.ok) return problemResponse(stored.error, { instance });
+			const row = stored.data[0];
+			return Response.json({
+				id: Number(row.id),
+				duplicate: row.duplicate
+			}, { status: row.duplicate ? 200 : 202 });
+		},
+		async process(handler, processOptions = {}) {
+			let succeeded = 0;
+			let failed = 0;
+			for (;;) {
+				const rows = await sql.queryRaw("select * from better_supabase.claim_webhooks($1, $2, $3, $4::interval)", [
+					options.source,
+					worker,
+					processOptions.batch ?? 10,
+					seconds(processOptions.lease ?? 300)
+				]);
+				if (rows.length === 0) return {
+					succeeded,
+					failed
+				};
+				for (const row of rows) {
+					const message = {
+						id: Number(row.id),
+						source: row.source,
+						messageId: row.message_id,
+						type: row.event_type,
+						payload: row.payload,
+						headers: row.headers,
+						attempts: row.attempts,
+						receivedAt: toInstant(row.received_at)
+					};
+					try {
+						const outcome = await handler(message);
+						if (typeof outcome === "object" && outcome !== null && "ok" in outcome && outcome.ok === false) throw new Error(errorText(outcome.error ?? "The handler failed"));
+						await sql.queryRaw("select better_supabase.complete_webhook($1, $2)", [message.id, worker]);
+						succeeded += 1;
+					} catch (cause) {
+						await sql.queryRaw("select better_supabase.fail_webhook($1, $2, $3)", [
+							message.id,
+							worker,
+							errorText(cause)
+						]);
+						failed += 1;
+					}
+				}
+			}
+		}
+	};
+}
+/** The Stripe event sent when a customer's active entitlements change. */
+const ENTITLEMENTS_UPDATED = "entitlements.active_entitlement_summary.updated";
+function stripeCustomerOf(payload) {
+	if (typeof payload !== "object" || payload === null) return void 0;
+	const customer = (payload.data?.object)?.customer;
+	if (typeof customer === "string") return customer;
+	const id = customer?.id;
+	return typeof id === "string" ? id : void 0;
+}
+/**
+* Users whose `memberships` claim carries the entitlements of the Stripe
+* customer in an `entitlements.active_entitlement_summary.updated` event, so
+* a job can invalidate their sessions. Empty for other payloads.
+*/
+function entitlementMembers(sql, payload) {
+	const customer = stripeCustomerOf(payload);
+	if (customer === void 0) return AsyncResult.ok([]);
+	return run(() => sql.queryRaw("select user_id from better_supabase.entitlement_members($1) as user_id", [customer])).map((rows) => rows.map((row) => row.user_id));
+}
+/**
+* Deletes audit entries past their retention and returns how many. Without
+* `retention` it is one `purge_audit_log` call (which honours an
+* `audit_retention` SQL hook); with it, each tenant is purged with its own
+* interval. Run it from a schedule until it returns 0.
+*/
+function purgeAuditLog(sql, options = {}) {
+	const olderThan = seconds(options.olderThan ?? "1 year");
+	const batch = options.batch ?? 1e4;
+	const purge = async (params, call) => {
+		const [row] = await sql.queryRaw(`select better_supabase.purge_audit_log(${call}) as n`, params);
+		return Number(row?.n ?? 0);
+	};
+	const { retention } = options;
+	if (!retention) return run(() => purge([olderThan, batch], "$1::interval, $2"));
+	return run(async () => {
+		const tenants = await sql.queryRaw("select tenant::text from better_supabase.audit_events_tenants($1::interval) as tenant", ["1 day"]);
+		let purged = 0;
+		for (const { tenant } of tenants) {
+			const days = await retention(tenant);
+			const keep = days === void 0 ? olderThan : `${days} days`;
+			purged += await purge([
+				keep,
+				batch,
+				tenant
+			], "$1::interval, $2, $3, true");
+		}
+		return purged;
+	});
+}
+//#endregion
+//#region src/jobs/outbox.ts
+function isOutboxRow(value) {
+	return typeof value === "object" && value !== null && "position" in value && "type" in value && "created_at" in value;
+}
+function toEvent(row) {
+	return {
+		position: row.position,
+		id: String(row.id),
+		type: row.type,
+		payload: row.payload,
+		source: row.source ?? null,
+		subject: row.subject ?? null,
+		tenant: row.tenant === void 0 || row.tenant === null ? null : String(row.tenant),
+		key: row.key ?? null,
+		actorId: row.actor_id ?? null,
+		createdAt: toInstant(row.created_at)
+	};
+}
+function toEvents(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter(isOutboxRow).map(toEvent);
+}
+/**
+* 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.
+*/
+function outboxCloudEvent(event, options) {
+	return {
+		specversion: "1.0",
+		id: event.id,
+		source: options.source,
+		type: `${options.typePrefix ?? "dev.better-supabase"}.${event.type}`,
+		...event.subject ? { subject: event.subject } : {},
+		time: event.createdAt.toString(),
+		datacontenttype: "application/json",
+		data: event.payload,
+		...event.tenant ? { partitionkey: event.tenant } : {},
+		...event.source ? { producer: event.source } : {}
+	};
+}
+function createOutbox(sql, options) {
+	const schema = sqlIdent(options.schema ?? "better_supabase");
+	const call = async (fn, args) => {
+		const params = args.map((_, index) => `$${String(index + 1)}`).join(", ");
+		const [row] = await sql.queryRaw(`select ${schema}.${sqlIdent(fn)}(${params}) as value`, args);
+		return row?.value ?? null;
+	};
+	async function relay(consumer, sink, relayOptions = {}, deadline) {
+		const owner = relayOptions.owner ?? workerId();
+		const batch = relayOptions.batch ?? 100;
+		const lease = relayOptions.lease ?? "1 minute";
+		const until = deadline ?? (relayOptions.budgetMs === void 0 ? Number.POSITIVE_INFINITY : Date.now() + relayOptions.budgetMs);
+		let delivered = 0;
+		while (Date.now() < until) {
+			let events;
+			try {
+				events = toEvents(await call("outbox_claim", [
+					consumer,
+					owner,
+					batch,
+					lease
+				]));
+			} catch (cause) {
+				return {
+					delivered,
+					error: asDbError(cause)
+				};
+			}
+			const last = events.at(-1);
+			if (last === void 0) {
+				await call("outbox_ack", [
+					consumer,
+					owner,
+					null
+				]).catch(() => null);
+				break;
+			}
+			try {
+				await sink.send(events.map((event) => outboxCloudEvent(event, options)));
+			} catch (cause) {
+				await call("outbox_ack", [
+					consumer,
+					owner,
+					null
+				]).catch(() => null);
+				return {
+					delivered,
+					error: toDbError(cause)
+				};
+			}
+			try {
+				await call("outbox_ack", [
+					consumer,
+					owner,
+					last.position
+				]);
+			} catch (cause) {
+				return {
+					delivered,
+					error: asDbError(cause)
+				};
+			}
+			delivered += events.length;
+			if (events.length < batch) break;
+		}
+		return { delivered };
+	}
+	return {
+		emit: (type, payload = {}, emitOptions = {}) => run(async () => String(await call("emit_event", [
+			type,
+			JSON.stringify(payload),
+			emitOptions.subject ?? null,
+			emitOptions.tenant ?? null,
+			emitOptions.key ?? null,
+			emitOptions.source ?? null
+		]))),
+		register: (consumer, registerOptions = {}) => run(async () => Number(await call("outbox_register", [
+			consumer,
+			registerOptions.types ?? null,
+			registerOptions.fromStart ?? false
+		]))),
+		unregister: (consumer) => run(async () => await call("outbox_unregister", [consumer]) === true),
+		relay: (consumer, sink, relayOptions) => relay(consumer, sink, relayOptions),
+		relayRoute(routeOptions) {
+			const secret = routeOptions.secret;
+			if (!secret) throw new TypeError("relayRoute needs a secret, such as process.env.CRON_SECRET");
+			return async (request) => {
+				const instance = new URL(request.url).pathname;
+				if (request.method !== "GET" && request.method !== "POST") return new Response(null, {
+					status: 405,
+					headers: { allow: "GET, POST" }
+				});
+				if (!verifySharedSecret(request, secret)) return problemResponse(dbError("unauthorized", "The relay route needs its bearer secret"), { instance });
+				const deadline = Date.now() + (routeOptions.budgetMs ?? 5e4);
+				const results = {};
+				for (const [consumer, sink] of Object.entries(routeOptions.consumers)) {
+					if (Date.now() >= deadline) break;
+					const result = await relay(consumer, sink, routeOptions, deadline);
+					if (result.error) routeOptions.onError?.(result.error, consumer);
+					results[consumer] = result;
+				}
+				const result = {
+					consumers: results,
+					budgetExhausted: Date.now() >= deadline
+				};
+				return Response.json(result);
+			};
+		},
+		history: (filter = {}) => run(async () => toEvents(await call("outbox_history", [
+			filter.subject ?? null,
+			filter.type ?? null,
+			filter.after ?? 0,
+			filter.limit ?? 100
+		]))),
+		purge: (olderThan, batch) => run(async () => Number(await call("purge_outbox", [olderThan ?? null, batch ?? null])))
+	};
+}
+//#endregion
+//#region src/jobs/queue.ts
+/**
+* The `jobs` SQL kit module over a service SQL connection. The same
+* functions back both `kits.jobs.options.backend` values (pgmq and table)
+* and both schedulers.
+*/
+function sqlQueueBackend(sql) {
 	return {
+		apiVersion: 1,
 		name: "sql",
+		leases: true,
 		async send(queue, payload, delay, maxAttempts, dedupeKey) {
 			const [row] = await sql.queryRaw("select better_supabase.enqueue_job($1, $2, $3, $4, $5) as id", [
 				queue,
@@ -81,17 +646,41 @@ function sqlTransport(sql) {
 			]);
 			return row?.extended ?? false;
 		},
-		async schedule(name, cron, queue, payload) {
-			await sql.queryRaw("select better_supabase.schedule_job($1, $2, $3, $4)", [
+		async replay(queue, id) {
+			const [row] = await sql.queryRaw("select better_supabase.replay_dead_job($1, $2) as id", [queue, id]);
+			return row?.id === null || row?.id === void 0 ? null : Number(row.id);
+		},
+		async schedule(name, cron, queue, payload, timeZone, nextRun) {
+			await sql.queryRaw("select better_supabase.schedule_job($1, $2, $3, $4, $5, $6)", [
 				name,
 				cron,
 				queue,
-				JSON.stringify(payload ?? {})
+				JSON.stringify(payload ?? {}),
+				timeZone,
+				nextRun.toString()
 			]);
 		},
 		async unschedule(name) {
 			const [row] = await sql.queryRaw("select better_supabase.unschedule_job($1) as done", [name]);
 			return row?.done ?? false;
+		},
+		async dueSchedules(lease, batch) {
+			return (await sql.queryRaw("select * from better_supabase.claim_due_schedules($1, $2)", [lease, batch])).map((row) => ({
+				name: row.job_name,
+				cron: row.schedule,
+				timeZone: row.timezone,
+				queue: row.queue,
+				payload: row.payload,
+				nextRun: toInstant(row.next_run)
+			}));
+		},
+		async advanceSchedule(name, ran, next) {
+			const [row] = await sql.queryRaw("select better_supabase.advance_schedule($1, $2, $3) as advanced", [
+				name,
+				ran.toString(),
+				next.toString()
+			]);
+			return row?.advanced ?? false;
 		}
 	};
 }
@@ -99,11 +688,11 @@ function sqlOnly(feature) {
 	throw new DbException(dbError("invalid_request", `${feature} needs a SQL connection; pgmq_public (PostgREST) does not support it`));
 }
 /**
-* Supabase's `pgmq_public` RPCs (Integrations → Queues → "Expose Queues via
-* PostgREST"). No lease check on complete, no retry delay and no
-* deduplication: a failed job simply reappears when its lease ends.
+* Supabase's `pgmq_public` RPCs (Integrations, Queues, "Expose Queues via
+* PostgREST"). No lease check on complete, no retry delay, no deduplication
+* and no schedules: a failed job reappears when its lease ends.
 */
-function postgrestTransport(client) {
+function pgmqPublicBackend(client) {
 	const call = async (fn, args) => {
 		const { data, error } = await client.schema("pgmq_public").rpc(fn, args);
 		if (error) {
@@ -117,7 +706,9 @@ function postgrestTransport(client) {
 		message_id: job.id
 	});
 	return {
-		name: "postgrest",
+		apiVersion: 1,
+		name: "pgmq_public",
+		leases: false,
 		async send(queue, payload, delay, maxAttempts, dedupeKey) {
 			if (dedupeKey !== void 0) sqlOnly("dedupeKey");
 			const ids = await call("send", {
@@ -131,11 +722,18 @@ function postgrestTransport(client) {
 			return Number(ids[0]);
 		},
 		async read(queue, lease, batch) {
-			return (await call("read", {
+			const rows = await call("read", {
 				queue_name: queue,
 				sleep_seconds: lease,
 				n: batch
-			})).map((row) => ({
+			});
+			const live = [];
+			for (const row of rows) if (row.read_ct > (row.message?.max_attempts ?? 5)) await call("archive", {
+				queue_name: queue,
+				message_id: row.msg_id
+			});
+			else live.push(row);
+			return live.map((row) => ({
 				id: row.msg_id,
 				attempts: row.read_ct,
 				enqueued_at: row.enqueued_at,
@@ -154,14 +752,55 @@ function postgrestTransport(client) {
 		unschedule: () => sqlOnly("unschedule")
 	};
 }
-/** pgmq and the inbox return `timestamptz` as text over RPC and as `Date` from `pg`. */
-const toInstant = (value) => value instanceof Date ? temporal().Instant.fromEpochMilliseconds(value.getTime()) : temporal().Instant.from(value);
+/** Marks a payload that carries a job context; pgmq stores it as the payload. */
+const ENVELOPE = "$bs";
+/** Schedule times are stored to the millisecond, the precision `Date` reads back. */
+const millis = (instant) => instant.round({
+	smallestUnit: "millisecond",
+	roundingMode: "floor"
+});
+function withContext(payload, context) {
+	if (!context) return payload;
+	const tenant = tenantOf(context) ?? tenantClaimPaths().map((path) => claimAt(context.claims, path)).find((id) => id !== void 0);
+	const recorded = {
+		...context.actor ? { actor: context.actor } : {},
+		...tenant === void 0 ? {} : { tenant }
+	};
+	if (!recorded.actor && recorded.tenant === void 0) return payload;
+	return {
+		[ENVELOPE]: 1,
+		context: recorded,
+		payload
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isActor(value) {
+	return isRecord(value) && typeof value["id"] === "string" && (value["kind"] === "user" || value["kind"] === "service" || value["kind"] === "anon");
+}
+function unwrap(stored) {
+	if (!isRecord(stored) || stored[ENVELOPE] !== 1 || !Object.hasOwn(stored, "payload")) return {
+		payload: stored,
+		context: {}
+	};
+	const { actor, tenant } = isRecord(stored["context"]) ? stored["context"] : {};
+	return {
+		payload: stored["payload"],
+		context: {
+			...isActor(actor) ? { actor } : {},
+			...typeof tenant === "string" && tenant.length > 0 ? { tenant } : {}
+		}
+	};
+}
 function toJob(queue, row) {
 	const message = row.message ?? {};
+	const { payload, context } = unwrap(message.payload);
 	return {
 		id: Number(row.id),
 		queue,
-		payload: message.payload,
+		payload,
+		context,
 		attempts: row.attempts,
 		maxAttempts: message.max_attempts ?? 5,
 		enqueuedAt: toInstant(row.enqueued_at),
@@ -169,26 +808,30 @@ function toJob(queue, row) {
 		lastError: message.last_error ?? null
 	};
 }
-function errorText(error) {
-	if (error instanceof Error) return error.message;
-	if (typeof error === "object" && error !== null && "message" in error) return String(error.message);
-	return String(error);
-}
 const QUEUE_NAME = /^[a-z_][a-z0-9_]{0,46}$/;
+function isBackend(source) {
+	return "apiVersion" in source;
+}
 function isSqlClient(source) {
 	return typeof source.queryRaw === "function";
 }
+function backendOf(source) {
+	if (isBackend(source)) return source;
+	return isSqlClient(source) ? sqlQueueBackend(source) : pgmqPublicBackend(source);
+}
+const later = (a, b) => temporal().Instant.compare(a, b) >= 0 ? a : b;
 /**
 * Typed jobs on Supabase Queues (pgmq), over the `jobs` SQL kit module.
 *
 * Pass a service SQL connection (`postgres.admin`, `ctx.sql`) for the full
-* feature set, or a service-role Supabase client to go through the
-* `pgmq_public` RPCs where no direct connection exists (edge functions).
-* Queue names are lowercase letters, digits and underscores.
+* feature set, a service-role Supabase client to go through the
+* `pgmq_public` RPCs where no direct connection exists (edge functions), or
+* any `QueueBackend`. Queue names are lowercase letters, digits and
+* underscores.
 */
 function createJobs(source, queues) {
 	for (const name of Object.keys(queues)) if (!QUEUE_NAME.test(name)) throw new TypeError(`Queue "${name}": pgmq queue names are lowercase letters, digits and underscores (at most 47)`);
-	const transport = isSqlClient(source) ? sqlTransport(source) : postgrestTransport(source);
+	const transport = backendOf(source);
 	const schemaOf = (queue) => {
 		const schema = queues[queue];
 		if (!schema) throw new TypeError(`Unknown queue "${queue}". Queues: ${Object.keys(queues).join(", ")}`);
@@ -204,7 +847,7 @@ function createJobs(source, queues) {
 	* Extends the lease of every job in `held` at half the lease, so jobs
 	* waiting their turn in a claimed batch don't expire before they run.
 	*/
-	const heartbeat = (held, lease) => transport.name === "sql" ? setInterval(() => {
+	const heartbeat = (held, lease) => transport.leases ? setInterval(() => {
 		for (const job of held) run(() => transport.extend(job, lease));
 	}, Math.max(1e3, lease * 1e3 / 2)) : void 0;
 	const handle = async (job, handler, workOptions) => {
@@ -216,9 +859,11 @@ function createJobs(source, queues) {
 				workOptions.onError?.(payload.error, job);
 				return false;
 			}
+			const context = workOptions.allTenants && job.context.tenant === void 0 ? allTenantsContext(job.context) : job.context;
 			const outcome = await handler(payload.data, {
 				...job,
-				payload: payload.data
+				payload: payload.data,
+				context
 			}, controller.signal);
 			if (typeof outcome === "object" && outcome !== null && "ok" in outcome && outcome.ok === false && "error" in outcome) throw outcome.error;
 			await complete(job);
@@ -230,7 +875,7 @@ function createJobs(source, queues) {
 			return false;
 		}
 	};
-	const loop = async (queue, handler, workOptions, forever) => {
+	const loop = async (queue, handler, workOptions, forever, deadline) => {
 		const concurrency = Math.max(1, workOptions.concurrency ?? 1);
 		const lease = workOptions.lease ?? 300;
 		const firstWait = workOptions.pollInterval ?? 1e3;
@@ -240,6 +885,7 @@ function createJobs(source, queues) {
 		const lanes = Array.from({ length: concurrency }, async () => {
 			let wait = firstWait;
 			while (!workOptions.signal?.aborted) {
+				if (deadline !== void 0 && Date.now() >= deadline) return;
 				const claimed = await claim(queue, {
 					...workOptions,
 					batch: workOptions.batch ?? 1
@@ -271,230 +917,91 @@ function createJobs(source, queues) {
 			failed
 		};
 	};
+	const runSchedules = async (scheduleOptions) => {
+		if (!transport.dueSchedules || !transport.advanceSchedule) return 0;
+		const due = await transport.dueSchedules(scheduleOptions.lease ?? 60, scheduleOptions.batch ?? 100);
+		let ran = 0;
+		for (const schedule of due) {
+			await transport.send(schedule.queue, schedule.payload, 0, 5, `schedule:${schedule.name}:${schedule.nextRun.toString()}`);
+			const next = millis(nextCronRun(schedule.cron, schedule.timeZone, later(nowInstant(), schedule.nextRun)));
+			if (await transport.advanceSchedule(schedule.name, schedule.nextRun, next)) ran += 1;
+		}
+		return ran;
+	};
 	return {
 		enqueue(queue, payload, enqueueOptions = {}) {
 			return AsyncResult.from(async () => {
 				const valid = await validate(schemaOf(queue), payload, "payload");
 				if (!valid.ok) return valid;
 				const delay = enqueueOptions.delay ?? (enqueueOptions.runAt ? Math.max(0, Math.ceil((enqueueOptions.runAt.epochMilliseconds - nowInstant().epochMilliseconds) / 1e3)) : 0);
-				return run(() => transport.send(queue, valid.data, delay, enqueueOptions.maxAttempts ?? 5, enqueueOptions.dedupeKey));
+				return run(() => transport.send(queue, withContext(valid.data, enqueueOptions.context), delay, enqueueOptions.maxAttempts ?? 5, enqueueOptions.dedupeKey));
 			});
 		},
 		claim,
 		complete,
 		fail,
 		extend: (job, lease) => run(() => transport.extend(job, lease)),
-		schedule(name, cron, queue, payload) {
+		replay: (queue, id) => run(() => {
+			if (!transport.replay) sqlOnly("replay");
+			return transport.replay(queue, id);
+		}),
+		schedule(name, cron, queue, payload, scheduleOptions = {}) {
 			return AsyncResult.from(async () => {
 				const valid = await validate(schemaOf(queue), payload, "payload");
 				if (!valid.ok) return valid;
-				return run(() => transport.schedule(name, cron, queue, valid.data));
+				const stored = withContext(valid.data, scheduleOptions.context);
+				const timeZone = scheduleOptions.timeZone ?? "UTC";
+				return run(() => {
+					const nextRun = millis(nextCronRun(cron, timeZone, nowInstant()));
+					return transport.schedule(name, cron, queue, stored, timeZone, nextRun);
+				});
 			});
 		},
 		unschedule: (name) => run(() => transport.unschedule(name)),
-		drain: (queue, handler, drainOptions = {}) => loop(queue, handler, drainOptions, false),
-		work: (queue, handler, workOptions = {}) => loop(queue, handler, workOptions, true)
-	};
-}
-async function sha256(text) {
-	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
-	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-/** HTTP idempotency keys (IETF `Idempotency-Key` header) over the `idempotency` SQL kit module. */
-function createIdempotency(sql, options = {}) {
-	const headerName = options.header ?? "idempotency-key";
-	const ttl = seconds(options.ttl ?? "24 hours");
-	const lock = seconds(options.lock ?? "1 minute");
-	const begin = (key, fingerprint, scope = "") => run(async () => {
-		const [row] = await sql.queryRaw("select * from better_supabase.begin_idempotent($1, $2, $3, $4::interval, $5::interval)", [
-			scope,
-			key,
-			fingerprint,
-			ttl,
-			lock
-		]);
-		return {
-			state: row.state,
-			status: row.status_code,
-			body: row.response
-		};
-	});
-	const complete = (key, status, body, scope = "") => run(async () => {
-		await sql.queryRaw("select better_supabase.complete_idempotent($1, $2, $3, $4)", [
-			scope,
-			key,
-			status,
-			JSON.stringify(body)
-		]);
-	});
-	const release = (key, scope = "") => run(async () => {
-		await sql.queryRaw("select better_supabase.release_idempotent($1, $2)", [scope, key]);
-	});
-	return {
-		begin,
-		complete,
-		release,
-		async handle(request, handler) {
-			const key = request.headers.get(headerName);
-			const instance = new URL(request.url).pathname;
-			if (!key) return options.required ? problemResponse(dbError("invalid_request", `The ${headerName} header is required`, { code: "IDEMPOTENCY_KEY_MISSING" }), { instance }) : handler(request);
-			if (key.length > 255) return problemResponse(dbError("invalid_request", `The ${headerName} header is too long`, { code: "IDEMPOTENCY_KEY_INVALID" }), { instance });
-			const scope = typeof options.scope === "function" ? options.scope(request) : options.scope ?? "";
-			const body = await request.clone().text();
-			const fingerprint = await sha256(`${request.method} ${instance}\n${body}`);
-			const started = await begin(key, fingerprint, scope);
-			if (!started.ok) return problemResponse(started.error, { instance });
-			const { state } = started.data;
-			switch (state) {
-				case "replay": {
-					const stored = started.data.body;
-					return new Response(stored.body, {
-						status: started.data.status ?? 200,
-						headers: {
-							...stored.contentType ? { "content-type": stored.contentType } : {},
-							"idempotency-replayed": "true"
-						}
-					});
-				}
-				case "running": return problemResponse(dbError("conflict", "A request with this idempotency key is still running", { code: "IDEMPOTENCY_KEY_IN_USE" }), {
-					instance,
-					headers: { "retry-after": "1" }
+		runSchedules: (scheduleOptions = {}) => run(() => runSchedules(scheduleOptions)),
+		drain: (queue, handler, drainOptions = {}) => loop(queue, handler, drainOptions, false, drainOptions.budgetMs === void 0 ? void 0 : Date.now() + drainOptions.budgetMs),
+		work: (queue, handler, workOptions = {}) => loop(queue, handler, workOptions, true),
+		drainRoute(routeOptions) {
+			const secret = routeOptions.secret;
+			if (!secret) throw new TypeError("drainRoute needs a secret, such as process.env.CRON_SECRET");
+			for (const queue of Object.keys(routeOptions.handlers)) schemaOf(queue);
+			return async (request) => {
+				const instance = new URL(request.url).pathname;
+				if (request.method !== "GET" && request.method !== "POST") return new Response(null, {
+					status: 405,
+					headers: { allow: "GET, POST" }
 				});
-				case "mismatch": return problemResponse(dbError("validation", "This idempotency key was used for a different request", {
-					code: "IDEMPOTENCY_KEY_REUSED",
-					issues: [{
-						message: "Use a new key for a new request",
-						path: [headerName]
-					}]
-				}), { instance });
-				case "started": break;
-				default: throw new TypeError(`Unknown idempotency state ${String(state)}`);
-			}
-			let response;
-			try {
-				response = await handler(request);
-			} catch (cause) {
-				await release(key, scope);
-				throw cause;
-			}
-			if (response.status >= 500) {
-				await release(key, scope);
-				return response;
-			}
-			const stored = {
-				body: await response.clone().text(),
-				contentType: response.headers.get("content-type")
-			};
-			await complete(key, response.status, stored, scope);
-			return response;
-		}
-	};
-}
-function defaultType(payload) {
-	if (typeof payload !== "object" || payload === null) return null;
-	const type = payload.type;
-	return typeof type === "string" ? type : null;
-}
-/** Store-then-process webhooks: acknowledge fast, process with retries, never twice. */
-function createInbox(sql, options) {
-	const worker = options.worker ?? workerId();
-	if (!options.secrets && !options.verify) throw new TypeError("createInbox needs `secrets` (Standard Webhooks) or `verify`");
-	const verified = async (request) => {
-		if (options.verify) return options.verify(request, await request.clone().text());
-		const result = await verifyWebhook(request, options.secrets);
-		return result.ok ? ok({
-			id: result.data.id,
-			payload: result.data.payload
-		}) : result;
-	};
-	return {
-		async receive(request) {
-			const instance = new URL(request.url).pathname;
-			if (request.method !== "POST") return new Response(null, {
-				status: 405,
-				headers: { allow: "POST" }
-			});
-			const message = await verified(request);
-			if (!message.ok) return problemResponse(message.error, { instance });
-			const headers = Object.fromEntries((options.keepHeaders ?? []).flatMap((name) => {
-				const value = request.headers.get(name);
-				return value === null ? [] : [[name.toLowerCase(), value]];
-			}));
-			const stored = await run(() => sql.queryRaw("select * from better_supabase.receive_webhook($1, $2, $3, $4, $5)", [
-				options.source,
-				message.data.id,
-				(options.typeOf ?? defaultType)(message.data.payload),
-				JSON.stringify(message.data.payload),
-				JSON.stringify(headers)
-			]));
-			if (!stored.ok) return problemResponse(stored.error, { instance });
-			const row = stored.data[0];
-			return Response.json({
-				id: Number(row.id),
-				duplicate: row.duplicate
-			}, { status: row.duplicate ? 200 : 202 });
-		},
-		async process(handler, processOptions = {}) {
-			let succeeded = 0;
-			let failed = 0;
-			for (;;) {
-				const rows = await sql.queryRaw("select * from better_supabase.claim_webhooks($1, $2, $3, $4::interval)", [
-					options.source,
-					worker,
-					processOptions.batch ?? 10,
-					seconds(processOptions.lease ?? 300)
-				]);
-				if (rows.length === 0) return {
-					succeeded,
-					failed
-				};
-				for (const row of rows) {
-					const message = {
-						id: Number(row.id),
-						source: row.source,
-						messageId: row.message_id,
-						type: row.event_type,
-						payload: row.payload,
-						headers: row.headers,
-						attempts: row.attempts,
-						receivedAt: toInstant(row.received_at)
-					};
+				if (!verifySharedSecret(request, secret)) return problemResponse(dbError("unauthorized", "The drain route needs its bearer secret"), { instance });
+				const deadline = Date.now() + (routeOptions.budgetMs ?? 5e4);
+				let scheduled = 0;
+				if (routeOptions.schedules ?? true) {
+					const ran = await run(() => runSchedules({}));
+					if (ran.ok) scheduled = ran.data;
+					else routeOptions.onError?.(ran.error);
+				}
+				const results = {};
+				for (const [queue, handler] of Object.entries(routeOptions.handlers)) {
+					if (handler === void 0) continue;
+					if (Date.now() >= deadline) break;
 					try {
-						const outcome = await handler(message);
-						if (typeof outcome === "object" && outcome !== null && "ok" in outcome && outcome.ok === false) throw new Error(errorText(outcome.error ?? "The handler failed"));
-						await sql.queryRaw("select better_supabase.complete_webhook($1, $2)", [message.id, worker]);
-						succeeded += 1;
+						results[queue] = await loop(queue, handler, routeOptions, false, deadline);
 					} catch (cause) {
-						await sql.queryRaw("select better_supabase.fail_webhook($1, $2, $3)", [
-							message.id,
-							worker,
-							errorText(cause)
-						]);
-						failed += 1;
+						routeOptions.onError?.(toDbError(cause));
+						results[queue] = {
+							succeeded: 0,
+							failed: 0
+						};
 					}
 				}
-			}
+				const result = {
+					schedules: scheduled,
+					queues: results,
+					budgetExhausted: Date.now() >= deadline
+				};
+				return Response.json(result);
+			};
 		}
 	};
 }
-/** The Stripe event sent when a customer's active entitlements change. */
-const ENTITLEMENTS_UPDATED = "entitlements.active_entitlement_summary.updated";
-function stripeCustomerOf(payload) {
-	if (typeof payload !== "object" || payload === null) return void 0;
-	const customer = (payload.data?.object)?.customer;
-	if (typeof customer === "string") return customer;
-	const id = customer?.id;
-	return typeof id === "string" ? id : void 0;
-}
-/**
-* Users whose `memberships` claim carries the entitlements of the Stripe
-* customer in an `entitlements.active_entitlement_summary.updated` event, so
-* a job can invalidate their sessions. Empty for other payloads.
-*/
-function entitlementMembers(sql, payload) {
-	const customer = stripeCustomerOf(payload);
-	if (customer === void 0) return AsyncResult.ok([]);
-	return run(() => sql.queryRaw("select user_id from better_supabase.entitlement_members($1) as user_id", [customer])).map((rows) => rows.map((row) => row.user_id));
-}
 //#endregion
-export { ENTITLEMENTS_UPDATED, createIdempotency, createInbox, createJobs, entitlementMembers };
+export { ENTITLEMENTS_UPDATED, assertCron, createIdempotency, createInbox, createJobs, createOutbox, entitlementMembers, nextCronRun, outboxCloudEvent, pgmqPublicBackend, purgeAuditLog, sqlQueueBackend };