@strav/payment 1.0.0-alpha.24

package/src/payment_manager.ts

@@ -0,0 +1,174 @@
+/**
+ * `PaymentManager` — the facade apps use for payment workflows.
+ *
+ * Three concept clusters:
+ *
+ *   - **Drivers.** Apps declare providers in
+ *     `config.payment.providers`. The manager constructs each
+ *     driver lazily on first `use(name)` + memoizes. Custom
+ *     drivers register via `manager.extend(name, factory)`.
+ *
+ *   - **Resource namespaces.** `customers`, `subscriptions`,
+ *     `products`, `prices`, `paymentMethods`, `charges`,
+ *     `invoices`, `checkout` — each accessor routes to the
+ *     active driver's matching `*Ops` group. The default driver
+ *     handles unqualified calls; `payment.use('asia').charges`
+ *     routes elsewhere.
+ *
+ *   - **Webhooks.** `manager.onWebhookEvent(type, handler)` /
+ *     `manager.onWebhookEvent(type, filter, handler)` registers
+ *     a normalized-event handler. The `paymentWebhook()` route
+ *     dispatches into the registry after dedup + normalize.
+ *
+ * Multitenancy: tenanted ledger tables rely on
+ * `app.tenant_id` session settings, the same RLS pattern as
+ * `@strav/database`. Apps that wrap calls in
+ * `tenants.withTenant(...)` get per-tenant ledger isolation for
+ * free.
+ */
+
+import type {
+  ChargeOps,
+  CheckoutOps,
+  CustomerOps,
+  InvoiceOps,
+  LinkOps,
+  PaymentDriver,
+  PaymentDriverFactory,
+  PaymentMethodOps,
+  PriceOps,
+  ProductOps,
+  SubscriptionOps,
+  WebhookOps,
+} from './payment_driver.ts'
+import {
+  PaymentConfigError,
+  UnknownProviderError,
+} from './payment_error.ts'
+import type {
+  PaymentEventType,
+  WebhookHandler,
+  WebhookHandlerFilter,
+} from './dto/payment_event.ts'
+import { PaymentWebhookRegistry } from './webhook/payment_webhook_registry.ts'
+import type { TenantManager } from '@strav/database'
+import type { PaymentLedger } from './ledger/payment_ledger.ts'
+import type { PaymentConfig, ProviderConfig } from './types.ts'
+
+export interface PaymentManagerOptions {
+  config: PaymentConfig
+  /** Optional ledger — when omitted, `applyEvent` during webhook dispatch no-ops. */
+  ledger?: PaymentLedger
+  /**
+   * Optional tenancy bridge. When set, the webhook dispatcher
+   * wraps ledger writes + user handlers in
+   * `tenantManager.withTenant(event.tenantId, ...)`. Events
+   * arrive without a `tenantId` skip the wrapper (and the
+   * ledger write, if ledger sync is on).
+   */
+  tenantManager?: TenantManager
+}
+
+export class PaymentManager {
+  readonly config: PaymentConfig
+  readonly webhookRegistry = new PaymentWebhookRegistry()
+  readonly ledger: PaymentLedger | undefined
+  readonly tenantManager: TenantManager | undefined
+
+  private readonly drivers = new Map<string, PaymentDriver>()
+  private readonly extensions = new Map<string, PaymentDriverFactory>()
+
+  constructor(options: PaymentManagerOptions) {
+    const { config } = options
+    if (!config.providers[config.default]) {
+      throw new PaymentConfigError(
+        `PaymentManager: default provider "${config.default}" is not configured.`,
+        {
+          context: {
+            default: config.default,
+            available: Object.keys(config.providers),
+          },
+        },
+      )
+    }
+    this.config = config
+    this.ledger = options.ledger
+    this.tenantManager = options.tenantManager
+  }
+
+  // ─── Driver routing ───────────────────────────────────────────────────
+
+  /** Resolve a driver by app-chosen instance name (or the default when omitted). */
+  use(name?: string): PaymentDriver {
+    const key = name ?? this.config.default
+    const cached = this.drivers.get(key)
+    if (cached) return cached
+
+    const cfg = this.config.providers[key]
+    if (!cfg) {
+      throw new UnknownProviderError(key, Object.keys(this.config.providers))
+    }
+    const ext = this.extensions.get(cfg.driver)
+    if (!ext) {
+      throw new PaymentConfigError(
+        `PaymentManager: unknown driver "${cfg.driver}" for provider "${key}". Register it via \`manager.extend("${cfg.driver}", factory)\` or install the matching adapter package.`,
+        { context: { driver: cfg.driver, available: [...this.extensions.keys()] } },
+      )
+    }
+    const driver = ext({ instanceName: key, config: cfg as ProviderConfig & { driver: string } })
+    this.drivers.set(key, driver)
+    return driver
+  }
+
+  /**
+   * Register a driver factory. Adapter packages
+   * (`@strav/payment-stripe`, …) call this from their
+   * ServiceProvider's `register()` step. Custom adapters
+   * register the same way.
+   */
+  extend(driverName: string, factory: PaymentDriverFactory): void {
+    this.extensions.set(driverName, factory)
+  }
+
+  /** Hand-wire a driver instance under an app-chosen name (tests / one-offs). */
+  useDriver(instanceName: string, driver: PaymentDriver): void {
+    this.drivers.set(instanceName, driver)
+  }
+
+  // ─── Resource namespaces (route to the default driver) ───────────────
+
+  get customers(): CustomerOps { return this.use().customers }
+  get products(): ProductOps { return this.use().products }
+  get prices(): PriceOps { return this.use().prices }
+  get subscriptions(): SubscriptionOps { return this.use().subscriptions }
+  get paymentMethods(): PaymentMethodOps { return this.use().paymentMethods }
+  get charges(): ChargeOps { return this.use().charges }
+  get invoices(): InvoiceOps { return this.use().invoices }
+  get checkout(): CheckoutOps { return this.use().checkout }
+  get links(): LinkOps { return this.use().links }
+  get webhook(): WebhookOps { return this.use().webhook }
+
+  // ─── Webhook handler registration ─────────────────────────────────────
+
+  onWebhookEvent(type: PaymentEventType, handler: WebhookHandler): void
+  onWebhookEvent(
+    type: PaymentEventType,
+    filter: WebhookHandlerFilter,
+    handler: WebhookHandler,
+  ): void
+  onWebhookEvent(
+    type: PaymentEventType,
+    filterOrHandler: WebhookHandlerFilter | WebhookHandler,
+    maybeHandler?: WebhookHandler,
+  ): void {
+    if (typeof filterOrHandler === 'function') {
+      this.webhookRegistry.on(type, filterOrHandler)
+    } else {
+      this.webhookRegistry.on(type, filterOrHandler, maybeHandler!)
+    }
+  }
+
+  clearWebhookHandlers(): void {
+    this.webhookRegistry.clear()
+  }
+}

