@memberjunction/ng-notifications 3.4.0 → 4.1.0

package/README.md

@@ -1,18 +1,6 @@
 # @memberjunction/ng-notifications
 
-Angular service for handling user notifications in MemberJunction applications, providing both UI notifications and database-backed persistent notifications.
-
-## Features
-
-- **Singleton Service Architecture**: Application-wide notification management with a single instance
-- **Dual Notification Types**: 
-  - Temporary UI notifications using Kendo UI
-  - Persistent database-backed notifications via User Notifications entity
-- **Real-time Updates**: Push notification integration for live updates
-- **Flexible Styling**: Support for success, error, warning, and info styles
-- **Auto-refresh**: Automatic notification refresh on user login
-- **Event Integration**: Seamless integration with MemberJunction global events
-- **Resource Linking**: Connect notifications to specific resources and records
+Angular singleton service for managing user notifications in MemberJunction applications. Provides both temporary UI notifications (Kendo toasts) and persistent database-backed notifications via the User Notifications entity.
 
 ## Installation
 
@@ -20,380 +8,143 @@ Angular service for handling user notifications in MemberJunction applications,
 npm install @memberjunction/ng-notifications
 ```
 
-## Requirements
-
-### Angular Version
-- Angular 18.0.2 or higher
-
-### Peer Dependencies
-- `@angular/common`: ^18.0.2
-- `@angular/core`: ^18.0.2
-- `@progress/kendo-angular-notification`: ^16.2.0
-
-### MemberJunction Dependencies
-- `@memberjunction/core`: ^2.43.0
-- `@memberjunction/core-entities`: ^2.43.0
-- `@memberjunction/global`: ^2.43.0
-- `@memberjunction/graphql-dataprovider`: ^2.43.0
+## Overview
+
+The notification service acts as a centralized hub for all notifications across the application. It automatically subscribes to MemberJunction global events, manages real-time push notification updates via GraphQL WebSockets, and maintains an observable stream of unread notification counts.
+
+```mermaid
+flowchart TD
+    subgraph Sources["Notification Sources"]
+        A["Application Code"]
+        B["MJGlobal Events"]
+        C["Push Notifications (WebSocket)"]
+    end
+    subgraph Service["MJNotificationService (Singleton)"]
+        D["CreateSimpleNotification()"]
+        E["CreateNotification()"]
+        F["Notification State"]
+    end
+    subgraph Outputs["Outputs"]
+        G["Kendo UI Toast"]
+        H["UserNotification Entity (DB)"]
+        I["Notifications$ Observable"]
+        J["UnreadCount$ Observable"]
+    end
+
+    A --> D
+    A --> E
+    B --> D
+    C --> F
+    D --> G
+    E --> H
+    F --> I
+    F --> J
+
+    style Sources fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Service fill:#7c5295,stroke:#563a6b,color:#fff
+    style Outputs fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
 
 ## Usage
 
-### Module Setup
-
-Import the `MJNotificationsModule` in your Angular module:
+### Module Import
 
 ```typescript
 import { MJNotificationsModule } from '@memberjunction/ng-notifications';
 
 @NgModule({
-  imports: [
-    // other imports...
-    MJNotificationsModule
-  ],
+  imports: [MJNotificationsModule]
 })
-export class YourModule { }
+export class YourModule {}
 ```
 
