# Notifications Arkstack notifications provide framework-neutral delivery for mail, SMS, and database-backed in-app notifications. ## Install Full app templates include the notifications package and a `src/config/notifications.ts` file. If you are adding it manually, install: ::: code-group ```sh [npm] npm i @arkstack/notifications ``` ```sh [pnpm] pnpm add @arkstack/notifications ``` ```sh [yarn] yarn add @arkstack/notifications ``` ::: ## Configuration Notification configuration is split into a default notification driver, driver-level options, and reusable transports. ```ts // src/config/notifications.ts import { env } from '@arkstack/common' export default () => ({ default_driver: env('NOTIFICATION_DRIVER', 'mail'), drivers: { mail: { transport: 'smtp', from: env('MAIL_FROM_ADDRESS', 'no-reply@example.com'), test_address: env('MAIL_TEST_ADDRESS'), }, sms: { transport: env('SMS_TRANSPORT', 'africastalking'), from: env('SMS_FROM'), }, db: { table: 'user_notifications', }, }, transports: { smtp: { host: env('MAIL_HOST', 'localhost'), port: env('MAIL_PORT', 1025), secure: env('MAIL_SECURE', false), auth: { user: env('SMTP_USER'), pass: env('SMTP_PASS'), }, }, africastalking: { username: env('AFRICASTALKING_USERNAME', 'sandbox'), apiKey: env('AFRICASTALKING_API_KEY'), senderId: env('AFRICASTALKING_SENDER_ID'), }, twilio: { accountSid: env('TWILIO_ACCOUNT_SID'), authToken: env('TWILIO_AUTH_TOKEN'), from: env('TWILIO_FROM'), }, }, }) ``` `default_driver` selects the notification channel used by `Notification.channel()`. `drivers.sms.transport` selects the SMS transport provider, and starter config reads that value from `SMS_TRANSPORT`. ## Mail Mail uses the configured SMTP transport. Recipients can be a string, an array of strings, a named address object, or an array of named address objects. ```ts import { Notification } from '@arkstack/notifications' await Notification.mail() .recipient({ 'ada@example.com': 'Ada Lovelace' }) .subject('Welcome, {name}') .data({ name: 'Ada' }) .send('Hello {name}, thanks for joining.') await Notification.mail() .recipient([{ 'grace@example.com': 'Grace Hopper' }, { 'katherine@example.com': 'Katherine Johnson' }]) .send('The report is ready.') ``` ## SMS SMS supports `africastalking` and `twilio` transports. ```ts import { Notification } from '@arkstack/notifications' await Notification.sms().recipient('+2348012345678').send('Your login code is {code}', undefined, undefined, { code: '123456', }) await Notification.sms({ transport: 'twilio' }) .recipient('+15551234567') .send('Your login code is {code}', undefined, undefined, { code: '123456', }) ``` ## Database Notifications The `db` driver stores in-app notifications through the `UserNotification` model. Full templates include the model and migration for a `user_notifications` table. ```ts await Notification.db() .recipient(user) .type('security') .action('Review login', '/account/security') .meta({ device: 'Chrome on macOS' }) .send('A new login was detected.', 'Security alert') ``` You can also broacast the new database notifcation using the configured realtime driver by channing the `broadcast` method. ```ts await Notification.db() .broadcast() .recipient(user) .type('security') .action('Review login', '/account/security') .meta({ device: 'Chrome on macOS' }) .send('A new login was detected.', 'Security alert') ``` The notification is stored, broadcast on the user's channel, and pushed to their devices when [device push](#device-push) is configured. Use `UserNotificationCenter` when you need to list, mark, or delete stored notifications: ```ts import { UserNotificationCenter } from '@arkstack/notifications' const unread = await UserNotificationCenter.unreadForUser(user) await UserNotificationCenter.markRead(unread[0]) await UserNotificationCenter.delete(unread[0]) ``` ## Realtime Notifications The `realtime` driver broadcasts a notification to connected clients. Each user has their own channel (`${channel_prefix}${user.id}`, e.g. `user.7`). ```ts await Notification.realtime() .recipient(user) .type('transaction') .action('View', '/wallet') .store() // also persist so the client can load history .send('You received $20.00', 'Payment received') ``` `.store()` is opt-in: when enabled the notification is written via `UserNotificationCenter` (giving it a real id and timestamps) **and** broadcast; otherwise it is broadcast only. Broadcast on an explicit channel with `.channel('team.updates')`, or change the client event name with `.event('alert')`. ### Transports `drivers.realtime.transport` picks how events reach clients: | Transport | Delivers to | Server SDK | Client SDK | | ------------------- | ------------------------------------- | ---------------- | ----------- | | `pusher` | Pusher Channels, or soketi via `host` | `pusher` | `pusher-js` | | `firebase` | FCM devices and topics | `firebase-admin` | `firebase` | | `firebase-database` | Firebase Realtime Database channels | `firebase-admin` | `firebase` | | `polling` | Nothing; clients poll on an interval | none | none | | `memory` | An in-process buffer, for tests | none | none | The SDKs are optional peer dependencies; install only the ones you use: ```sh pnpm add pusher # pusher pnpm add firebase-admin # firebase, firebase-database ``` To use a self-hosted Pusher-protocol server such as [soketi](https://soketi.app), set `host` and `port` (`PUSHER_HOST`, `PUSHER_PORT`) under `transports.pusher`. Clients receive the address through [the config route](#channel-authorization). When browsers reach the server at a different address than your app does, for example `soketi:6001` inside Docker but `localhost:6001` from the browser, or a TLS proxy in front of it, set `public_host`, `public_port` and `public_use_tls` (`PUSHER_PUBLIC_HOST`, `PUSHER_PUBLIC_PORT`, `PUSHER_PUBLIC_USE_TLS`). They only change what clients are provissioned with; each defaults to its server-side counterpart. `.channel()` (and `.recipient()`) also accept an **array**. For Pusher it fans out to multiple channels; for `firebase` it is treated as a list of **device registration tokens** and delivered via a chunked multicast (500 tokens per call). The multicast returns `{ successCount, failureCount, invalidTokens }`. Delete `invalidTokens` from your store, since FCM reports which are unregistered: ```ts await Notification.realtime({ transport: 'firebase' }) .channel(user.deviceTokens) // string[] of FCM registration tokens .send('You have a new message') ``` ### Broadcasting events A channel is just a channel. Use `Broadcast` to send your own event shapes over the configured transport, and pick them up with the client's `listen()`: ```ts import { Broadcast } from '@arkstack/notifications' await Broadcast.broadcast([`private-order.${order.id}`, `private-team.${order.teamId}`], 'order.updated', { id: order.id, status: order.status, }) ``` ### Channel authorization Register who may join each private channel. `{name}` placeholders match one segment (they never span a dot) and are passed to the callback. The first matching rule decides, unmatched channels are denied, and the per-user notification channel is allowed for its own user unless you register a rule for it. ```ts // src/routes/realtime.ts import { Broadcast } from '@arkstack/notifications' Broadcast.channel('private-team.{teamId}', async (user, { teamId }) => { return await TeamMember.where({ teamId, userId: user.id }).exists() }) await Broadcast.routes() // POST /realtime/auth, GET /realtime/config ``` `Broadcast.routes()` registers two routes behind the framework `auth` middleware (pass `{ prefix, middleware }` to change them): - `POST /realtime/auth` authorizes the requested channel and answers in the active transport's terms: a Pusher signature, or a Firebase custom token for `firebase-database`. - `GET /realtime/config` returns the public settings a client is created from. Secrets are never included. When a channel is joined by something other than the logged-in user, such as a guest holding a scoped token, call `Broadcast.handleAuth(subject, { socket_id, channel_name }, { uid })` from your own route. Rules receive whatever `subject` you pass. ### Device push Set `drivers.realtime.push` to `'firebase'` to also push every notification sent to a user to their registered devices over FCM, whatever the streaming transport is. When `push` is unset it is on only if the transport is `firebase`; set it to `false` to turn it off there. Tokens are read from `user.pushTokens` (a string, `string[]`, `{ token }` or `{ token }[]`), or from your own resolver: ```ts realtime: { transport: 'pusher', push: 'firebase', push_tokens: async (user) => (await UserPushToken.where({ userId: user.id, isActive: true }).get()).all(), }, ``` The send result carries the multicast outcome, so prune dead tokens there: ```ts const result = await Notification.realtime().recipient(user).send('Your payout has settled.') if (result.push?.invalidTokens.length) { await UserPushToken.whereIn('token', result.push.invalidTokens).delete() } ``` Skip the push for one send with `.push(false)`, or target specific devices with `.devices(tokens)`. ### Registering a browser for push `realtime.deviceToken()` asks for notification permission and returns this browser's FCM token, or `null` where web push is unavailable. It works whatever the streaming transport is, as long as the client config carries `firebase` (the config route includes it when `drivers.realtime.push` is `'firebase'`). Send the token to your API to store against the user: ```ts const token = await realtime.deviceToken({ serviceWorker: '/push-sw.js' }) if (token) await api.post('/push-tokens', { token, platform: 'web' }) ``` Background messages need a service worker. Pass its URL as `serviceWorker` and Arkstack registers it with the Firebase web config in its `firebaseConfig` query parameter, so the script needs no build step or secrets. Or pass a `ServiceWorkerRegistration` you registered yourself. Without the option, Firebase looks for `/firebase-messaging-sw.js`. ```js // public/push-sw.js importScripts('https://www.gstatic.com/firebasejs/11.10.0/firebase-app-compat.js') importScripts('https://www.gstatic.com/firebasejs/11.10.0/firebase-messaging-compat.js') firebase.initializeApp(JSON.parse(new URL(self.location).searchParams.get('firebaseConfig'))) firebase.messaging().onBackgroundMessage(({ data }) => { const notification = JSON.parse(data.payload) if (notification.retracted) return self.registration.showNotification(notification.title, { body: notification.description, tag: notification.tag ?? undefined, data: { link: notification.actionLink }, }) }) self.addEventListener('notificationclick', (event) => { event.notification.close() if (event.notification.data?.link) event.waitUntil(clients.openWindow(event.notification.data.link)) }) ``` Pushes are data-only messages, so the service worker decides what to show. The payload is the same notification object clients receive live. ### Delivery options FCM sends a data message at normal priority, and Android's Doze and App Standby may hold it until the next maintenance window. `.priority('high')` exempts it, and pairs naturally with a short TTL — FCM's own default is four weeks: ```ts await Notification.realtime({ transport: 'firebase' }) .channel(user.deviceTokens) .priority('high') .ttl(60) .collapseKey(`signin:${attemptId}`) // a retry replaces the prompt it repeats .send('Approve sign-in from Lagos?') ``` Pass TTL in seconds; each platform's unit is converted for you. Set defaults under `drivers.realtime.delivery`, override per send, and reach anything unmapped through `.delivery({ android, apns, webpush })`. Pusher ignores all of it — it pushes over a connection the client already holds open. On iOS this maps to APNs only for a visible push (`apns-push-type: alert`), since Apple requires background pushes to be low priority. Ringing or full-screen alerts need PushKit, which FCM cannot address at all. ### Superseding a notification `.tag()` gives a notification a stable identity, so a later one with the same tag replaces it on the client instead of stacking beside it: ```ts // asked await Notification.realtime({ transport: 'firebase' }) .channel(tokens) .tag(`signin:${attemptId}`) .collapseKey(`signin:${attemptId}`) .priority('high') .ttl(60) .send('Approve sign-in from Lagos?') // answered elsewhere await Notification.realtime({ transport: 'firebase' }) .channel(tokens) .tag(`signin:${attemptId}`) .collapseKey(`signin:${attemptId}`) .send('Sign-in approved') ``` Tag by the thing it is about (`order:42`), not the message. `tag` supersedes what was **displayed**; `collapseKey` supersedes what is still **queued** — set both when you want both. They stay separate because FCM allows only four collapse keys per device, so deriving one per tag would starve that budget. `.retract()` removes a notification with nothing in its place. Prefer a replacement where the outcome has content of its own: a retraction must travel as a silent push, which platforms throttle hardest. Retractions are never stored, and retracting does not touch a row already written by `.store()`. The React and Vue bindings apply this for you; for your own list, use the same reducer: ```ts import { supersede } from '@arkstack/realtime' client.subscribe(channel, (n) => setItems((items) => supersede(items, n, 50))) ``` Configure the transport in `src/config/notifications.ts` (`drivers.realtime`) and its credentials under `transports.*`. **Bringing your own transport.** `driverFactory` replaces the built-ins with anything implementing `RealtimeDriver` — a backend this package does not ship, or a fake in a test. Set it per send, or under `drivers.realtime` for the whole app; it takes precedence over `transport`. Do connection setup lazily inside the driver, as the bundled ones do. ```ts Notification.realtime({ driverFactory: () => new MyApnsDriver() }) ``` `broadcast()` also accepts payloads that are not notifications, so an application can push its own event shapes over the same channel and pick them up with the client's `listen()`. ### Firebase Realtime Database The `firebase-database` transport writes each event to `{root}/{channel}/{key}` (default root `arkstack/channels`). When a client is authorized for a channel, the server writes a grant to `arkstack/grants/{uid}/{channel}` that expires after `grant_ttl` seconds (default 3600) and returns a custom token to sign in with. Deploy security rules that check the grant, and index `at`: ```json { "rules": { "arkstack": { "channels": { "$channel": { ".read": "auth != null && root.child('arkstack/grants/' + auth.uid + '/' + $channel).val() > now", ".indexOn": ["at"] } } } } } ``` Everything else stays unreadable, so the grants and the event index are never exposed. Channel names are stored URL-encoded with `.` written as `%2E`, so rules see the same key the server wrote. The `uid` must be usable as a database key; it defaults to the subscriber's `id`. Events are not deleted automatically. Schedule a prune; each call removes at most `limit` events: ```ts import { Broadcast, FirebaseDatabaseRealtimeDriver } from '@arkstack/notifications' const driver = Broadcast.make('firebase-database') as FirebaseDatabaseRealtimeDriver while ((await driver.prune(24 * 3600, 500)) > 0); ``` ### Testing Set the transport to `memory` and read what was sent. The buffer lives on `globalThis`, so broadcasts made by code loaded separately from your tests are recorded too: ```ts import { MemoryRealtimeDriver } from '@arkstack/notifications' beforeEach(() => MemoryRealtimeDriver.clear()) expect(MemoryRealtimeDriver.broadcasts()).toContainEqual( expect.objectContaining({ channel: 'user.7', event: 'notification' }), ) ``` **Firebase credentials** can be provided two ways. Point `admin_sdk_path` (`FIREBASE_ADMINSDK`, default `firebase-adminsdk.json`, resolved from the project root) at a downloaded service-account JSON file; if that file is absent, the driver falls back to the inline `project_id` / `client_email` / `private_key` values (`FIREBASE_PROJECT_ID` / `FIREBASE_CLIENT_EMAIL` / `FIREBASE_PRIVATE_KEY`). `app_name` (`FIREBASE_APP_NAME`, default your `APP_NAME`) names the Firebase Admin app instance so repeated broadcasts reuse it. ### Consuming on the client Install `@arkstack/realtime` in your front-end and the matching client SDK (`pusher-js` or `firebase`). The simplest setup creates the client from the server's config route and adds your API's auth header: ```ts import { createRealtime } from '@arkstack/realtime' const headers = { Authorization: `Bearer ${token}` } const config = await fetch('/api/realtime/config', { headers }).then((r) => r.json()) const realtime = createRealtime({ ...config, pusher: config.pusher && { ...config.pusher, apiBase: '/api', auth: { headers }, }, 'firebase-database': config['firebase-database'] && { ...config['firebase-database'], apiBase: '/api', auth: { headers }, }, }) const unsubscribe = await realtime.forUser(user.id, (notification) => { console.log(notification.title, notification.description) }) // Your own events await realtime.listen(`private-order.${order.id}`, 'order.updated', refresh) ``` Under `polling` nothing arrives on a channel. `onPoll()` runs a handler on the advertised interval only while polling, so one code path serves every transport: ```ts await realtime.listen(channel, 'order.updated', refresh) await realtime.onPoll(refresh) ``` For tests, use `transport: 'memory'` and feed subscribers with `emitMemoryEvent(channel, event, payload)`. The transport SDKs are loaded with a dynamic `import()` of their package name (`pusher-js`, `firebase/app`, …), which a bundler resolves. On a page without a bundler, such as a plain ` ``` ::: ## Prepared Recipients `Notification.prepare()` can derive the recipient from a user-like object: ```ts await Notification.channel('mail').prepare(user, { name: user.name }).send('Hello {name}') await Notification.channel('sms').prepare(user).send('Your verification code is {code}', undefined, undefined, { code, }) await Notification.channel('db').prepare(user).send('Your payout has settled.', 'Payout settled') ```