@aevr/notifications
v1.3.4
Published
Multi-channel notification dispatch engine. Send email, in-app, Slack, Discord, Telegram, and webhook notifications from a single API.
Readme
@aevr/notifications
Delivery receipts
Every dispatch() returns a NotificationDispatchResult with one normalized
receipt for each recipient/channel attempt. Existing channels that return
void remain compatible and are recorded as sent. Channels with provider
visibility can return target counts and sent, partial, failed, or
unavailable status.
const result = await registry.dispatch(event, data, recipients, channels)
for (const receipt of result.receipts) {
console.log(receipt.channel, receipt.status, receipt.deliveredTargets)
}Web Push reports unavailable with NO_PUSH_SUBSCRIPTIONS when a recipient has
no registered browser subscription. This prevents a default-enabled channel
from being mistaken for a successful delivery. NotificationDispatchOptions
also provides an onReceipt observer for durable product-owned persistence.
Multi-channel notification dispatch engine for Node.js. Register renderers per event, dispatch to email, in-app, Slack, Discord, Telegram, and custom webhooks from a single API.
Install
npm install @aevr/notifications
# peer dep — required only if you use the email channel:
npm install @aevr/mailerQuick start
import { registerRenderer, dispatch } from "@aevr/notifications";
import { createMailer } from "@aevr/mailer";
import { EmailChannel } from "@aevr/notifications/email";
// 1. Wire up channels
const emailCh = new EmailChannel(createMailer());
// 2. Register a renderer for an event
registerRenderer("user.welcome", {
email: (data) => ({
subject: `Welcome, ${data.name}!`,
body: "Thanks for signing up.",
html: `<p>Thanks for signing up, <strong>${data.name}</strong>!</p>`,
}),
});
// 3. Dispatch — fire and forget
await dispatch(
"user.welcome",
{ name: "Alice" },
[{ userId: "u1", email: "[email protected]" }],
[emailCh],
);Channels
| Import | Channel | Notes |
|---|---|---|
| @aevr/notifications/email | EmailChannel | Requires @aevr/mailer peer dep |
| @aevr/notifications/webhook | createWebhookChannel | HMAC signing, custom body template |
| @aevr/notifications/telegram | createTelegramChannel | Message splitting, inline keyboard |
| @aevr/notifications/slack | createSlackChannel | Incoming Webhook, Block Kit |
| @aevr/notifications/discord | createDiscordChannel | Incoming Webhook, rich embeds |
| @aevr/notifications/in-app | createInAppChannel | Injected storage adapter |
| @aevr/notifications/push | createWebPushChannel | VAPID Web Push with injected subscription storage |
Web Push
import { createWebPushChannel, testWebPushDelivery } from "@aevr/notifications/push";
const push = createWebPushChannel({
vapid: {
subject: "mailto:[email protected]",
publicKey: process.env.VAPID_PUBLIC_KEY!,
privateKey: process.env.VAPID_PRIVATE_KEY!,
},
storage: {
getSubscriptions: (userId) => subscriptions.findByUser(userId),
removeSubscription: (userId, endpoint) => subscriptions.remove(userId, endpoint),
},
timeout: 8_000,
});
registerRenderer("product.alert", {
web_push: (data) => ({
subject: data.title,
body: data.message,
url: data.url,
meta: { tag: "product-alert" },
}),
});The product owns browser subscription HTTP routes and persistence. The channel owns VAPID delivery and removes endpoints that return HTTP 404 or 410. Set timeout to bound each provider request; web-push otherwise has no request timeout.
Normal dispatch() remains fire-and-forget: channel failures are logged and never block other channels. For diagnostics or synchronous workflows, use observable delivery:
const result = await push.sendWithResult(payload, recipient, {
endpoint: currentBrowserEndpoint, // optional: restrict to this device
});
// Or send a standard diagnostic payload without a renderer:
const test = await testWebPushDelivery(pushConfig, userId, {
endpoint: currentBrowserEndpoint,
url: "/settings/notifications",
});
// { attempted, delivered, staleRemoved, failed, storageError }
if (test.attempted === 0) return reply.status(409).send({ error: "No subscription" });
if (test.delivered === 0) return reply.send({ success: false, error: "Provider delivery failed", data: test });Diagnostic delivery defaults to an 8-second provider timeout, configurable through WebPushChannelConfig.timeout. failed[] includes the endpoint, provider HTTP status when available, and error message. Applications should sanitize or fingerprint endpoints before returning diagnostics to browsers. A 404/410 response removes the endpoint and increments staleRemoved rather than failed. When an edge proxy replaces upstream 5xx bodies, return a readable success: false diagnostic envelope with HTTP 200 after the probe completes.
Retry
import { withRetry } from "@aevr/notifications";
const resilientChannel = withRetry(slackCh, { maxAttempts: 3, backoffMs: 500 });Isolated registry (multi-tenant / testing)
import { createNotificationRegistry } from "@aevr/notifications";
const { registerRenderer, dispatch } = createNotificationRegistry();Testing
import { createMockChannel, assertDeliveredTo } from "@aevr/notifications/testing";
const mock = createMockChannel("email");
await dispatch("user.welcome", data, recipients, [mock]);
assertDeliveredTo(mock, "u1");Types
import type {
NotificationPayload,
NotificationRecipient,
NotificationChannel,
ChannelRenderer,
} from "@aevr/notifications";License
MIT
