Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Notifications

View as Markdownllms.txt

A notification is a short message to a person about something that happened: “Your export is ready”, “Grace invited you to Acme”, “Your post was published”. Unlike a mail, a notification doesn’t care how it arrives. You write it once, and it goes out over one or more channels: an email, an entry in the bell menu at the top of your app, and later SMS, Slack, Microsoft Teams or a phone push.

  1. Make a notification:

    Terminal window
    node strut make:notification PostPublished
  2. Fill it in:

    app/notifications/post-published.notification.ts
    import { Notification, type Notifiable } from '@strutvane/framework'
    import type { Post } from '../models/post.ts'
    /** Tells an author that their post is live. */
    export class PostPublished extends Notification {
    constructor(readonly post: Post) {
    super()
    }
    /** Which channels to use for this person. */
    via(_user: Notifiable): readonly string[] {
    return ['mail', 'database']
    }
    toMail() {
    return this.mail()
    .subject(`"${this.post.title}" is live`)
    .line('Good news: your post is now published.')
    .action('View your post', `/posts/${this.post.slug}`)
    }
    toDatabase() {
    return { post_id: this.post.id, title: this.post.title, message: 'Your post was published.' }
    }
    }
  3. Send it:

    app/http/controllers/post.controller.ts
    import { PostPublished } from '../../notifications/post-published.notification.ts'
    await author.notify(new PostPublished(post))

What you’ll see:

  • a mail “"Hello world" is live” in Mailpit (http://localhost:8025) or your log;
  • a red 1 on the bell in the top bar; clicking it shows “Your post was published.” with a link.
Channel What it does Phase
mail sends an email through your mailer 0.3
database stores a row in the notifications table; the bell and /notifications page read it 0.3
broadcast pushes it live to the open browser tab 0.3 (live delivery needs @strutvane/realtime, coming after 1.0)
sms, slack, teams, webpush, whatsapp via @strutvane/notification-channels coming after 1.0 (phase 6)

via() receives the person, so it can follow their preferences:

app/notifications/post-published.notification.ts
via(user: Notifiable): readonly string[] {
const channels = ['database'] // always in the bell
if (user.notify_by_email === true) channels.push('mail')
return channels
}

What you’ll see: people who switched email off still get the bell entry, and nothing in their inbox. (notify_by_email is a column you add to users yourself; a preference centre comes with notification-channels.)

Anything notifiable: by default your User model. It knows its email address (for mail) and its id (for database).

app/models/user.ts
import { Model, notifiable } from '@strutvane/framework'
export class User extends Model('users', { fillable: ['name', 'email'], hidden: ['password'], behaviours: [notifiable()] }) {}

behaviours is the planned way to add features to a model without decorators (catalogue F5); notifiable() adds notify(), notifications() and unreadNotifications().

import { Notification } from '@strutvane/framework'
await Notification.send(teamMembers, new PostPublished(post))

Each person gets their own copy, with their own via() answer.

To notify an address that has no user, for example the person who filled in a public contact form:

await Notification.route('mail', 'grace@example.com').notify(new ContactReceived(message))

Only channels with a route given (here mail) are used; database needs a user, so it’s skipped.

Sending over several channels takes time. Queue it, so the request answers at once:

app/notifications/post-published.notification.ts
export class PostPublished extends Notification {
static readonly queued = { afterCommit: true, tries: 3 }
// the rest of the class is unchanged
}

What you’ll see: notify() returns right away; a queue worker sends the mail and writes the bell entry. With afterCommit: true, nothing is sent until the transaction that created the post has committed, and nothing at all if it rolls back.

Each channel is sent as its own job, so a mail outage doesn’t stop the bell entry.

With the admin UI, the top bar has a bell with an unread count, a dropdown with the latest entries, and a full /notifications page. Users can mark one entry or all entries read. All of it reads the database channel; there’s nothing to build.

Under the hood, the notifications table holds one row per entry: who it’s for, the notification type, your toDatabase() data as JSON, and read_at. It’s an internal table, so it never gets an automatic API or admin screen of its own.

Reading them in your own code:

const unread = await user.unreadNotifications().limit(10).get()
await user.unreadNotifications().markAsRead()

Old read entries can be pruned with the planned model:prune command on the scheduler.

With teams, each entry belongs to the team it was created in. People see only the current team’s entries in the bell, and switching team switches the list. Your toDatabase() data is visible to the person notified, so don’t put another team’s data in it.

What fails What happens
The mail server is down the mail job retries with back-off; the bell entry is already there
A channel throws in toMail() (a bug) that channel’s job is recorded as a failed job (visible in @strutvane/queue-dashboard); other channels are unaffected
The person has no email address the mail channel is skipped and a warning is logged
An SMS provider rejects the number (phase 6) that job fails; the failure is recorded, nothing is retried forever
Not queued, and a channel throws the error reaches your code; catch it or queue the notification

Failed jobs can be retried with node strut queue:retry <id|all> once the cause is fixed. See Queues.

tests/feature/publish-post.test.ts
import { Notification } from '@strutvane/framework'
import { expect, it } from 'vitest'
import { PostPublished } from '../../app/notifications/post-published.notification.ts'
it('notifies the author when a post is published', async () => {
Notification.fake()
await client(app).withToken(aliceToken).postJson('/api/posts/hello-world/publish', {})
Notification.assertSentTo(alice, PostPublished, (sent, channels) => channels.includes('database'))
Notification.assertNotSentTo(bob, PostPublished)
})

Notification.fake() is a phase 2 fake (parity checklist); the assertion names follow Laravel and aren’t final. See Mocking.

Notifications behave the same. The mail channel follows your mailer: Mailpit with Docker, the log without. The bell reads your database, wherever it runs. Queue workers that send queued notifications run inside the app container in Docker mode, and on your machine otherwise.

Why: via() doesn’t include 'database', or the notification is queued and no worker is running. Fix: add the channel, and start a worker in development (npm run dev starts the processes packages register).

Error: PostPublished uses the "mail" channel but has no toMail() method.

(Something like this.) Why: every channel in via() needs its to<Channel>() method. Fix: add toMail(), or remove 'mail' from via().

Why: the code that sends it ran twice (a retried request, a listener registered twice). Fix: send notifications from one place, from a queued job with a unique id, or guard with an idempotency key on the route.

Why: links are built from APP_URL. Fix: set APP_URL to the real address on the server.

Why: the notification was sent outside a request, without a current team, so it was stored without one. Fix: send it inside the team’s context (jobs carry the team with them automatically; commands must set it).

  • Mail: mailers, templates and the dev inbox.
  • Queues: sending notifications in the background.
  • Events: reacting to “post published” and sending notifications from a listener.
  • Notification channels: SMS, Slack, Teams and push.