@quanticjs/notification-ui 8.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +92 -0
- package/dist/index.cjs +4627 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1054 -0
- package/dist/index.d.ts +1054 -0
- package/dist/index.js +4571 -0
- package/dist/index.js.map +1 -0
- package/package.json +78 -0
package/README.md
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# @quanticjs/notification-ui
|
|
2
|
+
|
|
3
|
+
The QuanticJS frontend for the **centralized notification engine**. Ships the
|
|
4
|
+
end-user surface — app-scoped bell, inbox, realtime updates, and a preference
|
|
5
|
+
matrix — plus the engine's management console (templates, broadcasts, segments,
|
|
6
|
+
DLQ, suppression, delivery analytics, API keys, webhooks).
|
|
7
|
+
|
|
8
|
+
All calls go through the host app's BFF to the engine; the browser never talks
|
|
9
|
+
to the engine directly. Uses the app's `ApiClient` from `QuanticProvider`, so
|
|
10
|
+
CSRF, auth refresh, and correlation IDs are handled for you.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
pnpm add @quanticjs/notification-ui
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Peers: `@quanticjs/react-core`, `@quanticjs/react-query`, `@quanticjs/react-ui`,
|
|
19
|
+
`@tanstack/react-query`, `react`. Runtime deps `socket.io-client` (realtime) and
|
|
20
|
+
`recharts` (analytics charts) are bundled as dependencies.
|
|
21
|
+
|
|
22
|
+
## Register your app (the one thing each consumer must do)
|
|
23
|
+
|
|
24
|
+
The engine is shared across apps, so notifications are **scoped by `appId`** — a
|
|
25
|
+
slug your app is registered as in the engine's application registry. Register it
|
|
26
|
+
once with `NotificationProvider`; the bell, inbox, realtime socket, and hooks
|
|
27
|
+
below all read it from context:
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
import { NotificationProvider, NotificationBell } from '@quanticjs/notification-ui';
|
|
31
|
+
import { AppShell } from '@quanticjs/react-layouts';
|
|
32
|
+
|
|
33
|
+
<NotificationProvider appId="delivery-hub">
|
|
34
|
+
<AppShell topBar={{ actions: <NotificationBell /> }}>
|
|
35
|
+
{/* routes */}
|
|
36
|
+
</AppShell>
|
|
37
|
+
</NotificationProvider>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
- The bell scopes to `delivery-hub` automatically — it shows only this app's
|
|
41
|
+
notifications plus system-wide ones.
|
|
42
|
+
- **Shell / portal:** omit `appId` to get the unified inbox across every app.
|
|
43
|
+
- Per-component override is still possible (`<NotificationBell appId="…" />`),
|
|
44
|
+
but the provider is the recommended single registration point.
|
|
45
|
+
|
|
46
|
+
`NotificationProvider` also opens the shared realtime socket. To disable realtime
|
|
47
|
+
(poll-only), pass `disabled`; to point at a non-default origin, pass `serverUrl`.
|
|
48
|
+
|
|
49
|
+
## End-user exports
|
|
50
|
+
|
|
51
|
+
| Export | Purpose |
|
|
52
|
+
|---|---|
|
|
53
|
+
| `NotificationProvider` / `useNotificationConfig` | App registration + ambient `appId`/`basePath`/poll config |
|
|
54
|
+
| `NotificationBell` | Bell + unread badge (app-scoped) |
|
|
55
|
+
| `NotificationInbox` | Inbox panel — list, mark-read, mark-all-read |
|
|
56
|
+
| `NotificationRealtimeProvider` / `useRealtimeContext` | Lower-level realtime socket (wrapped by `NotificationProvider`) |
|
|
57
|
+
| `NotificationPreferences` | Per-type × channel preference matrix with email digest |
|
|
58
|
+
| `useUnreadCount` / `useNotificationFeed` | Badge count + feed/mutations (socket-aware, fall back to polling) |
|
|
59
|
+
|
|
60
|
+
## Engine endpoint contract (via the host BFF)
|
|
61
|
+
|
|
62
|
+
| Operation | Request |
|
|
63
|
+
|---|---|
|
|
64
|
+
| List | `GET /notifications?page=1&pageSize=20[&appId]` → `{ items, total, page, limit, totalPages }` |
|
|
65
|
+
| Unread count | `GET /notifications/unread-count[?appId]` → `{ count }` |
|
|
66
|
+
| Mark read | `POST /notifications/:id/read` |
|
|
67
|
+
| Mark all read | `POST /notifications/read-all[?appId]` |
|
|
68
|
+
| Preferences | `GET` / `PUT /notifications/preferences` |
|
|
69
|
+
| Realtime | Socket.IO `/realtime` (BFF httpOnly cookie); events `notification:new`, `unread-count:changed` |
|
|
70
|
+
|
|
71
|
+
The host app's BFF must proxy `/api/notifications/*` and the `/realtime` socket to
|
|
72
|
+
the engine (service-to-service auth), and the app must be registered in the
|
|
73
|
+
engine (`POST /api/admin/applications`) before its `appId` resolves.
|
|
74
|
+
|
|
75
|
+
## Management console exports
|
|
76
|
+
|
|
77
|
+
Operator surfaces for the engine: `TemplateList`/`TemplateEditor`/
|
|
78
|
+
`TemplatePreviewPane`/`TemplateVersionHistory`, `BroadcastList`/
|
|
79
|
+
`BroadcastComposer`/`BroadcastProgress`, `SegmentList`/`SegmentBuilder`,
|
|
80
|
+
`DlqConsole`, `SuppressionManager`, `RecipientAdminPanel`, `CatalogEditor`/
|
|
81
|
+
`MissingTranslationsPanel`/`FallbackReportPanel`, `WebhookEndpointManager`,
|
|
82
|
+
`ApiKeyManager`, `ApplicationRegistryPanel`, `OperationsOverview`,
|
|
83
|
+
`DeliveryLogExplorer`/`DeliveryLogViewer`, `DeliveryAnalyticsPage` (+ `FunnelStats`/
|
|
84
|
+
`TrendChart`/`TypeTable`), `QuietHoursForm`/`FrequencyCapTable`/`TenantConfigForm`/
|
|
85
|
+
`TrackingConfigForm`. See `src/index.ts` for the full export list and prop types.
|
|
86
|
+
|
|
87
|
+
## Notes / follow-ups
|
|
88
|
+
|
|
89
|
+
- Component strings are currently English-only; i18n label props (the framework
|
|
90
|
+
`resolveLabels` pattern) are a tracked follow-up.
|
|
91
|
+
- `NotificationPreferences` is global per user — not yet per-app (an engine
|
|
92
|
+
roadmap item).
|