http-request-manager 18.7.1 → 18.7.3

package/README.md

@@ -468,21 +468,45 @@ this.wsService.getUsersInChannel('PUB-my-channel');
 
 #### Channel Naming Conventions
 
-The WebSocket service supports channel prefixes for organizing communication:
+The WebSocket service and state manager use a **channel type system** to organize communication. Channel prefixes are managed automatically by the state service.
 
-| Prefix | Description | Visibility |
-| :--- | :--- | :--- |
-| `PUB-` | Public channels for user messaging | Visible to users |
-| `SYS-` | System channels for internal communication | Hidden from users |
+##### Channel Types (`ChannelType` Enum)
+
+```typescript
+import { ChannelType, createChannelName } from 'http-request-manager';
+
+export enum ChannelType {
+  STATE = 'SYS',        // Private state synchronization channels
+  MESSAGE = 'MES',      // Messaging/communication channels (persisted notifications)
+  NOTIFICATION = 'PUB'  // Public notification/broadcast channels
+}
+
+// Utility function to create prefixed channel name
+createChannelName(ChannelType.STATE, 'USERS123');  // Returns 'SYS-USERS123'
+createChannelName(ChannelType.MESSAGE, 'alerts');   // Returns 'MES-alerts'
+createChannelName(ChannelType.NOTIFICATION, 'chat'); // Returns 'PUB-chat'
+```
+
+| Channel Type | Prefix | Description | Visibility | Persistence |
+| :--- | :--- | :--- | :--- | :--- |
+| `STATE` | `SYS-` | Private channels for state synchronization (CRUD operations) | Hidden from users | In-memory only |
+| `MESSAGE` | `MES-` | Messaging channels for notifications (persisted to database) | Visible to users | Database persisted |
+| `NOTIFICATION` | `PUB-` | Public channels for real-time messaging/chat | Visible to users | In-memory only |
+
+**Important:** When using `HTTPManagerStateService`, channel prefixes are automatically managed. You only need to provide the base channel name.
 
 **Example:**
 
 ```typescript
-// Create a public channel (visible in UI)
-this.wsService.createChannel('PUB-general-chat');
+// State service automatically adds SYS- prefix for state channels
+// User provides: 'USERS123'
+// State service uses: 'SYS-USERS123'
 
-// Create a system channel (hidden from UI)
-this.wsService.createChannel('SYS-internal-notifications');
+// For messaging channels, use subscribeToMessageChannel()
+stateService.subscribeToMessageChannel('alerts');  // Uses 'MES-alerts'
+
+// For notification channels, use subscribeToNotificationChannel()
+stateService.subscribeToNotificationChannel('announcements');  // Uses 'PUB-announcements'
 ```
 
 #### WebSocket Message Types
