Skip to content
DocspackagesDocumentation

@lunora/notify

Multi-channel notifications — ctx.notify / ctx.push over @visulima/notification, with edge-safe Web Push and FCM.

PackagesNotify

@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:

ChannelVariables
Web PushVAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT
FCMFCM_SERVICE_ACCOUNT (+ optional FCM_PROJECT_ID)
FCM with your own getAccessTokenFCM_PROJECT_ID, unless the config sets a string projectId
FCM for local developmentFCM_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 NOT_FOUND answer for a dead token) is detected by isGoneError and dropped rather than retried forever.

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 NOT_FOUND).

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.

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";