Skip to main content

Notifications

What it is​

The notifications module covers exactly two channels: push notifications (FCM, for OS-level alerts that work when the app is backgrounded or closed) and real-time in-app toasts (Firebase Realtime Database, for lightweight live UI feedback while the app is open). Email and SMS are handled separately as cross-cutting concerns in src/shared/ — this module doesn't own them. There's no salvaged legacy doc for this module; this guide is sourced directly from the code.

Core concepts​

  • Push (FCM): requires a registered device token (POST /register-token, storing fcmToken/deviceId/deviceType/appVersion per user via FCMTokenRepository). Delivered through firebase-notification.service.ts using firebase-admin's messaging API — survives app backgrounding/closure, shows as a native OS notification.
  • Realtime toast (Firebase RTDB): written directly to a Firebase Realtime Database path (not FCM) via FirebaseRealtimeToastService; the client listens to that path live. Meant for immediate, in-session feedback (e.g. "payment confirmed" while the user is actively looking at the screen) rather than something that needs to reach a closed app.
  • Multi-provider abstraction for everything else: email goes through an IEmailProvider interface (send/sendBulk/sendTemplate) with SES and Zeptomail implementations available; SMS/OTP have their own provider implementations (Termii for SMS, plus Cydene/Flutterwave/Meta WhatsApp for OTP delivery). None of these live in the notifications module — see src/shared/implementations/messaging/ and src/shared/utils/mail.ts.

How it works​

Push notification lifecycle​

  1. Client registers its FCM token on login/app-start: POST /v1/notifications/register-token.
  2. Client unregisters on logout: POST /v1/notifications/unregister-token.
  3. GET /my-tokens / GET /verify-token-count let a client (or support) inspect what's currently registered for a user.
  4. POST /cleanup-tokens / POST /cleanup-user-tokens remove stale/invalid tokens — FCM tokens rotate and expire, so this is a maintenance operation, not a one-time setup step.

Toast lifecycle​

  • POST /send-toast (plus send-success-toast/send-error-toast convenience variants) and POST /realtime-toast/event/.../user both create toasts, but through different mechanisms — the plain send-toast family goes through FCM's data-message capability, while realtime-toast/* writes to Firebase RTDB for the live-listening pattern. Check which one a given client integration actually subscribes to before assuming a toast "isn't working."
  • GET /realtime-toast/event/:eventId / GET /realtime-toast/my-toasts — fetch current toasts (e.g. on reconnect, to catch up on anything missed).
  • POST /realtime-toast/cleanup / DELETE /realtime-toast/:toastId — RTDB doesn't auto-expire data, so toasts need explicit cleanup to avoid unbounded growth.

Key business rules & edge cases​

  • Push and realtime-toast are not interchangeable — a toast sent via realtime-toast/event won't reach a user who has the app closed (no RTDB listener running); if the message needs to reach a closed app, it has to go through the FCM push path instead.
  • Token cleanup is manual/on-demand (cleanup-tokens), not automatic on every send — a burst of failed FCM sends to dead tokens doesn't self-heal without this being called (check for a cron/scheduled trigger before assuming it runs itself).
  • Email/SMS "notifications" in the product sense (e.g. RSVP confirmations, event reminders) are not issued through this module at all — they go through the messaging/broadcast/reminder services in src/shared/ and src/modules/events/. If you're looking for where a specific email gets sent, start in src/shared/utils/mail.ts and src/shared/templates/email/, not here.

POST /v1/notifications/register-token, POST /unregister-token, POST /send-toast, POST /realtime-toast/event, POST /realtime-toast/user, GET /realtime-toast/event/{eventId}, GET /realtime-toast/my-toasts. Not yet in the generated OpenAPI spec.

  • src/modules/notifications/notification.routes.ts, notification.controllers.ts, notification.service.ts
  • src/modules/notifications/firebase-notification.service.ts — FCM push
  • src/modules/notifications/firebase-realtime-toast.service.ts — RTDB toasts
  • src/shared/interfaces/email-provider.interface.ts, src/shared/implementations/messaging/ — email/SMS/OTP providers (separate from this module)