-### Service Injection
-
-The service is automatically provided at the root level, so you can inject it directly:
+### Simple (Transient) Notifications
 
 ```typescript
 import { MJNotificationService } from '@memberjunction/ng-notifications';
 
-@Component({
-  selector: 'app-example',
-  templateUrl: './example.component.html'
-})
-export class ExampleComponent {
-  constructor(private notificationService: MJNotificationService) {}
-  
-  // Or access the singleton instance
-  showNotification() {
-    MJNotificationService.Instance.CreateSimpleNotification(
-      'Operation completed', 
-      'success', 
-      3000
-    );
-  }
-}
-```
-
-## API Reference
-
-### MJNotificationService
-
-Singleton service for managing notifications across the application.
-
-#### Methods
-
-##### CreateSimpleNotification
-Creates a temporary UI notification that displays to the user.
-
-```typescript
-CreateSimpleNotification(
-  message: string, 
-  style: "none" | "success" | "error" | "warning" | "info" = "success", 
-  hideAfter?: number
-): void
-```
-
-**Parameters:**
-- `message`: Text to display to the user
-- `style`: Visual style of the notification (default: "success")
-- `hideAfter`: Optional duration in milliseconds before auto-hiding. If not specified, notification shows a close button
-
-**Examples:**
-```typescript
-// Basic success notification
-notificationService.CreateSimpleNotification('Data saved successfully');
-
-// Error notification that auto-hides after 5 seconds
-notificationService.CreateSimpleNotification(
-  'Failed to process request', 
-  'error', 
-  5000
+// Via singleton instance
+MJNotificationService.Instance.CreateSimpleNotification(
+  'Record saved successfully',
+  'success',
+  3000  // auto-hide after 3 seconds
 );
 
-// Warning with manual close
-notificationService.CreateSimpleNotification(
-  'Please review your changes', 
-  'warning'
+// Error notification without auto-hide
+MJNotificationService.Instance.CreateSimpleNotification(
+  'Failed to load data',
+  'error'
 );
 ```
 
-##### CreateNotification
-Creates a persistent notification stored in the database.
-
-```typescript
-async CreateNotification(
-  title: string, 
-  message: string, 
-  resourceTypeId: string | null, 
-  resourceRecordId: string | null, 
-  resourceConfiguration: any | null, 
-  displayToUser: boolean = true
-): Promise<UserNotificationEntity>
-```
-
-**Parameters:**
-- `title`: Notification title
-- `message`: Notification message content
-- `resourceTypeId`: Optional ID of the resource type this notification relates to
-- `resourceRecordId`: Optional ID of the specific resource record
-- `resourceConfiguration`: Optional configuration object (stored as JSON)
-- `displayToUser`: Whether to show a UI notification immediately (default: true)
+### Persistent (Database) Notifications
 
-**Examples:**
 ```typescript
-// Simple notification
-const notification = await notificationService.CreateNotification(
-  'Welcome!', 
-  'Thank you for joining our platform', 
-  null, 
-  null, 
-  null
-);
-
-// Resource-linked notification
-const reportNotification = await notificationService.CreateNotification(
-  'Report Generated', 
-  'Your monthly sales report is ready', 
-  reportResourceTypeId, 
-  reportId, 
-  { format: 'pdf', includeCharts: true }
-);
-
-// Silent notification (no immediate UI display)
-await notificationService.CreateNotification(
-  'Settings Updated', 
-  'Your preferences have been saved', 
-  null, 
-  null, 
-  null, 
-  false
+const notification = await MJNotificationService.Instance.CreateNotification(
+  'Report Ready',
+  'Your monthly sales report has been generated',
+  reportResourceTypeId,  // optional resource type ID
+  reportId,              // optional resource record ID
+  { format: 'pdf' },    // optional configuration JSON
+  true                   // display UI notification immediately
 );
 ```
 
-##### PushStatusUpdates
-Returns an observable for subscribing to real-time push notification updates.
+### Accessing Notification State
 
 ```typescript
-PushStatusUpdates(): Observable<string>
-```
+// All notifications
+const all = MJNotificationService.UserNotifications;
 
-**Example:**
-```typescript
-notificationService.PushStatusUpdates().subscribe(status => {
-  const statusObj = JSON.parse(status.message);
-  console.log('Push update received:', statusObj);
-});
-```
-
-#### Static Methods
-
-##### RefreshUserNotifications
-Manually refreshes the user's notifications from the database.
+// Unread only
+const unread = MJNotificationService.UnreadUserNotifications;
 
-```typescript
-static async RefreshUserNotifications(): Promise<void>
-```
+// Unread count
+const count = MJNotificationService.UnreadUserNotificationCount;
 
-**Example:**
-```typescript
+// Refresh from server
 await MJNotificationService.RefreshUserNotifications();
-console.log('Notifications refreshed');
-```
-
-#### Static Properties
-
-##### Instance
-Access the singleton instance of the notification service.
-
-```typescript
-static get Instance(): MJNotificationService
-```
-
-##### UserNotifications
-Get all notifications for the current user.
-
-```typescript
-static get UserNotifications(): UserNotificationEntity[]
-```
-
-##### UnreadUserNotifications
-Get only unread notifications.
-
-```typescript
-static get UnreadUserNotifications(): UserNotificationEntity[]
 ```
 
