better-supabase 0.3.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-Bl3rkOzo.js";
-import { n as nowInstant } from "../temporal-BwshQk0W.js";
-import { t as temporal } from "../temporal-required-CMxeSVPo.js";
-import { i as ok, n as err, o as toDbError, t as AsyncResult } from "../result-DWXatkd6.js";
-import { t as validate } from "../standard-FUi3Z3-7.js";
-import { a as problemResponse } from "../problem-CGt1ADix.js";
-import { t as fromPgError } from "../executor-C57jx2pn.js";
-import { c as verifyWebhook } from "../webhooks-CAIFQSTM.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,254 +185,27 @@ const sleep = (ms, signal) => new Promise((resolve) => {
 	}
 	signal?.addEventListener("abort", done, { once: true });
 });
-function sqlTransport(sql) {
-	return {
-		name: "sql",
-		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,
-				JSON.stringify(payload ?? {}),
-				delay,
-				maxAttempts,
-				dedupeKey ?? null
-			]);
-			return Number(row.id);
-		},
-		read: (queue, lease, batch) => sql.queryRaw("select * from better_supabase.claim_jobs($1, $2, $3)", [
-			queue,
-			lease,
-			batch
-		]),
-		async complete(job) {
-			const [row] = await sql.queryRaw("select better_supabase.complete_job($1, $2, $3) as done", [
-				job.queue,
-				job.id,
-				job.attempts
-			]);
-			return row?.done ?? false;
-		},
-		async fail(job, error, retryIn) {
-			const [row] = await sql.queryRaw("select better_supabase.fail_job($1, $2, $3, $4, $5) as status", [
-				job.queue,
-				job.id,
-				job.attempts,
-				error,
-				retryIn ?? null
-			]);
-			return row?.status ?? null;
-		},
-		async extend(job, lease) {
-			const [row] = await sql.queryRaw("select better_supabase.extend_job_lease($1, $2, $3, $4) as extended", [
-				job.queue,
-				job.id,
-				job.attempts,
-				lease
-			]);
-			return row?.extended ?? false;
-		},
-		async schedule(name, cron, queue, payload) {
-			await sql.queryRaw("select better_supabase.schedule_job($1, $2, $3, $4)", [
-				name,
-				cron,
-				queue,
-				JSON.stringify(payload ?? {})
-			]);
-		},
-		async unschedule(name) {
-			const [row] = await sql.queryRaw("select better_supabase.unschedule_job($1) as done", [name]);
-			return row?.done ?? false;
-		}
-	};
-}
-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.
-*/
-function postgrestTransport(client) {
-	const call = async (fn, args) => {
-		const { data, error } = await client.schema("pgmq_public").rpc(fn, args);
-		if (error) {
-			const message = typeof error === "object" && "message" in error ? String(error.message) : String(error);
-			throw new Error(`pgmq_public.${fn}: ${message}`, { cause: error });
-		}
-		return data;
-	};
-	const archive = (job) => call("archive", {
-		queue_name: job.queue,
-		message_id: job.id
-	});
-	return {
-		name: "postgrest",
-		async send(queue, payload, delay, maxAttempts, dedupeKey) {
-			if (dedupeKey !== void 0) sqlOnly("dedupeKey");
-			const ids = await call("send", {
-				queue_name: queue,
-				message: {
-					payload: payload ?? {},
-					max_attempts: maxAttempts
-				},
-				sleep_seconds: delay
-			});
-			return Number(ids[0]);
-		},
-		async read(queue, lease, batch) {
-			return (await call("read", {
-				queue_name: queue,
-				sleep_seconds: lease,
-				n: batch
-			})).map((row) => ({
-				id: row.msg_id,
-				attempts: row.read_ct,
-				enqueued_at: row.enqueued_at,
-				visible_until: row.vt,
-				message: row.message
-			}));
-		},
-		complete: archive,
-		async fail(job) {
-			if (job.attempts < job.maxAttempts) return "queued";
-			await archive(job);
-			return "dead";
-		},
-		extend: () => Promise.resolve(false),
-		schedule: () => sqlOnly("schedule"),
-		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);
-function toJob(queue, row) {
-	const message = row.message ?? {};
-	return {
-		id: Number(row.id),
-		queue,
-		payload: message.payload,
-		attempts: row.attempts,
-		maxAttempts: message.max_attempts ?? 5,
-		enqueuedAt: toInstant(row.enqueued_at),
-		visibleUntil: toInstant(row.visible_until),
-		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 isSqlClient(source) {
-	return typeof source.queryRaw === "function";
-}
-/**
-* 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.
-*/
-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 schemaOf = (queue) => {
-		const schema = queues[queue];
-		if (!schema) throw new TypeError(`Unknown queue "${queue}". Queues: ${Object.keys(queues).join(", ")}`);
-		return schema;
-	};
-	const complete = (job) => run(() => transport.complete(job));
-	const fail = (job, error, failOptions = {}) => run(() => transport.fail(job, errorText(error), failOptions.retryIn));
-	const claim = (queue, claimOptions = {}) => run(async () => {
-		schemaOf(queue);
-		return (await transport.read(queue, claimOptions.lease ?? 300, claimOptions.batch ?? 1)).map((row) => toJob(queue, row));
-	});
-	const handle = async (job, handler, workOptions) => {
-		const controller = new AbortController();
-		const lease = workOptions.lease ?? 300;
-		const heartbeat = transport.name === "sql" ? setInterval(() => {
-			run(() => transport.extend(job, lease));
-		}, Math.max(1e3, lease * 1e3 / 2)) : void 0;
-		try {
-			const payload = await validate(schemaOf(job.queue), job.payload, "payload");
-			if (!payload.ok) {
-				await fail(job, payload.error.message);
-				workOptions.onError?.(payload.error, job);
-				return false;
-			}
-			const outcome = await handler(payload.data, {
-				...job,
-				payload: payload.data
-			}, controller.signal);
-			if (typeof outcome === "object" && outcome !== null && "ok" in outcome && outcome.ok === false && "error" in outcome) throw outcome.error;
-			await complete(job);
-			return true;
-		} catch (cause) {
-			controller.abort();
-			await fail(job, cause);
-			workOptions.onError?.(typeof cause === "object" && cause !== null && "kind" in cause ? cause : toDbError(cause), job);
-			return false;
-		} finally {
-			clearInterval(heartbeat);
-		}
-	};
-	const loop = async (queue, handler, workOptions, forever) => {
-		const concurrency = Math.max(1, workOptions.concurrency ?? 1);
-		let succeeded = 0;
-		let failed = 0;
-		const lanes = Array.from({ length: concurrency }, async () => {
-			while (!workOptions.signal?.aborted) {
-				const claimed = await claim(queue, {
-					...workOptions,
-					batch: workOptions.batch ?? 1
-				});
-				if (!claimed.ok) throw new TypeError(claimed.error.message, { cause: claimed.error });
-				if (claimed.data.length === 0) {
-					if (!forever) return;
-					await sleep(workOptions.pollInterval ?? 1e3, workOptions.signal);
-					continue;
-				}
-				for (const job of claimed.data) if (await handle(job, handler, workOptions)) succeeded += 1;
-				else failed += 1;
-			}
-		});
-		await Promise.all(lanes);
-		return {
-			succeeded,
-			failed
-		};
-	};
-	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));
-			});
-		},
-		claim,
-		complete,
-		fail,
-		extend: (job, lease) => run(() => transport.extend(job, lease)),
-		schedule(name, cron, queue, payload) {
-			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));
-			});
-		},
-		unschedule: (name) => run(() => transport.unschedule(name)),
-		drain: (queue, handler, drainOptions = {}) => loop(queue, handler, drainOptions, false),
-		work: (queue, handler, workOptions = {}) => loop(queue, handler, workOptions, true)
-	};
-}
+//#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";
@@ -323,7 +245,7 @@ function createIdempotency(sql, options = {}) {
 			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 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);
