@juice-js/notifications 0.0.0-stage → 2.1.0-alpha.2

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 CHANGED
@@ -1,3 +1,102 @@
1
- # Temporary Holding Version
1
+ # @juice-js/notifications
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The signed-in person's side of [Juice.Notifications](https://github.com/creatorflow-io/Juice): a notification bell with the unread count, an
4
+ inbox panel kept live over SignalR, and settings pages for notification preferences, quiet hours and email addresses.
5
+
6
+ ## Install
7
+
8
+ ```bash
9
+ npm install @juice-js/notifications @microsoft/signalr
10
+ ```
11
+
12
+ Peers: Angular 22 (`common`, `core`, `forms`, `router`, `material`), `@ngx-translate/core` 18, `angular-oauth2-oidc` 22 (as
13
+ `@juice-js/auth` uses) and `@microsoft/signalr` 10.
14
+
15
+ ## Set up
16
+
17
+ ```ts
18
+ // app.module.ts (NgModule apps)
19
+ import { LAYOUT_TOOLBAR_ITEMS } from '@juice-js/layout';
20
+ import { NotificationBellComponent, NotificationsModule } from '@juice-js/notifications';
21
+
22
+ @NgModule({
23
+ imports: [
24
+ NotificationsModule.forRoot({ apiUrl: 'https://notifications.example.com' }),
25
+ ],
26
+ providers: [
27
+ // The bell in @juice-js/layout's toolbar.
28
+ { provide: LAYOUT_TOOLBAR_ITEMS, useValue: NotificationBellComponent, multi: true },
29
+ ],
30
+ })
31
+ export class AppModule {}
32
+ ```
33
+
34
+ Standalone apps use `provideNotifications({ apiUrl })` and put `<juice-notification-bell>` (or `<juice-inbox-panel>`) in their own toolbar.
35
+
36
+ - **The token:** list the API in `AuthModuleConfig.allowedUrls`, so `@juice-js/auth`'s interceptor sends the token with REST calls. The hub
37
+ takes it from `OAuthService` (or `accessToken` in the configuration).
38
+ - **The tenant:** the API routes by the tenant's id (a GUID). It is the access token's `platform_tenant` claim unless `tenantId` says
39
+ otherwise; it isn't the app's tenant identifier in its URL.
40
+ - **The API** must allow the app's origin: `Cors:Origins` in Juice.Notifications.
41
+
42
+ ## Settings pages
43
+
44
+ ```ts
45
+ {
46
+ path: ':tenant/notifications',
47
+ canActivate: [TenantGuard, AuthGuard],
48
+ loadChildren: () => import('@juice-js/notifications').then(m => m.NotificationsRoutingModule),
49
+ }
50
+ ```
51
+
52
+ `…/notifications/preferences` (a mode per category and channel, and quiet hours) and `…/notifications/contact-points` (add an email address,
53
+ or a phone number with `phoneNumbers`, receive a code, verify it; link chat accounts with `linkChannels`).
54
+
55
+ `…/notifications/templates` is for the tenant's admins: pick a type and a channel, edit its text (Scriban), preview it with sample data, save
56
+ it as the tenant's own or go back to the application's.
57
+
58
+ ## Web Push
59
+
60
+ Copy the service worker to the app's root (`angular.json`, the build's `assets`):
61
+
62
+ ```json
63
+ { "glob": "juice-push-sw.js", "input": "node_modules/@juice-js/notifications/assets", "output": "/" }
64
+ ```
65
+
66
+ Then, once the person is signed in and has asked for notifications (a button; browsers refuse a prompt nobody asked for):
67
+
68
+ ```ts
69
+ const device = await enableWebPush(api, { vapidPublicKey: environment.vapidPublicKey });
70
+ // on sign-out
71
+ await disableWebPush(api, device.id);
72
+ ```
73
+
74
+ `vapidPublicKey` is the tenant's `webpush` integration's public key. Types with a `push` template then reach this browser; clicking the
75
+ notification opens its link.
76
+
77
+ ## What it shows
78
+
79
+ - **Bell:** unread items in every group; it starts the inbox when the person signs in and stops it on sign-out.
80
+ - **Panel:** a tab per display group of the tenant with its unread count, a "needs action" filter (items with actions, not archived), items
81
+ newest first; opening one marks it read and follows its link; read, unread and archive per item; mark all read; more on demand.
82
+ - **Live:** the hub (`inboxChanged`) updates the counts and the items shown; after a reconnect everything reloads.
83
+
84
+ Item actions are listed from phase 2 and become buttons when Juice.Notifications acts on them (phase 3).
85
+
86
+ ## Configuration
87
+
88
+ | Field | Default | |
89
+ |---|---|---|
90
+ | `apiUrl` | (required) | The API's base URL, no trailing slash |
91
+ | `hubUrl` | `${apiUrl}/hubs/inbox` | |
92
+ | `tenantId` | the token's `platform_tenant` | A GUID, or a function returning one |
93
+ | `accessToken` | `OAuthService.getAccessToken()` | For the hub |
94
+ | `pageSize` | 20 | Items per page in the panel (≤ 100) |
95
+ | `linkChannels` | none | Chat accounts people may link: `['slack', 'telegram']` |
96
+ | `telegramBot` | | The Telegram bot's username, for the link that opens it with the code |
97
+ | `phoneNumbers` | false | People may add phone numbers for SMS |
98
+
99
+ ## Try it locally
100
+
101
+ With Juice.Notifications' local stack running (`services/notifications/deploy/local`, then `scripts/keycloak-update.sh` once), run
102
+ `ng serve -c notifications` here and sign in as `ann` or `ben` (password `PEOPLE_TEST_PASSWORD` in the stack's `.env`).
@@ -0,0 +1,37 @@
1
+ /*
2
+ * Juice Notifications' service worker for Web Push (@juice-js/notifications). Copy it to the app's root (angular.json assets:
3
+ * { "glob": "juice-push-sw.js", "input": "node_modules/@juice-js/notifications/assets", "output": "/" }) and pass its URL to enableWebPush.
4
+ *
5
+ * The service sends { title, body, url, deliveryId }. A notification shows the title and body; one per delivery (its tag), so a resend replaces
6
+ * it. Clicking it focuses a window already on the link, or opens one.
7
+ */
8
+ self.addEventListener('push', (event) => {
9
+ let message = {};
10
+ try {
11
+ message = event.data ? event.data.json() : {};
12
+ } catch {
13
+ message = { title: event.data ? event.data.text() : '' };
14
+ }
15
+ const title = message.title || 'Notification';
16
+ event.waitUntil(self.registration.showNotification(title, {
17
+ body: message.body || '',
18
+ tag: message.deliveryId || undefined,
19
+ data: { url: message.url || null, deliveryId: message.deliveryId || null },
20
+ }));
21
+ });
22
+
23
+ self.addEventListener('notificationclick', (event) => {
24
+ event.notification.close();
25
+ const url = event.notification.data && event.notification.data.url;
26
+ if (!url) {
27
+ return;
28
+ }
29
+ event.waitUntil((async () => {
30
+ const windows = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
31
+ const open = windows.find((w) => w.url === url);
32
+ if (open) {
33
+ return open.focus();
34
+ }
35
+ return self.clients.openWindow(url);
36
+ })());
37
+ });