Last updated:
@lunora/notify adds multi-channel notifications, wrapping the
@visulima/notification engine.
Web Push and Firebase Cloud Messaging (FCM) come first, alongside chat, in-app inbox, and webhook
channels; both are edge-safe under workerd (fetch + Web Crypto, no node:*).
It exposes two facades on the function context:
ctx.notify: the multi-channel facade (send,chat,inApp,webhook,push).ctx.push: the device-push sub-facade (register,send,broadcast,list,unregister).
Apple Push Notification service (APNs) over node:http2, SMS, plus the BullMQ / pg-boss / SQS queue adapters, are Node-only and are not wired into the
edge facade. Route heavy fan-out or those channels through @lunora/queue instead.
Configure defineNotify
Declare the edge channels and a subscription store in lunora/notify.ts.
webPushFromEnv / fcmFromEnv read config from the environment, and
d1SubscriptionStore persists device subscriptions in D1 (with lazy table
creation).
// lunora/notify.ts
import { defineNotify, webPushFromEnv, fcmFromEnv, d1SubscriptionStore } from "@lunora/notify";
export default defineNotify({
webPush: (env) => webPushFromEnv(env), // VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY / VAPID_SUBJECT
fcm: (env) => fcmFromEnv(env), // FCM_SERVICE_ACCOUNT (+ optional FCM_PROJECT_ID)
store: (env) => d1SubscriptionStore(env.DB),
});VAPID / FCM config via .dev.vars
lunora dev scaffolds these keys into .dev.vars from @lunora/config's
package-secrets registry — only for the channels defineNotify configures. Generate a Voluntary Application Server Identification (VAPID) keypair once with
npx web-push generate-vapid-keys:
VAPID_PUBLIC_KEY=<your-vapid-public-key>
VAPID_PRIVATE_KEY=<your-vapid-private-key>
VAPID_SUBJECT=mailto:you@example.com
FCM_SERVICE_ACCOUNT=<base64-of-your-service-account-key-json>FCM_SERVICE_ACCOUNT is the Google service-account key file, as JSON or base64 of it.
.dev.vars cannot hold the JSON's quotes, so store it base64-encoded there:
lunora env set FCM_SERVICE_ACCOUNT "$(base64 < key.json | tr -d '\n')". In production
the raw JSON works too: wrangler secret put FCM_SERVICE_ACCOUNT < key.json.
fcmFromEnv mints FCM access tokens from it on demand (edge-safe, via Web Crypto)
and caches each token until shortly before it expires, so the same
fcmFromEnv(env) line is correct in production. FCM_PROJECT_ID is optional; it
overrides the project_id in the key. A static FCM_ACCESS_TOKEN is still accepted
when no service account is set, for local work only: it expires within the hour.
To mint tokens yourself, for example with google-auth-library, pass your own
getAccessToken: fcm: (env) => ({ ...fcmFromEnv(env), getAccessToken }) or
fcm: (env) => fcmFromEnv(env, { getAccessToken }). Lunora reads that from
the fcm entry of an inline defineNotify({...}) in lunora/notify.ts, so lunora dev
and lunora deploy then ask for FCM_PROJECT_ID instead of FCM_SERVICE_ACCOUNT. Set
it even if the key file is still in env: the preflight does not take the project id from
the key file. If the same object also sets projectId to a string, no FCM key is asked
for at all. A config the build cannot read keeps asking for FCM_SERVICE_ACCOUNT.
A push payload must fit in 4096 bytes, the limit for both FCM and Web Push. A larger
send is rejected with PAYLOAD_TOO_LARGE before any device is contacted.
Native devices (Android and iOS)
Native FCM tokens come from the device, not from Expo's push service:
- Android:
getDevicePushTokenAsync()fromexpo-notificationsreturns the FCM registration token. Register it withctx.push.register({ kind: "fcm", token, userId }). - iOS:
getDevicePushTokenAsync()returns an APNs token, which FCM v1 does not accept. Get an FCM token from the Firebase Messaging SDK instead (with your APNs key uploaded to the Firebase project) and register that the same way. Direct APNs delivery usesnode:http2, so it is not on the edge facade.
Register a browser push subscription
On the client, subscribeToPush from @lunora/notify/web registers a service
worker and returns a Web Push subscription. Send it to a mutation (a storage
write) and persist it with ctx.push.register:
// client
import { subscribeToPush } from "@lunora/notify/web";
const { replacedEndpoint, subscription } = await subscribeToPush({ serviceWorkerUrl: "/sw.js", vapidPublicKey });
await client.mutation("registerDevice", { replacedEndpoint, subscription });replacedEndpoint is set only after a VAPID key rotation, when the helper
drops the stale browser subscription and mints a new one. The new subscription
has a new endpoint — hence a new store id — so it never upserts over the old
row, and every send to that row now answers 403 VapidPkHashMismatch, which is
(correctly) not a "gone" signal, so nothing prunes it either. Unregister it:
// lunora/registerDevice.ts
import { webPushId } from "@lunora/notify";
import { mutation, v } from "@/lunora/_generated/server";
export const registerDevice = mutation
.input({ replacedEndpoint: v.optional(v.string()), subscription: v.any() })
.mutation(async ({ ctx, args: { replacedEndpoint, subscription } }) => {
if (replacedEndpoint !== undefined) {
await ctx.push.unregister(webPushId(replacedEndpoint), { userId: ctx.auth?.userId });
}
await ctx.push.register({ subscription, userId: ctx.auth?.userId });
});unregister's owner argument is required, and the row is removed only when
it carries that same owner. A subscription id is derived from the endpoint, so
replacedEndpoint is a caller-controlled key and nothing about it proves the
browser that sent it ever held the subscription it names — without the scope,
anyone who could guess or observe another user's endpoint could silence that
device's notifications. A row owned by someone else is left alone silently, so
the call cannot be used to probe which endpoints exist. Register with the same
userId you unregister with; devices registered anonymously all share the one
anonymous scope and get no separation from this check.
Send from an action
Notification sends are external I/O, so they belong in actions. The
notify_send_outside_action advisor lint enforces
this. ctx.push.broadcast fans out to every stored subscription, reusing the
engine's retry + circuit-breaker middleware and pruning subscriptions the push
service reports as gone (Web Push 404/410, FCM's NOT_FOUND for a dead token):
// lunora/announce.ts
import { action, v } from "@/lunora/_generated/server";
export const announce = action.input({ title: v.string(), body: v.string() }).action(async ({ ctx, args: { title, body } }) => {
const result = await ctx.push.broadcast({ title, body });
// result: { total, sent, pruned, failed, outcomes }
return result;
});A single targeted send, and a multi-channel send through ctx.notify:
await ctx.push.send(subscriptionId, { title: "Hi", body: "…" });
await ctx.notify.send({
push: { title: "New drop", body: "…", to: pushTarget },
chat: { text: "New drop shipped" },
});Queue-backed fan-out
Move a large broadcast off the request path with
@lunora/queue.
Each queue message delivers exactly one bounded page (250 subscriptions by
default), so the consumer has to re-enqueue while nextFilter is set —
discarding the result silently stops the broadcast after the first page and
still acks the message as a success:
// producer (mutation/action)
await enqueuePushBroadcast(ctx.queues.push, { payload: { title: "New drop", body: "…" } });
// consumer (lunora/queues.ts)
for (const message of batch.messages) {
const { failedIds, nextFilter } = await runPushBroadcastPage(ctx.push, message.body);
if (nextFilter !== undefined) {
// More pages remain — enqueue the continuation. Each message still does
// only ONE bounded page of work. Pass `nextFilter` verbatim: it carries
// the cursor AND the remaining `filter.limit` budget.
await enqueuePushBroadcast(ctx.queues.push, { filter: nextFilter, payload: message.body.payload });
}
// Redeliver ONLY the recipients that failed. Retrying the whole page would
// re-POST every device it already reached.
if (failedIds.length > 0) {
await enqueuePushBroadcast(ctx.queues.push, { payload: message.body.payload, retryIds: failedIds });
}
message.ack();
}A page never throws on a partial failure — it reports failedIds alongside
nextFilter, so one permanently-failing device cannot strand the cursor and
halt the broadcast for everyone behind it. Re-enqueue those ids with
retryIds; that job throws while all of them still fail, so only the
failing device reaches the dead-letter queue — once any recipient recovers it
resolves instead, and the narrower retry never re-sends to a device the message
already reached. A page that merely pruned gone subscriptions is a success.
filter.limit is an overall audience cap here too: nextFilter carries the
remaining budget and is undefined once it is spent, so the walk stops rather
than granting each message a fresh limit.