Notifications Module

HTTP surface for the event-driven notification system — customer + vendor mobile-device registration for FCM push, admin broadcasts (one-off email or push to a defined audience), and the admin notification audit log.

Source: api-modules/notifications (registered via NotificationsModule.forRoot({ providers, templates, resolvers }) in apps/api/src/app.module.ts).

The module is a router, not a sender. It listens for domain events (order.placed, order.vendor.fulfilled, etc.) via NestJS @OnEvent, resolves recipients + channels via per-event resolvers, renders templates, and dispatches to provider modules. Concrete senders live in:

• api-modules/notifications-email-mailer — SMTP email via the mailer module
• api-modules/notifications-push-fcm — Firebase Cloud Messaging push

Both register NotificationProvider instances against NOTIFICATION_PROVIDERS. Adding a new channel (SMS, WhatsApp) is a new provider module — the core notifications module doesn't change.

Conventions

Authentication

Response envelope

Successful responses are wrapped by ResponseInterceptor:

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 200,
  "metadata": { /* optional, e.g. pagination */ }
}

Error envelope

Architecture

┌──────────────────────┐   EventEmitter2   ┌────────────────────────────────┐
│ order / shipping /   │ ──────────────▶  │ NotificationOrchestratorService │
│ catalog / cart …     │                  │ (listens via @OnEvent)          │
└──────────────────────┘                  └─────────────────┬──────────────┘
                                                            │
                            ┌───────────────────────────────┼──────────────────────┐
                            ▼                               ▼                      ▼
                  RecipientResolver           NotificationTemplate        NotificationProvider
                  (per-event class)           (per-(event, channel))      (email, push, ...)
                            │                               │                      │
                            └───── BullMQ "notification" ───┴──── enqueue ─────────┘
                                              │
                                              ▼
                                       NotificationLog
                                       (audit row per send)

Admin broadcast bypasses the resolver path: the controller writes a broadcast row, enqueues onto the notification.broadcast queue, and the worker fans out per-recipient notification jobs based on the chosen audience.

Domain types

DeviceResponse

type DeviceResponse = {
  id: string;
  platform: "android" | "ios";
  appKind: "customer" | "vendor";
  lastSeenAt: string;            // ISO; updated on every re-register
};

BroadcastResponse

type BroadcastResponse = {
  id: string;
  status: string;                // "scheduled" | "running" | "completed" | "cancelled" | "failed"
  audienceType: string;          // "all_customers" | "all_vendors" | "user_ids"
  channels: string[];            // subset of ["email", "push"]
  scheduledFor: string | null;   // ISO; null = send-now
  totalRecipients: number | null;
  sentCount: number;
  failedCount: number;
  createdAt: string;
};

NotificationLogResponse

One row per send attempt (success or failure). Use this to answer "did the customer get the email?" from support.

type NotificationLogResponse = {
  id: string;
  recipientUserId: string | null;     // null when send was to a non-user (rare)
  channel: string;                    // "email" | "push"
  provider: string;                   // e.g. "smtp-mailer", "fcm"
  eventType: string;                  // e.g. "order.placed", "admin.broadcast"
  broadcastId: string | null;         // populated for broadcast sends
  subject: string | null;             // email subject (or push title for "push")
  status: string;                     // "sent" | "failed"
  error: string | null;
  sentAt: string;                     // ISO
};

Devices

Both the customer and vendor app register their FCM token after login. Re-registering the same token is idempotent — it refreshes lastSeenAt instead of creating a duplicate row. Apps are expected to call DELETE on logout to stop unrelated pushes from leaking to a shared device.

POST /store/devices — Register customer device

Body

{
  "platform": "android",          // "android" | "ios"
  "token": "fcm-registration-token-..." // 10..4096 chars
}

Response 201 — DeviceResponse with appKind="customer".

DELETE /store/devices — Unregister customer device

Body

{ "token": "fcm-registration-token-..." }

Idempotent — unknown token is a no-op 200.

Response 200

{ "data": { "ok": true }, "message": "Success", "statusCode": 200 }

POST /vendor/devices — Register vendor device

Same shape and rules as the storefront version, scoped to the vendor session. Returns DeviceResponse with appKind="vendor".

DELETE /vendor/devices — Unregister vendor device

Same shape as storefront.

Admin broadcasts

Base path: /admin/notifications/broadcasts.

POST /admin/notifications/broadcasts — Create a broadcast

Required permission: notifications: broadcast. Send-now (omit scheduleFor) or scheduled (future ISO datetime).

Body

{
  "audience": {
    "type": "user_ids",
    "userIds": ["01J9...", "01J9..."]   // 1..10_000
  },
  "channels": ["email", "push"],         // 1..2 of "email" | "push"
  "content": {
    "email": {
      "subject": "Festive sale starts tomorrow",
      "html": "<h1>Save 30%</h1>...",
      "text": "Save 30%..."             // optional plaintext fallback
    },
    "push": {
      "title": "Festive sale",
      "body":  "Up to 30% off — starts in 24h",
      "imageUrl": "https://cdn.example/banner.png",
      "data": { "deepLink": "/sale" }
    }
  },
  "scheduleFor": "2026-05-12T03:00:00.000Z"   // optional; past values reject
}

audience.type discriminator (mutually exclusive):

Cross-field rule: content.email is required when channels contains "email"; content.push is required when channels contains "push".

Response 201 — BroadcastResponse. status reflects whether it's scheduled or already running.

Errors

GET /admin/notifications/broadcasts — List broadcasts

Required permission: notifications: view. Newest first.

Query

Response 200 — paginated envelope of BroadcastResponse[].

GET /admin/notifications/broadcasts/:id — Broadcast detail

Required permission: notifications: view. Returns the BroadcastResponse with current counters (sentCount, failedCount).

POST /admin/notifications/broadcasts/:id/cancel — Cancel a broadcast

Required permission: notifications: broadcast.

Response 200 — BroadcastResponse.

Admin log

GET /admin/notifications/log — Audit log

Required permission: notifications: view. One row per send attempt. Newest first.

Query

eventType="admin.broadcast" is the sentinel for sends from the broadcast pathway; per-event sends use the underlying domain event name.

Response 200 — paginated envelope of NotificationLogResponse[].

Event-driven sends (no HTTP surface)

The orchestrator subscribes to these events out of the box (see resolvers/order/). The set is extensible — add a RecipientResolver + NotificationTemplate (+ register them in NotificationsModule.forRoot) for any new event.

Recipient resolution falls back gracefully — a customer with no FCM device gets email-only; one with no email skips the email channel. Send failures land in notification_log with status="failed" and the provider error.

Configuration

Process env (used by provider modules)

Constants

Related modules

• notifications-email-mailer — SMTP email provider. Wraps @sc/mailer.
• notifications-push-fcm — FCM push provider.
• mailer — low-level SMTP transport.
• queue — BullMQ infrastructure shared with inventory and other async workers.
• order / shipping — primary event sources today. See order.md, shipping.md.