better-supabase 0.8.0 → 0.10.0

package/dist/blocks/waitlist/index.js

@@ -1,7 +1,12 @@
 import { n as isRecord } from "../../guards-6F2bCtQR.js";
-import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-bAKh-dGc.js";
-import { N as toInstant, S as recordOf, _ as optionalInstant, d as instantArg, i as blockCall, j as textOf, n as applyTemporal, v as optionalText, w as recordsOf } from "../../block-helpers-Cy3pB96I.js";
-import { r as hookError, t as authHook } from "../../verify-CJbYfADA.js";
+import { t as waitlistSqlOptions } from "../../options-EsUh744F.js";
+import { n as event, t as defineEvents } from "../../event-map-Dy2vKHai.js";
+import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-G4t1umrR.js";
+import { C as optionalText, D as recordOf, I as textOf, R as toInstant, S as optionalInstant, k as recordsOf, m as instantArg, n as applyTemporal, o as blockCall } from "../../block-helpers-BfVCR5Fc.js";
+import { r as withBlockHooks } from "../../block-hooks-ByKlh8Qy.js";
+import { n as blockFields } from "../../block-fields-BANwJ9Y_.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { r as hookError, t as authHook } from "../../verify-C9D_jjsQ.js";
 //#region src/blocks/waitlist/waitlist.ts
 const STATUSES = /* @__PURE__ */ new Set([
 	"waiting",
@@ -27,7 +32,8 @@ function entryOf(value) {
 		userId: optionalText(row["user_id"]),
 		decidedBy: optionalText(row["decided_by"]),
 		decidedAt: optionalInstant(row["decided_at"]),
-		createdAt: toInstant(textOf(row["created_at"]))
+		createdAt: toInstant(textOf(row["created_at"])),
+		fields: isRecord(row["fields"]) ? row["fields"] : {}
 	};
 }
 function codeOf(value) {
@@ -56,18 +62,21 @@ function generateInviteCode() {
 		12
 	].map((at) => chars.slice(at, at + 4).join("")).join("-");
 }
+/** The `waitlist` SQL module as typed calls. */
 function createWaitlist(options) {
 	applyTemporal(options);
 	const call = blockCall(options.transport, options.schema, options.mappers);
+	const fields = blockFields(options.fields, "waitlist entry fields");
 	const decide = (entryId, approve) => call("decide_waitlist_entry", {
 		id: entryId,
 		approve
-	}, entryOf);
-	return {
-		join: (email, more = {}) => call("join_waitlist", {
+	}, entryOf).andThen(fields.row);
+	return withBlockHooks({
+		join: (email, more = {}) => fields.args(more.fields).andThen((checked) => call("join_waitlist", {
 			email,
 			referrer: more.referrer ?? null,
-			metadata: more.metadata ?? {}
+			metadata: more.metadata ?? {},
+			fields: checked
 		}, (value) => {
 			const row = recordOf(value, "join_waitlist");
 			const status = statusOf(row["status"]);
@@ -75,12 +84,12 @@ function createWaitlist(options) {
 				position: optionalNumber(row["position"]),
 				status: status === "rejected" ? "waiting" : status
 			};
-		}),
+		})),
 		entries: (query = {}) => call("list_waitlist", {
 			status: query.status === void 0 ? "waiting" : query.status,
 			page_size: query.limit ?? 50,
 			after_position: query.afterPosition ?? null
-		}, (value) => recordsOf(value, "list_waitlist").map(entryOf)),
+		}, (value) => recordsOf(value, "list_waitlist").map(entryOf)).andThen(fields.rows),
 		approve: (entryId) => decide(entryId, true),
 		reject: (entryId) => decide(entryId, false),
 		createCode: (input = {}) => {
@@ -105,7 +114,10 @@ function createWaitlist(options) {
 				role: optionalText(row["role"])
 			};
 		})
-	};
+	}, options.hooks, {
+		block: "waitlist",
+		...options.logger ? { logger: options.logger } : {}
+	});
 }
 /**
 * The before-user-created Auth hook: lets an address sign up when it is
@@ -130,4 +142,26 @@ function waitlistHook(options) {
 	}, options.verify);
 }
 //#endregion
-export { createWaitlist, dbTransport, generateInviteCode, rpcTransport, sqlTransport, waitlistHook };
+//#region src/blocks/waitlist/events.ts
+/** The `waitlist` block's event types, for its manifest and `onBlockEvent`. */
+const waitlistEvents = defineEvents({
+	"organization.member_added": event(),
+	"waitlist.approved": event(),
+	"waitlist.rejected": event(),
+	"invite_code.created": event(),
+	"invite_code.revoked": event()
+});
+//#endregion
+//#region src/blocks/waitlist/manifest.ts
+/** The `waitlist` block's manifest (ADR 0029). */
+const waitlistBlock = defineBlock({
+	name: "waitlist",
+	sql: ["waitlist"],
+	options: { waitlist: waitlistSqlOptions },
+	events: waitlistEvents,
+	create: createWaitlist,
+	category: "growth",
+	recipes: ["waitlist-signup"]
+});
+//#endregion
+export { createWaitlist, dbTransport, generateInviteCode, rpcTransport, sqlTransport, waitlistBlock, waitlistEvents, waitlistHook };

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