package/src/payment_provider.ts

@@ -0,0 +1,93 @@
+/**
+ * `PaymentProvider` — `ServiceProvider` that wires
+ * `PaymentManager`, `PaymentWebhookEventRepository`, and
+ * (when ledger is enabled) `PaymentLedger` into the container
+ * from `config.payment`.
+ *
+ * Adapter packages register their drivers separately via their
+ * own ServiceProvider (e.g. `StripePaymentProvider`) in
+ * `register()` BEFORE this provider's `boot()` runs. The order
+ * is enforced by listing the adapter providers AFTER
+ * `PaymentProvider` in the app's `bootstrap/providers.ts` —
+ * `register()` runs in declaration order, then `boot()` runs in
+ * the same order. Adapter `register()` calls
+ * `manager.extend(driver, factory)`; this provider's `boot()`
+ * eagerly resolves each configured instance, surfacing config
+ * errors at boot.
+ *
+ * Alternatively, an adapter's `boot()` can do the eager resolve
+ * itself. Either pattern is supported.
+ */
+
+// biome-ignore lint/style/useImportType: PostgresDatabase + TenantManager value imports for the container's binding factory.
+import { PostgresDatabase, TenantManager } from '@strav/database'
+import {
+  type Application,
+  ConfigRepository,
+  ServiceProvider,
+} from '@strav/kernel'
+import { PaymentLedger } from './ledger/payment_ledger.ts'
+import { PaymentConfigError } from './payment_error.ts'
+import { PaymentManager } from './payment_manager.ts'
+import type { PaymentConfig } from './types.ts'
+import { PaymentWebhookEventRepository } from './webhook/payment_webhook_event_repository.ts'
+// biome-ignore lint/style/useImportType: EventBus value import for the container's binding factory.
+import { EventBus } from '@strav/kernel'
+
+export class PaymentProvider extends ServiceProvider {
+  override readonly name = 'payment'
+  override readonly dependencies = ['config', 'database']
+
+  override register(app: Application): void {
+    app.singleton(PaymentManager, (c) => {
+      const raw = c.resolve(ConfigRepository).get('payment') as PaymentConfig | undefined
+      if (!raw) {
+        throw new PaymentConfigError(
+          'PaymentProvider: `config.payment` is missing. Add `config/payment.ts` with at least one provider.',
+        )
+      }
+      if (!raw.providers || Object.keys(raw.providers).length === 0) {
+        throw new PaymentConfigError(
+          'PaymentProvider: `config.payment.providers` is empty. Configure at least one provider.',
+        )
+      }
+
+      const ledgerEnabled = raw.ledger?.enabled ?? true
+      const ledger = ledgerEnabled ? new PaymentLedger(c.resolve(PostgresDatabase)) : undefined
+
+      // TenantManager is optional — apps that don't use the
+      // multi-tenant database surface can still use payment.
+      // When present, the webhook dispatcher uses it to scope
+      // ledger writes + user handlers per-event.
+      let tenantManager: TenantManager | undefined
+      try {
+        tenantManager = c.resolve(TenantManager)
+      } catch {
+        tenantManager = undefined
+      }
+
+      return new PaymentManager({
+        config: raw,
+        ...(ledger ? { ledger } : {}),
+        ...(tenantManager ? { tenantManager } : {}),
+      })
+    })
+
+    app.singleton(
+      PaymentWebhookEventRepository,
+      (c) =>
+        new PaymentWebhookEventRepository({
+          db: c.resolve(PostgresDatabase),
+          events: c.resolve(EventBus),
+        }),
+    )
+  }
+
+  override boot(app: Application): void {
+    // Force-resolve so config errors surface at boot. Driver
+    // instances are constructed lazily on first `use()` — adapter
+    // ServiceProviders register the factories during `register()`,
+    // which by this point has already run.
+    app.resolve(PaymentManager)
+  }
+}

