Skip to content
DocsconceptsDocumentation

Push notifications

Configure defineNotify in lunora/notify.ts for Web Push + FCM, register browser subscriptions, and send via ctx.notify / ctx.push from an action.

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() from expo-notifications returns the FCM registration token. Register it with ctx.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 uses node: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.