@@ -1,151 +1,149 @@
 /// <reference lib="esnext.temporal" />
-import { t as AsyncResult, w as ErrorMapper } from "../../result-BchM1XZn.js";
-import { t as SqlClient } from "../../executor-ngjKL_Pe.js";
-import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-inD4fFq-.js";
-import { m as RequestContext } from "../../plugin-CPK2HsbY.js";
-import { a as EventHub } from "../../events-D1BOCll8.js";
-import { r as BlockTemporalOptions } from "../../block-helpers-C0Xj8War.js";
-import { t as BlockProblemOptions } from "../../problem-TvGdxO1t.js";
-import { i as EventSink } from "../../cloud-event-Dune0KI7.js";
-import { a as verifySharedSecret, i as signWebhook, n as VerifyOptions, o as verifyWebhook, r as WebhookInput, t as VerifiedWebhook } from "../../signatures-BRS_p3WD.js";
-import { a as DatabaseWebhookPayload, c as hookError, d as stripeInboxVerify, f as verifyStripeWebhook, i as DatabaseChange, l as isDatabaseWebhook, n as AuthHookKind, o as authHook, r as AuthHooks, s as databaseChange, t as AuthHookError, u as signStripeWebhook } from "../../verify-C91Wyp40.js";
-import { _ as PublicUrlOptions, a as hmacSigner, b as publicUrl, c as WebhookSecretStore, d as WebhookPolicyError, f as WebhookRequest, g as AllowUrl, h as fetchTransport, i as WebhookSigner, l as sqlSecretStore, m as WebhookTransport, n as StandardWebhooksOptions, o as standardWebhooks, p as WebhookResponse, r as WebhookSignInput, s as RotateSecretOptions, t as HmacSignerOptions, u as FetchTransportOptions, v as ResolveHost, y as isPublicAddress } from "../../signers-cpdmZYrv.js";
+import { f as Result, t as AsyncResult, w as ErrorMapper } from "../../result-Cj3yWhjH.js";
+import { U as IncomingWebhookEventData, ht as WebhookEventData, o as EventHub, wt as Events } from "../../events-CtAHxPal.js";
+import { m as RequestContext } from "../../plugin-D5OIaP93.js";
+import { i as CredentialRef, o as CredentialToken, r as CredentialProvider } from "../../provider-CQ1SrhLa.js";
+import { n as SqlClient } from "../../executor-DzJQVTE2.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-NbUJygA7.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-7pMBVsE6.js";
+import { n as BlockHooks } from "../../block-hooks-C_WaodoA.js";
+import { _ as Jobs, g as JobHandler, x as QueueSchemas } from "../../types-P1S1cj6N.js";
+import { t as BlockProblemOptions } from "../../problem-CEjyhV5T.js";
+import { i as EventSink, t as CloudEvent } from "../../cloud-event-bwsBwVNG.js";
+import { g as SubscriberPolicy, i as AuthorizationHooks } from "../../authorization-hooks-Do5djkpz.js";
+import { s as BlockOf } from "../../define-block-BlHQxDIQ.js";
+import { a as verifySharedSecret, i as signWebhook, n as VerifyOptions, o as verifyWebhook, r as WebhookInput, t as VerifiedWebhook } from "../../signatures-BMdJ7neI.js";
+import { a as DatabaseWebhookPayload, c as hookError, d as stripeInboxVerify, f as verifyStripeWebhook, i as DatabaseChange, l as isDatabaseWebhook, n as AuthHookKind, o as authHook, r as AuthHooks, s as databaseChange, t as AuthHookError, u as signStripeWebhook } from "../../verify-3NLjUIER.js";
+import { A as IncomingVerify, C as isPublicAddress, D as IncomingDelivery, E as CreatedIncomingWebhook, F as UpdateIncomingWebhookInput, I as UpdatedIncomingWebhook, M as IncomingWebhooks, N as IncomingWebhooksOptions, O as IncomingDestination, P as RotatedIncomingSecret, S as ResolveHost, T as CreateIncomingWebhookInput, _ as WebhookResponse, a as WebhookSignInput, b as AllowUrl, c as standardWebhooks, d as RotateSecretOptions, f as WebhookSecretStore, g as WebhookRequest, h as WebhookPolicyError, i as StandardWebhooksOptions, j as IncomingWebhook, k as IncomingDestinationResult, l as standardWebhooksAsymmetric, m as FetchTransportOptions, n as HmacSignerOptions, o as WebhookSigner, p as sqlSecretStore, r as RawSigner, s as hmacSigner, t as AsymmetricWebhooksOptions, u as webhookPublicKey, v as WebhookTransport, w as publicUrl, x as PublicUrlOptions, y as fetchTransport } from "../../signers-BjSgNAXP.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/core/hmac.d.ts
 /** Constant-time string comparison. */
 export declare function timingSafeEqual(a: string, b: string): boolean;
 //#endregion