-##### UnreadUserNotificationCount
-Get the count of unread notifications.
-
-```typescript
-static get UnreadUserNotificationCount(): number
-```
+## API Reference
 
-**Example:**
-```typescript
-// Display unread count in UI
-const unreadCount = MJNotificationService.UnreadUserNotificationCount;
-console.log(`You have ${unreadCount} unread notifications`);
+### MJNotificationService
 
-// Process unread notifications
-const unread = MJNotificationService.UnreadUserNotifications;
-unread.forEach(notification => {
-  console.log(notification.Title, notification.Message);
-});
-```
+| Method | Description |
+|--------|-------------|
+| `CreateSimpleNotification(message, style?, hideAfter?)` | Display a temporary toast notification |
+| `CreateNotification(title, message, resourceTypeId?, resourceRecordId?, config?, displayToUser?)` | Create a persistent notification in the database |
+| `PushStatusUpdates()` | Returns an Observable for real-time push notifications |
+
+| Static Property | Type | Description |
+|-----------------|------|-------------|
+| `Instance` | `MJNotificationService` | Singleton instance |
+| `UserNotifications` | `UserNotificationEntity[]` | All user notifications |
+| `UnreadUserNotifications` | `UserNotificationEntity[]` | Unread notifications only |
+| `UnreadUserNotificationCount` | `number` | Count of unread notifications |
+
+### Notification Styles
+
+| Style | Use Case |
+|-------|----------|
+| `'success'` | Completed operations, confirmations |
+| `'error'` | Failed operations, validation errors |
+| `'warning'` | Important notices requiring attention |
+| `'info'` | General information |
+| `'none'` | Unstyled notification |
 
 ## Event Integration
 
-The service automatically integrates with MemberJunction global events:
-
-### Handled Events
-
-1. **MJEventType.LoggedIn**
-   - Refreshes user notifications from the database
-   - Subscribes to push notification updates
-
-2. **MJEventType.DisplaySimpleNotificationRequest**
-   - Displays notifications triggered from other parts of the application
-   - Allows centralized notification handling
-
-3. **MJEventType.ComponentEvent** (code: "UserNotificationsUpdated")
-   - Refreshes the notification list when updates occur
-
-### Push Notification Handling
-
-The service processes push notifications for:
-- **User Notifications**: Automatically refreshes when new notifications are created
-- **Other Types**: Displays as simple notifications (except for specific system types)
-
-## Best Practices
-
-### 1. Use Appropriate Notification Types
-
-```typescript
-// Use simple notifications for transient messages
-this.notificationService.CreateSimpleNotification(
-  'File uploaded successfully', 
-  'success', 
-  3000
-);
-
-// Use database notifications for important persistent messages
-await this.notificationService.CreateNotification(
-  'Invoice Due', 
-  'Invoice #1234 is due in 3 days', 
-  invoiceResourceTypeId, 
-  invoiceId, 
-  { dueDate: '2024-01-15', amount: 1500 }
-);
-```
-
-### 2. Handle Errors Gracefully
-
-```typescript
-try {
-  await this.notificationService.CreateNotification(
-    'Task Complete', 
-    'Your scheduled task has finished', 
-    null, 
-    null, 
-    null
-  );
-} catch (error) {
-  // Fall back to simple notification on error
-  this.notificationService.CreateSimpleNotification(
-    'Could not save notification', 
-    'error', 
-    5000
-  );
-}
-```
-
-### 3. Leverage Resource Linking
-
-When notifications relate to specific entities or resources, always include the resource information:
-
-```typescript
-// Link to a specific record
-await this.notificationService.CreateNotification(
-  'Order Shipped', 
-  `Order ${orderNumber} has been shipped`, 
-  orderResourceTypeId, 
-  orderId, 
-  { trackingNumber: 'ABC123', carrier: 'FedEx' }
-);
-```
-
-### 4. Use Consistent Styling
-
-- **Success**: Completed operations, confirmations
-- **Error**: Failed operations, validation errors
-- **Warning**: Important notices, confirmations needed
-- **Info**: General information, tips
-
-### 5. Consider Auto-hide Duration
-
-```typescript
-// Quick confirmations: 2-3 seconds
-this.notificationService.CreateSimpleNotification('Saved', 'success', 2000);
-
-// Important messages: 5+ seconds or manual close
-this.notificationService.CreateSimpleNotification(
-  'Please review the validation errors below', 
-  'warning'
-);
-```
-
-## Integration with MemberJunction
-
-### User Context
-
-The service automatically uses the current user context from MemberJunction metadata:
-
-```typescript
-// Notifications are automatically associated with the current user
-const notification = await this.notificationService.CreateNotification(
-  'Personal Alert', 
-  'This is just for you', 
-  null, 
-  null, 
-  null
-);
-// notification.UserID is automatically set to the current user
-```
-
-### Entity Integration
-
-Notifications are stored as `UserNotificationEntity` objects, allowing full entity operations:
-
-```typescript
-// Mark notification as read
-const notification = MJNotificationService.UnreadUserNotifications[0];
-notification.Unread = false;
-await notification.Save();
-
-// Delete old notifications
-const oldNotifications = MJNotificationService.UserNotifications
-  .filter(n => n.CreatedAt < someDate);
-for (const notif of oldNotifications) {
-  await notif.Delete();
-}
-```
-
-## Module Exports
+The service automatically handles these MJGlobal events:
 
