better-supabase 0.5.0 → 0.6.0

package/dist/blocks/attachments/index.js

@@ -0,0 +1,222 @@
+import { n as dbError } from "../../errors-B11Duf73.js";
+import { a as ok, r as err, t as AsyncResult } from "../../result-DzUbqgdW.js";
+import { n as rpcTransport, r as sqlTransport } from "../../block-transport-BLr-ZgLc.js";
+import { O as textOf, c as errorText, d as isRecord, h as optionalText, i as blockCall, k as toInstant, m as optionalInstant, n as applyTemporal, x as recordsOf, y as recordOf } from "../../block-helpers-DWHxHsEQ.js";
+import { t as fromStorageError } from "../../errors-DLjJHPLK.js";
+//#region src/blocks/attachments/attachments.ts
+const STATUSES = [
+	"pending",
+	"clean",
+	"infected",
+	"failed"
+];
+function statusOf(value) {
+	const status = STATUSES.find((candidate) => candidate === value);
+	if (status === void 0) throw new TypeError(`Unknown attachment status ${JSON.stringify(value)}`);
+	return status;
+}
+function attachmentOf(value) {
+	const row = recordOf(value, "attachments");
+	return {
+		id: textOf(row["id"]),
+		organizationId: optionalText(row["organization_id"]),
+		subjectType: optionalText(row["subject_type"]),
+		subjectId: optionalText(row["subject_id"]),
+		bucket: textOf(row["bucket"]),
+		path: textOf(row["object_path"]),
+		name: textOf(row["name"]),
+		mimeType: textOf(row["mime_type"]),
+		size: Number(row["size"]),
+		status: statusOf(row["status"]),
+		scanDetail: optionalText(row["scan_detail"]),
+		metadata: isRecord(row["metadata"]) ? row["metadata"] : {},
+		uploadedBy: optionalText(row["uploaded_by"]),
+		createdAt: toInstant(textOf(row["created_at"])),
+		uploadedAt: optionalInstant(row["uploaded_at"]),
+		scannedAt: optionalInstant(row["scanned_at"])
+	};
+}
+const notFound = () => dbError("not_found", "No attachment you can see has this id", { hint: "ATTACHMENT_NOT_FOUND" });
+function stored(reply) {
+	return AsyncResult.from(async () => {
+		try {
+			const { data, error } = await reply;
+			if (error) return err(fromStorageError(error, "storage.objects"));
+			if (data === null || data === void 0) return err(dbError("network", "Storage returned no data"));
+			return ok(data);
+		} catch (cause) {
+			return err(fromStorageError(cause, "storage.objects"));
+		}
+	});
+}
+function lookup(call, id) {
+	return call("get_attachment", { id }, (value) => value).andThen((value) => Promise.resolve(isRecord(value) ? ok(attachmentOf(value)) : err(notFound())));
+}
+/** Attachments as the caller: the table's and the bucket's policies apply. */
+function createAttachments(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const requireScan = options.requireScan ?? true;
+	const ttl = options.downloadTtl ?? 300;
+	const bucket = (attachment) => options.storage.from(attachment.bucket);
+	/** Why a file can't be read yet, or `undefined` once it can. */
+	const gate = (attachment) => {
+		return attachment.status === "clean" || !requireScan && attachment.status !== "infected" && attachment.uploadedAt !== void 0 ? void 0 : dbError("invalid_request", attachment.status === "infected" ? "The file failed the malware scan" : "The file is not scanned yet", { hint: "ATTACHMENT_NOT_SCANNED" });
+	};
+	const upload = (attachment) => call("create_attachment", {
+		tenant: attachment.organizationId,
+		name: attachment.name,
+		mime_type: attachment.mimeType,
+		size: attachment.size,
+		subject_type: attachment.subjectType,
+		subject_id: attachment.subjectId,
+		metadata: attachment.metadata
+	}, attachmentOf).andThen((created) => stored(bucket(created).createSignedUploadUrl(created.path)).map((url) => ({
+		attachment: created,
+		signedUrl: url.signedUrl,
+		token: url.token
+	})));
+	return {
+		upload,
+		confirm: (id) => call("confirm_attachment", { id }, attachmentOf),
+		get: (id) => lookup(call, id),
+		list: (organizationId, subject) => call("list_attachments", {
+			tenant: organizationId,
+			subject_type: subject?.type,
+			subject_id: subject?.id
+		}, (value) => recordsOf(value, "list_attachments").map(attachmentOf)),
+		download: (id, download = {}) => lookup(call, id).andThen((attachment) => {
+			const blocked = gate(attachment);
+			if (blocked) return Promise.resolve(err(blocked));
+			return stored(bucket(attachment).createSignedUrl(attachment.path, ttl, download.as === void 0 ? void 0 : { download: download.as })).map((url) => ({
+				attachment,
+				signedUrl: url.signedUrl
+			}));
+		}),
+		put: (attachment, file) => upload(attachment).andThen(async ({ attachment: created }) => {
+			const target = bucket(created);
+			if (!target.upload) return err(dbError("invalid_request", "The storage client has no upload", { hint: "ATTACHMENT_STORAGE_CLIENT" }));
+			const sent = await stored(target.upload(created.path, file, {
+				contentType: created.mimeType,
+				upsert: false
+			}));
+			if (!sent.ok) return sent;
+			return call("confirm_attachment", { id: created.id }, attachmentOf);
+		}),
+		read: (id) => lookup(call, id).andThen((attachment) => {
+			const blocked = gate(attachment);
+			if (blocked) return Promise.resolve(err(blocked));
+			return stored(bucket(attachment).download(attachment.path)).map((file) => ({
+				attachment,
+				file
+			}));
+		}),
+		remove: (id) => lookup(call, id).andThen((attachment) => stored(bucket(attachment).remove([attachment.path]))).andThen(() => call("delete_attachment", { id }, (value) => value === true))
+	};
+}
+/**
+* Scans uploaded files with the app's `scan` function and records `clean`,
+* `infected` or `failed`. A file already clean or infected is not scanned
+* again, so replayed events and retried jobs are safe.
+*/
+function createAttachmentScanner(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema);
+	const prefix = `${options.typePrefix ?? "dev.better-supabase"}.`;
+	const record = (id, status, detail) => call("set_attachment_status", {
+		id,
+		status,
+		detail
+	}, (value) => value).andThen((value) => Promise.resolve(isRecord(value) ? ok(attachmentOf(value)) : err(notFound())));
+	const scan = (id, signal) => lookup(call, id).andThen((attachment) => {
+		if (attachment.status === "clean" || attachment.status === "infected") return Promise.resolve(ok(attachment));
+		if (attachment.uploadedAt === void 0) return Promise.resolve(err(dbError("invalid_request", "The file was not uploaded yet", { hint: "ATTACHMENT_NOT_UPLOADED" })));
+		return stored(options.storage.from(attachment.bucket).download(attachment.path)).andThen(async (file) => {
+			let verdict;
+			try {
+				verdict = await options.scan(file, attachment, signal);
+			} catch (cause) {
+				const failed = await record(id, "failed", errorText(cause));
+				return failed.ok ? err(dbError("raised", `The scan failed: ${errorText(cause)}`, { hint: "ATTACHMENT_SCAN_FAILED" })) : failed;
+			}
+			return record(id, verdict.status, verdict.detail);
+		});
+	});
+	return {
+		scan,
+		job: async (payload, _job, signal) => {
+			await scan(payload.attachmentId, signal).orThrow();
+		},
+		sink: () => ({ async send(events) {
+			for (const event of events) {
+				if ((event.type.startsWith(prefix) ? event.type.slice(prefix.length) : event.type) !== "attachment.uploaded" || !isRecord(event.data)) continue;
+				const id = optionalText(event.data["attachmentId"]);
+				if (id !== void 0) await scan(id).orThrow();
+			}
+		} })
+	};
+}
+function scannedOf(value) {
+	const row = recordOf(value, "scanned_objects");
+	const status = textOf(row["status"]);
+	return {
+		bucket: textOf(row["bucket"]),
+		path: textOf(row["object_path"]),
+		status: status === "clean" || status === "infected" || status === "failed" ? status : "pending",
+		detail: optionalText(row["scan_detail"]),
+		scannedAt: optionalInstant(row["scanned_at"])
+	};
+}
+/**
+* The scan gate for objects outside the attachments table, such as a file
+* drive or avatars: scans an object with the app's `scan` function and
+* records the verdict in `scanned_objects`, which storage policies read with
+* `object_clean(bucket_id, name)`. With `options.scanBuckets`, new objects in
+* those buckets get a pending row and an `object.uploaded` event.
+*/
+function createObjectScanner(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema);
+	const prefix = `${options.typePrefix ?? "dev.better-supabase"}.`;
+	const record = (bucket, path, status, detail) => call("set_object_scan", {
+		bucket,
+		path,
+		status,
+		detail
+	}, scannedOf);
+	const scan = (bucket, path, signal) => call("object_scan", {
+		bucket,
+		path
+	}, (value) => isRecord(value) ? scannedOf(value) : void 0).andThen((current) => {
+		if (current?.status === "clean" || current?.status === "infected") return Promise.resolve(ok(current));
+		return stored(options.storage.from(bucket).download(path)).andThen(async (file) => {
+			let verdict;
+			try {
+				verdict = await options.scan(file, {
+					bucket,
+					path
+				}, signal);
+			} catch (cause) {
+				const failed = await record(bucket, path, "failed", errorText(cause));
+				return failed.ok ? err(dbError("raised", `The scan failed: ${errorText(cause)}`, { hint: "ATTACHMENT_SCAN_FAILED" })) : failed;
+			}
+			return record(bucket, path, verdict.status, verdict.detail);
+		});
+	});
+	return {
+		scan,
+		job: async (payload, _job, signal) => {
+			await scan(payload.bucket, payload.path, signal).orThrow();
+		},
+		sink: () => ({ async send(events) {
+			for (const event of events) {
+				if ((event.type.startsWith(prefix) ? event.type.slice(prefix.length) : event.type) !== "object.uploaded" || !isRecord(event.data)) continue;
+				const bucket = optionalText(event.data["bucket"]);
+				const path = optionalText(event.data["path"]);
+				if (bucket !== void 0 && path !== void 0) await scan(bucket, path).orThrow();
+			}
+		} })
+	};
+}
+//#endregion
+export { createAttachmentScanner, createAttachments, createObjectScanner, rpcTransport, sqlTransport };

