@lunora/notify gives an app two context surfaces: ctx.notify for
multi-channel messages (chat, in-app inbox, webhooks) and ctx.push for device
push (Web Push and Firebase Cloud Messaging (FCM)). Both are built on
@visulima/notification,
with subscription storage and queue-backed fan-out on top.
Declare the channels in lunora/notify.ts and codegen wires the rest, exactly
the way defineFlags feeds ctx.flags:
// lunora/notify.ts
import { d1SubscriptionStore, defineNotify, fcmFromEnv, webPushFromEnv } from "@lunora/notify";
export default defineNotify({
fcm: (env) => fcmFromEnv(env),
store: (env) => d1SubscriptionStore(env.DB),
webPush: (env) => webPushFromEnv(env),
});defineNotify is pure validation plus branding: it throws a TypeError on a
malformed channel rather than deferring the failure to the first send. Codegen
discovers the default export, imports it into the generated worker, and builds
the ctx facades from it.
Configuration from the environment
webPushFromEnv and fcmFromEnv read the conventional variables, so a project
sets them in .dev.vars (or as secrets) rather than in code:
| Channel | Variables |
|---|---|
| Web Push | VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT |
| FCM | FCM_SERVICE_ACCOUNT (+ optional FCM_PROJECT_ID) |
FCM with your own getAccessToken | FCM_PROJECT_ID, unless the config sets a string projectId |
| FCM for local development | FCM_ACCESS_TOKEN, used only when FCM_SERVICE_ACCOUNT is not set. It expires within an hour. |
The key names are exported as WEB_PUSH_ENV_KEYS / FCM_ENV_KEYS so tooling can
reference them without restating string literals.
Subscriptions
ctx.push.register(...) accepts either a web-push subscription or an FCM token,
optionally tied to a userId. Two stores ship:
memorySubscriptionStore(): tests and dev.d1SubscriptionStore(env.DB): durable and edge-safe.
SubscriptionStore is a small interface (get / list / delete / …), so a
custom backing store is a matter of implementing it. list filters apply
server-side and take a limit, so a large audience never materializes wholesale
inside the isolate. broadcast pages through the whole audience with keyset pagination, so it
reaches everyone matched. A limit on the filter caps the total across all pages.
Dead subscriptions prune themselves: an endpoint the push service reports as gone
(Web Push HTTP 404/410, or FCM's UNREGISTERED code for a dead token) is
detected by isGoneError and dropped
rather than retried forever.
FCM platform fields, topics and conditions
ctx.push.send and broadcast take an fcmOverrides block for per-platform FCM fields
(android, apns, webpush, fcm_options). It is forwarded to the message as
sent and merged over what the common fields produce, so it wins on a clash. Web
Push ignores it. clickAction maps to android.notification.click_action, and
sound and badge to their Android and APNs slots. ttl and urgency apply on
every FCM target: Android ttl/priority, APNs apns-expiration/apns-priority,
and Web Push TTL/Urgency. A block with nothing in it is left out, so a data-only
send carries no notification.
FCM's own retries and timeout fields are honoured for topic and condition
sends. retries is capped at 10 attempts, so a large count cannot keep a send retrying for hours. A Retry-After up to 10 seconds is waited out; a longer one fails the send.
A device send makes one POST per engine attempt, so the engine's retries apply once.
ctx.push.sendToTopic(topic, payload) and sendToCondition(expression, payload)
send one FCM message to every device subscribed to a topic, or matching a condition
such as "'sports' in topics". Lunora does not manage topic membership; subscribe
devices with the Firebase client SDK or the Admin API. These sends have no
subscription rows, so they resolve to a success receipt carrying the FCM message id, and a failure throws.
They need the fcm channel.
What is deliberately not on the edge
Only channels that survive workerd are wired here: Web Push and FCM run on Web
Crypto and fetch. Apple Push Notification service (APNs) needs node:http2, and
the SMS and Node-only queue adapters likewise have no edge implementation, so the
edge facade does not expose them. Route heavy fan-out through @lunora/queue instead: enqueuePushBroadcast
hands the audience to a queue and runPushBroadcastPage drains it, so one request
never blocks on thousands of sends.
API
The entries below cover the main exports. The full list is in
api-snapshots/notify.api.md.
defineNotify(config)
Type: (config: NotifyConfig) => NotifyDefinition
Validates the channel configuration and returns it for codegen. It throws a
TypeError for a malformed channel, and when neither webPush nor fcm is set.
memorySubscriptionStore()
Type: () => SubscriptionStore
In-memory subscription store for tests and development.
d1SubscriptionStore(database, options?)
Type: (database: D1Like, options?: D1StoreOptions) => SubscriptionStore
Durable subscription store on a D1 database. options.tableName sets the table name.
webPushFromEnv(env, overrides?) and fcmFromEnv(env, overrides?)
Type: (env: NotifyEnv, overrides?: Partial<WebPushConfig>) => WebPushConfig | undefined
and (env: NotifyEnv, overrides?: Partial<FcmConfig>) => FcmConfig | undefined
Read the channel configuration from the environment variables in the table above.
overrides replaces any field read from the environment.
isGoneError(message, kind?)
Type: (message: string | undefined, kind?: StoredSubscription["kind"]) => boolean
Returns true when a push error message means the subscription is gone (Web Push
HTTP 404 or 410, or FCM UNREGISTERED).
enqueuePushBroadcast(queue, job) and runPushBroadcastPage(push, job)
Type: (queue: QueueProducerLike, job: Omit<PushBroadcastJob, "type">) => Promise<void>
and (push: LunoraPush, job: PushBroadcastJob) => Promise<PushBroadcastPageOutcome>
enqueuePushBroadcast hands a broadcast job to a queue. runPushBroadcastPage
delivers one page of that job and returns the outcome.
ctx.push.sendToTopic(topic, payload) and ctx.push.sendToCondition(expression, payload)
Type: (topic: string, payload: PushContent) => Promise<SuccessReceipt> and
(expression: string, payload: PushContent) => Promise<SuccessReceipt>
Send one FCM message to a topic or condition. Resolves to a success receipt whose messageId is the FCM message name.
See FCM platform fields, topics and conditions.
WEB_PUSH_ENV_KEYS and FCM_ENV_KEYS
Type: const objects of environment variable names
The variable names from the table above, so tooling can reference them without string literals.
Browser side
@lunora/notify/web is the client half: service-worker registration and
permission flow, kept in its own subpath so none of it reaches the worker bundle.
Import the helpers from that subpath:
import { isPushSupported, subscribeToPush, unsubscribeFromPush } from "@lunora/notify/web";