package/src/tenant_metadata.ts

@@ -0,0 +1,60 @@
+/**
+ * Conventional metadata key that carries the Strav tenant id on
+ * every create-call that should produce tenant-scoped webhooks.
+ *
+ * Multi-tenant apps stamp this on every `payment.customers.create`,
+ * `payment.charges.create`, `payment.subscriptions.create`, etc.
+ * Providers echo metadata back on every webhook delivery, so the
+ * framework's `paymentWebhook()` dispatcher reads it back and
+ * wraps ledger writes + user handlers in
+ * `TenantManager.withTenant(...)`.
+ *
+ * Why a framework-namespaced key (not just `tenant_id`): some
+ * apps use generic `tenant_id` for their own purposes (Stripe
+ * Connect tenancy, partner account routing, …). `strav_tenant_id`
+ * is reserved.
+ *
+ * Key length: provider metadata limits — Stripe ≤ 40 chars, Omise
+ * keys ≤ 255 chars. Our prefix `strav_tenant_id` is 15 chars, well
+ * within both. Values are app-supplied tenant ids (typically
+ * ULIDs = 26 chars).
+ */
+
+export const TENANT_METADATA_KEY = 'strav_tenant_id'
+
+/**
+ * Build a metadata bag that stamps the tenant id alongside
+ * any caller-supplied keys. Use on every create call that should
+ * produce tenant-scoped webhook events.
+ *
+ * ```ts
+ * await payment.customers.create({
+ *   email: user.email,
+ *   metadata: tenantedMetadata(user.tenant_id, { source: 'signup' }),
+ * })
+ * ```
+ *
+ * If `extra` already contains `strav_tenant_id`, the explicit
+ * argument wins — apps that want to override (rare; testing
+ * fixtures) can do so.
+ */
+export function tenantedMetadata(
+  tenantId: string,
+  extra: Record<string, string> = {},
+): Record<string, string> {
+  return { ...extra, [TENANT_METADATA_KEY]: tenantId }
+}
+
+/**
+ * Extract a Strav tenant id from a provider's metadata bag. Used
+ * by driver `normalize` functions when reading webhook events.
+ * Returns `undefined` when the metadata is missing or the tenant
+ * key isn't set.
+ */
+export function readTenantId(
+  metadata: Record<string, unknown> | null | undefined,
+): string | undefined {
+  if (!metadata) return undefined
+  const v = metadata[TENANT_METADATA_KEY]
+  return typeof v === 'string' && v.length > 0 ? v : undefined
+}

package/src/types.ts

