tapimo 0.0.0 → 0.0.2

package/src/internal/Webhooks.ts

@@ -0,0 +1,940 @@
+import { nanoid } from 'nanoid'
+import { Hash, Hex } from 'ox'
+
+import type * as app_Webhooks from '../apps/webhooks.js'
+import type * as Metrics from '../Metrics.js'
+import * as MetricSink from './MetricSink.js'
+import * as Store from './Store.js'
+import * as WebhookDestination from './WebhookDestination.js'
+
+// The destination layer lives in `./WebhookDestination.js`. Re-export only the
+// pieces that belong on the public `Webhooks.*` surface: the `Destination` and
+// `Result` types, the `InvalidUrlError` thrown by subscription writes, and the
+// signature-verification API a consumer uses to authenticate a delivery
+// (`verify` + `signatureHeader`, with `sign` as its pair). The transport-specific
+// validators/log helpers stay internal to `WebhookDestination`.
+export type { Destination, Result } from './WebhookDestination.js'
+export { InvalidUrlError, sign, signatureHeader, verify } from './WebhookDestination.js'
+
+/**
+ * Event types a subscription can listen to. The canonical set lives in the apps
+ * layer ({@link app_Webhooks.eventTypes}), co-located with the per-type schemas
+ * and descriptions that reference apps-layer read schemas; this storage layer
+ * only consumes the type.
+ */
+export type EventType = app_Webhooks.EventType
+
+/** Lifecycle status of a subscription. */
+export type Status = 'active' | 'disabled' | 'paused'
+
+/**
+ * Authenticated owner of a subscription. Derived from the request principal:
+ * API keys are org-scoped; MPP payers are identified by their stable DID.
+ */
+export type Owner =
+  | {
+      /** Owning organization id (any key in the org manages its webhooks). */
+      orgId: string
+      /** Owner kind. */
+      type: 'api_key'
+    }
+  | {
+      /** Verified MPP payer identifier (e.g. `did:pkh:…`). */
+      payer: string
+      /** Owner kind. */
+      type: 'mpp'
+    }
+
+/**
+ * Optional human context describing what a subscription is for. Carried onto
+ * every delivered {@link Envelope} and surfaced by destinations (Slack header +
+ * description, Better Stack log fields, and the raw `url` payload).
+ */
+export type Context = {
+  /** Longer description of the subscription's purpose. */
+  description?: string | undefined
+  /** Arbitrary key/value labels echoed on every delivery and rendered by destinations. */
+  metadata?: Record<string, string> | undefined
+  /** Short label for the subscription (e.g. `Prod USDC large transfers`). */
+  title?: string | undefined
+}
+
+/** A durable webhook subscription record. */
+export type Subscription = {
+  /** Chain the subscription listens on. */
+  chainId: number
+  /** Optional human context describing what the subscription is for. */
+  context?: Context | undefined
+  /** ISO timestamp of creation. */
+  createdAt: string
+  /** Where matched events are delivered (URL or Slack channel). */
+  destination: WebhookDestination.Destination
+  /** Event type the subscription listens to. */
+  eventType: EventType
+  /** ISO expiry timestamp; set for MPP-owned subscriptions (TTL-bounded). */
+  expiresAt?: string | undefined
+  /** Consecutive delivery failures; drives auto-disable. */
+  failureCount: number
+  /** Event-type-specific filter predicates. */
+  filters: Record<string, unknown>
+  /** Subscription id (`wh_…`). */
+  id: string
+  /** ISO timestamp of the last successful delivery, if any. */
+  lastDeliveryAt?: string | undefined
+  /** Authenticated owner. */
+  owner: Owner
+  /** HMAC signing secret. Returned once at creation; never exposed by reads. */
+  secret: string
+  /** Lifecycle status. */
+  status: Status
+  /** ISO timestamp of the last mutation. */
+  updatedAt: string
+}
+
+/** Fields accepted when creating a subscription. */
+export type CreateInput = {
+  /** Chain to listen on. */
+  chainId: number
+  /** Optional human context describing what the subscription is for. */
+  context?: Context | undefined
+  /** Where matched events are delivered. `url` destinations are SSRF-validated. */
+  destination: WebhookDestination.Destination
+  /** Event type to listen to. */
+  eventType: EventType
+  /** Event-type-specific filter predicates. */
+  filters?: Record<string, unknown> | undefined
+  /** Owner derived from the request principal. */
+  owner: Owner
+  /** Time-to-live in milliseconds; set the subscription to expire (MPP TTL). */
+  ttl?: number | undefined
+}
+
+/** Mutable fields accepted when patching a subscription. */
+export type PatchInput = {
+  /** New human context, or `null` to clear it. */
+  context?: Context | null | undefined
+  /** New delivery destination. `url` destinations are re-validated for SSRF. */
+  destination?: WebhookDestination.Destination | undefined
+  /** New filter predicates. */
+  filters?: Record<string, unknown> | undefined
+  /** New lifecycle status (`active`/`paused`/`disabled`). */
+  status?: Status | undefined
+}
+
+/** Outcome status of a delivery-log row. */
+export type DeliveryStatus = 'failed' | 'pending' | 'succeeded'
+
+/**
+ * A durable delivery-log row recording one delivery attempt. Persisted by
+ * {@link deliverAndRecord} so deliveries are observable and replayable (Phase
+ * C); the read endpoint returns these verbatim.
+ */
+export type Delivery = {
+  /** Consecutive attempt number (1-based) at the time of this delivery. */
+  attempt: number
+  /** ISO timestamp the attempt was recorded. */
+  createdAt: string
+  /**
+   * The exact envelope that was sent, persisted so the delivery can be replayed
+   * verbatim (manual retry). Internal-only: the public delivery row omits it.
+   */
+  envelope: Envelope
+  /** Failure reason when `status` is `failed`. */
+  error?: string | undefined
+  /** Idempotent event id this delivery carried (`evt_…`). */
+  eventId: string
+  /** Delivery id (`whd_…`); time-sortable so keys order chronologically. */
+  id: string
+  /** Subscriber callback URL the attempt targeted. */
+  requestUrl: string
+  /** Wall-clock duration of the attempt in ms, when a request was made. */
+  responseMs?: number | undefined
+  /** HTTP response status, when a response was received. */
+  responseStatus?: number | undefined
+  /** Outcome status. */
+  status: DeliveryStatus
+  /** Owning subscription id. */
+  subscriptionId: string
+}
+
+/**
+ * Creates a subscription, validating its URL and (optionally) enforcing a
+ * per-owner cap, then persists it and indexes it for the poller.
+ */
+export async function createSubscription(
+  store: Store.State,
+  input: CreateInput,
+  options: createSubscription.Options = {},
+): Promise<Subscription> {
+  WebhookDestination.assertDestination(input.destination)
+
+  if (options.maxPerOwner !== undefined) {
+    const existing = await listSubscriptions(store, input.owner)
+    if (existing.length >= options.maxPerOwner) throw new LimitExceededError(options.maxPerOwner)
+  }
+
+  const now = (options.now ?? (() => new Date()))()
+  const iso = now.toISOString()
+  const subscription: Subscription = {
+    chainId: input.chainId,
+    ...(input.context === undefined ? {} : { context: input.context }),
+    createdAt: iso,
+    destination: input.destination,
+    eventType: input.eventType,
+    failureCount: 0,
+    filters: input.filters ?? {},
+    id: generateId(now),
+    owner: input.owner,
+    secret: generateSecret(),
+    status: 'active',
+    updatedAt: iso,
+    ...(input.ttl === undefined
+      ? {}
+      : { expiresAt: new Date(now.getTime() + input.ttl).toISOString() }),
+  }
+
+  await writeSubscription(store, subscription)
+  return subscription
+}
+
+export declare namespace createSubscription {
+  /** Options for {@link createSubscription}. */
+  type Options = {
+    /** Reject creation once the owner has this many subscriptions. */
+    maxPerOwner?: number | undefined
+    /** Clock used for timestamps (injectable for tests). */
+    now?: (() => Date) | undefined
+  }
+}
+
+/** Reads a single subscription scoped to its owner. Returns null when absent. */
+export async function getSubscription(
+  store: Store.State,
+  owner: Owner,
+  id: string,
+): Promise<Subscription | null> {
+  return readSubscription(store, subscriptionKey(owner, id))
+}
+
+/**
+ * Lists an owner's subscriptions, newest first, with optional keyset paging.
+ * Subscription ids embed a timestamp, so lexical key order is chronological.
+ */
+export async function listSubscriptions(
+  store: Store.State,
+  owner: Owner,
+  options: listSubscriptions.Options = {},
+): Promise<Subscription[]> {
+  const prefix = subscriptionPrefix(owner)
+  const { keys } = await store.list({ prefix })
+
+  // Newest first: ids sort chronologically ascending, so reverse for descending.
+  let names = keys
+    .map((key) => key.name)
+    .sort()
+    .reverse()
+  if (options.cursor) names = names.filter((name) => name < `${prefix}${options.cursor}`)
+  if (options.offset) names = names.slice(options.offset)
+  if (options.limit !== undefined) names = names.slice(0, options.limit)
+
+  // Hydrate the page in parallel: the reads are independent, and a serial
+  // loop costs one store round trip per row (an N+1 against the production
+  // Durable Object).
+  const subscriptions = await Promise.all(names.map((name) => readSubscription(store, name)))
+  return subscriptions.filter((subscription) => subscription !== null)
+}
+
+export declare namespace listSubscriptions {
+  /** Options for {@link listSubscriptions}. */
+  type Options = {
+    /** Return subscriptions older than this id (keyset paging, newest first). */
+    cursor?: string | undefined
+    /** Maximum subscriptions to return. */
+    limit?: number | undefined
+    /** Rows to skip from the head (positional pagination; exclusive with `cursor`). */
+    offset?: number | undefined
+  }
+}
+
+/**
+ * Counts an owner's subscriptions. Reads only the key set under the owner
+ * prefix (no row hydration), so it's a single store `list` — exact and cheap,
+ * since the per-owner set is bounded by `maxPerOwner`. Feeds the opt-in
+ * `meta.totalCount` on `GET /webhooks`.
+ */
+export async function countSubscriptions(store: Store.State, owner: Owner): Promise<number> {
+  const { keys } = await store.list({ prefix: subscriptionPrefix(owner) })
+  return keys.length
+}
+
+/**
+ * Patches an owner's subscription, re-validating the URL when changed and
+ * re-indexing for the poller when the status changes. Returns null when absent.
+ */
+export async function updateSubscription(
+  store: Store.State,
+  owner: Owner,
+  id: string,
+  patch: PatchInput,
+  options: updateSubscription.Options = {},
+): Promise<Subscription | null> {
+  const current = await getSubscription(store, owner, id)
+  if (!current) return null
+
+  if (patch.destination !== undefined) WebhookDestination.assertDestination(patch.destination)
+
+  const now = (options.now ?? (() => new Date()))()
+  const next: Subscription = {
+    ...current,
+    // `context: null` clears it (stored as undefined; drops from JSON + reads).
+    ...(patch.context === undefined
+      ? {}
+      : { context: patch.context === null ? undefined : patch.context }),
+    ...(patch.destination === undefined ? {} : { destination: patch.destination }),
+    ...(patch.filters === undefined ? {} : { filters: patch.filters }),
+    ...(patch.status === undefined ? {} : { status: patch.status }),
+    updatedAt: now.toISOString(),
+  }
+
+  await writeSubscription(store, next)
+  return next
+}
+
+export declare namespace updateSubscription {
+  /** Options for {@link updateSubscription}. */
+  type Options = {
+    /** Clock used for timestamps (injectable for tests). */
+    now?: (() => Date) | undefined
+  }
+}
+
+/** Deletes an owner's subscription and its index/cursor keys. */
+export async function deleteSubscription(
+  store: Store.State,
+  owner: Owner,
+  id: string,
+): Promise<boolean> {
+  const current = await getSubscription(store, owner, id)
+  if (!current) return false
+
+  await store.delete(subscriptionKey(owner, id))
+  await store.delete(activeKey(current.chainId, current.eventType, id))
+  await store.delete(cursorKey(id))
+
+  // Drop the delivery log so a deleted subscription leaves no orphaned rows.
+  const { keys } = await store.list({ prefix: deliveryPrefix(id) })
+  for (const { name } of keys) await store.delete(name)
+  return true
+}
+
+/**
+ * Lists active subscriptions for a `(chainId, eventType)` stream. Used by the
+ * poller; reads the secondary index, then hydrates each subscription.
+ */
+export async function listActive(
+  store: Store.State,
+  chainId: number,
+  eventType: EventType,
+): Promise<Subscription[]> {
+  const { keys } = await store.list({ prefix: activePrefix(chainId, eventType) })
+
+  const subscriptions: Subscription[] = []
+  for (const { name } of keys) {
+    const subKey = await store.get(name)
+    if (!subKey) continue
+    const subscription = await readSubscription(store, subKey)
+    if (subscription) subscriptions.push(subscription)
+  }
+  return subscriptions
+}
+
+/** Reads a subscription's keyset cursor. Returns null when unset. */
+export async function getCursor(
+  store: Store.State,
+  subscriptionId: string,
+): Promise<string | null> {
+  return store.get(cursorKey(subscriptionId))
+}
+
+/** Writes a subscription's keyset cursor. */
+export async function setCursor(
+  store: Store.State,
+  subscriptionId: string,
+  cursor: string,
+): Promise<void> {
+  await store.put(cursorKey(subscriptionId), cursor)
+}
+
+/**
+ * Default delivery-log retention. Rows are written with this TTL so a busy
+ * subscription's log doesn't grow unbounded; tune per deployment.
+ */
+export const deliveryRetentionMs = 7 * 24 * 60 * 60 * 1_000
+
+/** Records one delivery-log row (stateful, owner-agnostic; scoped per subscription). */
+export async function recordDelivery(
+  store: Store.State,
+  delivery: Delivery,
+  options: recordDelivery.Options = {},
+): Promise<void> {
+  const ttl = options.ttl ?? deliveryRetentionMs
+  await store.put(deliveryKey(delivery.subscriptionId, delivery.id), JSON.stringify(delivery), {
+    ttl,
+  })
+}
+
+export declare namespace recordDelivery {
+  /** Options for {@link recordDelivery}. */
+  type Options = {
+    /** Row time-to-live in ms; defaults to {@link deliveryRetentionMs}. */
+    ttl?: number | undefined
+  }
+}
+
+/**
+ * Lists a subscription's delivery log, newest first, with optional keyset
+ * paging. Delivery ids embed a timestamp, so lexical key order is chronological.
+ */
+export async function listDeliveries(
+  store: Store.State,
+  subscriptionId: string,
+  options: listDeliveries.Options = {},
+): Promise<Delivery[]> {
+  const prefix = deliveryPrefix(subscriptionId)
+  const { keys } = await store.list({ prefix })
+
+  // Newest first: ids sort chronologically ascending, so reverse for descending.
+  let names = keys
+    .map((key) => key.name)
+    .sort()
+    .reverse()
+  if (options.cursor) names = names.filter((name) => name < `${prefix}${options.cursor}`)
+  if (options.offset) names = names.slice(options.offset)
+  if (options.limit !== undefined) names = names.slice(0, options.limit)
+
+  // Hydrate the page in parallel: the reads are independent, and a serial
+  // loop costs one store round trip per row (an N+1 against the production
+  // Durable Object).
+  const deliveries = await Promise.all(names.map((name) => readDelivery(store, name)))
+  return deliveries.filter((delivery) => delivery !== null)
+}
+
+export declare namespace listDeliveries {
+  /** Options for {@link listDeliveries}. */
+  type Options = {
+    /** Return deliveries whose id sorts before this one (older entries). */
+    cursor?: string | undefined
+    /** Maximum deliveries to return. */
+    limit?: number | undefined
+    /** Rows to skip from the head (positional pagination; exclusive with `cursor`). */
+    offset?: number | undefined
+  }
+}
+
+/**
+ * Counts a subscription's delivery-log entries. Reads only the key set under
+ * the delivery prefix (no row hydration), so it's a single store `list` —
+ * exact, and bounded by the delivery retention TTL. Feeds the opt-in
+ * `meta.totalCount` on `GET /webhooks/:id/deliveries`.
+ */
+export async function countDeliveries(store: Store.State, subscriptionId: string): Promise<number> {
+  const { keys } = await store.list({ prefix: deliveryPrefix(subscriptionId) })
+  return keys.length
+}
+
+/** Loads a single delivery-log row (`null` when absent), scoped to its subscription. */
+export async function getDelivery(
+  store: Store.State,
+  subscriptionId: string,
+  deliveryId: string,
+): Promise<Delivery | null> {
+  return readDelivery(store, deliveryKey(subscriptionId, deliveryId))
+}
+
+/**
+ * Default number of consecutive delivery failures after which a subscription
+ * auto-disables (and is dropped from the poller's active index).
+ */
+export const maxFailures = 10
+
+/**
+ * Records a successful delivery: resets the consecutive-failure counter and
+ * stamps `lastDeliveryAt`. Returns the updated subscription (re-persisted so the
+ * poller's active index and TTL stay correct).
+ */
+export async function recordSuccess(
+  store: Store.State,
+  subscription: Subscription,
+  options: recordSuccess.Options = {},
+): Promise<Subscription> {
+  const now = (options.now ?? (() => new Date()))()
+  const next: Subscription = {
+    ...subscription,
+    failureCount: 0,
+    lastDeliveryAt: now.toISOString(),
+    updatedAt: now.toISOString(),
+  }
+  await writeSubscription(store, next)
+  return next
+}
+
+export declare namespace recordSuccess {
+  /** Options for {@link recordSuccess}. */
+  type Options = {
+    /** Clock used for timestamps; injectable for tests. */
+    now?: (() => Date) | undefined
+  }
+}
+
+/**
+ * Records a failed delivery: increments the consecutive-failure counter and,
+ * once it reaches `maxFailures`, sets `status: 'disabled'` so the subscription
+ * drops out of the poller's active index (surfaced via the API). Returns the
+ * updated subscription.
+ */
+export async function recordFailure(
+  store: Store.State,
+  subscription: Subscription,
+  options: recordFailure.Options = {},
+): Promise<Subscription> {
+  const now = (options.now ?? (() => new Date()))()
+  const failureCount = subscription.failureCount + 1
+  const disabled = failureCount >= (options.maxFailures ?? maxFailures)
+  const next: Subscription = {
+    ...subscription,
+    failureCount,
+    ...(disabled ? { status: 'disabled' } : {}),
+    updatedAt: now.toISOString(),
+  }
+  await writeSubscription(store, next)
+  return next
+}
+
+export declare namespace recordFailure {
+  /** Options for {@link recordFailure}. */
+  type Options = {
+    /** Consecutive failures before auto-disabling (default {@link maxFailures}). */
+    maxFailures?: number | undefined
+    /** Clock used for timestamps; injectable for tests. */
+    now?: (() => Date) | undefined
+  }
+}
+
+/**
+ * Delivers an envelope to its subscription and records the outcome: success
+ * resets the failure counter and stamps `lastDeliveryAt`; failure increments it
+ * and auto-disables after {@link maxFailures}. This is the single delivery entry
+ * point shared by the Cloudflare Queue consumer and the self-host inline path.
+ */
+export async function deliverAndRecord(
+  store: Store.State,
+  subscription: Subscription,
+  envelope: Envelope,
+  options: deliverAndRecord.Options = {},
+): Promise<WebhookDestination.Result> {
+  // Snapshot the attempt before recordSuccess/recordFailure mutate the counter.
+  const attempt = subscription.failureCount + 1
+  const result = await WebhookDestination.from(subscription.destination).deliver({
+    envelope,
+    secret: subscription.secret,
+    ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+  })
+  if (result.ok) await recordSuccess(store, subscription, options)
+  else await recordFailure(store, subscription, options)
+
+  // Emit a `webhook:delivery` metric. recordSuccess/recordFailure are immutable
+  // (they spread into a new record), so `subscription.failureCount` here is still
+  // the pre-mutation snapshot the sink needs to derive the attempt bucket.
+  // Best-effort, like delivery logging.
+  const metrics = options.metrics ? MetricSink.webhooks(options.metrics) : undefined
+  if (metrics) {
+    metrics.record({
+      envelope,
+      result,
+      subscription,
+      trigger: options.trigger ?? 'queue',
+      type: 'webhook:delivery',
+    })
+    metrics.flush()
+  }
+
+  // Append a delivery-log row. Best-effort: a logging failure must never change
+  // the delivery outcome the caller (Queue consumer / inline path) acts on.
+  try {
+    await recordDelivery(
+      store,
+      buildDelivery({ attempt, envelope, result, subscription }, options),
+      options.deliveryRetentionMs === undefined ? {} : { ttl: options.deliveryRetentionMs },
+    )
+  } catch {
+    // delivery logging is best-effort
+  }
+
+  return result
+}
+
+export declare namespace deliverAndRecord {
+  /** Options for {@link deliverAndRecord}. */
+  type Options = {
+    /** Delivery-log row TTL in ms; defaults to {@link deliveryRetentionMs}. */
+    deliveryRetentionMs?: number | undefined
+    /** `fetch` implementation passed through to {@link deliver}. */
+    fetch?: typeof globalThis.fetch | undefined
+    /** Consecutive failures before auto-disabling (default {@link maxFailures}). */
+    maxFailures?: number | undefined
+    /** Metrics backend; emits one `webhook:delivery` event per attempt. */
+    metrics?: Metrics.Metrics | undefined
+    /** Clock used for timestamps; injectable for tests. */
+    now?: (() => Date) | undefined
+    /** Delivery timeout in ms passed through to {@link deliver}. */
+    timeoutMs?: number | undefined
+    /** Where this attempt originated; tags the `webhook:delivery` event (default `queue`). */
+    trigger?: MetricSink.Trigger | undefined
+  }
+}
+
+/** Builds a delivery-log row from an attempt's envelope and classified result. */
+function buildDelivery(
+  input: {
+    attempt: number
+    envelope: Envelope
+    result: WebhookDestination.Result
+    subscription: Subscription
+  },
+  options: { now?: (() => Date) | undefined } = {},
+): Delivery {
+  const { attempt, envelope, result, subscription } = input
+  const now = (options.now ?? (() => new Date()))()
+  return {
+    attempt,
+    createdAt: now.toISOString(),
+    envelope,
+    eventId: envelope.id,
+    id: generateDeliveryId(now),
+    requestUrl: WebhookDestination.destinationLabel(subscription.destination),
+    status: result.ok ? 'succeeded' : 'failed',
+    subscriptionId: subscription.id,
+    ...(result.error === undefined ? {} : { error: result.error }),
+    ...(result.durationMs === undefined ? {} : { responseMs: result.durationMs }),
+    ...(result.status === undefined ? {} : { responseStatus: result.status }),
+  }
+}
+
+/**
+ * Computes a stable, idempotent event id from its on-chain coordinates so
+ * re-deliveries are dedupable by the receiver.
+ */
+export function eventId(options: eventId.Options): string {
+  const input = `${options.chainId}:${options.eventType}:${options.blockNumber}:${options.logIndex}`
+  return `evt_${Hash.sha256(Hex.fromString(input)).slice(2)}`
+}
+
+export declare namespace eventId {
+  /** Options for {@link eventId}. */
+  type Options = {
+    /** Block number the event was indexed in. */
+    blockNumber: bigint | number | string
+    /** Chain the event occurred on. */
+    chainId: number
+    /** Event type. */
+    eventType: EventType
+    /** Log index within the block (or transaction index for transaction events). */
+    logIndex: bigint | number | string
+  }
+}
+
+/** The JSON envelope delivered to subscribers. */
+export type Envelope = {
+  /** Chain the event occurred on. */
+  chainId: number
+  /** Human context copied from the subscription, when set. */
+  context?: Context | undefined
+  /** ISO timestamp the envelope was built. */
+  createdAt: string
+  /** The same row shape the corresponding read endpoint returns. */
+  data: unknown
+  /** Stable, idempotent event id (`evt_…`). */
+  id: string
+  /** Originating subscription id. */
+  subscriptionId: string
+  /** Event type; `ping` marks a synthetic test delivery (see {@link buildPingEnvelope}). */
+  type: EventType | 'ping'
+}
+
+/** Builds a delivery envelope for an event matched against a subscription. */
+export function buildEnvelope(options: buildEnvelope.Options): Envelope {
+  const { subscription } = options
+  return {
+    chainId: subscription.chainId,
+    ...(subscription.context === undefined ? {} : { context: subscription.context }),
+    createdAt: (options.createdAt ?? new Date()).toISOString(),
+    data: options.data,
+    id: eventId({
+      blockNumber: options.blockNumber,
+      chainId: subscription.chainId,
+      eventType: subscription.eventType,
+      logIndex: options.logIndex,
+    }),
+    subscriptionId: subscription.id,
+    type: subscription.eventType,
+  }
+}
+
+export declare namespace buildEnvelope {
+  /** Options for {@link buildEnvelope}. */
+  type Options = {
+    /** Block number the event was indexed in. */
+    blockNumber: bigint | number | string
+    /** Timestamp to stamp on the envelope; defaults to now. */
+    createdAt?: Date | undefined
+    /** Decoded event row (same shape the read endpoint returns). */
+    data: unknown
+    /** Log index within the block. */
+    logIndex: bigint | number | string
+    /** Subscription the event matched. */
+    subscription: Subscription
+  }
+}
+
+/**
+ * Builds a synthetic `ping` envelope so an owner can test a subscription's
+ * endpoint (connectivity, TLS, signature verification) without waiting for a real
+ * on-chain event. The id is randomized per call so repeated pings are never
+ * deduped by the receiver; `type` is `ping` and `data` is a recognizable
+ * `{ ping: true }` marker rather than an event row, so receivers can tell a test
+ * delivery apart from a real event.
+ */
+export function buildPingEnvelope(
+  subscription: Subscription,
+  options: buildPingEnvelope.Options = {},
+): Envelope {
+  const now = options.createdAt ?? new Date()
+  const nonce = options.nonce ?? Hex.random(16).slice(2)
+  return {
+    chainId: subscription.chainId,
+    ...(subscription.context === undefined ? {} : { context: subscription.context }),
+    createdAt: now.toISOString(),
+    data: { ping: true },
+    id: `evt_${Hash.sha256(Hex.fromString(`ping:${subscription.id}:${nonce}`)).slice(2)}`,
+    subscriptionId: subscription.id,
+    type: 'ping',
+  }
+}
+
+export declare namespace buildPingEnvelope {
+  /** Options for {@link buildPingEnvelope}. */
+  type Options = {
+    /** Timestamp to stamp on the envelope; defaults to now. */
+    createdAt?: Date | undefined
+    /** Deterministic nonce for the event id; defaults to random (tests only). */
+    nonce?: string | undefined
+  }
+}
+
+/**
+ * Delivers a synthetic {@link buildPingEnvelope} to a subscription's endpoint and
+ * logs the attempt. Unlike {@link deliverAndRecord} it deliberately does NOT
+ * touch the subscription's `failureCount`/`status`: a test ping must never
+ * auto-disable a healthy subscription or reset a real failure streak. The
+ * delivery row is still appended (best-effort) so the ping is observable via the
+ * delivery log.
+ */
+export async function ping(
+  store: Store.State,
+  subscription: Subscription,
+  options: ping.Options = {},
+): Promise<ping.Result> {
+  const now = options.now ?? (() => new Date())
+  const envelope = buildPingEnvelope(subscription, {
+    createdAt: now(),
+    ...(options.nonce === undefined ? {} : { nonce: options.nonce }),
+  })
+  const result = await WebhookDestination.from(subscription.destination).deliver({
+    envelope,
+    secret: subscription.secret,
+    ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+  })
+
+  // Best-effort: a logging failure must never change the result the caller sees.
+  const delivery = buildDelivery({ attempt: 1, envelope, result, subscription }, { now })
+  try {
+    await recordDelivery(
+      store,
+      delivery,
+      options.deliveryRetentionMs === undefined ? {} : { ttl: options.deliveryRetentionMs },
+    )
+  } catch {
+    // delivery logging is best-effort
+  }
+
+  return { delivery, envelope, result }
+}
+
+export declare namespace ping {
+  /** Options for {@link ping}. */
+  type Options = {
+    /** Delivery-log row TTL in ms; defaults to {@link deliveryRetentionMs}. */
+    deliveryRetentionMs?: number | undefined
+    /** `fetch` implementation passed through to {@link deliver}. */
+    fetch?: typeof globalThis.fetch | undefined
+    /** Deterministic event-id nonce; defaults to random (tests only). */
+    nonce?: string | undefined
+    /** Clock used for timestamps; injectable for tests. */
+    now?: (() => Date) | undefined
+    /** Delivery timeout in ms passed through to {@link deliver}. */
+    timeoutMs?: number | undefined
+  }
+  /** Outcome of a ping: the classified delivery result plus the logged row. */
+  type Result = {
+    /** The delivery-log row that was recorded. */
+    delivery: Delivery
+    /** The synthetic envelope that was sent. */
+    envelope: Envelope
+    /** The classified transport result. */
+    result: WebhookDestination.Result
+  }
+}
+
+function ownerKey(owner: Owner): string {
+  return owner.type === 'api_key'
+    ? `api_key:${encodeURIComponent(owner.orgId)}`
+    : `mpp:${encodeURIComponent(owner.payer)}`
+}
+
+function subscriptionPrefix(owner: Owner): string {
+  return `webhook:sub:${ownerKey(owner)}:`
+}
+
+function subscriptionKey(owner: Owner, id: string): string {
+  return `${subscriptionPrefix(owner)}${id}`
+}
+
+function cursorKey(subscriptionId: string): string {
+  return `webhook:cursor:${subscriptionId}`
+}
+
+function deliveryPrefix(subscriptionId: string): string {
+  return `webhook:delivery:${subscriptionId}:`
+}
+
+function deliveryKey(subscriptionId: string, deliveryId: string): string {
+  return `${deliveryPrefix(subscriptionId)}${deliveryId}`
+}
+
+function activePrefix(chainId: number, eventType: EventType): string {
+  return `webhook:active:${chainId}:${eventType}:`
+}
+
+function activeKey(chainId: number, eventType: EventType, id: string): string {
+  return `${activePrefix(chainId, eventType)}${id}`
+}
+
+async function readSubscription(store: Store.State, key: string): Promise<Subscription | null> {
+  const raw = await store.get(key)
+  if (!raw) return null
+  try {
+    return JSON.parse(raw) as Subscription
+  } catch {
+    // Corrupt entries are treated as absent.
+    return null
+  }
+}
+
+async function readDelivery(store: Store.State, key: string): Promise<Delivery | null> {
+  const raw = await store.get(key)
+  if (!raw) return null
+  try {
+    return JSON.parse(raw) as Delivery
+  } catch {
+    // Corrupt entries are treated as absent.
+    return null
+  }
+}
+
+async function writeSubscription(store: Store.State, subscription: Subscription): Promise<void> {
+  const ttl = ttlFor(subscription)
+  const key = subscriptionKey(subscription.owner, subscription.id)
+  await store.put(key, JSON.stringify(subscription), { ttl })
+
+  // Mirror status into the poller's secondary index: only `active`
+  // subscriptions are polled. The index value is the subscription's storage key
+  // so the poller can hydrate without knowing the owner.
+  const indexKey = activeKey(subscription.chainId, subscription.eventType, subscription.id)
+  if (subscription.status === 'active') await store.put(indexKey, key, { ttl })
+  else await store.delete(indexKey)
+}
+
+function ttlFor(subscription: Subscription): number | undefined {
+  if (!subscription.expiresAt) return undefined
+  return Math.max(1, new Date(subscription.expiresAt).getTime() - Date.now())
+}
+
+function generateId(now: Date): string {
+  // Zero-pad the epoch-ms so ids sort chronologically by string comparison
+  // (mirroring delivery ids), letting listSubscriptions page newest-first; 15
+  // digits leaves headroom well past the year 5138.
+  const timestamp = now.getTime().toString().padStart(15, '0')
+  return `wh_${timestamp}_${nanoid()}`
+}
+
+function generateDeliveryId(now: Date): string {
+  // Zero-pad the epoch-ms so ids sort chronologically by string comparison; 15
+  // digits leaves headroom well past the year 5138.
+  const timestamp = now.getTime().toString().padStart(15, '0')
+  return `whd_${timestamp}_${nanoid()}`
+}
+
+function generateSecret(): string {
+  return `whsec_${Hex.random(32).slice(2)}`
+}
+
+export class LimitExceededError extends Error {
+  /** The cap that was reached. */
+  limit: number
+
+  constructor(limit: number) {
+    super(`Webhook subscription limit reached (${limit}).`)
+    this.name = 'Webhooks.LimitExceededError'
+    this.limit = limit
+  }
+}
+
+/**
+ * Thrown when a subscription's `filters` fail to validate against the schema for
+ * its `eventType`. The detection path treats stored filters as **fail-closed**:
+ * an invalid filter never degrades to a firehose, so the API rejects bad filters
+ * at create/patch time rather than silently widening the match set later.
+ */
+export class InvalidFilterError extends Error {
+  /** Event type whose filters failed validation. */
+  eventType: string
+  /** Per-field validation issues, suitable for an API error `details` array. */
+  details: readonly InvalidFilterError.Detail[]
+
+  constructor(eventType: string, details: readonly InvalidFilterError.Detail[] = []) {
+    super(`Invalid filters for "${eventType}" webhook subscription.`)
+    this.name = 'Webhooks.InvalidFilterError'
+    this.eventType = eventType
+    this.details = details
+  }
+}
+
+export declare namespace InvalidFilterError {
+  /** A single validation issue: a message plus the path to the invalid value. */
+  type Detail = {
+    /** Human-readable validation message. */
+    message: string
+    /** Path to the invalid value within the `filters` object. */
+    path?: readonly (string | number)[] | undefined
+  }
+}
+
+/** Thrown when webhook operations run without a configured state store. */
+export class UnconfiguredError extends Error {
+  constructor() {
+    super('Webhooks are not configured for this deployment.')
+    this.name = 'Webhooks.UnconfiguredError'
+  }
+}