better-supabase 0.3.0 → 0.5.0

package/dist/testing/index.js

@@ -1,20 +1,20 @@
-import { n as dbError } from "../errors-Bl3rkOzo.js";
-import { i as temporalText } from "../temporal-BwshQk0W.js";
-import { t as temporal } from "../temporal-required-CMxeSVPo.js";
-import { i as ok } from "../result-DWXatkd6.js";
-import { t as BetterSupabase } from "../define-DF341GDj.js";
-import { a as toBase64Url, r as fromBase64, t as base64ToText } from "../base64-CQeB1eSf.js";
-import { r as resolveConfig } from "../config-Be4GwsqI.js";
+import { n as dbError } from "../errors-DtwXa6b8.js";
+import { i as temporalText } from "../temporal-CVlIV2DZ.js";
+import { t as temporal } from "../temporal-required-CAt4Dc9Z.js";
+import { i as ok } from "../result-BKiliPY7.js";
+import { t as BetterSupabase } from "../define-cNKzqwL_.js";
+import { a as toBase64Url, r as fromBase64, t as base64ToText } from "../base64-D2gsioCY.js";
+import { a as resolveConfig } from "../kits-CGLLrNPd.js";
 import { t as isList } from "../guards-BnzDvFrz.js";
 import { ENV_VARIABLES } from "../env/index.js";
-import { n as postgresExecutor } from "../executor-C57jx2pn.js";
+import { n as postgresExecutor } from "../executor-XycESQPH.js";
 import { toCloudEvents } from "../events/index.js";
 import { createClient } from "@supabase/supabase-js";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 //#region src/testing/jwt.ts
