http-request-manager 18.15.34 → 18.16.1

package/src/docs/WEBSOCKET_MESSAGE_SERVICE.md

@@ -1,799 +0,0 @@
-# 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).