better-supabase 0.0.0 → 0.1.0

package/dist/jobs/index.d.ts

@@ -0,0 +1,173 @@
+import { o as Result, p as DbError, t as AsyncResult } from "../result-CTkCZ6JA.js";
+import { t as SqlClient } from "../executor-Bje4suQF.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/jobs/index.d.ts
+export type QueueSchemas = Readonly<Record<string, StandardSchemaV1>>;
+type PayloadIn<Q extends QueueSchemas, N extends keyof Q> = StandardSchemaV1.InferInput<Q[N]>;
+type PayloadOut<Q extends QueueSchemas, N extends keyof Q> = StandardSchemaV1.InferOutput<Q[N]>;
+export interface Job<P = unknown> {
+  /** The pgmq message id. */
+  readonly id: number;
+  readonly queue: string;
+  readonly payload: P;
+  /** 1 on the first run (pgmq's `read_ct`). */
+  readonly attempts: number;
+  readonly maxAttempts: number;
+  readonly enqueuedAt: Date;
+  /** End of the lease: the job becomes claimable again after this. */
+  readonly visibleUntil: Date;
+  readonly lastError: string | null;
+}
+export interface EnqueueOptions {
+  /** Run no earlier than this. */
+  readonly runAt?: Date;
+  /** Seconds to wait before running. */
+  readonly delay?: number;
+  /** Defaults to 5. After this many failed attempts the job is archived as dead. */
+  readonly maxAttempts?: number;
+  /**
+   * While a job with this key is waiting or running, enqueueing again returns
+   * its id. SQL connections only.
+   */
+  readonly dedupeKey?: string;
+}
+export interface ClaimOptions {
+  /** Defaults to 1. */
+  readonly batch?: number;
+  /** Seconds a claimed job stays invisible to other workers. Defaults to 300. */
+  readonly lease?: number;
+}
+export interface FailOptions {
+  /** Retry after this many seconds instead of the exponential backoff. SQL connections only. */
+  readonly retryIn?: number;
+}
+export type JobHandler<P> = (payload: P, job: Job<P>, signal: AbortSignal) => unknown;
+export interface WorkOptions extends ClaimOptions {
+  /** Jobs handled at once. Defaults to 1. */
+  readonly concurrency?: number;
+  /** Wait between polls when the queue is empty, in ms. Defaults to 1000. */
+  readonly pollInterval?: number;
+  /** Stops the loop; running jobs finish first. */
+  readonly signal?: AbortSignal;
+  readonly onError?: (error: DbError, job: Job) => void;
+}
+export interface DrainResult {
+  readonly succeeded: number;
+  readonly failed: number;
+}
+export interface Jobs<Q extends QueueSchemas> {
+  /** Validates the payload with the queue's schema, then enqueues it. Returns the job id. */
+  enqueue<N extends Extract<keyof Q, string>>(queue: N, payload: PayloadIn<Q, N>, options?: EnqueueOptions): AsyncResult<number>;
+  claim<N extends Extract<keyof Q, string>>(queue: N, options?: ClaimOptions): AsyncResult<Job<PayloadOut<Q, N>>[]>;
+  /** Archives the job. `false` when the lease was lost (another worker claimed it since). */
+  complete(job: Job): AsyncResult<boolean>;
+  /** Returns the new state: `queued` (will retry), `dead` (archived), or `null` when the lease was lost. */
+  fail(job: Job, error: unknown, options?: FailOptions): AsyncResult<"queued" | "dead" | null>;
+  /** Pushes the lease out by `lease` seconds. `false` when it was lost or the transport can't. */
+  extend(job: Job, lease: number): AsyncResult<boolean>;
+  /**
+   * Enqueues `payload` on a cron schedule with pg_cron (`'0 3 * * *'`,
+   * `'30 seconds'`). Re-scheduling a name replaces it. SQL connections only.
+   */
+  schedule<N extends Extract<keyof Q, string>>(name: string, cron: string, queue: N, payload: PayloadIn<Q, N>): AsyncResult<void>;
+  unschedule(name: string): AsyncResult<boolean>;
+  /** Processes ready jobs until the queue is empty. For cron and edge invocations. */
+  drain<N extends Extract<keyof Q, string>>(queue: N, handler: JobHandler<PayloadOut<Q, N>>, options?: Omit<WorkOptions, "pollInterval" | "signal">): Promise<DrainResult>;
+  /** Polls and processes jobs until `signal` aborts. */
+  work<N extends Extract<keyof Q, string>>(queue: N, handler: JobHandler<PayloadOut<Q, N>>, options?: WorkOptions): Promise<DrainResult>;
+}
+/** A Supabase client, or anything with `.schema(name).rpc(fn, args)`. */
+export interface QueueRpcClient {
+  schema(name: string): {
+    rpc(fn: string, args: Readonly<Record<string, unknown>>): PromiseLike<{
+      data: unknown;
+      error: unknown;
+    }>;
+  };
+}
+/**
+ * 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.
+ */
+export declare function createJobs<const Q extends QueueSchemas>(source: SqlClient | QueueRpcClient, queues: Q): Jobs<Q>;
+export interface IdempotencyOptions {
+  /** Separates keys of different endpoints or tenants. Defaults to `''`. */
+  readonly scope?: string | ((request: Request) => string);
+  /** How long a completed response is replayed. Defaults to `24 hours`. */
+  readonly ttl?: number | string;
+  /** How long a running request holds the key. Defaults to `1 minute`. */
+  readonly lock?: number | string;
+  /** Answer 400 when the header is missing. Defaults to false (run without a key). */
+  readonly required?: boolean;
+  /** Defaults to `Idempotency-Key`. */
+  readonly header?: string;
+}
+export type IdempotencyState = "started" | "replay" | "running" | "mismatch";
+export interface Idempotency {
+  /**
+   * Runs `handler` at most once per key: retries with the same key and body
+   * get the stored response (with `Idempotency-Replayed: true`).
+   */
+  handle(request: Request, handler: (request: Request) => Promise<Response> | Response): Promise<Response>;
+  /** The lower-level protocol, for non-HTTP callers. */
+  begin(key: string, fingerprint: string, scope?: string): AsyncResult<{
+    state: IdempotencyState;
+    status: number | null;
+    body: unknown;
+  }>;
+  complete(key: string, status: number, body: unknown, scope?: string): AsyncResult<void>;
+  release(key: string, scope?: string): AsyncResult<void>;
+}
+/** HTTP idempotency keys (IETF `Idempotency-Key` header) over the `idempotency` SQL kit module. */
+export declare function createIdempotency(sql: SqlClient, options?: IdempotencyOptions): Idempotency;
+export interface InboxMessage<T = unknown> {
+  readonly id: number;
+  readonly source: string;
+  readonly messageId: string;
+  readonly type: string | null;
+  readonly payload: T;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly attempts: number;
+  readonly receivedAt: Date;
+}
+export interface InboxOptions {
+  /** Name of the sender, e.g. `stripe` or `supabase-auth`. */
+  readonly source: string;
+  /** Standard Webhooks secrets; the signature is verified before storing. */
+  readonly secrets?: string | readonly string[];
+  /** Custom verification for senders that don't use Standard Webhooks. */
+  readonly verify?: (request: Request, body: string) => Promise<Result<{
+    id: string;
+    payload: unknown;
+  }>>;
+  /** Event type from the payload. Defaults to `payload.type`. */
+  readonly typeOf?: (payload: unknown) => string | null;
+  /** Headers kept with the message. Defaults to none. */
+  readonly keepHeaders?: readonly string[];
+  readonly worker?: string;
+}
+export interface Inbox {
+  /** Verifies and stores a webhook; answers 202, or 200 for a duplicate delivery. */
+  receive(request: Request): Promise<Response>;
+  /** Processes stored messages until none are ready. */
+  process<T = unknown>(handler: (message: InboxMessage<T>) => unknown, options?: {
+    readonly batch?: number;
+    readonly lease?: number | string;
+  }): Promise<DrainResult>;
+}
+/** Store-then-process webhooks: acknowledge fast, process with retries, never twice. */
+export declare function createInbox(sql: SqlClient, options: InboxOptions): Inbox;
+/** The Stripe event sent when a customer's active entitlements change. */
+export declare const ENTITLEMENTS_UPDATED = "entitlements.active_entitlement_summary.updated";
+/**
+ * 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.
+ */
+export declare function entitlementMembers(sql: SqlClient, payload: unknown): AsyncResult<readonly string[]>;
+//#endregion
+export type { SqlClient };

package/dist/jobs/index.js

@@ -0,0 +1,477 @@
+import { c as mapDbError, n as dbError, t as DbException } from "../errors-Bl3rkOzo.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-DPu6Fh-t.js";
+import { t as fromPgError } from "../executor-Ceq60hPM.js";
+import { c as verifyWebhook } from "../webhooks-DbMTJJX2.js";
+//#region src/jobs/index.ts
+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));
+		}
+	});
+}
+function seconds(value) {
+	return typeof value === "number" ? `${String(value)} seconds` : value;
+}
+function workerId() {
+	return `worker-${crypto.randomUUID().slice(0, 8)}`;
+}
+const sleep = (ms, signal) => new Promise((resolve) => {
+	if (signal?.aborted) return resolve();
+	const timer = setTimeout(done, ms);
+	function done() {
+		clearTimeout(timer);
+		signal?.removeEventListener("abort", done);
+		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" && error !== null && "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")
+	};
+}
+const toDate = (value) => value instanceof Date ? value : new Date(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: toDate(row.enqueued_at),
+		visibleUntil: toDate(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.getTime() - Date.now()) / 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)
+	};
+}
+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" }
+				});
+				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: toDate(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) {
+	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 };