package/dist/blocks/audit/index.d.ts

@@ -0,0 +1,366 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "../../result-D7y2fT87.js";
+import { L as TableKey, a as AnyModels, i as AnyFunctions } from "../../types-6BdhkmZe.js";
+import { t as SqlClient } from "../../executor-DbvExCFC.js";
+import { i as sqlTransport, r as rpcTransport, t as BlockTransport } from "../../block-transport-DvaoPuZ9.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CKtbFcRv.js";
+import { t as BetterSupabase, zt as WhereInput } from "../../define-CJJkkr1-.js";
+import { r as EventSink, t as CloudEvent } from "../../cloud-event-C1JCc1bH.js";
+import { i as ListDefinition } from "../../list-query-BRt-zDF7.js";
+import { n as AuditCategory } from "../../context-BCrWe7ow.js";
+//#region src/blocks/audit/audit.d.ts
+interface PurgeAuditLogOptions extends BlockTemporalOptions {
+  /** How long entries are kept when `retention` has no answer. Defaults to `1 year`. */
+  readonly olderThan?: number | string;
+  /** The most entries deleted per tenant in one call. Defaults to 10000. */
+  readonly batch?: number;
+  /**
+   * Days a tenant keeps its entries (a plan's retention, say); `undefined`
+   * uses `olderThan`. Called with `null` for entries without a tenant.
+   * Retention shorter than a day is not supported. `setAuditRetention`
+   * reads the days from a column.
+   */
+  readonly retention?: (tenant: string | null) => number | undefined | Promise<number | undefined>;
+}
+type Retention = NonNullable<PurgeAuditLogOptions["retention"]>;
+/**
+ * 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.
+ */
+export declare function purgeAuditLog(sql: SqlClient, options?: PurgeAuditLogOptions): AsyncResult<number>;
+interface AuditRetentionSource {
+  /** `schema.table` holding one row per tenant, e.g. `public.organizations`. */
+  readonly table: string;
+  /** The integer column with the days to keep; `null` uses `olderThan`. */
+  readonly column: string;
+  /** The tenant id column. Defaults to `id`. */
+  readonly key?: string;
+}
+/**
+ * A `retention` callback for `purgeAuditLog` that reads each tenant's days
+ * from a column (a plan's `audit_retention_days`, say). `purgeAuditLog` reads
+ * every tenant's days in one query; a direct call reads one tenant.
+ */
+export declare function setAuditRetention(sql: SqlClient, source: AuditRetentionSource): Retention;
+/** One audit entry as `exportAuditLog` reads it. */
+interface AuditEntry {
+  readonly id: string;
+  readonly occurredAt: Temporal.Instant;
+  /** `insert`, `update` and `delete` for row changes; `event` for `audit_event()`. */
+  readonly op: string;
+  readonly table?: string;
+  readonly record?: string;
+  readonly changed?: readonly string[];
+  readonly actor?: string;
+  readonly actorRole?: string;
+  readonly organizationId?: string;
+  readonly eventType?: string;
+  readonly category?: string;
+  readonly outcome?: string;
+  readonly source?: string;
+  readonly targetType?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface OcsfProduct {
+  readonly name: string;
+  readonly vendor_name?: string;
+  readonly version?: string;
+}
+/**
+ * One entry as an OCSF event (`SPEC_PINS.ocsf`). Row changes are Entity
+ * Management (3004); semantic events are API Activity (6003), with the
+ * activity read from the event type's last segment (`deal.created` is Create).
+ */
+export declare function toOcsf(entry: AuditEntry, product: OcsfProduct): Record<string, unknown>;
+interface ExportAuditLogOptions extends BlockTemporalOptions {
+  /** Only this tenant's entries. */
+  readonly organizationId: string;
+  readonly from?: Temporal.Instant;
+  /** Exclusive. */
+  readonly to?: Temporal.Instant;
+  /** `ndjson` writes entries as they are; `ocsf` maps each with `toOcsf`. */
+  readonly format?: "ndjson" | "ocsf";
+  /** Required for `ocsf`: `metadata.product`. */
+  readonly product?: OcsfProduct;
+  /** Rows per query. Defaults to 1000. */
+  readonly batch?: number;
+  /** Defaults to `better_supabase.audit_events`. */
+  readonly table?: string;
+}
+/**
+ * Streams one tenant's audit entries as newline-delimited JSON, in id
+ * order, one keyset query per batch. Run it with a member's claims (the
+ * `readPolicy` filters) or as the service role. It reads the managed
+ * module's column names; for an adopted log, the version 3 columns or CSV,
+ * use `createAuditLog().export()`, which reads `list_audit_events`.
+ */
+export declare function exportAuditLog(sql: SqlClient, options: ExportAuditLogOptions): ReadableStream<Uint8Array>;
+type AuditSort = "newest" | "oldest";
+type AuditFacet = "table" | "record" | "op" | "actor" | "event" | "category" | "outcome" | "target";
+type AuditListDefinition<M extends AnyModels, T extends TableKey<M>, E> = ListDefinition<M, T, E, AuditSort, AuditFacet, false, "cursor"> & {
+  /** A `where` for `run(db, query, { where })`: entries in `[from, to)`. */
+  between(from?: Temporal.Instant, to?: Temporal.Instant): WhereInput<M, T>;
+};
+/**
+ * A cursor-paged list over the audit table through the Data API or
+ * `ctx.sql` (generate types for the module's schema to get it in your
+ * models; facets follow the managed column names). `createAuditLog().list()`
+ * reads `list_audit_events` instead, with an adopted log's columns mapped.
+ * Filtered by actor,
+ * table, record, event type, category, outcome and target, newest first.
+ * The `readPolicy` and the `restricted` table decide what a member sees.
+ */
+export declare function auditListQuery<M extends AnyModels, D, Fn extends AnyFunctions, E, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, Fn, E>, table: T, options?: {
+  readonly pageSize?: number;
+  readonly maxPageSize?: number;
+}): AuditListDefinition<M, T, E>;
+//#endregion
+//#region src/blocks/audit/csv.d.ts
+/** A CSV export column: a key, or a key and the header to write for it. */
+type AuditCsvColumn = string | {
+  readonly key: string;
+  readonly label: string;
+};
+/** How `export({ format: "csv" })` writes its rows. */
+interface AuditCsvOptions<Columns extends AuditColumns = AuditColumns> {
+  /**
+   * The columns, in order: a key of the record (`eventType`),
+   * `columns.<name>` for a column `metadataColumns` fills, or
+   * `restricted.<field>` (`ip`, `userAgent`, `sessionId`, `metadata`, `old`,
+   * `new` or `changes`) for a caller who may reveal the entries. A restricted
+   * column reads each page through `reveal_audit_entries`, which records
+   * `audit.revealed`, and is empty for entries the caller may not reveal.
+   * Defaults to the built-in columns.
+   */
+  readonly columns?: readonly AuditCsvColumn[];
+  /** Lines written before the header row, one cell each, such as a title. */
+  readonly preamble?: readonly string[];
+  /**
+   * The row to write, by column key. It gets the default row, the record and
+   * its restricted details (only with a restricted column).
+   */
+  readonly formatRow?: (row: Readonly<Record<string, unknown>>, record: AuditRecord<Columns>, details: AuditDetails | undefined) => Readonly<Record<string, unknown>>;
+}
+//#endregion
+//#region src/blocks/audit/sink.d.ts
+interface AuditSinkOptions {
+  /** The type prefix stripped from each event's `type`. Defaults to `dev.better-supabase`. */
+  readonly typePrefix?: string;
+  /**
+   * The category for an event type (without the prefix), from the categories
+   * the SQL modules use. Defaults to `security` for `account.*` and
+   * `support.*`, and no category for the rest.
+   */
+  readonly category?: (eventType: string) => AuditCategory | undefined;
+}
+/**
+ * The audit entry for one CloudEvent: its type without the prefix, its
+ * subject as the record, the tenant from the `tenant` or `partitionkey`
+ * extension (or `data.organizationId`), and the data as metadata. The
+ * idempotency key is the event's source and id, so a redelivery records once.
+ */
+export declare function auditEventOf(event: CloudEvent, options?: AuditSinkOptions): AuditEventInput;
+/**
+ * An `EventSink` that records each CloudEvent in the audit log. `send`
+ * throws when an entry fails, so an outbox relay retries the batch; the
+ * idempotency key keeps the entries already written from repeating.
+ */
+export declare function auditSink(record: (event: AuditEventInput) => AsyncResult<string>, options?: AuditSinkOptions): EventSink;
+//#endregion
+//#region src/blocks/audit/client.d.ts
+/** The adopted log's own columns, by column name, as `metadataColumns` maps them. */
+type AuditColumns = Readonly<Record<string, unknown>>;
+/**
+ * One entry as `list_audit_events` returns it: the module's columns under
+ * stable keys, whatever the adopted log calls them. Fields the log doesn't
+ * have, or the caller may not read, are missing.
+ */
+interface AuditRecord<Columns extends AuditColumns = AuditColumns> {
+  readonly id: string;
+  readonly occurredAt: Temporal.Instant;
+  readonly op?: string;
+  readonly table?: string;
+  readonly record?: string;
+  readonly changed?: readonly string[];
+  readonly old?: Readonly<Record<string, unknown>>;
+  readonly new?: Readonly<Record<string, unknown>>;
+  readonly actorId?: string;
+  readonly actorRole?: string;
+  readonly actorKind?: string;
+  readonly actorLabel?: string;
+  readonly tenant?: string;
+  readonly tenantLabel?: string;
+  readonly impersonatedBy?: string;
+  readonly impersonationReason?: string;
+  readonly supportSession?: string;
+  readonly eventType?: string;
+  readonly category?: string;
+  readonly outcome?: string;
+  readonly source?: string;
+  readonly targetType?: string;
+  readonly targetLabel?: string;
+  readonly summary?: string;
+  readonly requestId?: string;
+  readonly correlationId?: string;
+  readonly scope?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /**
+   * The adopted log's columns that `sql.modules.audit.options.metadataColumns`
+   * fills, by column name. Missing without that option.
+   */
+  readonly columns?: Readonly<Partial<Columns>>;
+}
+/** Where a page ends: pass it as `before` for the next, older page. */
+interface AuditCursor {
+  readonly occurredAt: Temporal.Instant;
+  readonly id: string;
+}
+type OneOrMany = string | readonly string[];
+interface AuditListOptions {
+  readonly organizationId?: OneOrMany;
+  readonly eventType?: OneOrMany;
+  readonly actorId?: OneOrMany;
+  readonly targetType?: OneOrMany;
+  readonly record?: OneOrMany;
+  readonly category?: OneOrMany;
+  readonly outcome?: OneOrMany;
+  readonly source?: OneOrMany;
+  readonly actorKind?: OneOrMany;
+  readonly correlationId?: OneOrMany;
+  readonly search?: string;
+  readonly order?: "desc" | "asc";
+  readonly count?: boolean;
+  /** Entries at or after this instant. */
+  readonly since?: Temporal.Instant;
+  /** Entries before this instant. */
+  readonly until?: Temporal.Instant;
+  /** `page.next` of the previous page; `undefined` starts at the newest. */
+  readonly cursor?: AuditCursor | undefined;
+  /** Default 50, at most 1000. */
+  readonly limit?: number;
+  readonly offset?: number;
+}
+interface AuditPage<Columns extends AuditColumns = AuditColumns> {
+  readonly entries: readonly AuditRecord<Columns>[];
+  /** The cursor of the next page, or `undefined` on the last one. */
+  readonly next: AuditCursor | undefined;
+  readonly total?: number;
+}
+/** The restricted details `reveal` returns, when the entry has them. */
+interface AuditDetails {
+  readonly entry: string;
+  readonly old?: Readonly<Record<string, unknown>>;
+  readonly new?: Readonly<Record<string, unknown>>;
+  readonly ip?: string;
+  readonly userAgent?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly sessionId?: string;
+  readonly changes?: unknown;
+}
+interface AuditExportOptions<Columns extends AuditColumns = AuditColumns> extends Omit<AuditListOptions, "before" | "limit" | "count">, AuditCsvOptions<Columns> {
+  /**
+   * `ndjson` (default) writes the records as they are, `csv` a spreadsheet
+   * with a header row, `ocsf` each record mapped with `toOcsf`.
+   */
+  readonly format?: "ndjson" | "csv" | "ocsf";
+  /** Required for `ocsf`: `metadata.product`. */
+  readonly product?: OcsfProduct;
+  /** Entries per call. Default 500. */
+  readonly batch?: number;
+}
+/** The part of `supabase.storage.from(bucket)` an export upload uses. */
+interface AuditExportBucket {
+  upload(path: string, body: Blob, options?: {
+    contentType?: string;
+    upsert?: boolean;
+  }): PromiseLike<{
+    readonly data: unknown;
+    readonly error: unknown;
+  }>;
+  createSignedUrl?(path: string, expiresIn: number, options?: {
+    download?: string | boolean;
+  }): PromiseLike<{
+    readonly data: {
+      readonly signedUrl: string;
+    } | null;
+    readonly error: unknown;
+  }>;
+}
+interface AuditExportToStorageOptions<Columns extends AuditColumns = AuditColumns> extends AuditExportOptions<Columns> {
+  readonly storage: {
+    from(bucket: string): AuditExportBucket;
+  };
+  readonly bucket: string;
+  /** The object path, such as `{organizationId}/audit/{jobId}.csv`. */
+  readonly path: string;
+  /** Also sign a download URL that lives this many seconds. */
+  readonly signedUrlTtl?: number;
+}
+interface AuditEventInput {
+  readonly eventType: string;
+  readonly category?: string;
+  readonly outcome?: string;
+  readonly source?: string;
+  readonly targetType?: string;
+  readonly record?: string;
+  readonly organizationId?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly idempotencyKey?: string;
+  readonly restricted?: Readonly<Record<string, unknown>>;
+  readonly summary?: string;
+  readonly targetLabel?: string;
+  readonly correlationId?: string;
+  readonly actorId?: string;
+  readonly actorKind?: string;
+  readonly actorLabel?: string;
+  readonly ip?: string;
+  readonly userAgent?: string;
+  readonly sessionId?: string;
+  readonly requestId?: string;
+  readonly scope?: string;
+}
+interface AuditLogOptions extends BlockTemporalOptions {
+  /** `sqlTransport(ctx.postgres)` for members, or `rpcTransport` over an API schema. */
+  readonly transport: BlockTransport;
+  /** The audit module's schema, or its API schema. Default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+interface AuditLog<Columns extends AuditColumns = AuditColumns> {
+  record(event: AuditEventInput): AsyncResult<string>;
+  /** A page of the entries the caller can read, newest first. */
+  list(options?: AuditListOptions): AsyncResult<AuditPage<Columns>>;
+  /**
+   * The restricted details of one entry for a caller with the reveal
+   * permission in its tenant (or platform staff); the reveal is itself
+   * recorded as `audit.revealed`. `not_found` otherwise.
+   */
+  reveal(entryId: string): AsyncResult<AuditDetails>;
+  /** Every matching entry as NDJSON, CSV or OCSF, read page by page as the caller. */
+  export(options?: AuditExportOptions<Columns>): ReadableStream<Uint8Array>;
+  /**
+   * Writes an export to a Storage object, for a job that runs it in the
+   * background (the data lifecycle export bucket, say), and returns the path
+   * and a signed URL when `signedUrlTtl` is set.
+   */
+  exportToStorage(options: AuditExportToStorageOptions<Columns>): AsyncResult<{
+    readonly path: string;
+    readonly url: string | undefined;
+  }>;
+  /**
+   * An `EventSink` that records CloudEvents, for `forwardBlockEvents`,
+   * `forwardMutations`, an outbox relay or the server's `audit` option.
+   * Build the log on a service-role transport so the event's actor counts.
+   */
+  sink(options?: AuditSinkOptions): EventSink;
+}
+/**
+ * The audit log over the `audit` module's functions, as the caller: the
+ * read policy decides what `list` and `export` return, and column mappings
+ * of an adopted log are already applied.
+ */
+export declare function createAuditLog<Columns extends AuditColumns = AuditColumns>(options: AuditLogOptions): AuditLog<Columns>;
+//#endregion
+export { type AuditColumns, type AuditCsvColumn, type AuditCsvOptions, type AuditCursor, type AuditDetails, type AuditEntry, type AuditEventInput, type AuditExportBucket, type AuditExportOptions, type AuditExportToStorageOptions, type AuditFacet, type AuditListDefinition, type AuditListOptions, type AuditLog, type AuditLogOptions, type AuditPage, type AuditRecord, type AuditRetentionSource, type AuditSinkOptions, type AuditSort, type BlockTransport, type ExportAuditLogOptions, type OcsfProduct, type PurgeAuditLogOptions, rpcTransport, sqlTransport };