@@ -0,0 +1,49 @@
+/**
+ * `@strav/payment` — runtime config shapes.
+ *
+ * `PaymentConfig` is the `config.payment` shape apps declare in
+ * `config/payment.ts`. Multi-provider by default: a `providers`
+ * map keyed by app-chosen name, each with a `driver` discriminator
+ * the framework resolves to a concrete `PaymentDriver`. Apps that
+ * want a single provider just register one entry.
+ *
+ * `ProviderConfig` is intentionally free-form (`[key: string]:
+ * unknown`) so each adapter package owns its own config shape
+ * (`StripeConfig`, `PaddleConfig`, `OmiseConfig`) without forcing
+ * the core to know every vendor field.
+ */
+
+export interface PaymentConfig {
+  /** Key into `providers`. The default routing target for unqualified `payment.*` calls. */
+  default: string
+  providers: Record<string, ProviderConfig>
+  ledger?: LedgerConfig
+}
+
+export interface ProviderConfig {
+  /**
+   * Driver identifier — must match a built-in (`'stripe'`,
+   * `'paddle'`, `'omise'`) or a name registered via
+   * `manager.extend(name, factory)`.
+   */
+  driver: string
+  /** Driver-specific fields — see each adapter's `*Config`. */
+  [key: string]: unknown
+}
+
+export interface LedgerConfig {
+  /**
+   * Mirror provider state (customers / subscriptions / invoices)
+   * into the local ledger tables. Default `true`. When false,
+   * only the webhook dedup table is used; apps own their own
+   * ledger.
+   */
+  enabled?: boolean
+  /**
+   * When `enabled`, upsert into the ledger on every webhook
+   * delivery (before user handlers fire). Default `true`. Apps
+   * that prefer eventual consistency via a background job set
+   * this to `false` and run their own sync.
+   */
+  syncOnWebhook?: boolean
+}

package/src/webhook/index.ts

@@ -0,0 +1,8 @@
+export { PaymentWebhookEvent } from './payment_webhook_event.ts'
+export { PaymentWebhookEventRepository } from './payment_webhook_event_repository.ts'
+export { paymentWebhookEventSchema } from './payment_webhook_event_schema.ts'
+export {
+  paymentWebhook,
+  type PaymentWebhookOptions,
+} from './payment_webhook.ts'
+export { PaymentWebhookRegistry } from './payment_webhook_registry.ts'

package/src/webhook/payment_webhook.ts

