@quanticjs/notification-ui

The QuanticJS frontend for the centralized notification engine. Ships the end-user surface — app-scoped bell, inbox, realtime updates, and a preference matrix — plus the engine's management console (templates, broadcasts, segments, DLQ, suppression, delivery analytics, API keys, webhooks).

All calls go through the host app's BFF to the engine; the browser never talks to the engine directly. Uses the app's ApiClient from QuanticProvider, so CSRF, auth refresh, and correlation IDs are handled for you.

Install

pnpm add @quanticjs/notification-ui

Peers: @quanticjs/react-core, @quanticjs/react-query, @quanticjs/react-ui, @tanstack/react-query, react. Runtime deps socket.io-client (realtime) and recharts (analytics charts) are bundled as dependencies.

Register your app (the one thing each consumer must do)

The engine is shared across apps, so notifications are scoped by appId — a slug your app is registered as in the engine's application registry. Register it once with NotificationProvider; the bell, inbox, realtime socket, and hooks below all read it from context:

import { NotificationProvider, NotificationBell } from '@quanticjs/notification-ui';
import { AppShell } from '@quanticjs/react-layouts';

<NotificationProvider appId="delivery-hub">
  <AppShell topBar={{ actions: <NotificationBell /> }}>
    {/* routes */}
  </AppShell>
</NotificationProvider>

• The bell scopes to delivery-hub automatically — it shows only this app's notifications plus system-wide ones.
• Shell / portal: omit appId to get the unified inbox across every app.
• Per-component override is still possible (<NotificationBell appId="…" />), but the provider is the recommended single registration point.

NotificationProvider also opens the shared realtime socket. To disable realtime (poll-only), pass disabled; to point at a non-default origin, pass serverUrl.

End-user exports

| Export | Purpose | |---|---| | NotificationProvider / useNotificationConfig | App registration + ambient appId/basePath/poll config | | NotificationCenter | Drop-in all-in-one: badge bell + integrated inbox popover (focus-trapped). Use this in a shell's TopBar.actions. | | NotificationBell | Badge-only bell primitive (onClick) — compose your own dropdown | | NotificationInbox | Inbox panel — list, mark-read, mark-all-read | | NotificationRealtimeProvider / useRealtimeContext | Lower-level realtime socket (wrapped by NotificationProvider) | | NotificationPreferences | Per-type × channel preference matrix with email digest | | useUnreadCount / useNotificationFeed | Badge count + feed/mutations (socket-aware, fall back to polling) |

Engine endpoint contract (via the host BFF)

| Operation | Request | |---|---| | List | GET /notifications?page=1&pageSize=20[&appId] → { items, total, page, limit, totalPages } | | Unread count | GET /notifications/unread-count[?appId] → { count } | | Mark read | POST /notifications/:id/read | | Mark all read | POST /notifications/read-all[?appId] | | Preferences | GET / PUT /notifications/preferences | | Realtime | Socket.IO /realtime (BFF httpOnly cookie); events notification:new, unread-count:changed |

The host app's BFF must proxy /api/notifications/* and the /realtime socket to the engine (service-to-service auth), and the app must be registered in the engine (POST /api/admin/applications) before its appId resolves.

Management console exports

Operator surfaces for the engine: TemplateList/TemplateEditor/ TemplatePreviewPane/TemplateVersionHistory, BroadcastList/ BroadcastComposer/BroadcastProgress, SegmentList/SegmentBuilder, DlqConsole, SuppressionManager, RecipientAdminPanel, CatalogEditor/ MissingTranslationsPanel/FallbackReportPanel, WebhookEndpointManager, ApiKeyManager, ApplicationRegistryPanel, OperationsOverview, DeliveryLogExplorer/DeliveryLogViewer, DeliveryAnalyticsPage (+ FunnelStats/ TrendChart/TypeTable), QuietHoursForm/FrequencyCapTable/TenantConfigForm/ TrackingConfigForm. See src/index.ts for the full export list and prop types.

Notes / follow-ups

• Component strings are currently English-only; i18n label props (the framework resolveLabels pattern) are a tracked follow-up.
• NotificationPreferences is global per user — not yet per-app (an engine roadmap item).