@memberjunction/ng-notifications 2.43.0 → 2.44.0

package/README.md

@@ -4,13 +4,15 @@ Angular service for handling user notifications in MemberJunction applications,
 
 ## Features
 
-- Singleton notification service for consistent application-wide notifications
-- Support for temporary UI notifications
-- Database-backed persistent user notifications
-- Real-time push notification updates
-- Notification styling options (success, error, warning, info)
-- Automatic notification refresh on login
-- Unread notification tracking
+- **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
 
 ## Installation
 
@@ -18,86 +20,154 @@ 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
+
 ## Usage
 
-The service is automatically provided at the root level, so you can inject it directly into your components:
+### Module Setup
+
+Import the `MJNotificationsModule` in your Angular module:
+
+```typescript
+import { MJNotificationsModule } from '@memberjunction/ng-notifications';
+
+@NgModule({
+  imports: [
+    // other imports...
+    MJNotificationsModule
+  ],
+})
+export class YourModule { }
+```
+
+### Service Injection
+
+The service is automatically provided at the root level, so you can inject it directly:
 
 ```typescript
 import { MJNotificationService } from '@memberjunction/ng-notifications';
 
 @Component({
-  // ...
+  selector: 'app-example',
+  templateUrl: './example.component.html'
 })
-export class YourComponent {
-  constructor(private notificationService: MJNotificationService) {
-    // Use the service directly
-  }
+export class ExampleComponent {
+  constructor(private notificationService: MJNotificationService) {}
   
   // Or access the singleton instance
   showNotification() {
-    MJNotificationService.Instance.CreateSimpleNotification('Operation completed', 'success', 3000);
+    MJNotificationService.Instance.CreateSimpleNotification(
+      'Operation completed', 
+      'success', 
+      3000
+    );
   }
 }
 ```
 
-## Features
+## API Reference
 
-### Simple UI Notifications
+### MJNotificationService
 
-Display temporary notifications to the user:
+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('Operation completed successfully');
+notificationService.CreateSimpleNotification('Data saved successfully');
 
-// Error notification that disappears after 5 seconds
+// Error notification that auto-hides after 5 seconds
 notificationService.CreateSimpleNotification(
-  'An error occurred while processing your request', 
+  'Failed to process request', 
   'error', 
   5000
 );
 
-// Warning notification with manual close button
+// Warning with manual close
 notificationService.CreateSimpleNotification(
-  'Please verify your input data', 
+  'Please review your changes', 
   'warning'
 );
-
-// Informational notification
-notificationService.CreateSimpleNotification(
-  'New updates are available', 
-  'info', 
-  3000
-);
 ```
 
-### Persistent Database Notifications
+##### CreateNotification
+Creates a persistent notification stored in the database.
 
-Create notifications that are stored in the database and can be viewed later:
+```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)
 
+**Examples:**
 ```typescript
-// Create a simple notification
-await notificationService.CreateNotification(
-  'New Comment', 
-  'User John added a comment to your post', 
+// Simple notification
+const notification = await notificationService.CreateNotification(
+  'Welcome!', 
+  'Thank you for joining our platform', 
   null, 
   null, 
   null
 );
 
-// Create a notification linked to a resource
-await notificationService.CreateNotification(
-  'Report Ready', 
-  'Your requested report is now available', 
+// Resource-linked notification
+const reportNotification = await notificationService.CreateNotification(
+  'Report Generated', 
+  'Your monthly sales report is ready', 
   reportResourceTypeId, 
   reportId, 
-  { reportConfig: 'some-config-data' }
+  { format: 'pdf', includeCharts: true }
 );
 
-// Create a notification but don't display it to the user immediately
+// Silent notification (no immediate UI display)
 await notificationService.CreateNotification(
-  'Background Update', 
-  'System updated your preferences', 
+  'Settings Updated', 
+  'Your preferences have been saved', 
   null, 
   null, 
   null, 
@@ -105,43 +175,225 @@ await notificationService.CreateNotification(
 );
 ```
 
-### Accessing User Notifications
+##### PushStatusUpdates
+Returns an observable for subscribing to real-time push notification updates.
 
-Retrieve user notifications:
+```typescript
+PushStatusUpdates(): Observable<string>
+```
 
+**Example:**
 ```typescript
-// Get all notifications for the current user
-const notifications = MJNotificationService.UserNotifications;
+notificationService.PushStatusUpdates().subscribe(status => {
+  const statusObj = JSON.parse(status.message);
+  console.log('Push update received:', statusObj);
+});
+```
 
-// Get only unread notifications
-const unreadNotifications = MJNotificationService.UnreadUserNotifications;
+#### Static Methods
 
-// Get count of unread notifications
-const unreadCount = MJNotificationService.UnreadUserNotificationCount;
+##### RefreshUserNotifications
+Manually refreshes the user's notifications from the database.
 
-// Manually refresh notifications from the database
+```typescript
+static async RefreshUserNotifications(): Promise<void>
+```
+
+**Example:**
+```typescript
 await MJNotificationService.RefreshUserNotifications();
+console.log('Notifications refreshed');
 ```
 
-## Push Notifications
+#### Static Properties
 
-The service automatically subscribes to push notifications after login, handling:
+##### Instance
+Access the singleton instance of the notification service.
+
+```typescript
+static get Instance(): MJNotificationService
+```
 
-- User notification updates
-- System status messages
-- Custom event propagation
+##### UserNotifications
+Get all notifications for the current user.
 
 ```typescript
-// Access push status updates directly
-notificationService.PushStatusUpdates().subscribe(status => {
-  // Handle status updates
+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
+```
+
+**Example:**
+```typescript
+// Display unread count in UI
+const unreadCount = MJNotificationService.UnreadUserNotificationCount;
+console.log(`You have ${unreadCount} unread notifications`);
+
+// Process unread notifications
+const unread = MJNotificationService.UnreadUserNotifications;
+unread.forEach(notification => {
+  console.log(notification.Title, notification.Message);
 });
 ```
 
 ## Event Integration
 
-The service integrates with MemberJunction global events, reacting to:
+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 package exports:
+- `MJNotificationsModule` - The Angular module to import
+- `MJNotificationService` - The notification service
+
+## Support
 
-- `MJEventType.LoggedIn`: Refreshes notifications and sets up push updates
-- `MJEventType.DisplaySimpleNotificationRequest`: Displays notifications from other parts of the application
-- `MJEventType.ComponentEvent` with `UserNotificationsUpdated` code: Refreshes notification list
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ng-notifications",
-  "version": "2.43.0",
+  "version": "2.44.0",
   "description": "MemberJunction: Simple Angular library for displaying user notifications",
   "main": "./dist/public-api.js",
   "typings": "./dist/public-api.d.ts",
@@ -24,10 +24,10 @@
     "@progress/kendo-angular-notification": "16.2.0"
   },
   "dependencies": {
-    "@memberjunction/core": "2.43.0",
-    "@memberjunction/core-entities": "2.43.0",
-    "@memberjunction/global": "2.43.0",
-    "@memberjunction/graphql-dataprovider": "2.43.0",
+    "@memberjunction/core": "2.44.0",
+    "@memberjunction/core-entities": "2.44.0",
+    "@memberjunction/global": "2.44.0",
+    "@memberjunction/graphql-dataprovider": "2.44.0",
     "tslib": "^2.3.0",
     "rxjs": "^7.8.1"
   },