@@ -0,0 +1,190 @@
+/**
+ * Provider-agnostic webhook route handler.
+ *
+ * Mount once per app:
+ *
+ *   router.post('/webhooks/:provider', paymentWebhook())
+ *
+ * Per request flow:
+ *
+ *   1. Read the `:provider` route param — picks the driver
+ *      instance to verify against.
+ *   2. Read the raw body. Signature is computed over the bytes,
+ *      so JSON-parsing first invalidates verification.
+ *   3. Resolve the signature header — drivers carry their own
+ *      header name (`stripe-signature`, `paddle-signature`,
+ *      `x-omise-signature`); the handler reads them all.
+ *   4. `driver.webhook.verify(rawBody, signature)` — returns the
+ *      provider-native event. 400 + retry on failure.
+ *   5. Idempotency claim against
+ *      `payment_webhook_event(provider, provider_event_id)`. The
+ *      first delivery wins; replays return 200 `{ duplicate: true }`.
+ *   6. `driver.webhook.normalize(event)` — maps onto a
+ *      `NormalizedWebhookEvent`. `null` means the event isn't on
+ *      the framework's closed union; the dedup row stays, but no
+ *      user handler fires.
+ *   7. Dispatch matching handlers from `PaymentWebhookRegistry`.
+ *      Handlers run in registration order. Throwing leaves
+ *      `processed_at` NULL so dashboards can surface stuck
+ *      events; the route returns 500 so the provider retries.
+ *   8. Mark `processed_at` on success.
+ */
+
+import type { HttpContext } from '@strav/http'
+import type { NormalizedWebhookEvent, WebhookHandlerContext } from '../dto/payment_event.ts'
+import { PaymentManager } from '../payment_manager.ts'
+import { UnknownProviderError, WebhookSignatureError } from '../payment_error.ts'
+import { PaymentWebhookEventRepository } from './payment_webhook_event_repository.ts'
+
+export interface PaymentWebhookOptions {
+  /** Override the global ledger-sync flag for this route. */
+  syncLedger?: boolean
+}
+
+const SIGNATURE_HEADERS = [
+  'stripe-signature',
+  'paddle-signature',
+  'x-omise-signature',
+  'webhook-signature',
+]
+
+export function paymentWebhook(
+  options: PaymentWebhookOptions = {},
+): (ctx: HttpContext) => Promise<Response> {
+  return async (ctx: HttpContext): Promise<Response> => {
+    const providerName = ctx.request.params['provider']
+    if (!providerName) {
+      return ctx.response.json(
+        { error: 'Missing :provider route param. Mount as `/webhooks/:provider`.' },
+        { status: 400 },
+      )
+    }
+
+    const manager = ctx.container.resolve(PaymentManager)
+    let driver
+    try {
+      driver = manager.use(providerName)
+    } catch (cause) {
+      if (cause instanceof UnknownProviderError) {
+        return ctx.response.json({ error: cause.message }, { status: 404 })
+      }
+      throw cause
+    }
+
+    const signature = findSignatureHeader(ctx.request.headers)
+    if (!signature) {
+      return ctx.response.json(
+        { error: 'Missing provider signature header.' },
+        { status: 400 },
+      )
+    }
+
+    const rawBody = await ctx.request.raw.text()
+
+    let nativeEvent: unknown
+    try {
+      nativeEvent = await driver.webhook.verify(rawBody, signature)
+    } catch (cause) {
+      if (cause instanceof WebhookSignatureError) {
+        return ctx.response.json({ error: cause.message }, { status: 400 })
+      }
+      throw cause
+    }
+
+    const normalized = driver.webhook.normalize(nativeEvent)
+    const eventIdForDedup = normalized?.id ?? extractEventId(nativeEvent)
+    const eventTypeForDedup = normalized?.type ?? extractEventType(nativeEvent) ?? 'unknown'
+
+    if (!eventIdForDedup) {
+      return ctx.response.json(
+        { error: 'Provider event is missing an id; cannot dedup.' },
+        { status: 400 },
+      )
+    }
+
+    const repo = ctx.container.resolve(PaymentWebhookEventRepository)
+    const claimed = await repo.claim(providerName, eventIdForDedup, eventTypeForDedup)
+    if (!claimed) {
+      return ctx.response.json({ received: true, duplicate: true })
+    }
+
+    if (normalized) {
+      // The route picks the driver instance by `:provider`. Apps
+      // register handlers against the same instance name they
+      // configured (`payment.use('asia') ↔ /webhooks/asia`), so
+      // we override the normalized event's `provider` field with
+      // the instance name. Drivers fill `provider` with their
+      // own name (`'stripe'`, `'omise'`) but instance-name routing
+      // is what the dispatcher honours.
+      const routed: NormalizedWebhookEvent = { ...normalized, provider: providerName }
+      const syncLedger = options.syncLedger ?? manager.config.ledger?.syncOnWebhook ?? true
+
+      // Tenant routing — when the event carries a `tenantId`
+      // (drivers read `metadata.strav_tenant_id`) AND a
+      // TenantManager is wired, scope ledger writes + user
+      // handlers via `withTenant`. The `tx` argument is the
+      // executor on which `withTenant` set `app.tenant_id`
+      // (LOCAL = transaction scope); ledger writes MUST use it
+      // so `current_setting('app.tenant_id')` resolves.
+      //
+      // Events without a `tenantId` skip the ledger write (the
+      // tables are tenanted; writing without scope would violate
+      // RLS / NOT NULL) but still dispatch to user handlers so
+      // apps can reconcile manually.
+      if (routed.tenantId && manager.tenantManager) {
+        await manager.tenantManager.withTenant(routed.tenantId, async (tx) => {
+          if (syncLedger && manager.ledger) {
+            await manager.ledger.applyEvent(routed, tx)
+          }
+          await dispatch(manager, routed)
+        })
+      } else {
+        await dispatch(manager, routed)
+      }
+    }
+
+    await repo.markProcessed(providerName, eventIdForDedup)
+    return ctx.response.json({ received: true, duplicate: false })
+  }
+}
+
+async function dispatch(
+  manager: PaymentManager,
+  event: NormalizedWebhookEvent,
+): Promise<void> {
+  const handlers = manager.webhookRegistry.resolve(event.type, event.provider)
+  if (handlers.length === 0) return
+  const ctx: WebhookHandlerContext = {
+    event,
+    eventId: event.id,
+    eventType: event.type,
+    provider: event.provider,
+    ...(event.tenantId ? { tenantId: event.tenantId } : {}),
+    raw: event.raw,
+  }
+  for (const handler of handlers) {
+    await handler(ctx)
+  }
+}
+
+function findSignatureHeader(headers: Headers): string | null {
+  for (const name of SIGNATURE_HEADERS) {
+    const value = headers.get(name)
+    if (value) return value
+  }
+  return null
+}
+
+function extractEventId(event: unknown): string | null {
+  if (event && typeof event === 'object' && 'id' in event && typeof (event as { id: unknown }).id === 'string') {
+    return (event as { id: string }).id
+  }
+  return null
+}
+
+function extractEventType(event: unknown): string | null {
+  if (event && typeof event === 'object' && 'type' in event && typeof (event as { type: unknown }).type === 'string') {
+    return (event as { type: string }).type
+  }
+  return null
+}

