http-request-manager 18.15.32 → 18.15.34

package/src/docs/WEBSOCKET_MESSAGE_SERVICE.md

@@ -0,0 +1,799 @@
+# WebSocket Message Service
+
+A unified, type-safe service for sending WebSocket messages with automatic prefix management and concrete message models.
+
+## Overview
+
+The `WebSocketMessageService` provides a simplified API for sending WebSocket messages across different channel types. It automatically handles channel prefixes, message validation, and provides compile-time type safety.
+
+## Key Features
+
+✅ **Type-Safe Messages** - Concrete models with TypeScript validation  
+✅ **Automatic Prefix Management** - SYS-, PUB-, MES- prefixes handled automatically  
+✅ **Runtime Validation** - Checks required fields before sending  
+✅ **Boolean Return Values** - Simple success/failure indication  
+✅ **Silent Failure** - Console errors without exceptions  
+✅ **Single Service** - One injection point for all WebSocket messaging  
+
+## Installation
+
+The service is automatically available when you import `HttpRequestManagerModule`:
+
+```typescript
+import { HttpRequestManagerModule } from 'http-request-manager';
+
+@NgModule({
+  imports: [HttpRequestManagerModule.forRoot({})]
+})
+export class AppModule { }
+```
+
+## Usage
+
+### Import the Service
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { 
+  WebSocketMessageService,
+  StateMessage,
+  PublicMessage,
+  NotificationMessage
+} from 'http-request-manager';
+
+@Component({
+  selector: 'app-messaging',
+  template: `...`
+})
+export class MessagingComponent {
+  private wsMessageService = inject(WebSocketMessageService);
+}
+```
+
+---
+
+## Message Types
+
+The service supports three message types, each with its own channel prefix:
+
+| Type | Prefix | Use Case | Model |
+|------|--------|----------|-------|
+| **State** | `SYS-` | CRUD operations, state synchronization | `StateMessage` |
+| **Public** | `PUB-` | Chat, broadcast, general messaging | `PublicMessage` |
+| **Notification** | `MES-` | Persistent notifications with history | `NotificationMessage` |
+
+---
+
+## API Reference
+
+### `sendStateMessage(path, payload)`
+
+Send a state message for CRUD operations and state synchronization.
+
+**Parameters:**
+- `path: (string|number)[]` - Path array (e.g., `['ai', 'tests']`)
+- `payload: StateMessage` - Message with sessionId and content
+
+**Returns:** `boolean` - `true` if sent successfully, `false` otherwise
+
+**Channel:** `SYS-{path.join('/')}` (e.g., `SYS-ai/tests`)
+
+**Example:**
+
+```typescript
+const message = StateMessage.adapt({
+  sessionId: { id: 'user123', name: 'John', email: 'john@example.com' },
+  content: { 
+    action: 'create',
+    data: { name: 'New Item', value: 42 }
+  }
+});
+
+const success = this.wsMessageService.sendStateMessage(
+  ['ai', 'tests'], 
+  message
+);
+
+if (!success) {
+  console.warn('Failed to send state message');
+}
+```
+
+**Validation:**
+- ✅ `sessionId.id` is required
+- ✅ `content` can be any object
+- ✅ WebSocket must be connected
+
+---
+
+### `sendPublicMessage(channel, payload)`
+
+Send a public message for chat, broadcast, or general messaging.
+
+**Parameters:**
+- `channel: string` - Channel name (without prefix)
+- `payload: PublicMessage` - Message with sessionId and content.message
+
+**Returns:** `boolean` - `true` if sent successfully, `false` otherwise
+
+**Channel:** `PUB-{channel}` (e.g., `PUB-chat`)
+
+**Example:**
+
+```typescript
+const chatMessage = PublicMessage.adapt({
+  sessionId: { id: 'user123', name: 'John' },
+  content: { 
+    message: 'Hello everyone!',
+    timestamp: Date.now()
+  }
+});
+
+const success = this.wsMessageService.sendPublicMessage('chat', chatMessage);
+```
+
+**Validation:**
+- ✅ `sessionId.id` is required
+- ✅ `content.message` is required (string)
+- ✅ `content` can have additional properties
+- ✅ WebSocket must be connected
+
+---
+
+### `sendNotification(channel, payload)`
+
+Send a persistent notification with history support.
+
+**Parameters:**
+- `channel: string` - Channel name (without prefix)
+- `payload: NotificationMessage` - Message with sessionId and message
+
+**Returns:** `boolean` - `true` if sent successfully, `false` otherwise
+
+**Channel:** `MES-{channel}` (e.g., `MES-alerts`)
+
+**Example:**
+
+```typescript
+const notification = NotificationMessage.adapt({
+  sessionId: { id: 'user123', name: 'John', color: '#FF0000' },
+  message: 'New item created!',
+  timestamp: Date.now(),
+  priority: 'high'
+});
+
+const success = this.wsMessageService.sendNotification('alerts', notification);
+```
+
+**Validation:**
+- ✅ `sessionId.id` is required
+- ✅ `message` is required (string)
+- ✅ Additional properties allowed (index signature)
+- ✅ WebSocket must be connected
+
+---
+
+### `sendToCustomChannel(channel, payload)`
+
+Send to a custom channel without automatic prefix.
+
+**Parameters:**
+- `channel: string` - Full channel name (as-is)
+- `payload: any` - Any message payload
+
+**Returns:** `boolean` - `true` if sent successfully, `false` otherwise
+
+**Channel:** Raw channel name (no prefix added)
+
+**Example:**
+
+```typescript
+const success = this.wsMessageService.sendToCustomChannel(
+  'CUSTOM-my-channel',
+  { custom: 'data', value: 123 }
+);
+```
+
+**Validation:**
+- ✅ WebSocket must be connected
+- ✅ No payload validation (accepts any data)
+
+---
+
+## Message Models
+
+All message models follow the data-model pattern with `Interface` + `Class` + `adapt()` method.
+
+### StateMessage
+
+Used for state synchronization and CRUD operations.
+
+```typescript
+export interface StateMessageInterface {
+  sessionId: { id: string; ldap?: string; name?: string; email?: string };
+  content: any;
+}
+
+export class StateMessage implements StateMessageInterface {
+  constructor(
+    public sessionId: { id: string; ldap?: string; name?: string; email?: string } = { id: '' },
+    public content: any = {}
+  ) {}
+
+  static adapt(item?: any): StateMessage {
+    return new StateMessage(
+      item?.sessionId,
+      item?.content
+    );
+  }
+}
+```
+
+**Usage:**
+
+```typescript
+// With adapt()
+const message = StateMessage.adapt({
+  sessionId: { id: 'user123', name: 'John' },
+  content: { action: 'update', data: { id: 1, name: 'Updated' } }
+});
+
+// With constructor
+const message = new StateMessage(
+  { id: 'user123', name: 'John' },
+  { action: 'delete', id: 1 }
+);
+```
+
+---
+
+### PublicMessage
+
+Used for chat and broadcast messaging.
+
+```typescript
+export interface PublicMessageInterface {
+  sessionId: { id: string; ldap?: string; name?: string; email?: string };
+  content: { message: string; [key: string]: any };
+}
+
+export class PublicMessage implements PublicMessageInterface {
+  constructor(
+    public sessionId: { id: string; ldap?: string; name?: string; email?: string } = { id: '' },
+    public content: { message: string; [key: string]: any } = { message: '' }
+  ) {}
+
+  static adapt(item?: any): PublicMessage {
+    return new PublicMessage(
+      item?.sessionId,
+      item?.content
+    );
+  }
+}
+```
+
+**Usage:**
+
+```typescript
+const message = PublicMessage.adapt({
+  sessionId: { id: 'user123', name: 'John' },
+  content: { 
+    message: 'Hello!',
+    emoji: '👋',
+    replyTo: 42
+  }
+});
+```
+
+---
+
+### NotificationMessage
+
+Used for persistent notifications with history.
+
+```typescript
+export interface NotificationMessageInterface {
+  sessionId: { id: string; ldap?: string; name?: string; email?: string; color?: string };
+  message: string;
+  [key: string]: any;
+}
+
+export class NotificationMessage implements NotificationMessageInterface {
+  sessionId: { id: string; ldap?: string; name?: string; email?: string; color?: string };
+  message: string;
+  [key: string]: any;
+
+  constructor(
+    sessionId: { id: string; ldap?: string; name?: string; email?: string; color?: string } = { id: '' },
+    message: string = '',
+    additionalProperties: any = {}
+  ) {
+    this.sessionId = sessionId;
+    this.message = message;
+    Object.assign(this, additionalProperties);
+  }
+
+  static adapt(item?: any): NotificationMessage {
+    return new NotificationMessage(
+      item?.sessionId,
+      item?.message,
+      item
+    );
+  }
+}
+```
+
+**Usage:**
+
+```typescript
+const notification = NotificationMessage.adapt({
+  sessionId: { id: 'user123', name: 'John', color: '#FF0000' },
+  message: 'System update scheduled',
+  timestamp: Date.now(),
+  link: '/updates/123',
+  icon: 'notification'
+});
+```
+
+---
+
+## ChannelType Enum
+
+The service uses the `ChannelType` enum for prefix management:
+
+```typescript
+export enum ChannelType {
+  STATE = 'SYS',           // System/state channel (CRUD operations)
+  PUBLIC = 'PUB',          // Public messaging (chat/broadcast)
+  NOTIFICATION = 'MES',    // Notification channel (persistent messages)
+  CUSTOM = ''              // No prefix (raw channel name)
+}
+```
+
+**Note:** `ChannelType` is already exported from `request-manager-state-service` to avoid conflicts.
+
+---
+
+## Error Handling
+
+The service uses silent failure with console errors:
+
+### Validation Errors
+
+```typescript
+// Missing sessionId.id
+const message = StateMessage.adapt({
+  sessionId: {},  // ❌ Missing id
+  content: { action: 'create' }
+});
+
+const success = this.wsMessageService.sendStateMessage(['ai', 'tests'], message);
+// Console: ❌ WebSocketMessageService: StateMessage must have sessionId.id
+// Returns: false
+```
+
+### Connection Errors
+
+```typescript
+// WebSocket not connected
+const success = this.wsMessageService.sendPublicMessage('chat', message);
+// Console: ❌ WebSocketMessageService: Cannot send public message - not connected
+// Returns: false
+```
+
+### Success Example
+
+```typescript
+const message = PublicMessage.adapt({
+  sessionId: { id: 'user123' },
+  content: { message: 'Hello!' }
+});
+
+const success = this.wsMessageService.sendPublicMessage('chat', message);
+// Console: (no error)
+// Returns: true
+// Message sent to: PUB-chat
+```
+
+---
+
+## Complete Examples
+
+### Example 1: State Synchronization (CRUD)
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { WebSocketMessageService, StateMessage } from 'http-request-manager';
+
+@Component({
+  selector: 'app-data-sync',
+  template: `<button (click)="createItem()">Create Item</button>`
+})
+export class DataSyncComponent {
+  private wsMessageService = inject(WebSocketMessageService);
+
+  createItem() {
+    const message = StateMessage.adapt({
+      sessionId: { id: 'user123', name: 'John' },
+      content: {
+        action: 'create',
+        data: {
+          name: 'New Product',
+          price: 29.99,
+          category: 'Electronics'
+        }
+      }
+    });
+
+    const success = this.wsMessageService.sendStateMessage(
+      ['products', 'inventory'],
+      message
+    );
+
+    if (success) {
+      console.log('✅ State update sent to SYS-products/inventory');
+    } else {
+      console.warn('❌ Failed to send state update');
+    }
+  }
+}
+```
+
+---
+
+### Example 2: Chat Application
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { WebSocketMessageService, PublicMessage } from 'http-request-manager';
+
+@Component({
+  selector: 'app-chat',
+  template: `
+    <input [(ngModel)]="messageText" placeholder="Type message...">
+    <button (click)="sendMessage()">Send</button>
+  `
+})
+export class ChatComponent {
+  private wsMessageService = inject(WebSocketMessageService);
+  messageText = '';
+
+  sendMessage() {
+    const chatMessage = PublicMessage.adapt({
+      sessionId: { 
+        id: 'user123', 
+        name: 'John',
+        color: '#00FF00'
+      },
+      content: { 
+        message: this.messageText,
+        timestamp: Date.now(),
+        type: 'text'
+      }
+    });
+
+    const success = this.wsMessageService.sendPublicMessage('general', chatMessage);
+    
+    if (success) {
+      this.messageText = '';
+    }
+  }
+}
+```
+
+---
+
+### Example 3: Notification System
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { WebSocketMessageService, NotificationMessage } from 'http-request-manager';
+
+@Component({
+  selector: 'app-notifications',
+  template: `<button (click)="notifyUser()">Notify User</button>`
+})
+export class NotificationsComponent {
+  private wsMessageService = inject(WebSocketMessageService);
+
+  notifyUser() {
+    const notification = NotificationMessage.adapt({
+      sessionId: { 
+        id: 'user123', 
+        name: 'System',
+        color: '#FF0000'
+      },
+      message: 'Your order has been shipped!',
+      orderId: 'ORD-12345',
+      trackingNumber: 'TRACK-67890',
+      link: '/orders/12345',
+      icon: 'shipping',
+      priority: 'high'
+    });
+
+    const success = this.wsMessageService.sendNotification(
+      'user-notifications',
+      notification
+    );
+  }
+}
+```
+
+---
+
+### Example 4: Multi-Channel Messaging
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { 
+  WebSocketMessageService, 
+  StateMessage, 
+  PublicMessage,
+  NotificationMessage 
+} from 'http-request-manager';
+
+@Component({
+  selector: 'app-multi-channel',
+  template: `
+    <button (click)="sendAll()">Send to All Channels</button>
+  `
+})
+export class MultiChannelComponent {
+  private wsMessageService = inject(WebSocketMessageService);
+
+  sendAll() {
+    // Send state update
+    const stateMsg = StateMessage.adapt({
+      sessionId: { id: 'user123' },
+      content: { action: 'update', data: { status: 'online' } }
+    });
+    this.wsMessageService.sendStateMessage(['users', 'status'], stateMsg);
+
+    // Send chat message
+    const chatMsg = PublicMessage.adapt({
+      sessionId: { id: 'user123' },
+      content: { message: 'User is now online!' }
+    });
+    this.wsMessageService.sendPublicMessage('activity', chatMsg);
+
+    // Send notification
+    const notification = NotificationMessage.adapt({
+      sessionId: { id: 'user123' },
+      message: 'Status changed to online'
+    });
+    this.wsMessageService.sendNotification('alerts', notification);
+  }
+}
+```
+
+---
+
+## Comparison with Old Approach
+
+### Before (Multiple Services)
+
+```typescript
+// Inject 3 different services
+private stateService = inject(StateServiceDemo);
+private messageService = inject(MessageServiceDemo);
+private notificationService = inject(NotificationServiceDemo);
+
+// Different patterns for each
+this.stateService.updateConnection(server, wsServer, token, user, ['ai', 'tests']);
+this.stateService.createRecord(data);  // Hidden channel
+
+this.messageService.sendMessage(msg, ['chat']);  // Manual prefix
+
+this.notificationService.sendNotification('alerts', msg);  // Manual prefix
+```
+
+### After (Unified Service)
+
+```typescript
+// Inject 1 service
+private wsMessageService = inject(WebSocketMessageService);
+
+// Consistent pattern for all
+this.wsMessageService.sendStateMessage(['ai', 'tests'], stateMsg);  // Explicit
+this.wsMessageService.sendPublicMessage('chat', chatMsg);  // Explicit
+this.wsMessageService.sendNotification('alerts', notification);  // Explicit
+```
+
+**Benefits:**
+- ✅ Single injection point
+- ✅ Consistent API across all message types
+- ✅ Explicit channel names (no hidden state)
+- ✅ Type-safe message models
+- ✅ Automatic prefix management
+
+---
+
+## Best Practices
+
+### 1. Always Use `adapt()` Method
+
+```typescript
+// ✅ Correct
+const message = StateMessage.adapt({
+  sessionId: { id: 'user123' },
+  content: { action: 'create' }
+});
+
+// ❌ Avoid
+const message = new StateMessage({ id: 'user123' }, { action: 'create' });
+```
+
+### 2. Check Return Value
+
+```typescript
+const success = this.wsMessageService.sendPublicMessage('chat', message);
+
+if (!success) {
+  // Handle failure (log, retry, notify user, etc.)
+  console.warn('Message not sent - WebSocket may be disconnected');
+}
+```
+
+### 3. Include Session ID
+
+Always provide at least `sessionId.id`:
+
+```typescript
+// ✅ Minimum required
+StateMessage.adapt({
+  sessionId: { id: 'user123' },
+  content: { ... }
+});
+
+// ❌ Will fail validation
+StateMessage.adapt({
+  sessionId: {},  // Missing id
+  content: { ... }
+});
+```
+
+### 4. Use Meaningful Paths/Channels
+
+```typescript
+// ✅ Clear and descriptive
+sendStateMessage(['products', 'inventory'], message);
+sendPublicMessage('customer-support', message);
+sendNotification('order-updates', message);
+
+// ❌ Vague
+sendStateMessage(['data'], message);
+sendPublicMessage('channel1', message);
+```
+
+### 5. Extend NotificationMessage with Custom Properties
+
+```typescript
+const notification = NotificationMessage.adapt({
+  sessionId: { id: 'user123' },
+  message: 'Order shipped',
+  // Custom properties
+  orderId: 'ORD-123',
+  trackingNumber: 'TRACK-456',
+  estimatedDelivery: '2026-04-05',
+  carrier: 'FedEx'
+});
+```
+
+---
+
+## Troubleshooting
+
+### Message Not Sending
+
+**Problem:** `sendStateMessage()` returns `false`
+
+**Solution:**
+1. Check console for error messages
+2. Verify WebSocket is connected: `WebSocketManagerService.isConnected()`
+3. Ensure `sessionId.id` is provided
+4. Check path is not empty: `['ai', 'tests']` not `[]`
+
+### Wrong Channel Received
+
+**Problem:** Messages appearing on unexpected channels
+
+**Solution:**
+1. Verify channel name construction
+2. Check prefix is correct (SYS-, PUB-, MES-)
+3. Ensure no typos in path/channel names
+
+### TypeScript Errors
+
+**Problem:** Type errors when creating messages
+
+**Solution:**
+1. Use `adapt()` method for automatic type inference
+2. Ensure `sessionId` object has required properties
+3. For `PublicMessage`, ensure `content.message` is a string
+4. For `NotificationMessage`, ensure `message` is a string
+
+---
+
+## Related Documentation
+
+- [WebSocket Manager Service](./WS_MANAGER_README.md) - Underlying WebSocket connection management
+- [Advanced WebSocket Guide](./ADVANCED_WEBSOCKET.md) - Channel architecture, presence tracking, message replay
+- [ChannelMessage Model](./MODELS_README.md#channelmessage) - Base message structure
+- [Complete API Reference](./COMPLETE_API_REFERENCE.md) - Full library API documentation
+
+---
+
+## Migration Guide
+
+### From MessageServiceDemo
+
+**Before:**
+
+```typescript
+private messageService = inject(MessageServiceDemo);
+
+this.messageService.sendMessage(
+  ChannelMessage.adapt({
+    sessionId: { id: 'user123' },
+    content: { message: 'Hello' }
+  }),
+  ['chat']
+);
+```
+
+**After:**
+
+```typescript
+private wsMessageService = inject(WebSocketMessageService);
+
+this.wsMessageService.sendPublicMessage(
+  'chat',
+  PublicMessage.adapt({
+    sessionId: { id: 'user123' },
+    content: { message: 'Hello' }
+  })
+);
+```
+
+### From NotificationServiceDemo
+
+**Before:**
+
+```typescript
+private notificationService = inject(NotificationServiceDemo);
+
+this.notificationService.sendNotification('alerts', {
+  sessionId: { id: 'user123' },
+  message: 'New notification'
+});
+```
+
+**After:**
+
+```typescript
+private wsMessageService = inject(WebSocketMessageService);
+
+this.wsMessageService.sendNotification(
+  'alerts',
+  NotificationMessage.adapt({
+    sessionId: { id: 'user123' },
+    message: 'New notification'
+  })
+);
+```
+
+---
+
+## Summary
+
+The `WebSocketMessageService` provides a unified, type-safe approach to WebSocket messaging with:
+
+- ✅ **Three message types** - State (SYS-), Public (PUB-), Notification (MES-)
+- ✅ **Automatic prefixes** - No manual string concatenation
+- ✅ **Type safety** - Compile-time validation of message structures
+- ✅ **Runtime validation** - Checks required fields before sending
+- ✅ **Simple API** - Boolean return values for success/failure
+- ✅ **Silent failure** - Console errors without exceptions
+- ✅ **Backward compatible** - Existing services continue to work
+
+For more information, see the [WebSocket Manager Service documentation](./WS_MANAGER_README.md) or the [Advanced WebSocket Guide](./ADVANCED_WEBSOCKET.md).