-The package exports:
-- `MJNotificationsModule` - The Angular module to import
-- `MJNotificationService` - The notification service
+- **`MJEventType.LoggedIn`** -- Refreshes notifications and subscribes to push updates
+- **`MJEventType.DisplaySimpleNotificationRequest`** -- Displays notifications from any part of the application
+- **`MJEventType.ComponentEvent`** (`UserNotificationsUpdated`) -- Refreshes the notification list
 
-## Support
+## Dependencies
 
-For issues or questions:
-- Check the [MemberJunction documentation](https://docs.memberjunction.com)
-- Submit issues to the [GitHub repository](https://github.com/MemberJunction/MJ)
-- Contact MemberJunction support
+- [@memberjunction/core](../../MJCore/README.md) -- Metadata, UserInfo
+- [@memberjunction/core-entities](../../MJCoreEntities/README.md) -- UserNotificationEntity
+- [@memberjunction/global](../../MJGlobal/README.md) -- MJGlobal event system
+- [@memberjunction/graphql-dataprovider](../../GraphQLDataProvider/README.md) -- Push notification subscriptions
+- `@progress/kendo-angular-notification` -- Toast notification rendering

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ng-notifications",
-  "version": "3.4.0",
+  "version": "4.1.0",
   "description": "MemberJunction: Simple Angular library for displaying user notifications",
   "main": "./dist/public-api.js",
   "typings": "./dist/public-api.d.ts",
@@ -15,21 +15,21 @@
   "author": "",
   "license": "ISC",
   "devDependencies": {
-    "@angular/compiler": "18.2.14",
-    "@angular/compiler-cli": "18.2.14"
+    "@angular/compiler": "21.1.3",
+    "@angular/compiler-cli": "21.1.3"
   },
   "peerDependencies": {
-    "@angular/common": "18.2.14",
-    "@angular/core": "18.2.14",
-    "@progress/kendo-angular-notification": "16.2.0"
+    "@angular/common": "21.1.3",
+    "@angular/core": "21.1.3",
+    "@progress/kendo-angular-notification": "22.0.1"
   },
   "dependencies": {
-    "@memberjunction/core": "3.4.0",
-    "@memberjunction/core-entities": "3.4.0",
-    "@memberjunction/global": "3.4.0",
-    "@memberjunction/graphql-dataprovider": "3.4.0",
-    "tslib": "^2.3.0",
-    "rxjs": "^7.8.1"
+    "@memberjunction/core": "4.1.0",
+    "@memberjunction/core-entities": "4.1.0",
+    "@memberjunction/global": "4.1.0",
+    "@memberjunction/graphql-dataprovider": "4.1.0",
+    "tslib": "^2.8.1",
+    "rxjs": "^7.8.2"
   },
   "sideEffects": false,
   "repository": {