@strav/payment 1.0.0-alpha.24

package/src/webhook/payment_webhook_event_schema.ts

@@ -0,0 +1,40 @@
+/**
+ * `paymentWebhookEventSchema` — system-wide dedup ledger for
+ * incoming webhooks from every configured provider.
+ *
+ * On every delivery (after signature verification), the framework
+ * does:
+ *
+ *   INSERT INTO payment_webhook_event (...) ON CONFLICT DO NOTHING
+ *
+ * The first delivery wins the INSERT and fires user handlers;
+ * subsequent deliveries (provider retries, concurrent webhook
+ * workers) see the conflict and return 200 without re-firing.
+ *
+ * Why NOT tenanted: webhooks arrive without tenant context. The
+ * endpoint can't know which tenant a payload belongs to until
+ * after signature verification + payload inspection — too late
+ * for the framework-level dedup INSERT.
+ *
+ * Why a composite unique key `(provider, provider_event_id)`:
+ * different providers may emit colliding event id formats; the
+ * pair is the actual uniqueness contract.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const paymentWebhookEventSchema = defineSchema(
+  'payment_webhook_event',
+  Archetype.Event,
+  (t) => {
+    t.id()
+    t.string('provider').max(64).notNull()
+    t.string('provider_event_id').max(255).notNull()
+    t.string('event_type').max(128).notNull()
+    t.timestamp('received_at').notNull()
+    t.timestamp('processed_at').nullable()
+    // Composite (provider, provider_event_id) unique constraint
+    // is added by `applyPaymentLedgerMigration` — the schema
+    // builder only exposes per-column `.unique()`.
+  },
+)

package/src/webhook/payment_webhook_registry.ts

@@ -0,0 +1,65 @@
+/**
+ * Handler registry for normalized payment webhook events.
+ *
+ * Apps register handlers at boot:
+ *
+ *   payment.onWebhookEvent('subscription.created', (ctx) => { ... })
+ *   payment.onWebhookEvent('charge.succeeded', { provider: 'stripe' }, (ctx) => { ... })
+ *
+ * Handlers fire in registration order. A thrown handler aborts
+ * the rest and surfaces a 500 (the provider retries). Multiple
+ * handlers per `(eventType, provider?)` are fine.
+ *
+ * Filter semantics: when `filter.provider` is set, the handler
+ * only fires for that provider; when omitted, the handler fires
+ * for any provider that emits the type.
+ */
+
+import type {
+  PaymentEventType,
+  WebhookHandler,
+  WebhookHandlerFilter,
+} from '../dto/payment_event.ts'
+
+interface RegisteredHandler {
+  filter: WebhookHandlerFilter
+  handler: WebhookHandler
+}
+
+export class PaymentWebhookRegistry {
+  private readonly handlers = new Map<PaymentEventType, RegisteredHandler[]>()
+
+  on(eventType: PaymentEventType, handler: WebhookHandler): void
+  on(
+    eventType: PaymentEventType,
+    filter: WebhookHandlerFilter,
+    handler: WebhookHandler,
+  ): void
+  on(
+    eventType: PaymentEventType,
+    filterOrHandler: WebhookHandlerFilter | WebhookHandler,
+    maybeHandler?: WebhookHandler,
+  ): void {
+    const { filter, handler } =
+      typeof filterOrHandler === 'function'
+        ? { filter: {}, handler: filterOrHandler }
+        : { filter: filterOrHandler, handler: maybeHandler! }
+    const existing = this.handlers.get(eventType) ?? []
+    existing.push({ filter, handler })
+    this.handlers.set(eventType, existing)
+  }
+
+  /** Remove every registered handler. Tests use this to keep cases isolated. */
+  clear(): void {
+    this.handlers.clear()
+  }
+
+  /** Resolve the handlers that match a given `(type, provider)` pair. */
+  resolve(eventType: PaymentEventType, provider: string): readonly WebhookHandler[] {
+    const matches = this.handlers.get(eventType)
+    if (!matches) return []
+    return matches
+      .filter((m) => !m.filter.provider || m.filter.provider === provider)
+      .map((m) => m.handler)
+  }
+}