package/src/webhook/payment_webhook_event.ts

@@ -0,0 +1,22 @@
+/**
+ * `PaymentWebhookEvent` — typed row of the dedup ledger.
+ *
+ * Apps rarely touch this directly. Operator dashboards use it to
+ * list recent events, surface processing latencies, or flag
+ * stuck deliveries (rows where `processed_at` is still NULL after
+ * dispatch should have completed).
+ */
+
+import { Model } from '@strav/database'
+import { paymentWebhookEventSchema } from './payment_webhook_event_schema.ts'
+
+export class PaymentWebhookEvent extends Model {
+  static override readonly schema = paymentWebhookEventSchema
+
+  id!: string
+  provider!: string
+  provider_event_id!: string
+  event_type!: string
+  received_at!: Date
+  processed_at!: Date | null
+}

package/src/webhook/payment_webhook_event_repository.ts

@@ -0,0 +1,65 @@
+/**
+ * `PaymentWebhookEventRepository` — data access for the webhook
+ * dedup ledger.
+ *
+ * Two custom helpers on top of the generic CRUD surface:
+ *
+ *   - `claim(provider, eventId, type)` — atomic INSERT ... ON
+ *     CONFLICT DO NOTHING RETURNING id. Returns the row on win,
+ *     `null` when another delivery already recorded the
+ *     `(provider, provider_event_id)` pair.
+ *
+ *   - `markProcessed(provider, eventId)` — bumps `processed_at`
+ *     to NOW(). Observability-only; not part of the dedup
+ *     decision. Rows with `received_at` set but `processed_at`
+ *     NULL surface stuck deliveries (handler threw / process
+ *     crashed mid-dispatch).
+ */
+
+import { quoteIdent, Repository } from '@strav/database'
+import { ulid } from '@strav/kernel'
+import { PaymentWebhookEvent } from './payment_webhook_event.ts'
+import { paymentWebhookEventSchema } from './payment_webhook_event_schema.ts'
+
+export class PaymentWebhookEventRepository extends Repository<PaymentWebhookEvent> {
+  static override readonly schema = paymentWebhookEventSchema
+  static override readonly model = PaymentWebhookEvent
+
+  /**
+   * Atomically record receipt of an event. Returns the inserted
+   * row when this call won the race, `null` when the
+   * `(provider, provider_event_id)` pair was already recorded.
+   */
+  async claim(
+    provider: string,
+    providerEventId: string,
+    eventType: string,
+  ): Promise<PaymentWebhookEvent | null> {
+    const table = quoteIdent(paymentWebhookEventSchema.name)
+    const sql = `
+      INSERT INTO ${table}
+        ("id", "provider", "provider_event_id", "event_type", "received_at")
+      VALUES ($1, $2, $3, $4, NOW())
+      ON CONFLICT ("provider", "provider_event_id") DO NOTHING
+      RETURNING *
+    `
+    const rows = await this.db.query<Record<string, unknown>>(sql, [
+      ulid(),
+      provider,
+      providerEventId,
+      eventType,
+    ])
+    if (rows.length === 0) return null
+    return this.hydrate(rows[0]!)
+  }
+
+  /** Bump `processed_at` to NOW(). No-op when the row doesn't exist. */
+  async markProcessed(provider: string, providerEventId: string): Promise<void> {
+    const table = quoteIdent(paymentWebhookEventSchema.name)
+    await this.db.execute(
+      `UPDATE ${table} SET "processed_at" = NOW()
+       WHERE "provider" = $1 AND "provider_event_id" = $2`,
+      [provider, providerEventId],
+    )
+  }
+}