@@ -480,5 +402,606 @@ function entitlementMembers(sql, 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,
+				JSON.stringify(payload ?? {}),
+				delay,
+				maxAttempts,
+				dedupeKey ?? null
+			]);
+			return Number(row.id);
+		},
+		read: (queue, lease, batch) => sql.queryRaw("select * from better_supabase.claim_jobs($1, $2, $3)", [
+			queue,
+			lease,
+			batch
+		]),
+		async complete(job) {
+			const [row] = await sql.queryRaw("select better_supabase.complete_job($1, $2, $3) as done", [
+				job.queue,
+				job.id,
+				job.attempts
+			]);
+			return row?.done ?? false;
+		},
+		async fail(job, error, retryIn) {
+			const [row] = await sql.queryRaw("select better_supabase.fail_job($1, $2, $3, $4, $5) as status", [
+				job.queue,
+				job.id,
+				job.attempts,
+				error,
+				retryIn ?? null
+			]);
+			return row?.status ?? null;
+		},
+		async extend(job, lease) {
+			const [row] = await sql.queryRaw("select better_supabase.extend_job_lease($1, $2, $3, $4) as extended", [
+				job.queue,
+				job.id,
+				job.attempts,
+				lease
+			]);
+			return row?.extended ?? false;
+		},
+		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 ?? {}),
+				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;
+		}
+	};
+}
+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, no deduplication
+* and no schedules: a failed job reappears when its lease ends.
+*/
+function pgmqPublicBackend(client) {
+	const call = async (fn, args) => {
+		const { data, error } = await client.schema("pgmq_public").rpc(fn, args);
+		if (error) {
+			const message = typeof error === "object" && "message" in error ? String(error.message) : String(error);
+			throw new Error(`pgmq_public.${fn}: ${message}`, { cause: error });
+		}
+		return data;
+	};
+	const archive = (job) => call("archive", {
+		queue_name: job.queue,
+		message_id: job.id
+	});
+	return {
+		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", {
+				queue_name: queue,
+				message: {
+					payload: payload ?? {},
+					max_attempts: maxAttempts
+				},
+				sleep_seconds: delay
+			});
+			return Number(ids[0]);
+		},
+		async read(queue, lease, batch) {
+			const rows = await call("read", {
+				queue_name: queue,
+				sleep_seconds: lease,
+				n: batch
+			});
+			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,
+				visible_until: row.vt,
+				message: row.message
+			}));
+		},
+		complete: archive,
+		async fail(job) {
+			if (job.attempts < job.maxAttempts) return "queued";
+			await archive(job);
+			return "dead";
+		},
+		extend: () => Promise.resolve(false),
+		schedule: () => sqlOnly("schedule"),
+		unschedule: () => sqlOnly("unschedule")
+	};
+}
+/** 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,
+		context,
+		attempts: row.attempts,
+		maxAttempts: message.max_attempts ?? 5,
+		enqueuedAt: toInstant(row.enqueued_at),
+		visibleUntil: toInstant(row.visible_until),
+		lastError: message.last_error ?? null
+	};
+}
+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, 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 = backendOf(source);
+	const schemaOf = (queue) => {
+		const schema = queues[queue];
+		if (!schema) throw new TypeError(`Unknown queue "${queue}". Queues: ${Object.keys(queues).join(", ")}`);
+		return schema;
+	};
+	const complete = (job) => run(() => transport.complete(job));
+	const fail = (job, error, failOptions = {}) => run(() => transport.fail(job, errorText(error), failOptions.retryIn));
+	const claim = (queue, claimOptions = {}) => run(async () => {
+		schemaOf(queue);
+		return (await transport.read(queue, claimOptions.lease ?? 300, claimOptions.batch ?? 1)).map((row) => toJob(queue, row));
+	});
+	/**
+	* 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.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) => {
+		const controller = new AbortController();
+		try {
+			const payload = await validate(schemaOf(job.queue), job.payload, "payload");
+			if (!payload.ok) {
+				await fail(job, payload.error.message);
+				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,
+				context
+			}, controller.signal);
+			if (typeof outcome === "object" && outcome !== null && "ok" in outcome && outcome.ok === false && "error" in outcome) throw outcome.error;
+			await complete(job);
+			return true;
+		} catch (cause) {
+			controller.abort();
+			await fail(job, cause);
+			workOptions.onError?.(typeof cause === "object" && cause !== null && "kind" in cause ? cause : toDbError(cause), job);
+			return false;
+		}
+	};
+	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;
+		const maxWait = Math.max(firstWait, workOptions.maxPollInterval ?? 3e4);
+		let succeeded = 0;
+		let failed = 0;
+		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
+				});
+				if (!claimed.ok) throw new TypeError(claimed.error.message, { cause: claimed.error });
+				if (claimed.data.length === 0) {
+					if (!forever) return;
+					await sleep(wait, workOptions.signal);
+					wait = Math.min(maxWait, wait * 2);
+					continue;
+				}
+				wait = firstWait;
+				const held = new Set(claimed.data);
+				const timer = heartbeat(held, lease);
+				try {
+					for (const job of claimed.data) {
+						if (await handle(job, handler, workOptions)) succeeded += 1;
+						else failed += 1;
+						held.delete(job);
+					}
+				} finally {
+					clearInterval(timer);
+				}
+			}
+		});
+		await Promise.all(lanes);
+		return {
+			succeeded,
+			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, withContext(valid.data, enqueueOptions.context), delay, enqueueOptions.maxAttempts ?? 5, enqueueOptions.dedupeKey));
+			});
+		},
+		claim,
+		complete,
+		fail,
+		extend: (job, lease) => run(() => transport.extend(job, lease)),
+		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;
+				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)),
+		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" }
+				});
+				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 {
+						results[queue] = await loop(queue, handler, routeOptions, false, deadline);
+					} catch (cause) {
+						routeOptions.onError?.(toDbError(cause));
+						results[queue] = {
+							succeeded: 0,
+							failed: 0
+						};
+					}
+				}
+				const result = {
+					schedules: scheduled,
+					queues: results,
+					budgetExhausted: Date.now() >= deadline
+				};
+				return Response.json(result);
+			};
+		}
+	};
+}
 //#endregion
-export { ENTITLEMENTS_UPDATED, createIdempotency, createInbox, createJobs, entitlementMembers };
+export { ENTITLEMENTS_UPDATED, assertCron, createIdempotency, createInbox, createJobs, createOutbox, entitlementMembers, nextCronRun, outboxCloudEvent, pgmqPublicBackend, purgeAuditLog, sqlQueueBackend };