Notifications Module — Admin

HTTP surface for the admin notification operations: composing and sending broadcasts (one-shot email and/or push to a targeted audience) and inspecting the notification log (per-message audit of every send across every channel and trigger).

Source: api-modules/notifications/src/controllers/admin-broadcast.controller.ts, api-modules/notifications/src/controllers/admin-notification-log.controller.ts.

Channels are plugged in via the per-channel modules (notifications-email-mailer, notifications-push-fcm). Broadcast send / schedule are queue-backed — the controller returns immediately with a row whose status reflects scheduled/in-progress; per-recipient jobs run async.

Conventions

Authentication

All endpoints require a Better-Auth admin session and a role granting the matching notifications:* permission.

Response envelope

Successful responses are wrapped by ResponseInterceptor:

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

Error envelope

Domain types

BroadcastResponse

type BroadcastResponse = {
  id: string;
  status: string;                // service-defined: "scheduled", "in_progress", "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; // null until the audience is materialised
  sentCount: number;
  failedCount: number;
  createdAt: string;             // ISO
};

NotificationLogResponse

type NotificationLogResponse = {
  id: string;
  recipientUserId: string | null;
  channel: string;               // "email" | "push" | ...
  provider: string;              // e.g. "mailer", "fcm"
  eventType: string;             // domain event that triggered the send (or "broadcast")
  broadcastId: string | null;    // populated when triggered by a broadcast
  subject: string | null;        // for email
  status: string;                // "sent" | "failed" | provider-specific
  error: string | null;          // free-form provider error message
  sentAt: string;                // ISO
};

Broadcasts

Base path: /admin/notifications/broadcasts.

POST /admin/notifications/broadcasts — Create + send (or schedule) a broadcast

Required permission: notifications: broadcast. The controller enqueues the broadcast and returns the persisted row immediately. If scheduleFor is omitted, the broadcast starts dispatching at once; if present, it is queued as a delayed job.

Body

{
  "audience": { "type": "all_customers" },
  "channels": ["email", "push"],
  "content": {
    "email": {
      "subject": "Our biggest sale of the year",
      "html": "<h1>Hi!</h1>...",
      "text": "Hi! ..."
    },
    "push": {
      "title": "Sale starts now",
      "body": "Up to 50% off across the store",
      "imageUrl": "https://cdn.example/banners/sale.png",
      "data": { "deepLink": "/sale" }
    }
  },
  "scheduleFor": "2026-06-01T03:00:00.000Z"
}

Audience union

Channels + content

channels is a 1..2 subset of ["email", "push"]. The merged content block must include a sub-payload for every channel listed in channels. Channel-content shapes:

Other fields

Response 201 — BroadcastResponse.

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.

Errors

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

Required permission: notifications: broadcast. Semantics:

• Scheduled: removes the delayed start job and marks the row cancelled.
• In-progress: marks the row cancelled; remaining per-recipient jobs skip when popped from the queue. In-flight provider calls already running are not aborted.
• Already completed / cancelled: no-op service-side, response still 200.

Response 200 — cancelled BroadcastResponse.

Errors

Notification log

GET /admin/notifications/log — Audit of sends

Required permission: notifications: view. Newest first. Use to answer "did the customer get the e-mail?" from support, or to debug a stuck broadcast.

Query

Response 200 — paginated envelope of NotificationLogResponse[].

Related modules

• admin-rbac — gates every endpoint via notifications:view / notifications:broadcast. See admin-rbac.md.
• notifications-email-mailer / notifications-push-fcm — channel plugins consumed by both broadcasts and per-event triggers; the log row's provider reflects which plugin handled the send.
• order, vendor, reviews — emit domain events that the notifications module subscribes to and turns into log entries (visible via this admin log).