@@ -543,6 +567,326 @@ export class UsersStore extends HTTPManagerStateService<User> {
 }
 ```
 
+---
+
+## Real-Time Features
+
+The `http-request-manager` library provides two distinct real-time communication features:
+
+1. **Messaging (PUB- channels)** - Real-time chat/messaging between users
+2. **Notifications (MES- channels)** - Persistent notifications stored in database
+
+Both features integrate seamlessly with `HTTPManagerStateService` and automatically manage channel prefixes.
+
+### Messaging Feature (PUB- Channels)
+
+**Purpose:** Real-time messaging/chat functionality for communication between users.
+
+**Characteristics:**
+
+- Messages are broadcast in real-time to subscribed users
+- Messages are stored in-memory only (not persisted to database)
+- Uses `PUB-` prefix (automatically added)
+- Ideal for chat applications, live collaboration, etc.
+
+#### Messaging Observables
+
+| Observable | Type | Description |
+| :--- | :--- | :--- |
+| `channels$` | `Observable<string[]>` | List of all available channels |
+| `communicationMessages$` | `Observable<any[]>` | All received messages |
+| `latestCommunicationMessages$` | `Observable<any>` | Most recent message received |
+| `connectionStatus$` | `Observable<boolean>` | WebSocket connection status |
+| `user$` | `Observable<WSUser>` | Current user information |
+
+#### Messaging Methods
+
+```typescript
+// Create a new messaging channel
+stateService.createChannel('general-chat');  // Creates PUB-general-chat
+
+// Subscribe to a channel to receive messages
+stateService.subscribeToChannel('general-chat');  // Subscribes to PUB-general-chat
+
+// Unsubscribe from a channel
+stateService.unsubscribeFromChannel('general-chat');
+
+// Get all available channels
+stateService.getAllChannels();
+
+// Send a message to specific channels
+stateService.wsMessaging(
+  ChannelMessage.adapt({
+    sessionId: currentUser,
+    content: { message: 'Hello everyone!' }
+  }),
+  ['general-chat', 'team-updates']  // Channels (PUB- prefix added automatically)
+);
+```
+
+#### Demo Component: `WsMessagingComponent`
+
+The library includes a demo component showcasing messaging functionality:
+
+```html
+<app-ws-messaging
+  [server]="'http://localhost:8080'"
+  [wsServer]="'ws://localhost:8080'"
+  [jwtToken]="'your-jwt-token'"
+  [user]="{ ldap: 'jdoe', name: 'John Doe', email: 'jdoe@example.com' }">
+</app-ws-messaging>
+```
+
+**Features demonstrated:**
+
+- Create public channels
+- Subscribe/unsubscribe to channels
+- Send messages to multiple channels
+- View real-time message stream
+- Toast notifications for incoming messages
+
+---
+
+### Notifications Feature (MES- Channels)
+
+**Purpose:** Persistent notifications that are stored in the database and can be retrieved with date filters.
+
+**Characteristics:**
+
+- Notifications are persisted to the server database
+- Supports date-range queries (startEpoch, endEpoch)
+- Uses `MES-` prefix (automatically added)
+- Retrieves historical notifications on subscription
+- Ideal for announcements, alerts, audit logs, etc.
+
+#### Notification Observables
+
+| Observable | Type | Description |
+| :--- | :--- | :--- |
+| `notificationChannels$` | `Observable<string[]>` | In-memory notification channels from server |
+| `todaysNotificationChannels$` | `Observable<string[]>` | Channels with notifications posted today (from DB) |
+| `notificationMessages$` | `Observable<any[]>` | All notification messages |
+| `latestNotification$` | `Observable<any>` | Most recent notification received |
+
+#### Notification Methods
+
+```typescript
+// Create a notification channel
+stateService.createNotificationChannel('alerts');  // Creates MES-alerts
+
+// Get all notification channels (in-memory)
+stateService.getNotificationChannels();
+
+// Get today's notification channels (from database)
+stateService.getTodaysNotificationChannels();
+
+// Subscribe to notifications with optional date filter
+stateService.subscribeToNotificationChannel('alerts', {
+  startEpoch: Math.floor(Date.now() / 1000) - 86400,  // Last 24 hours
+  endEpoch: Math.floor(Date.now() / 1000)
+});
+
+// Unsubscribe from notifications
+stateService.unsubscribeFromNotificationChannel('alerts');
+
+// Send a notification (persisted to database)
+stateService.sendNotification('alerts', {
+  title: 'System Alert',
+  message: 'Scheduled maintenance at midnight',
+  priority: 'high'
+});
+```
+
+#### Notification Message Structure
+
+```typescript
+interface NotificationMessage {
+  id: number;
+  channel: string;      // e.g., 'MES-alerts'
+  created: number;      // epoch seconds
+  user_name: string;    // sender's name
+  sessionId: any;       // sender's session info
+  content: any;         // notification payload
+}
+```
+
+#### Demo Component: `WsNotificationsComponent`
+
+The library includes a demo component showcasing notification functionality:
+
+```html
+<app-ws-notifications
+  [server]="'http://localhost:8080'"
+  [wsServer]="'ws://localhost:8080'"
+  [jwtToken]="'your-jwt-token'"
+  [user]="{ ldap: 'jdoe', name: 'John Doe', email: 'jdoe@example.com' }">
+</app-ws-notifications>
+```
+
+**Features demonstrated:**
+
+- Create notification channels
+- View today's notification channels (from database)
+- Subscribe with date range filters
+- Connect/disconnect from channels
+- Send notifications (persisted)
+- View historical notifications in a table
+
+---
+
+### Creating a Custom State Service with Messaging & Notifications
+
+Here's a complete example of a state service that utilizes all real-time features:
+
+```typescript
+import { Injectable } from '@angular/core';
+import { HTTPManagerStateService, ChannelType, createChannelName } from 'http-request-manager';
+import { ApiRequest, DataType, DatabaseStorage } from 'http-request-manager';
+
+export interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+@Injectable({
+  providedIn: 'root'
+})
+export class UserStateService extends HTTPManagerStateService<User> {
+
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        server: 'http://localhost:8080',
+        path: ['api', 'users'],
+        adapter: (data: any) => data as User,
+        ws: {
+          id: 'USERS123',  // Base name - automatically becomes SYS-USERS123
+          wsServer: 'ws://localhost:8080',
+          jwtToken: '',
+          retry: { times: 3, delay: 5 }
+        }
+      }),
+      DataType.ARRAY,
+      DatabaseStorage.adapt({ table: 'users-cache', expiresIn: '1d' })
+    );
+  }
+
+  // Initialize connection with user info
+  initializeConnection(wsServer: string, jwtToken: string, user: any) {
+    this.setApiRequestOptions(
+      ApiRequest.adapt({
+        ...this.ApiRequestOptions,
+        ws: {
+          ...this.ApiRequestOptions.ws,
+          wsServer,
+          jwtToken,
+          user
+        }
+      })
+    );
+  }
+
+  // === MESSAGING (PUB- channels) ===
+
+  createChatRoom(roomName: string) {
+    this.createChannel(roomName);  // Creates PUB-{roomName}
+  }
+
+  joinChatRoom(roomName: string) {
+    this.subscribeToChannel(roomName);
+  }
+
+  leaveChatRoom(roomName: string) {
+    this.unsubscribeFromChannel(roomName);
+  }
+
+  sendChatMessage(content: string, rooms: string[]) {
+    this.wsMessaging(
+      { content: { message: content } },
+      rooms
+    );
+  }
+
+  // === NOTIFICATIONS (MES- channels) ===
+
+  createNotificationStream(streamName: string) {
+    this.createNotificationChannel(streamName);  // Creates MES-{streamName}
+  }
+
+  subscribeToAlerts(streamName: string, lastHours: number = 24) {
+    const now = Math.floor(Date.now() / 1000);
+    const startEpoch = now - (lastHours * 3600);
+
+    this.subscribeToNotificationChannel(streamName, {
+      startEpoch,
+      endEpoch: now
+    });
+  }
+
+  sendAlert(streamName: string, alert: { title: string; message: string; priority: string }) {
+    this.sendNotification(streamName, alert);
+  }
+}
+```
+
+**Usage in Component:**
+
+```typescript
+@Component({
+  selector: 'app-dashboard',
+  template: `
+    <div *ngIf="connectionStatus$ | async">
+      <!-- Chat Messages -->
+      <div *ngFor="let msg of chatMessages$ | async">
+        {{ msg.content.message }}
+      </div>
+
+      <!-- Notifications -->
+      <div *ngFor="let notification of notifications$ | async">
+        {{ notification.content.title }}: {{ notification.content.message }}
+      </div>
+    </div>
+  `
+})
+export class DashboardComponent implements OnInit {
+  userState = inject(UserStateService);
+
+  connectionStatus$ = this.userState.connectionStatus$;
+  chatMessages$ = this.userState.communicationMessages$;
+  notifications$ = this.userState.notificationMessages$;
+
+  ngOnInit() {
+    // Initialize WebSocket connection
+    this.userState.initializeConnection(
+      'ws://localhost:8080',
+      'jwt-token',
+      { ldap: 'jdoe', name: 'John Doe' }
+    );
+
+    // Join a chat room
+    this.userState.joinChatRoom('general');
+
+    // Subscribe to alerts from last 24 hours
+    this.userState.subscribeToAlerts('system-alerts', 24);
+  }
+
+  sendMessage(text: string) {
+    this.userState.sendChatMessage(text, ['general']);
+  }
+
+  sendAlert() {
+    this.userState.sendAlert('system-alerts', {
+      title: 'Update Available',
+      message: 'A new version is available',
+      priority: 'medium'
+    });
+  }
+}
+```
+
+---
+
 ### 8. Database Manager Service (`DatabaseManagerService`)
 
 **Path:** `database-manager-service/database.manager.service.ts`