better-supabase 0.5.1 → 0.6.0

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

@@ -0,0 +1,304 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "../../result-D7y2fT87.js";
+import { t as SqlClient } from "../../executor-DbvExCFC.js";
+import { i as sqlTransport, n as RpcClient, r as rpcTransport, t as BlockTransport } from "../../block-transport-DvaoPuZ9.js";
+import { m as RequestContext } from "../../plugin-FGY8UhYm.js";
+import { a as EventHub } from "../../events-DWDhx77e.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CKtbFcRv.js";
+import { t as BlockProblemOptions } from "../../problem-DD8LZFjc.js";
+import { r as EventSink } from "../../cloud-event-C1JCc1bH.js";
+import { _ as verifySharedSecret, a as DatabaseWebhookPayload, c as WebhookInput, d as hookError, f as isDatabaseWebhook, g as timingSafeEqual, h as stripeInboxVerify, i as DatabaseChange, l as authHook, m as signWebhook, n as AuthHookKind, o as VerifiedWebhook, p as signStripeWebhook, r as AuthHooks, s as VerifyOptions, t as AuthHookError, u as databaseChange, v as verifyStripeWebhook, y as verifyWebhook } from "../../verify-DPuWngD4.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-4y62_VIi.js";
+//#region src/blocks/webhooks/incoming.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`. */
+  readonly source?: string;
+  /**
+   * Deliveries per endpoint and period, counted with the `rate-limit`
+   * module's `hit_rate_limit`. Unset: no limit.
+   */
+  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;
+  };
+}
+/** 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;
+}
+/** 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;
+}
+interface UpdateIncomingWebhookInput {
+  readonly name?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly verify?: IncomingVerify;
+  readonly signatureHeader?: string;
+}
+interface UpdatedIncomingWebhook {
+  readonly id: string;
+  readonly tenant: string;
+  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.
+   */
+  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[]>;
+}
+/** 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.
+ */
+export declare function createIncomingWebhooks(sql: SqlClient, options?: IncomingWebhooksOptions): IncomingWebhooks;
+//#endregion
+//#region src/blocks/webhooks/outgoing.d.ts
+/** One claimed delivery, as `shouldDeliver`, `transform` and `headers` see it. */
+interface WebhookDelivery {
+  readonly id: string;
+  readonly endpointId: string;
+  readonly url: string;
+  readonly type: string;
+  readonly payload: unknown;
+  /** 1 on the first try. Counted when the delivery is claimed. */
+  readonly attempt: number;
+  readonly tenant: string | null;
+  readonly eventId: string | null;
+  readonly runId: string | null;
+  readonly createdAt: Temporal.Instant;
+}
+interface RetryPolicy {
+  /** Attempts before a delivery is dead-lettered. Defaults to 8. */
+  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
+   * receiver's `Retry-After` wins when it asks for longer, up to a day.
+   */
+  readonly backoff?: (attempt: number) => number;
+  /** Statuses worth retrying. Defaults to 408, 429 and 5xx; network errors always retry. */
+  readonly retryable?: (status: number) => boolean;
+}
+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`. */
+  readonly schema?: string;
+  /** Defaults to `fetchTransport({ allowUrl })`. */
+  readonly http?: WebhookTransport;
+  /** Used by the default `http`. Defaults to `publicUrl()`. */
+  readonly allowUrl?: AllowUrl;
+  /** Defaults to `standardWebhooks()`. */
+  readonly signer?: WebhookSigner;
+  /** Defaults to `sqlSecretStore(transport)`. */
+  readonly secrets?: WebhookSecretStore;
+  readonly retry?: RetryPolicy;
+  /** Return `false` (or throw) to cancel a delivery instead of sending it. */
+  readonly shouldDeliver?: (delivery: WebhookDelivery) => boolean | Promise<boolean>;
+  /**
+   * The JSON body. Defaults to the Standard Webhooks envelope,
+   * `{ type, timestamp, data }`.
+   */
+  readonly transform?: (delivery: WebhookDelivery) => unknown;
+  /** 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;
+  readonly context?: RequestContext;
+  /** Error mappers that run before the built-in ones, as in `betterSupabase.mapError()`. */
+  readonly mappers?: readonly ErrorMapper[];
+}
+interface PublishInput {
+  readonly type: string;
+  readonly data: unknown;
+  readonly tenant?: string;
+  /** With an id, publishing it again never queues a second delivery. */
+  readonly id?: string;
+}
+interface DispatchInput {
+  readonly endpointId: string;
+  readonly type: string;
+  readonly data: unknown;
+  /** An external run id stored with the delivery, e.g. a workflow run. */
+  readonly runId?: string;
+  readonly eventId?: string;
+}
+interface DeliverWebhooksOptions {
+  /** Deliveries per claim. Defaults to 25. */
+  readonly batch?: number;
+  /**
+   * Requests in flight at once. Defaults to 10, so a batch of 25 at the
+   * 10-second timeout finishes well inside the lease.
+   */
+  readonly concurrency?: number;
+  /** How long a claim holds a delivery. Defaults to `'2 minutes'`. */
+  readonly lease?: string;
+  readonly budgetMs?: number;
+}
+interface DeliverWebhooksResult {
+  readonly succeeded: number;
+  /** Failed attempts that will retry. */
+  readonly retrying: number;
+  /** Deliveries that ran out of attempts or can't succeed. */
+  readonly dead: number;
+  readonly canceled: number;
+  /** Endpoints disabled after failing for `disableAfter`. */
+  readonly disabled: number;
+}
+interface WebhooksRouteOptions extends DeliverWebhooksOptions, BlockProblemOptions {
+  readonly secret: string | undefined;
+  readonly onError?: (error: unknown) => void;
+}
+interface Webhooks {
+  /** Queues the event for each subscribed endpoint; returns how many. */
+  publish(event: PublishInput): AsyncResult<number>;
+  /** Sends to one endpoint outside its subscriptions; returns the delivery id. */
+  dispatch(input: DispatchInput): AsyncResult<string>;
+  /** Queues a finished delivery again. */
+  redeliver(deliveryId: string): AsyncResult<string>;
+  /** A new signing secret, returned once. */
+  rotateSecret(endpointId: string, options?: RotateSecretOptions): AsyncResult<string>;
+  /** Sends due deliveries. Run it from a cron route or a job. */
+  deliver(options?: DeliverWebhooksOptions): Promise<DeliverWebhooksResult>;
+  /** A `GET`/`POST` handler for Vercel Cron that runs `deliver` behind a bearer secret. */
+  deliverRoute(options: WebhooksRouteOptions): (request: Request) => Promise<Response>;
+  /**
+   * An `EventSink` that publishes CloudEvents, e.g. from the outbox relay.
+   * Endpoints subscribe to unprefixed types, so it removes `typePrefix`
+   * (`dev.better-supabase` by default, the relay's default) and the dot.
+   */
+  sink(options?: WebhookSinkOptions): EventSink;
+}
+interface WebhookSinkOptions {
+  /** The relay's `typePrefix`. */
+  readonly typePrefix?: string;
+}
+export declare function createWebhooks(options: WebhooksOptions): Webhooks;
+//#endregion
+//#region src/blocks/webhooks/safe-fetch.d.ts
+interface SafeFetchOptions extends PublicUrlOptions {
+  /** The fetch to call. Defaults to the global `fetch`. */
+  readonly fetch?: typeof fetch;
+  /**
+   * Decides which URLs a request (and each redirect) may reach. Defaults to
+   * `publicUrl(options)`: HTTPS only, no credentials, public addresses only.
+   */
+  readonly allowUrl?: AllowUrl;
+  /** Redirects followed, each checked with `allowUrl`. Defaults to 3. */
+  readonly maxRedirects?: number;
+  /** Per call, across redirects. Defaults to 10 seconds. */
+  readonly timeoutMs?: number;
+  readonly sensitiveHeaders?: readonly string[];
+}
+/** A request `safeFetch` refused: a URL outside the policy or too many redirects. */
+export declare class UnsafeUrlError extends Error {
+  override readonly name = "UnsafeUrlError";
+}
+export declare class UrlCheckError extends Error {
+  override readonly name = "UrlCheckError";
+}
+/**
+ * A `fetch` for URLs that users or tenants supply (link previews, imports,
+ * avatars by URL, callback URLs): it refuses private, loopback and
+ * link-local addresses, non-HTTPS URLs and credentials in the URL, checks
+ * every redirect against the same policy before following it, and stops
+ * after `timeoutMs`. It throws `UnsafeUrlError` for a refused URL and
+ * `UrlCheckError` when the check itself failed (a DNS lookup error). A redirect
+ * to another origin drops the credential headers and `sensitiveHeaders`.
+ *
+ * DNS can change between the check and the connection; route the requests
+ * through an egress proxy when that matters.
+ */
+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, fetchTransport, hmacSigner, hookError, isDatabaseWebhook, isPublicAddress, publicUrl, rpcTransport, signStripeWebhook, signWebhook, sqlSecretStore, sqlTransport, standardWebhooks, stripeInboxVerify, timingSafeEqual, verifySharedSecret, verifyStripeWebhook, verifyWebhook };