# Notifications

> In-app notifications + realtime SSE in an AdonisJS + Inertia app. Stack: `@facteurjs/adonisjs` for the notification classes and delivery channels + `@adonisjs/transmit` for the SSE transport. Notifications persist to Postgres and push to a per-user SSE channel. Bell + unread badge in the logged-in shell. Emission goes through domain events. Use when adding a new notification type, wiring a listener, adding a custom SSE channel, or debugging the bell. Trigger on: "add notification", "notify user", "SSE", "bell", "facteur", "transmit".

- Skill: `filipebraida/notifications` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add filipebraida/notifications`
- Raw SKILL.md: https://api.skillmd.com/api/skills/filipebraida/notifications/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: filipebraida (https://skillmd.com/u/filipebraida)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/filipebraida/notifications

---


# Notifications + SSE

In-app notifications persist as rows in the `notifications` table and stream to the user's personal channel in realtime via SSE. Facteur (`@facteurjs/adonisjs`) is the framework: one `Notification<User, Params>` class per type, with a `deliverBy: { database, transmit }` config and per-channel methods (`asDatabaseMessage`, `asTransmitMessage`). Transmit (`@adonisjs/transmit`) is the SSE transport — in-memory / single-node by default (`transport: null` in `config/transmit.ts`); swap to a distributed transport (e.g. Redis) when scaling out to multiple instances. Emission always goes through domain events: actions emit, a listener calls `facteur.notification(...).params(...).to([user]).send()`.

## Rules

- **A dedicated `notifications` module** owns the model, transformer, controller and routes for the bell:
  - `GET /notifications` → list + unseen count.
  - `POST /notifications/:id/read` → mark one read.
  - `POST /notifications/seen` → mark all as seen (the dot disappears; row stays "unread").
  - `POST /notifications/read` → mark all read.
- **Notification classes** live at `app/<mod>/notifications/<name>_notification.ts`, extending `Notification<User, Params>`:
  ```ts
  static options = { name: 'user-welcome', deliverBy: { database: true, transmit: true } }
  asDatabaseMessage() { return DatabaseMessage.create().setType(...).setContent({...}).setTags([...]) }
  asTransmitMessage() { return TransmitMessage.create().setContent({ kind: '...' }) }
  ```
- **User routing** via `User.notificationTargets()`:
  ```ts
  {
    database: { notifiableId: String(this.id) },
    transmit: { channel: `notifications/user-${this.id}` },
  }
  ```
  Facteur maps each channel's target automatically.
- **Emission goes through events** — see [[actions-events]]. The listener calls:
  ```ts
  await facteur.notification(SomeNotification).params({...}).to([user]).send()
  ```
- **Shared prop `unseenNotifications`** (count) is computed in the Inertia middleware when a user is authenticated. It powers the bell badge on first render — the SSE stream keeps it in sync afterward.
- **Bell UI** subscribes to the per-user channel via `useNotificationsChannel(user.id, onIncoming)`, hits the endpoint to fetch the list when opened, marks-all-seen on open, marks-read on click.
- **Frontend SSE client** is a lazy singleton: one `EventSource` on `/__transmit/events`, all channels multiplex through it.
- **SSE transport** — `apps/web/config/transmit.ts` defaults to `transport: null` (in-memory, single-node). The `@adonisjs/transmit` provider auto-registers the `/__transmit/*` routes, so the bell works out of the box. Swap `transport` for a distributed driver (Redis) when horizontally scaling.

## Doc refs

- Facteur — https://github.com/facteurjs/facteur
- AdonisJS Transmit — https://docs.adonisjs.com/guides/digging-deeper/transmit
- SSE spec (MDN) — https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

## Workflow

### Add a new notification type

1. **Class** at `app/<mod>/notifications/<name>_notification.ts`:
   ```ts
   import { DatabaseMessage } from '@facteurjs/adonisjs/channels/database'
   import { TransmitMessage } from '@facteurjs/adonisjs/channels/transmit'
   import { Notification } from '@facteurjs/adonisjs/types'

   export interface OrderShippedParams { orderId: number; trackingUrl: string }

   export default class OrderShippedNotification extends Notification<User, OrderShippedParams> {
     static options = { name: 'order-shipped', deliverBy: { database: true, transmit: true } }

     asDatabaseMessage() {
       const { orderId, trackingUrl } = this.params
       return DatabaseMessage.create()
         .setType('order-shipped')
         .setContent({ title: 'Your order shipped', body: `Order #${orderId}`, link: trackingUrl })
         .setTags(['order', 'shipping'])
     }

     asTransmitMessage() {
       return TransmitMessage.create().setContent({ kind: 'order-shipped' })
     }
   }
   ```
2. **Emit via event**. The action does:
   ```ts
   emitter.emit('order:shipped', { user, orderId, trackingUrl })
   ```
3. **Listener** in `<mod>/start/events.ts`:
   ```ts
   emitter.on('order:shipped', async ({ user, orderId, trackingUrl }) => {
     await facteur.notification(OrderShippedNotification)
       .params({ orderId, trackingUrl })
       .to([user])
       .send()
   })
   ```
4. Frontend rendering reads `content.title` / `content.body` / `content.link` from the persisted row — the bell renders every notification uniformly. `kind` on the transmit message is available for client-side filtering by type if needed.
5. Verify: a functional spec that emits the event and asserts a notification row persisted for the user. Don't fake the emitter in a listener spec — see [[testing]].

### Custom SSE channel (not a Facteur notification)

For resource-scoped realtime (job progress, live status) that isn't a per-user Facteur notification — hardcoded channel pattern, `transmit.authorize`, broadcast from a listener → [references/custom-sse-channel.md](references/custom-sse-channel.md).

### Testing

- Endpoint test: insert rows directly via `Notification.create({...})` and hit the 4 endpoints.
- End-to-end listener test: `mail.fake()` first (to keep any co-fired mail from actually sending), then `await emitter.emit('event:name', payload)`, then assert the `Notification` row exists.

See [[testing]].

## Anti-patterns

- ❌ Calling `facteur.notification(...).send()` directly from an action — emit an event; the listener sends.
- ❌ Hardcoding `notifications/user-<id>` in components — use the per-user subscription hook.
- ❌ Storing render logic in the transmit message — the DB row is the durable copy; transmit is just a nudge (`{ kind: '...' }` is enough).
- ❌ Sending massive payloads over transmit — the browser refetches the list on notification; keep transmit small.

## Related skills

[[actions-events]] · [[routes]] · [[mail]] · [[layout-shells]] · [[testing]] · [[authorization]]