Notifications

1. 1

   Choose a canonical event key

   Callers use a canonical event key for preferences and delivery logs. Application-owned events may also have editable templates; team.invite remains Supabase Auth-owned.

   Relevant Product code

   • src/features/notifications/shared/events/registry.ts
2. 2

   Queue the work

   The queue helper writes notification_outbox rows with recipient, payload, resource id, dedupe key, status, and next attempt time.

   Relevant Product code

   • src/features/notifications/server/delivery/queue/notify-queue.ts
3. 3

   Claim atomically

   The worker uses claim_notification_batch to avoid two workers sending the same queued message.

   Relevant Product code

   • src/features/notifications/server/outbox/services/worker.ts
   • supabase/migrations/20260426000000_init.sql
4. 4

   Dispatch, retry, or dead-letter

   Delivery runs through the registry, records provider status, retries transient failures with backoff, and dead-letters exhausted rows.

   Relevant Product code

   • src/features/notifications/server/outbox/services/worker.ts
   • src/features/notifications/server/events/dispatch.ts

Use this example as a starting point, then adapt it to your product's rules and configuration.

This is the complete current registry. Add events here first, then explicitly decide whether delivery is Supabase Auth-owned or application-owned before adding an editable template.

export const NOTIFICATION_EVENT_KEY_VALUES = [
  "lead.new",
  "lead.contact.message",
  "lead.contact.reply",
  "team.invite",
  "auth.signup.welcome",
  "system.alert",
  "operations.stripe.dispute.created",
  "billing.invoice.payment_succeeded",
  "billing.invoice.payment_failed",
  "billing.subscription.started",
  "billing.subscription.changed",
  "billing.subscription.canceled",
  "billing.subscription.expired",
  "billing.subscription.expiring_soon",
  "billing.refund.issued",
  "billing.order.completed",
  "billing.credit_pack.granted",
  "billing.credit_balance.low",
  "billing.usage.threshold_reached",
  "billing.usage.summary",
] as const;