-//#region src/blocks/webhooks/incoming-types.d.ts
-/** How a delivery proves it came from the sender. */
-type IncomingVerify = "none" | "standard-webhooks" | "hmac-sha256" | "shared-secret";
-interface IncomingWebhooksOptions extends BlockProblemOptions, BlockTemporalOptions {
-  /** The schema of the `webhooks-in` module. Defaults to `better_supabase`. */
-  readonly schema?: string;
-  /** The webhook inbox source deliveries are stored under. Defaults to `webhook-in`. */
+//#region src/blocks/webhooks/incoming.d.ts
+/** The header that carries an endpoint's id on stored deliveries. */
+export declare const INCOMING_ENDPOINT_HEADER = "x-bs-endpoint-id";
+/**
+ * Tenant-owned trigger URLs over the `webhooks-in` SQL module: create
+ * endpoints, then route `/hooks/<token>` to `receive`. Deliveries land in
+ * the webhook inbox (`createWebhookInbox`), where a worker processes them,
+ * or in `options.destination`.
+ */
+export declare function createIncomingWebhooks(options: IncomingWebhooksOptions): IncomingWebhooks;
+//#endregion
+//#region src/blocks/webhooks/destinations.d.ts
+/**
+ * Stores deliveries in the webhook inbox under `source` (the delivery's
+ * source when unset), with the endpoint's tenant and the id
+ * `<endpoint id>:<message id>`. The default destination of
+ * `createIncomingWebhooks`.
+ */
+export declare function inboxDestination(sql: SqlClient, options?: {
   readonly source?: string;
+}): IncomingDestination;
+interface JobsDestinationOptions<Q extends QueueSchemas, N extends Extract<keyof Q, string>> {
+  readonly queue: N;
   /**
-   * Deliveries per endpoint and period, counted with the `rate-limit`
-   * module's `hit_rate_limit`. Unset: no limit.
+   * The job payload for a delivery, checked by the queue's schema. Unset, the
+   * queue receives the delivery itself.
    */
-  readonly rateLimit?: {
-    readonly max: number;
-    /** Seconds, or a Postgres interval such as `1 minute`. */
-    readonly period: number | string;
-  };
-  /** Request headers stored with each delivery. Defaults to none. */
-  readonly keepHeaders?: readonly string[];
-}
-interface CreateIncomingWebhookInput {
-  readonly tenant: string;
-  readonly name: string;
-  /** Defaults to `none`: the token in the URL is the only credential. */
-  readonly verify?: IncomingVerify;
-  readonly metadata?: Readonly<Record<string, unknown>>;
-  /** The header that carries the HMAC for `hmac-sha256`. Defaults to `x-signature`. */
-  readonly signatureHeader?: string;
-  /** The record the endpoint belongs to, a type from `options.subjects`. */
-  readonly subject?: {
-    readonly type: string;
-    readonly id: string;
-  };
+  readonly payload?: (delivery: IncomingDelivery) => StandardSchemaV1.InferInput<Q[N]>;
+  /** Defaults to the queue's default (5). */
+  readonly maxAttempts?: number;
 }
-/** An endpoint as members see it: everything but the token and secret. */
-interface IncomingWebhook {
-  readonly id: string;
-  readonly tenant: string;
-  readonly name: string;
-  readonly verify: IncomingVerify;
-  readonly signatureHeader: string | null;
-  readonly enabled: boolean;
-  readonly maxBodyBytes: number;
-  readonly receiveCount: number;
-  readonly lastReceivedAt: string | null;
-  readonly lastStatus: number | null;
-  readonly metadata: Readonly<Record<string, unknown>>;
-  readonly subject: {
-    readonly type: string;
-    readonly id: string;
-  } | null;
-  readonly createdBy: string | null;
-  readonly createdAt: string;
+/**
+ * Enqueues each delivery once on a jobs queue (`jobs.enqueueOnce`) with the
+ * dedupe key `<endpoint id>:<message id>` and the endpoint's tenant as the
+ * job's tenant. A repeat is a duplicate while the job waits, runs or stays
+ * archived; `jobs.purge` ends that window.
+ */
+export declare function jobsDestination<Q extends QueueSchemas, N extends Extract<keyof Q, string>>(jobs: Jobs<Q>, options: JobsDestinationOptions<Q, N>): IncomingDestination;
+//#endregion
+//#region src/blocks/webhooks/encoders.d.ts
+/** The endpoint an encoder writes for. */
+interface WebhookEncodeTarget {
+  readonly url: string;
+  /** The endpoint takes many events per request. */
+  readonly batch: boolean;
+  readonly tenant: string | null;
 }
-/** A new endpoint: its token (for the URL) and secret are shown once. */
-interface CreatedIncomingWebhook {
-  readonly id: string;
-  readonly tenant: string;
-  readonly name: string;
-  readonly verify: IncomingVerify;
-  readonly token: string;
-  readonly secret: string | null;
-  readonly signatureHeader: string | null;
-  readonly subject: {
-    readonly type: string;
-    readonly id: string;
-  } | null;
+/** The request body and the headers that describe it, such as `content-type`. */
+interface WebhookEncoded {
+  readonly body: string;
+  readonly headers: Readonly<Record<string, string>>;
 }
-interface UpdateIncomingWebhookInput {
-  readonly name?: string;
-  readonly metadata?: Readonly<Record<string, unknown>>;
-  readonly verify?: IncomingVerify;
-  readonly signatureHeader?: string;
+/**
+ * What a response means when the status alone doesn't tell: a collector
+ * that answers 200 with an error code, or accepts part of a batch.
+ * `retry` tries the delivery again; `dead` dead-letters it.
+ */
+interface WebhookVerdict {
+  readonly outcome: "succeeded" | "retry" | "dead";
+  readonly error?: string;
 }
-interface UpdatedIncomingWebhook {
-  readonly id: string;
-  readonly tenant: string;
+/**
+ * Turns claimed deliveries, as CloudEvents, into the request one endpoint
+ * `format` expects. Versioned: a breaking change to this contract ships a
+ * new `apiVersion`.
+ */
+interface WebhookEncoder {
+  readonly apiVersion: 1;
+  /** The endpoint `format` it serves: lowercase letters, digits and dashes. */
   readonly name: string;
-  readonly verify: IncomingVerify;
-  readonly secret: string | null;
-  readonly signatureHeader: string | null;
-  readonly metadata: Readonly<Record<string, unknown>>;
-}
-interface RotatedIncomingSecret {
-  readonly secret: string;
-  readonly previousSecretExpiresAt: Temporal.Instant | null;
-}
-interface IncomingWebhooks {
   /**
-   * The route for `/hooks/<token>`: finds the endpoint, checks the body
-   * size, the rate limit and the signature, stores the delivery in the
-   * webhook inbox with the endpoint's tenant and answers 202 (200 for a
-   * repeated delivery). A delivery repeats when its signed `webhook-id`
-   * does (`standard-webhooks`), when its body does (`hmac-sha256`, whose
-   * signature covers only the body), or when its `webhook-id` header does
-   * (`none`). Needs a service connection.
+   * Adds the Standard Webhooks signature headers. Collectors that
+   * authenticate with a token from `credential_ref` don't need them.
    */
-  receive(request: Request, token: string): Promise<Response>;
-  /** Creates an endpoint for a tenant; the caller needs `webhooks.manage`. */
-  create(input: CreateIncomingWebhookInput): AsyncResult<CreatedIncomingWebhook>;
-  /** A new token, and with `rotateSecret` a new secret. */
-  rotate(id: string, options?: {
-    readonly rotateSecret?: boolean;
-  }): AsyncResult<{
-    readonly token: string;
-    readonly secret: string | null;
-  }>;
-  rotateSecret(id: string, options?: {
-    readonly grace?: Temporal.Duration | string;
-  }): AsyncResult<RotatedIncomingSecret>;
-  update(id: string, input: UpdateIncomingWebhookInput): AsyncResult<UpdatedIncomingWebhook>;
-  setEnabled(id: string, enabled: boolean): AsyncResult<boolean>;
-  remove(id: string): AsyncResult<boolean>;
-  /**
-   * A tenant's endpoints, or one subject's, as the caller sees them (the
-   * read policy hides endpoints whose subject they can't read).
-   */
-  list(tenant: string, subject?: {
-    readonly type: string;
-    readonly id?: string;
-  }): AsyncResult<readonly IncomingWebhook[]>;
+  readonly signed: boolean;
+  encode(events: readonly CloudEvent[], target: WebhookEncodeTarget): WebhookEncoded | Promise<WebhookEncoded>;
+  /** The headers a `credential_ref` token becomes. Defaults to the token's own `headers`. */
+  authorize?(token: CredentialToken): Readonly<Record<string, string>>;
+  /** Reads the response; `undefined` leaves it to the status and the retry policy. */
+  classify?(response: WebhookResponse): WebhookVerdict | undefined;
 }
-//#endregion
-//#region src/blocks/webhooks/incoming.d.ts
-/** The header that carries an endpoint's id on stored deliveries. */
-export declare const INCOMING_ENDPOINT_HEADER = "x-bs-endpoint-id";
+/** The default format: CloudEvents over HTTP, structured or batched per endpoint. */
+export declare function cloudEvents(): WebhookEncoder;
 /**
- * Tenant-owned trigger URLs over the `webhooks-in` SQL module: create
- * endpoints, then route `/hooks/<token>` to `receive`. Deliveries land in
- * the webhook inbox (`createWebhookInbox`), where a worker processes them.
+ * The 0.8 body, `{ type, timestamp, data }`, with `data` from `transform`;
+ * a batch is a JSON array of them. Signed with Standard Webhooks like
+ * `cloudevents`.
  */
-export declare function createIncomingWebhooks(sql: SqlClient, options?: IncomingWebhooksOptions): IncomingWebhooks;
+export declare function standardEnvelope(): WebhookEncoder;
+interface OtlpLogsOptions {
+  /** The resource's `service.name`. Defaults to `better-supabase`. */
+  readonly serviceName?: string;
+  /** More resource attributes, such as `deployment.environment.name`. */
+  readonly resource?: Readonly<Record<string, string>>;
+  /** The `severityNumber` of each record. Defaults to 9 (INFO). */
+  readonly severity?: (event: CloudEvent) => number;
+}
+/**
+ * OTLP/HTTP logs in the JSON encoding: one `ExportLogsServiceRequest` per
+ * request, a log record per event with the CloudEvents attributes. Point
+ * the endpoint at a collector's `/v1/logs`.
+ */
+export declare function otlpLogs(options?: OtlpLogsOptions): WebhookEncoder;
+interface SplunkHecOptions {
+  /** The index to write to. Defaults to the token's default index. */
+  readonly index?: string;
+  /** Defaults to `_json`. */
+  readonly sourcetype?: string;
+  /** Defaults to the CloudEvents `source`. */
+  readonly source?: string;
+  readonly host?: string;
+}
+/**
+ * The Splunk HTTP Event Collector's event format: one JSON object per
+ * event, the CloudEvent as `event`. Point the endpoint at
+ * `/services/collector/event` and set `credential_ref` to the HEC token.
+ */
+export declare function splunkHec(options?: SplunkHecOptions): WebhookEncoder;
+/**
+ * RFC 8935 push delivery of Security Event Tokens: the body is the compact
+ * SET from the delivery's `data.set`, one per request. The shared-signals
+ * block creates these endpoints (`format: 'set'`) and dispatches to them.
+ */
+export declare function securityEvents(): WebhookEncoder;
 //#endregion
 //#region src/blocks/webhooks/outgoing-types.d.ts
 /** One claimed delivery, as `shouldDeliver`, `transform` and `headers` see it. */
@@ -160,6 +158,25 @@ interface WebhookDelivery {
   readonly tenant: string | null;
   readonly eventId: string | null;
   readonly runId: string | null;
+  /** The CloudEvents `subject`, such as `invoices/123`, when the event has one. */
+  readonly subject: string | null;
+  /** The user who owns the endpoint, or `null` for a service principal's endpoint. */
+  readonly owner: string | null;
+  /**
+   * The tenant's default service principal, which an endpoint without an
+   * owner runs as, when the service-principals module is installed.
+   */
+  readonly principal: string | null;
+  /** The permissions a service principal's endpoint declares. */
+  readonly permissions: readonly string[] | null;
+  /** The endpoint takes CloudEvents batches. */
+  readonly batch: boolean;
+  /** `v1` signs with the endpoint's secrets, `v1a` with `asymmetricSigner`. */
+  readonly signing: "v1" | "v1a";
+  /** The encoder that writes the request body, such as `cloudevents` or `otlp-logs`. */
+  readonly format: string;
+  /** The credential whose token authenticates the request, if any. */
+  readonly credentialRef: CredentialRef | null;
   readonly createdAt: Temporal.Instant;
 }
 interface RetryPolicy {
@@ -167,7 +184,8 @@ interface RetryPolicy {
   readonly maxAttempts?: number;
   /**
    * Seconds before the next attempt. Defaults to 5 seconds, 5 minutes, 30
-   * minutes, 2 hours, 5 hours, then 10 hours, each with full jitter. A
+   * minutes, 2 hours, 5 hours, then 10 hours. Each wait is at least half
+   * its step and at least a second, plus a random share of the rest. A
    * receiver's `Retry-After` wins when it asks for longer, up to a day.
    */
   readonly backoff?: (attempt: number) => number;
@@ -177,30 +195,86 @@ interface RetryPolicy {
 interface WebhooksOptions extends BlockTemporalOptions {
   /** `sqlTransport(postgres.admin)` for the worker, or the user's connection to manage. */
   readonly transport: BlockTransport;
-  /** `sql.modules.webhooks-out.schema`. Defaults to `better_supabase`. */
+  /** The module schema, or its API schema: `defineBlocks` passes it from `blocks.generated.ts`. Default `better_supabase`. */
   readonly schema?: string;
   /** Defaults to `fetchTransport({ allowUrl })`. */
   readonly http?: WebhookTransport;
   /** Used by the default `http`. Defaults to `publicUrl()`. */
   readonly allowUrl?: AllowUrl;
-  /** Defaults to `standardWebhooks()`. */
+  /** Signs deliveries to `v1` endpoints. Defaults to `standardWebhooks()`. */
   readonly signer?: WebhookSigner;
+  /**
+   * Signs deliveries to endpoints with `signing = 'v1a'`, usually
+   * `standardWebhooksAsymmetric({ signer })`. Without it those deliveries
+   * are dead-lettered.
+   */
+  readonly asymmetricSigner?: WebhookSigner;
   /** Defaults to `sqlSecretStore(transport)`. */
   readonly secrets?: WebhookSecretStore;
+  /**
+   * Encoders for endpoint `format`s beyond, or replacing, the built-in
+   * `cloudevents`, `standard`, `otlp-logs`, `splunk-hec` and `set`. A
+   * delivery to a format without an encoder is dead-lettered.
+   */
+  readonly encoders?: readonly WebhookEncoder[];
+  /**
+   * The format of an endpoint whose row has none, such as an adopted table
+   * that doesn't map `format` or holds `null`.
+   * `blocks.webhooks-out.options.defaultFormat`, which `defineBlocks` passes,
+   * and the column default. Defaults to `cloudevents`.
+   */
+  readonly defaultFormat?: string;
+  /**
+   * Resolves an endpoint's `credential_ref` to the token that
+   * authenticates its requests. Without it, such deliveries are
+   * dead-lettered.
+   */
+  readonly credentials?: CredentialProvider;
   readonly retry?: RetryPolicy;
   /** Return `false` (or throw) to cancel a delivery instead of sending it. */
   readonly shouldDeliver?: (delivery: WebhookDelivery) => boolean | Promise<boolean>;
+  /** The CloudEvent's `data`. Defaults to the published payload. */
+  readonly transform?: (delivery: WebhookDelivery) => unknown;
   /**
-   * The JSON body. Defaults to the Standard Webhooks envelope,
-   * `{ type, timestamp, data }`.
+   * The CloudEvents `source`, an absolute URI. Defaults to `/webhooks` on
+   * `appUrl`, or `urn:better-supabase:webhooks` without one.
    */
-  readonly transform?: (delivery: WebhookDelivery) => unknown;
+  readonly source?: string;
+  /** The app's public URL, such as `https://app.example.com`. */
+  readonly appUrl?: string;
+  /** Prepended to each type with a dot, such as `com.example`. Defaults to none. */
+  readonly typePrefix?: string;
+  /**
+   * The CloudEvents `dataschema`: an absolute URI, or a function that picks
+   * one per delivery or leaves it out with `undefined`.
+   */
+  readonly dataschema?: string | ((delivery: WebhookDelivery) => string | undefined);
+  /**
+   * The W3C `traceparent` of the delivery, sent as the CloudEvents
+   * `traceparent` extension. A value that is not a valid trace context is
+   * left out.
+   */
+  readonly traceparent?: (delivery: WebhookDelivery) => string | undefined;
+  /**
+   * Narrows each event's claimed deliveries to the endpoints whose owner
+   * may read it. A delivery it leaves out is canceled; a throw retries every
+   * delivery of the event. Each delivery is checked against its own stored
+   * `subject`. Defaults to `authorization.delivery.subscribers`; with
+   * `authorization` but no such policy, to `subjectReaders(transport)`, so
+   * an event about a `config.subjects` record only reaches endpoints whose
+   * owner (or service principal) may read that record.
+   */
+  readonly subscribers?: SubscriberPolicy;
+  /** `server.authorization`, for its `delivery.subscribers` policy. */
+  readonly authorization?: Pick<AuthorizationHooks, "delivery">;
   /** Extra headers, e.g. an `idempotency-key`. */
   readonly headers?: (delivery: WebhookDelivery) => Readonly<Record<string, string>>;
   /** Characters of the response body kept in the log. Defaults to 2000. */
   readonly responseBodyLimit?: number;
   /** `betterSupabase.events`, for `webhook.*` block events. */
   readonly events?: EventHub;
+  /** `withBlockHooks` hooks around the client's methods, such as a check before `publish`. */
+  readonly hooks?: BlockHooks<Webhooks>;
   readonly context?: RequestContext;
   /** Error mappers that run before the built-in ones, as in `betterSupabase.mapError()`. */
   readonly mappers?: readonly ErrorMapper[];
@@ -211,6 +285,14 @@ interface PublishInput {
   readonly tenant?: string;
   /** With an id, publishing it again never queues a second delivery. */
   readonly id?: string;
+  /** What the event is about, such as `invoices/123`: the CloudEvents `subject`. */
+  readonly subject?: string;
+  /**
+   * The permission an endpoint owner needs in the tenant to receive the
+   * event, such as `invoices.read`. Defaults to the module's view
+   * permission (`webhooks.read`).
+   */
+  readonly readPermission?: string;
 }
 interface DispatchInput {
   readonly endpointId: string;
@@ -249,6 +331,12 @@ interface WebhooksRouteOptions extends DeliverWebhooksOptions, BlockProblemOptio
 interface Webhooks {
   /** Queues the event for each subscribed endpoint; returns how many. */
   publish(event: PublishInput): AsyncResult<number>;
+  /**
+   * Queues up to 1000 events in one `publish_webhook_events` call, with
+   * `publish`'s checks per event: one `Result` (how many endpoints) per
+   * event, in order. The outer result fails only when the call does.
+   */
+  publishMany(events: readonly PublishInput[]): AsyncResult<readonly Result<number>[]>;
   /** Sends to one endpoint outside its subscriptions; returns the delivery id. */
   dispatch(input: DispatchInput): AsyncResult<string>;
   /** Queues a finished delivery again. */
@@ -265,6 +353,22 @@ interface Webhooks {
    * (`dev.better-supabase` by default, the relay's default) and the dot.
    */
   sink(options?: WebhookSinkOptions): EventSink;
+  /**
+   * Deletes up to `batch` finished deliveries created before `olderThan`
+   * (`purge_webhook_deliveries`); returns how many. Keep `olderThan` above
+   * the window you republish in: a purged event id can be queued again.
+   */
+  purge(options?: PurgeWebhookDeliveriesOptions): AsyncResult<number>;
+  /** A job handler that runs `purge`; schedule it nightly. */
+  purgeJob(options?: PurgeWebhookDeliveriesOptions): JobHandler<unknown>;
+}
+interface PurgeWebhookDeliveriesOptions {
+  /** Seconds, or an interval such as `"30 days"`. Defaults to 30 days. */
+  readonly olderThan?: number | string;
+  /** Also delete dead deliveries. Defaults to false. */
+  readonly includeDead?: boolean;
+  /** Defaults to 10000. */
+  readonly batch?: number;
 }
 interface WebhookSinkOptions {
   /** The relay's `typePrefix`. */
@@ -310,4 +414,32 @@ export declare class UrlCheckError extends Error {
  */
 export declare function createSafeFetch(options?: SafeFetchOptions): typeof fetch;
 //#endregion
-export { type AllowUrl, type AuthHookError, type AuthHookKind, type AuthHooks, type BlockTransport, type CreateIncomingWebhookInput, type CreatedIncomingWebhook, type DatabaseChange, type DatabaseWebhookPayload, type DeliverWebhooksOptions, type DeliverWebhooksResult, type DispatchInput, type FetchTransportOptions, type HmacSignerOptions, type IncomingVerify, type IncomingWebhook, type IncomingWebhooks, type IncomingWebhooksOptions, type PublicUrlOptions, type PublishInput, type ResolveHost, type RetryPolicy, type RotateSecretOptions, type RotatedIncomingSecret, type RpcClient, type SafeFetchOptions, type StandardWebhooksOptions, type UpdateIncomingWebhookInput, type UpdatedIncomingWebhook, type VerifiedWebhook, type VerifyOptions, type WebhookDelivery, type WebhookInput, WebhookPolicyError, type WebhookRequest, type WebhookResponse, type WebhookSecretStore, type WebhookSignInput, type WebhookSigner, type WebhookSinkOptions, type WebhookTransport, type Webhooks, type WebhooksOptions, type WebhooksRouteOptions, authHook, databaseChange, dbTransport, fetchTransport, hmacSigner, hookError, isDatabaseWebhook, isPublicAddress, publicUrl, rpcTransport, signStripeWebhook, signWebhook, sqlSecretStore, sqlTransport, standardWebhooks, stripeInboxVerify, verifySharedSecret, verifyStripeWebhook, verifyWebhook };
+//#region src/blocks/webhooks/events.d.ts
+/** The events of the `webhooks` block: type to data. */
+type WebhooksEvents = {
+  readonly "webhook.delivered": WebhookEventData;
+  readonly "webhook.failed": WebhookEventData;
+  readonly "webhook.disabled": WebhookEventData;
+  readonly "webhook.secret_rotated": WebhookEventData;
+};
+/** The `webhooks` block's event types, for its manifest and `onBlockEvent`. */
+export declare const webhooksEvents: Events<WebhooksEvents>;
+/** The events of the `incoming-webhooks` block: type to data. */
+type IncomingWebhooksEvents = {
+  readonly "incoming_webhook.created": IncomingWebhookEventData;
+  readonly "incoming_webhook.updated": IncomingWebhookEventData;
+  readonly "incoming_webhook.enabled_set": IncomingWebhookEventData;
+  readonly "incoming_webhook.token_rotated": IncomingWebhookEventData;
+  readonly "incoming_webhook.secret_rotated": IncomingWebhookEventData;
+  readonly "incoming_webhook.deleted": IncomingWebhookEventData;
+};
+/** The `incoming-webhooks` block's event types, for its manifest and `onBlockEvent`. */
+export declare const incomingWebhooksEvents: Events<IncomingWebhooksEvents>;
+//#endregion
+//#region src/blocks/webhooks/manifest.d.ts
+/** The `webhooks` block's manifest (ADR 0029). */
+export declare const webhooksBlock: BlockOf<"webhooks", typeof createWebhooks, WebhooksEvents>;
+/** The `incoming-webhooks` block's manifest (ADR 0029). */
+export declare const incomingWebhooksBlock: BlockOf<"incoming-webhooks", typeof createIncomingWebhooks, IncomingWebhooksEvents>;
+//#endregion
+export { type AllowUrl, type AsymmetricWebhooksOptions, type AuthHookError, type AuthHookKind, type AuthHooks, type BlockTransport, type CreateIncomingWebhookInput, type CreatedIncomingWebhook, type DatabaseChange, type DatabaseWebhookPayload, type DeliverWebhooksOptions, type DeliverWebhooksResult, type DispatchInput, type FetchTransportOptions, type HmacSignerOptions, type IncomingDelivery, type IncomingDestination, type IncomingDestinationResult, type IncomingVerify, type IncomingWebhook, type IncomingWebhooks, type IncomingWebhooksEvents, type IncomingWebhooksOptions, type JobsDestinationOptions, type OtlpLogsOptions, type PublicUrlOptions, type PublishInput, type PurgeWebhookDeliveriesOptions, type RawSigner, type ResolveHost, type RetryPolicy, type RotateSecretOptions, type RotatedIncomingSecret, type RpcClient, type SafeFetchOptions, type SplunkHecOptions, type StandardWebhooksOptions, type UpdateIncomingWebhookInput, type UpdatedIncomingWebhook, type VerifiedWebhook, type VerifyOptions, type WebhookDelivery, type WebhookEncodeTarget, type WebhookEncoded, type WebhookEncoder, type WebhookInput, WebhookPolicyError, type WebhookRequest, type WebhookResponse, type WebhookSecretStore, type WebhookSignInput, type WebhookSigner, type WebhookSinkOptions, type WebhookTransport, type WebhookVerdict, type Webhooks, type WebhooksEvents, type WebhooksOptions, type WebhooksRouteOptions, authHook, databaseChange, dbTransport, fetchTransport, hmacSigner, hookError, isDatabaseWebhook, isPublicAddress, publicUrl, rpcTransport, signStripeWebhook, signWebhook, sqlSecretStore, sqlTransport, standardWebhooks, standardWebhooksAsymmetric, stripeInboxVerify, verifySharedSecret, verifyStripeWebhook, verifyWebhook, webhookPublicKey };