-const encoder = new TextEncoder();
+const encoder = /* @__PURE__ */ new TextEncoder();
 /**
 * Signs an HS256 access token the local Supabase stack accepts. Test-only:
 * production tokens come from Supabase Auth.
@@ -44,7 +44,7 @@ async function signTestJwt(secret, claims) {
 }
 /**
 * Accepts `signTestJwt` tokens as users, for API servers tested against the
-* local stack: `createServer(sb, { auth: { resolvers: [localAuth(secret)] } })`.
+* local stack: `createServer(betterSupabase, { auth: { resolvers: [localAuth(secret)] } })`.
 * Tokens that are not HS256-signed with `secret` fall through. Test-only.
 */
 function localAuth(secret) {
@@ -198,11 +198,11 @@ async function signFor(stack, url, claims) {
 * still uses the shared JWT secret.
 *
 * ```ts
-* const alice = await asUser(sb, { sub: aliceId, tenant_id: acme });
+* const alice = await asUser(betterSupabase, { sub: aliceId, tenant_id: acme });
 * expect(await alice.db.customers.count().orThrow()).toBe(3);
 * ```
 */
-async function asUser(sb, claims, stack = {}) {
+async function asUser(betterSupabase, claims, stack = {}) {
 	const url = stack.url ?? env$1(...ENV_VARIABLES.url) ?? "http://127.0.0.1:54321";
 	const publishableKey = stack.publishableKey ?? env$1(...ENV_VARIABLES.publishableKey, "SUPABASE_ANON_KEY");
 	if (!publishableKey) throw new TypeError("asUser needs publishableKey or $SUPABASE_PUBLISHABLE_KEY. Run `better-supabase env` to write it to .env.local.");
@@ -225,8 +225,8 @@ async function asUser(sb, claims, stack = {}) {
 		token,
 		claims: full,
 		supabase,
-		db: sb.connect(supabase, context),
-		sql: stack.postgres ? sb.connect(postgresExecutor(stack.postgres.asUser(full)), context) : void 0
+		db: betterSupabase.connect(supabase, context),
+		sql: stack.postgres ? betterSupabase.connect(postgresExecutor(stack.postgres.asUser(full)), context) : void 0
 	};
 }
 //#endregion
@@ -246,7 +246,7 @@ function settle(promise, ms) {
 /**
 * Measures every document and RSC navigation response during `during` and
 * fails when one render makes more database calls or waves than allowed.
-* Needs `createNext(sb, { debug })` and `next.debugRoute()` in the app.
+* Needs `createNext(betterSupabase, { debug })` and `bs.debugRoute()` in the app.
 */
 async function expectDbBudget(page, expectation) {
 	const seen = [];
@@ -267,12 +267,12 @@ async function expectDbBudget(page, expectation) {
 	} finally {
 		page.off("response", listener);
 	}
-	if (seen.length === 0) throw new Error("expectDbBudget: no response carried x-bs-request-id. Enable createNext(sb, { debug: { enabled: true } }) and run the proxy.");
+	if (seen.length === 0) throw new Error("expectDbBudget: no response carried x-bs-request-id. Enable createNext(betterSupabase, { debug: { enabled: true } }) and run the proxy.");
 	await Promise.all(seen.map(({ response }) => settle(response.finished(), expectation.timeoutMs ?? 1e4)));
 	const renders = [];
 	for (const { response, id, url } of seen) {
 		const reply = await page.request.get(url);
-		if (!reply.ok()) throw new Error(`expectDbBudget: ${url} answered ${reply.status()}. Mount next.debugRoute() at that path.`);
+		if (!reply.ok()) throw new Error(`expectDbBudget: ${url} answered ${reply.status()}. Mount bs.debugRoute() at that path.`);
 		renders.push({
 			url: response.url(),
 			requestId: id,
@@ -348,17 +348,17 @@ const recorder = (ops) => ({
 		}));
 	}
 });
-/** The operation `run` sends to the executor, built by `sb` without touching a database. */
-async function captureOp(sb, run) {
+/** The operation `run` sends to the executor, built by `betterSupabase` without touching a database. */
+async function captureOp(betterSupabase, run) {
 	const ops = [];
-	await run(sb.connect(recorder(ops)));
+	await run(betterSupabase.connect(recorder(ops)));
 	const [op] = ops;
 	if (!op) throw new Error("the repository call did not reach the executor");
 	return op;
 }
-function tableKey(sb, table) {
-	const key = table ?? Object.keys(sb.meta.tables)[0];
-	if (!key || !(key in sb.meta.tables)) throw new TypeError(`better-supabase: unknown table "${String(key)}"`);
+function tableKey(betterSupabase, table) {
+	const key = table ?? Object.keys(betterSupabase.meta.tables)[0];
+	if (!key || !(key in betterSupabase.meta.tables)) throw new TypeError(`better-supabase: unknown table "${String(key)}"`);
 	return key;
 }
 const hasName = (subject) => ["has a name", () => {
@@ -370,14 +370,14 @@ const hasName = (subject) => ["has a name", () => {
 * than thrown, and (with `create`) a write round trip.
 *
 * ```ts
-* it('conforms', () => testExecutor(myExecutor, { sb, table: 'tags', create: { name: 'x' } }));
+* it('conforms', () => testExecutor(myExecutor, { betterSupabase, table: 'tags', create: { name: 'x' } }));
 * ```
 */
 function testExecutor(executor, options) {
-	const { sb } = options;
-	const table = tableKey(sb, options.table);
+	const { betterSupabase } = options;
+	const table = tableKey(betterSupabase, options.table);
 	const context = { errorMappers: [] };
-	const read = () => captureOp(sb, (db) => db[table]["findMany"]({ limit: 2 }));
+	const read = () => captureOp(betterSupabase, (db) => db[table]["findMany"]({ limit: 2 }));
 	const create = options.create;
 	return conform(`Executor "${executor.name}"`, [
 		hasName(executor),
@@ -396,7 +396,7 @@ function testExecutor(executor, options) {
 			}
 		}],
 		["counts rows", async () => {
-			const op = await captureOp(sb, (db) => db[table]["count"]());
+			const op = await captureOp(betterSupabase, (db) => db[table]["count"]());
 			const result = await executor.execute(op, context);
 			expect(result.ok, `count failed: ${result.ok ? "" : result.error.message}`);
 			expect(typeof result.data.count === "number" && result.data.count >= 0, "count must be a number");
@@ -444,7 +444,7 @@ function testExecutor(executor, options) {
 		}],
 		executor.batch && ["batch returns one result per operation, in order", async () => {
 			const rows = await read();
-			const count = await captureOp(sb, (db) => db[table]["count"]());
+			const count = await captureOp(betterSupabase, (db) => db[table]["count"]());
 			const missing = {
 				...rows,
 				table: {
@@ -464,12 +464,12 @@ function testExecutor(executor, options) {
 			expect(third?.ok === false, "a failing operation must fail on its own, as a result");
 		}],
 		create && ["round-trips a write", async () => {
-			const repository = sb.connect(executor)[table];
+			const repository = betterSupabase.connect(executor)[table];
 			const created = await repository["create"](create);
 			expect(created.ok, `create failed: ${JSON.stringify(created.error)}`);
 			const row = created.data;
 			for (const [key, value] of Object.entries(create)) expect(same(row[key], value), `created row has ${key} = ${JSON.stringify(row[key])}`);
-			const [primary] = sb.meta.tables[table].primaryKey;
+			const [primary] = betterSupabase.meta.tables[table].primaryKey;
 			expect(primary, "write checks need a table with a primary key");
 			const removed = await repository["delete"](row[primary]);
 			expect(removed.ok, `delete failed: ${JSON.stringify(removed.error)}`);
@@ -546,6 +546,147 @@ function testEventSink(sink, options = {}) {
 		}]
 	]);
 }
+function claimedJob(queue, row) {
+	const instant = temporal().Instant.fromEpochMilliseconds(0);
+	return {
+		id: Number(row.id),
+		queue,
+		payload: row.message?.payload,
+		attempts: row.attempts,
+		maxAttempts: row.message?.max_attempts ?? 5,
+		enqueuedAt: instant,
+		visibleUntil: instant,
+		lastError: row.message?.last_error ?? null,
+		context: {}
+	};
+}
+/**
+* Proves a `QueueBackend` round-trips payloads, hides claimed messages for
+* their lease, counts attempts, retries and dead-letters on `fail`, and
+* (when it has `leases`) rejects a stale attempt and extends a lease. It
+* writes to `options.queue` on the backend's real store.
+*/
+function testQueueBackend(backend, options) {
+	const { queue } = options;
+	const claimOne = async () => {
+		const [row] = await backend.read(queue, 30, 1);
+		return row && claimedJob(queue, row);
+	};
+	return conform(`QueueBackend "${backend.name}"`, [
+		hasName(backend),
+		["has apiVersion 1", () => {
+			const version = backend.apiVersion;
+			expect(version === 1, "apiVersion must be 1");
+		}],
+		["round-trips a payload and leases it", async () => {
+			const id = await backend.send(queue, { n: 1 }, 0, 3, void 0);
+			expect(Number.isFinite(id), "send must return a numeric id");
+			const job = await claimOne();
+			expect(job?.id === id, "read must return the sent message");
+			expect(same(job.payload, { n: 1 }), "the payload must round-trip");
+			expect(job.attempts === 1, "the first claim must be attempt 1");
+			expect(job.maxAttempts === 3, "max_attempts must round-trip");
+			expect(await claimOne() === void 0, "a leased message must stay hidden from other reads");
+			expect(await backend.complete(job), "complete must return true");
+		}],
+		backend.leases && ["rejects a stale attempt and extends a lease", async () => {
+			await backend.send(queue, { n: 2 }, 0, 3, void 0);
+			const job = await claimOne();
+			expect(job, "read must return the sent message");
+			expect(!await backend.complete({
+				...job,
+				attempts: job.attempts + 1
+			}), "complete with another attempt must return false");
+			expect(await backend.extend(job, 60), "extend must return true");
+			expect(await backend.complete(job), "complete must return true");
+		}],
+		["retries, then dead-letters at max attempts", async () => {
+			await backend.send(queue, { n: 3 }, 0, 2, void 0);
+			const first = await claimOne();
+			expect(first, "read must return the sent message");
+			expect(await backend.fail(first, "boom", 0) === "queued", "fail before max_attempts must return queued");
+			const second = await claimOne();
+			expect(second?.attempts === 2, "a retried message must be attempt 2");
+			expect(await backend.fail(second, "boom", 0) === "dead", "fail at max_attempts must return dead");
+			expect(await claimOne() === void 0, "a dead message must not be claimed again");
+		}],
+		(options.dedupe ?? backend.leases) && ["returns the first id for a repeated dedupe key", async () => {
+			expect(await backend.send(queue, { n: 4 }, 0, 3, "same") === await backend.send(queue, { n: 4 }, 0, 3, "same"), "a waiting dedupe key must return its id");
+			const job = await claimOne();
+			expect(job, "read must return the sent message");
+			await backend.complete(job);
+		}]
+	]);
+}
+/**
+* Proves a `SupportSessionStore` starts sessions with the input it was
+* given, shows a running session only to its admin, ends the admin's
+* previous session on start, ends a session once, and lists sessions.
+* It writes sessions to the store; they are all ended when it returns.
+*/
+function testSupportSessionStore(store, options) {
+	const { admin } = options;
+	const [first, second] = options.targets;
+	const start = (targetUserId) => store.start({
+		adminId: admin.id,
+		adminClaims: admin.claims,
+		targetUserId,
+		reason: "conformance",
+		ttlSeconds: 600,
+		readOnly: true,
+		metadata: { ticket: "T-1" }
+	});
+	return conform(`SupportSessionStore "${store.name}"`, [
+		hasName(store),
+		["has apiVersion 1", () => {
+			const version = store.apiVersion;
+			expect(version === 1, "apiVersion must be 1");
+		}],
+		["starts a session with its input and shows it to its admin only", async () => {
+			const session = await start(first);
+			try {
+				expect(session.id.length > 0, "start must return an id");
+				expect(session.adminId === admin.id, "adminId must round-trip");
+				expect(session.targetUserId === first, "targetUserId must round-trip");
+				expect(session.reason === "conformance", "reason must round-trip");
+				expect(session.readOnly, "readOnly must round-trip");
+				expect(same(session.metadata, { ticket: "T-1" }), "metadata must round-trip");
+				const seconds = (session.expiresAt.epochMilliseconds - session.startedAt.epochMilliseconds) / 1e3;
+				expect(Math.abs(seconds - 600) < 5, "expiresAt must be ttlSeconds after startedAt");
+				expect((await store.get(session.id, admin.id))?.id === session.id, "get must return the running session");
+				expect(await store.get(session.id, first) === void 0, "get must hide a session from anyone but its admin");
+			} finally {
+				await store.end(session.id, "admin");
+			}
+		}],
+		["ends the admin's previous session on start", async () => {
+			const older = await start(first);
+			const newer = await start(second);
+			try {
+				expect(await store.get(older.id, admin.id) === void 0, "starting a session must end the admin's previous one");
+				expect((await store.get(newer.id, admin.id))?.id === newer.id, "the new session must be running");
+			} finally {
+				await store.end(newer.id, "admin");
+			}
+		}],
+		["ends a session once and lists it", async () => {
+			const session = await start(first);
+			expect(await store.end(session.id, "admin"), "end must return true");
+			expect(!await store.end(session.id, "admin"), "ending an ended session must return false");
+			expect(await store.get(session.id, admin.id) === void 0, "get must not return an ended session");
+			const entry = (await store.list({
+				adminId: admin.id,
+				active: false
+			})).find((item) => item.id === session.id);
+			expect(entry, "list must include the ended session");
+			expect(entry.endedAt !== void 0, "an ended session has endedAt");
+			expect((await store.list({
+				adminId: admin.id,
+				active: true
+			})).every((item) => item.id !== session.id), "list({ active: true }) must leave out ended sessions");
+		}]
+	]);
+}
 async function resolveSafely(resolver, request) {
 	try {
 		return await resolver.resolve(request);
@@ -643,12 +784,12 @@ function testGenerator(generator, options) {
 * results intact when it wraps them.
 */
 function testPlugin(plugin, options) {
-	const { sb } = options;
-	const table = tableKey(sb, options.table);
+	const { betterSupabase } = options;
+	const table = tableKey(betterSupabase, options.table);
 	const context = options.context ?? {};
 	const hook = (op) => ({
 		table: op.table,
-		schema: sb.meta,
+		schema: betterSupabase.meta,
 		context,
 		options: {},
 		now: () => temporal().Instant.fromEpochMilliseconds(0)
@@ -660,26 +801,41 @@ function testPlugin(plugin, options) {
 			expect(plugin.apiVersion === 1, `apiVersion is ${String(plugin.apiVersion)}`);
 		}],
 		["installs and builds repositories", () => {
-			const db = sb.use(plugin).connect(recorder([]), context);
-			for (const key of Object.keys(sb.meta.tables)) expect(db[key], `db.${key} is missing`);
+			const db = betterSupabase.use(plugin).connect(recorder([]), context);
+			for (const key of Object.keys(betterSupabase.meta.tables)) expect(db[key], `db.${key} is missing`);
 		}],
 		plugin.transformQuery && ["transformQuery is pure and deterministic", async () => {
-			const op = await captureOp(sb, (db) => db[table]["findMany"]({ limit: 1 }));
+			const op = await captureOp(betterSupabase, (db) => db[table]["findMany"]({ limit: 1 }));
 			const first = plugin.transformQuery(frozenCopy(op), hook(op));
 			const second = plugin.transformQuery(frozenCopy(op), hook(op));
 			expect(typeof first === "object" && first !== null && first.kind === op.kind, "must return an operation of the same kind");
 			expect(same(first, second), "two calls with the same input differ");
 		}],
 		plugin.beforeMutation && create && ["beforeMutation is pure and deterministic", async () => {
-			const op = await captureOp(sb, (db) => db[table]["create"](create));
+			const op = await captureOp(betterSupabase, (db) => db[table]["create"](create));
 			if (op.kind === "select") throw new Violation("create did not produce a mutation");
 			const first = await plugin.beforeMutation(frozenCopy(op), hook(op));
 			const second = await plugin.beforeMutation(frozenCopy(op), hook(op));
 			expect(first.kind === op.kind, "must return a mutation of the same kind");
 			expect(same(first, second), "two calls with the same input differ");
 		}],
+		plugin.afterMutation && create && ["afterMutation cannot change the result", async () => {
+			const row = {
+				marker: "conformance",
+				nested: { kept: true }
+			};
+			const result = await betterSupabase.use(plugin).connect({
+				name: "rows",
+				execute: () => Promise.resolve(ok({
+					rows: [structuredClone(row)],
+					count: 1
+				}))
+			}, context)[table]["create"](create);
+			expect(result.ok, "create failed");
+			expect(same(result.data, row), "afterMutation changed the returned row");
+		}],
 		plugin.wrapExecutor && ["wrapExecutor keeps results intact", async () => {
-			const op = await captureOp(sb, (db) => db[table]["findMany"]({ limit: 1 }));
+			const op = await captureOp(betterSupabase, (db) => db[table]["findMany"]({ limit: 1 }));
 			const data = {
 				rows: [{ marker: "conformance" }],
 				count: 1
@@ -723,12 +879,12 @@ function env(names) {
 /**
 * Checks row-level security between two tenants against a running stack: for
 * each table, a user of one tenant must not select, insert, update or delete
-* the other tenant's rows. Runs without `sb`'s plugins, so the `tenant()`
+* the other tenant's rows. Runs without `betterSupabase`'s plugins, so the `tenant()`
 * plugin can't hide a missing policy. Throws a `ConformanceError` naming each
 * table and command that leaks; removes every row it created.
 *
 * ```ts
-* await expectTenantIsolation(sb, {
+* await expectTenantIsolation(betterSupabase, {
 *   tenants: [
 *     { id: ACME, claims: { sub: alice, tenant_id: ACME } },
 *     { id: GLOBEX, claims: { sub: bob, tenant_id: GLOBEX } },
@@ -742,9 +898,9 @@ function env(names) {
 * });
 * ```
 */
-async function expectTenantIsolation(sb, options) {
+async function expectTenantIsolation(betterSupabase, options) {
 	const stack = options.stack ?? {};
-	const bare = new BetterSupabase(sb.schema);
+	const bare = new BetterSupabase(betterSupabase.schema);
 	const url = stack.url ?? env(ENV_VARIABLES.url) ?? "http://127.0.0.1:54321";
 	const secretKey = stack.secretKey ?? env(ENV_VARIABLES.secretKey);
 	if (!secretKey) throw new TypeError("expectTenantIsolation needs stack.secretKey or $SUPABASE_SECRET_KEY to seed rows.");
@@ -884,14 +1040,14 @@ function statement(table, rows) {
 * casing and Insert types; `better-supabase seed` renders them to SQL.
 *
 * ```ts
-* export const seed = defineSeed(sb, {
+* export const seed = defineSeed(betterSupabase, {
 *   organizations: { acme: { id: ACME, name: 'Acme' } },
 *   customers: { first: { organizationId: ACME, name: 'First customer' } },
 * });
 * ```
 */
-function defineSeed(sb, fixtures) {
-	const meta = sb.meta;
+function defineSeed(betterSupabase, fixtures) {
+	const meta = betterSupabase.meta;
 	const statements = () => {
 		const keys = Object.keys(fixtures).filter((key) => fixtures[key] !== void 0);
 		for (const key of keys) {
@@ -915,4 +1071,176 @@ function defineSeed(sb, fixtures) {
 	};
 }
 //#endregion
-export { ConformanceError, LOCAL_JWT_SECRET, asUser, createTestSigner, defineSeed, expectDbBudget, expectTenantIsolation, isSeed, localAuth, localSigningKey, signLocalJwt, signTestJwt, signTestJwtWithKey, testAuthResolver, testCacheAdapter, testEventSink, testExecutor, testGenerator, testPlugin };
+//#region src/testing/notification-channel.ts
+const STATUSES = /* @__PURE__ */ new Set(["sent", "skipped"]);
+function sample(channel, email) {
+	const createdAt = temporal().Instant.fromEpochMilliseconds(0);
+	return Object.freeze({
+		deliveryId: "00000000-0000-4000-8000-00000000c0f0",
+		channel,
+		attempts: 1,
+		userId: "00000000-0000-4000-8000-0000000000aa",
+		email,
+		notification: Object.freeze({
+			id: "00000000-0000-4000-8000-00000000c0f1",
+			eventId: "00000000-0000-4000-8000-00000000c0f2",
+			type: "conformance.check",
+			data: Object.freeze({ title: "Conformance" }),
+			tenant: null,
+			actorId: null,
+			subject: Object.freeze({
+				type: "task",
+				id: "42",
+				label: "Conformance"
+			}),
+			summary: "Conformance check",
+			actionPath: "/",
+			priority: null,
+			createdAt,
+			readAt: null,
+			resolvedAt: null
+		}),
+		text: Object.freeze({ title: "Conformance check" })
+	});
+}
+/**
+* Runs the `NotificationChannel` contract against `channel`: the API version,
+* a name, and one frozen sample message it must send without mutating.
+* Throws a `ConformanceError` listing every failed check.
+*/
+function testNotificationChannel(channel, options = {}) {
+	const message = sample(channel.name, options.email ?? null);
+	return conform(`NotificationChannel "${channel.name}"`, [
+		["has apiVersion 1", () => {
+			const version = channel.apiVersion;
+			expect(version === 1, "apiVersion must be 1");
+		}],
+		["has a name", () => {
+			expect(typeof channel.name === "string" && channel.name.length > 0, "name must be a non-empty string");
+		}],
+		["sends a message without mutating it and returns a valid result", async () => {
+			const result = await channel.send(message);
+			if (result === void 0) return;
+			expect(result.status === void 0 || STATUSES.has(result.status), `status must be "sent" or "skipped", got ${String(result.status)}`);
+			for (const key of ["provider", "providerMessageId"]) expect(result[key] === void 0 || typeof result[key] === "string", `${key} must be a string`);
+		}],
+		options.received && ["delivers the message", async () => {
+			expect((await options.received()).includes(message.deliveryId), `delivery ${message.deliveryId} was not received`);
+		}]
+	]);
+}
+//#endregion
+//#region src/testing/webhooks.ts
+const SECRET = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";
+function signInput(body, timestamp) {
+	return Object.freeze({
+		id: "msg_conformance",
+		body,
+		timestamp,
+		secrets: Object.freeze([SECRET])
+	});
+}
+function isHeaders(value) {
+	return typeof value === "object" && value !== null && Object.values(value).every((entry) => typeof entry === "string");
+}
+/**
+* Runs the `WebhookSigner` contract against `signer`: the API version, a
+* name, string headers that depend on the body and are stable for the same
+* input, and, with `verify`, a signature the receiver accepts.
+*/
+function testWebhookSigner(signer, options = {}) {
+	const body = JSON.stringify({
+		type: "conformance.check",
+		data: { n: 1 }
+	});
+	const now = temporal().Now.instant();
+	return conform(`WebhookSigner "${signer.name}"`, [
+		["has apiVersion 1", () => {
+			const version = signer.apiVersion;
+			expect(version === 1, "apiVersion must be 1");
+		}],
+		["has a name", () => {
+			expect(typeof signer.name === "string" && signer.name.length > 0, "name must be a non-empty string");
+		}],
+		["returns string headers, stable for the same input", async () => {
+			const first = await signer.sign(signInput(body, now));
+			const second = await signer.sign(signInput(body, now));
+			expect(isHeaders(first), "sign must return a record of string headers");
+			expect(isHeaders(first) && Object.keys(first).length > 0, "sign must return at least one header");
+			expect(JSON.stringify(first) === JSON.stringify(second), "the same input must produce the same headers");
+		}],
+		["changes the headers when the body changes", async () => {
+			const original = await signer.sign(signInput(body, now));
+			const tampered = await signer.sign(signInput(`${body} `, now));
+			expect(JSON.stringify(original) !== JSON.stringify(tampered), "the signature must cover the body");
+		}],
+		options.verify && ["produces a signature the receiver verifies", async () => {
+			const headers = await signer.sign(signInput(body, now));
+			expect(await options.verify({
+				headers,
+				body
+			}, SECRET), "the receiver rejected the signature");
+		}]
+	]);
+}
+/**
+* Runs the `WebhookTransport` contract against `transport`: the API version,
+* a name, and one POST to `options.url` that returns an HTTP status and a
+* string body.
+*/
+function testWebhookTransport(transport, options) {
+	const body = JSON.stringify({
+		type: "conformance.check",
+		id: crypto.randomUUID()
+	});
+	return conform(`WebhookTransport "${transport.name}"`, [
+		["has apiVersion 1", () => {
+			const version = transport.apiVersion;
+			expect(version === 1, "apiVersion must be 1");
+		}],
+		["has a name", () => {
+			expect(typeof transport.name === "string" && transport.name.length > 0, "name must be a non-empty string");
+		}],
+		["sends the request and returns a status and a body", async () => {
+			const response = await transport.send(Object.freeze({
+				url: options.url,
+				headers: Object.freeze({ "content-type": "application/json" }),
+				body
+			}));
+			expect(Number.isInteger(response.status) && response.status >= 100 && response.status <= 599, `status must be an HTTP status, got ${String(response.status)}`);
+			const responseBody = response.body;
+			expect(typeof responseBody === "string", "body must be a string");
+		}],
+		options.received && ["delivers the body", async () => {
+			expect((await options.received()).includes(body), "the receiver did not get the body");
+		}]
+	]);
+}
+/**
+* Runs the `WebhookSecretStore` contract against `store`: the API version, a
+* list of strings, and, when it can rotate, a new secret listed first while
+* the previous one keeps signing.
+*/
+function testWebhookSecretStore(store, options) {
+	return conform("WebhookSecretStore", [
+		["has apiVersion 1", () => {
+			const version = store.apiVersion;
+			expect(version === 1, "apiVersion must be 1");
+		}],
+		["lists the secrets as strings", async () => {
+			const secrets = await store.secrets(options.endpointId);
+			expect(Array.isArray(secrets) && secrets.every((secret) => typeof secret === "string"), "secrets must return an array of strings");
+		}],
+		store.rotate && ["rotates to a new secret and keeps the previous one during the overlap", async () => {
+			const first = await store.rotate(options.endpointId, { overlap: "1 hour" });
+			const second = await store.rotate(options.endpointId, { overlap: "1 hour" });
+			expect(typeof first === "string" && first.length > 0, "rotate must return the new secret");
+			expect(first !== second, "each rotation must create a new secret");
+			const secrets = await store.secrets(options.endpointId);
+			expect(secrets[0] === second, "the newest secret must be listed first");
+			expect(secrets.includes(first), "the previous secret must keep signing during the overlap");
+		}]
+	]);
+}
+//#endregion
+export { ConformanceError, LOCAL_JWT_SECRET, asUser, createTestSigner, defineSeed, expectDbBudget, expectTenantIsolation, isSeed, localAuth, localSigningKey, signLocalJwt, signTestJwt, signTestJwtWithKey, testAuthResolver, testCacheAdapter, testEventSink, testExecutor, testGenerator, testNotificationChannel, testPlugin, testQueueBackend, testSupportSessionStore, testWebhookSecretStore, testWebhookSigner, testWebhookTransport };

package/dist/{types-DONv9SHN.d.ts → types-Dnf_wRDz.d.ts}

@@ -62,6 +62,8 @@ interface TableFlags {
   readonly actor?: {
     readonly createdBy?: string;
     readonly updatedBy?: string;
+    /** The admin behind an impersonated write; `null` otherwise. */
+    readonly impersonatedBy?: string;
   };
   /** App column used for optimistic concurrency, usually `updatedAt`. */
   readonly version?: string;
@@ -140,7 +142,7 @@ interface PermdockBucketPolicy {
   readonly segment?: number;
   /**
    * Schema of the helpers `permdock rls generate` writes: PermDock's
-   * `rls.schema`. Defaults to `public`.
+   * `rls.schema`. Defaults to `permdock`, PermDock's default.
    */
   readonly schema?: string;
 }
@@ -153,14 +155,35 @@ interface PermdockTopicPolicy {
   readonly scope: string;
   /** 1-based `:`-separated topic segment holding the scope id. Defaults to the `{orgId}` segment. */
   readonly segment?: number;
+  /** Schema of PermDock's helpers (`rls.schema`). Defaults to `permdock`. */
   readonly schema?: string;
 }
 type BucketPolicyName = "tenant" | "owner" | "public" | "none";
+/**
+ * A policy through the SQL kit's [access contract](/docs/kits/access):
+ * `tenant_ids_with(permission)` for the tenant id in the path, or
+ * `is_platform(permission)`. Works with every access model.
+ */
+interface AccessBucketPolicy {
+  readonly access: {
+    /** Downloads, signed URLs, renders and metadata reads. */
+    readonly read: string;
+    /** Listing; without it `read` covers listing too. */
+    readonly list?: string;
+    /** Uploads, updates and moves; also deletes unless `delete` is set. */
+    readonly write: string;
+    readonly delete?: string;
+  };
+  /** `tenant` (default) checks the path's tenant segment; `platform` checks platform permissions. */
+  readonly scope?: "tenant" | "platform";
+  /** 1-based path segment holding the tenant id. Defaults to the `{orgId}` segment. */
+  readonly segment?: number;
+}
 interface BucketMeta {
   readonly id: string;
   readonly public: boolean;
   readonly path: string;
-  readonly policy?: BucketPolicyName | PermdockBucketPolicy;
+  readonly policy?: BucketPolicyName | PermdockBucketPolicy | AccessBucketPolicy;
   /** Claim paths for the tenant policy, when `config.claims.tenant` is not the default. */
   readonly tenant?: {
     readonly claim: readonly string[];
@@ -248,4 +271,4 @@ type IsUnion<T, U = T> = T extends unknown ? [U] extends [T] ? false : true : ne
 type PrimaryKeyValue<M extends AnyModels, T extends keyof M> = true extends IsUnion<PrimaryKeyColumn<M, T>> ? { readonly [K in PrimaryKeyColumn<M, T>]: Row<M, T>[K]; } : Row<M, T>[PrimaryKeyColumn<M, T>];
 type Simplify<T> = { [K in keyof T]: T[K]; } & {};
 //#endregion
-export { SchemaMeta as A, PrimaryKeyValue as C, Relations as D, RelationTypes as E, UniqueConstraint as F, UniqueKeyName as I, UniqueWhere as L, TableFlags as M, TableKey as N, Row as O, TableMeta as P, Update as R, PrimaryKeyColumn as S, RelationMeta as T, ModelFlags as _, Casing as a, PermdockBucketPolicy as b, Codec as c, Flags as d, ForeignKeyConstraint as f, Insert as g, FunctionsOf as h, BucketPolicyName as i, Simplify as j, Schema as k, ColumnMeta as l, FunctionTypes as m, AnyModels as n, CheckConstraint as o, FunctionMeta as p, BucketMeta as r, ClaimsMeta as s, AnyFunctions as t, DatabaseOf as u, ModelTypes as v, RealtimeTableMeta as w, PermdockTopicPolicy as x, ModelsOf as y };
+export { Schema as A, PrimaryKeyColumn as C, RelationTypes as D, RelationMeta as E, TableMeta as F, UniqueConstraint as I, UniqueKeyName as L, Simplify as M, TableFlags as N, Relations as O, TableKey as P, UniqueWhere as R, PermdockTopicPolicy as S, RealtimeTableMeta as T, Insert as _, BucketPolicyName as a, ModelsOf as b, ClaimsMeta as c, DatabaseOf as d, Flags as f, FunctionsOf as g, FunctionTypes as h, BucketMeta as i, SchemaMeta as j, Row as k, Codec as l, FunctionMeta as m, AnyFunctions as n, Casing as o, ForeignKeyConstraint as p, AnyModels as r, CheckConstraint as s, AccessBucketPolicy as t, ColumnMeta as u, ModelFlags as v, PrimaryKeyValue as w, PermdockBucketPolicy as x, ModelTypes as y, Update as z };