Client
The @openg2p/notification npm package. It renders the inbox, talks to the notification provider from the browser, and is what the staff UI installs.
@openg2p/notification is the inbox library. A host app renders Inbox and passes a connection config. The package talks to the notification provider through an adapter, so application UI does not import the provider SDK.
The package does not send. Sending stays in the connector. Novu is the built-in adapter. Other adapters register on NotificationFactory. The Novu install, and where email and SMS providers are documented, is in Novu.
What the package does
Bell with unread badge and dropdown inbox
All, Unread, Read, and Archived filters
Mark as read, mark all as read, archive, and unarchive
Live updates over the notification provider WebSocket
Pages of 20
Localization overrides
useInboxSessionfor custom UI insideInbox
Host app
│
▼
Inbox / Bell / useInboxSession
│
▼
NotificationFactory.create(provider, connection)
│
▼
NotificationService adapter
│
▼
Notification provider API and WebSocketThe browser connects to the notification provider. OpenG2P backends do not proxy inbox REST or WebSocket traffic.
Inbox
Bell, panel, and session wiring
NotificationFactory
Looks up a provider by name
NotificationService
Provider-neutral inbox contract: list, counts, read, archive, live events
NovuNotificationService
Built-in adapter. Registered as "novu"
Do not render Inbox until provider, applicationIdentifier, and subscriber.subscriberId are all set. The subscriber id is the same value the connector uses as recipient_id. See Identity.
Package and install
The package name is @openg2p/notification, version 0.1.0, license MPL-2.0. Published files are dist only: CommonJS (dist/index.js), ESM (dist/index.mjs), and types (dist/index.d.ts).
Peer dependencies: react, react-dom, and lucide-react. The built-in adapter depends on @novu/js. Host apps still import Inbox from @openg2p/notification.
The registry staff UI installs the packed tarball from GitHub:
That is the dependency in registry-platform/ui/staff-ui/package.json. Any other UI uses the same command.
To point a local app at a tarball you just built:
Build the tarball
From notifications/client:
npm install
Install dependencies
npm run build
Compile src to dist with tsup (CJS, ESM, and types). The banner is "use client"
npm test
Run the Vitest suite once
npm run test:watch
Re-run tests on file changes
npm pack
Write openg2p-notification-0.1.0.tgz from dist
Build before npm pack. Optional: npm run lint, npm run lint:fix, npm run clean.
Commit or publish that tarball when the staff UI (or another app) should pick up a new client. The staff UI URL above tracks develop, so a new tarball at that path is what npm install fetches.
Render the inbox
provider is the adapter name. applicationIdentifier, backendUrl, and socketUrl are public. subscriberHash is the HMAC of subscriberId when the provider requires it. email and firstName are optional profile fields on the subscriber.
Theme
Pass theme so the inbox follows the host. When omitted, the package uses the registry palette (#EABB13, #ED7C22, #F3F1F4, #E1E1E1, #A1A1A1, #000000, #FFFFFF).
accentSoft is computed from accent and surface when you omit it. CSS variables are accepted, which is what the staff UI does.
Switch provider
Inbox never imports a provider SDK. It calls NotificationFactory.create(config.provider, connection) and talks to the NotificationService that comes back. To leave Novu, write an adapter for the new system and register it under a name. The Inbox props, the theme, and the localization stay the same.
The package registers "novu" itself, from register.ts. Any other name has to be registered before Inbox mounts. If the name is not registered, create throws Unknown provider "name" and the inbox shows a connection error instead of the list.
The client and the connector are switched separately. Both must point at the same system and use the same subscriber id. See Both sides.
The adapter contract
A provider is a class whose constructor takes a NotificationConnection and that implements NotificationService. Both types, NotificationFactory, and NotificationProvider are exported from @openg2p/notification.
The constructor receives the connection fields from config:
subscriber
subscriberId, plus optional email and firstName. The id is the connector's recipient_id
applicationIdentifier
The provider's application or tenant id. Novu requires it. Another adapter can ignore it
subscriberHash
HMAC of subscriberId. Use it, or an equivalent token, to authenticate the browser
backendUrl
Public API URL
socketUrl
Public WebSocket URL
context, contextHash
Optional scoping values. Novu passes them through
Throw from the constructor when a field your adapter needs is missing. The Novu adapter does this for subscriberId and applicationIdentifier.
The methods are:
list({ limit, after, filter })
Return { notifications, hasMore }. after is the id of the last item already shown. filter is all, unread, read, or archived. Only archived returns archived items. The other three exclude them
unreadCount()
Count of items that are not read and not archived
readCount()
Count of items that are read and not archived
archivedCount()
Count of archived items
markRead(id), readAll()
Mark one item, or all items, read
markSeen(ids)
Mark items seen. The session batches these calls
archive(id), unarchive(id)
Move an item into or out of the archive
onReceived(handler)
Call handler with each new notification pushed over the socket. Return a function that unsubscribes
onUnreadCount(handler)
Call handler with the new unread count when it changes. Return a function that unsubscribes
disconnect()
Close the socket. The inbox calls it on unmount and when the connection changes
Every async method rejects with an Error on failure. The inbox shows that message and offers a retry.
Map the provider's records onto the package's Notification type. id, title, body, read, and createdAt are required. Buttons go in primaryAction and secondaryAction, each with a label and an optional redirect.url. A notification-level redirect makes the row open that URL. The Novu mapping is toNotification in providers/novu.ts.
The inbox builds a new service when provider or any connection field changes, and it calls disconnect() on the old one. Keep the constructor cheap and put all socket cleanup in disconnect().
Register an adapter outside the package
Register at module scope in a client file that the page imports, so it runs in the browser before Inbox mounts:
Then set config.provider to "acme". In the staff UI that value comes from NOTIFICATION_PROVIDER.
Add an adapter inside the package
Use this when the adapter should ship to every UI.
Add
src/providers/acme.tswith the class.Register it in
src/providers/register.ts:NotificationFactory.register("acme", AcmeNotificationService). That file is the only onepackage.jsonlists undersideEffects, so registration there survives bundling.Export the class from
src/providers/index.ts.Add
src/providers/acme.test.ts. Usenovu.test.tsas the model.Run
npm run build,npm test, andnpm packas in Build the tarball. Commit the new tarball so the UI installs it.
Both sides
Name
NOTIFICATION_PROVIDER=acme
config.provider = "acme"
Address
NOTIFICATION_PROVIDER_URL, NOTIFICATION_PROVIDER_API_KEY
backendUrl, socketUrl, and the session values the adapter reads
In Registry, one Helm value, global.notificationProvider, feeds NOTIFICATION_PROVIDER on the staff API, the Celery worker, and the staff UI. Changing it is enough only when the Python image has the new provider module and the UI bundle has the new adapter. See Deployment.
Before you switch:
Create the matching workflows on the new system. The event keys and payload fields in Workflows and payloads do not change.
Move the staff UI guard if it requires
NOTIFICATION_APPLICATION_IDENTIFIER.NotificationInboxrenders nothing without it, even if the new adapter does not use it.Notifications already stored in the old provider do not move. The inbox shows only what the new provider holds.
Staff UI
The registry staff UI is the reference host. Source: ui/staff-ui.
NotificationInbox renders Inbox in the header. It returns nothing until notificationProvider, notificationApplicationIdentifier, and subscriberId are set. Theme tokens are the staff UI CSS variables (--color-primary-first and the rest). Copy comes from next-intl (notifications, no_notifications).
The browser does not read NEXT_PUBLIC_* Novu variables. The server reads NOTIFICATION_* and passes a runtime config into the layout.
Server variable
Passed to Inbox as
Meaning
NOTIFICATION_PROVIDER
config.provider
Adapter name. novu in current deploys
NOTIFICATION_APPLICATION_IDENTIFIER
applicationIdentifier
Provider environment application identifier. Public
NOTIFICATION_BACKEND_URL
backendUrl
Public provider API URL
NOTIFICATION_WEBSOCKET_URL
socketUrl
Public provider WebSocket URL
NOTIFICATION_SECRET_KEY
used only to compute subscriberHash
Server-only. Never sent to the browser
Local names are in ui/staff-ui/.env.example. Helm maps the same pod env from global.notificationApplicationIdentifier, global.notificationBackendUrl, global.notificationWebsocketUrl, and global.notificationHmacSecretKey. See Deployment.
backendUrl and socketUrl are the public hosts (https:// plus the provider API and WebSocket hostnames). They are not the in-cluster connector URL.
Session
There is no separate inbox route and the connector does not mint a session. getNotificationHmac runs when the layout loads runtime config:
Read the Keycloak access token from the cookie.
Take
preferred_usernameassubscriberId, plusemailandgiven_namewhen the token has them. The subscriber id is not taken from the query string.When
NOTIFICATION_SECRET_KEYis set, computeHMAC-SHA256of that username and return it assubscriberHash.
clientSafeConfig.getAll() puts those fields on the runtime config. Inbox gives the hash to the provider adapter. Later list, read, and socket calls use the subscriber token the provider issues from that hash. The hash is not an Authorization header on those calls.
The subscriber id must be the same Keycloak username the connector uses as recipient_id. When in-app HMAC is enabled on the provider and the hash is missing, the inbox does not load. A missing secret still returns the subscriber id, so the bell can render, and the provider then rejects the session if HMAC is required.
The staff UI does not configure email or SMS delivery. Those credentials are added on the provider. See Email and SMS.
Last updated
Was this helpful?