@futdevpro/nts-dynamo 1.15.56 → 1.15.58

package/src/_modules/messaging/README.md

@@ -1,354 +1,354 @@
-# Dynamo NTS Messaging Module [DyNTS-MSG]
-
-TODO: The Entire Messaging system is AI generated, therefore we need to clean it up, and remove the unnecessary elements
-
-## Overview
-
-The DyNTS Messaging module provides the **backend implementation** for the unified messaging system. It handles all server-side operations including data persistence, business logic, real-time events, and API endpoints. The module integrates with bot and assistant modules to provide AI-powered messaging capabilities.
-
-## Import
-
-```typescript
-import * from '@futdevpro/dynamo-nts/messaging';
-```
-
-## Key Features
-
-- **Data Services**: CRUD operations for messages and conversations
-- **Control Services**: Business logic orchestration and validation
-- **Event Handling**: Real-time socket communication
-- **API Endpoints**: RESTful HTTP endpoints for all messaging operations
-- **Bot Integration**: Seamless integration with AI bot modules
-- **Assistant Integration**: Support for AI assistant workflows
-- **Authentication**: User authentication and authorization
-- **Error Handling**: Comprehensive error handling and logging
-- **Real-time Events**: Socket-based live updates
-- **Agent Process Tracking**: AI reasoning and tool usage recording
-
-## Architecture
-
-The messaging module follows a layered architecture:
-
-```
-┌─────────────────────────────────────┐
-│     HTTP Controller (API)          │
-└────────────────┬──────────────────┘
-                 │
-┌────────────────▼──────────────────┐
-│     Control Services             │
-│  • Main Control                  │
-│  • Integration Control           │
-│  • Events Service                │
-└────────────────┬──────────────────┘
-                 │
-┌────────────────▼──────────────────┐
-│     Data Services                │
-│  • Message Data Service          │
-│  • Conversation Data Service     │
-└────────────────┬──────────────────┘
-                 │
-┌────────────────▼──────────────────┐
-│     Database Layer               │
-└─────────────────────────────────┘
-```
-
-## Services
-
-### Data Services
-
-#### `DyNTS_Msg_Message_DataService`
-
-Handles all message data operations:
-
-```typescript
-class DyNTS_Msg_Message_DataService {
-  async saveData(message: DyFM_Msg_Message): Promise<void>;
-  async getDataById(messageId: string): Promise<DyFM_Msg_Message>;
-  async markAsRead(messageId: string, userId: string): Promise<void>;
-  async deleteData(messageId: string): Promise<void>;
-}
-```
-
-**Usage Example:**
-```typescript
-const messageService = new DyNTS_Msg_Message_DataService({
-  issuer: 'user-id',
-});
-
-const message = await messageService.getDataById('msg-123');
-await messageService.markAsRead('msg-123', 'user-id');
-```
-
-#### `DyNTS_Msg_Conversation_DataService`
-
-Handles all conversation data operations:
-
-```typescript
-class DyNTS_Msg_Conversation_DataService {
-  async saveData(conversation: DyFM_Msg_Conversation): Promise<void>;
-  async getDataById(conversationId: string): Promise<DyFM_Msg_Conversation>;
-  async updateLastMessage(conversationId: string, messageId: string, content: string): Promise<void>;
-  async addParticipant(conversationId: string, participant: DyFM_Msg_Participant): Promise<void>;
-  async removeParticipant(conversationId: string, userId: string): Promise<void>;
-}
-```
-
-### Control Services
-
-#### `DyNTS_Msg_Main_ControlService`
-
-Singleton service for orchestration and business logic:
-
-```typescript
-class DyNTS_Msg_Main_ControlService extends DyNTS_SingletonService {
-  static getInstance(): DyNTS_Msg_Main_ControlService;
-  
-  // Messages
-  async sendMessage(conversationId: string, messageData: Partial<DyFM_Msg_Message>, senderId: string, issuer: string): Promise<DyFM_Msg_Message>;
-  async editMessage(messageId: string, content: string, userId: string, issuer: string): Promise<DyFM_Msg_Message>;
-  async deleteMessage(messageId: string, userId: string, issuer: string): Promise<void>;
-  async markMessagesAsRead(messageIds: string[], userId: string, issuer: string): Promise<{ success: boolean; count: number }>;
-  
-  // Reactions
-  async addReaction(messageId: string, emoji: string, userId: string, issuer: string): Promise<DyFM_Msg_Message>;
-  async removeReaction(messageId: string, emoji: string, userId: string, issuer: string): Promise<DyFM_Msg_Message>;
-  
-  // Conversations
-  async createConversation(conversationData: Partial<DyFM_Msg_Conversation>, creatorId: string, issuer: string): Promise<DyFM_Msg_Conversation>;
-  async updateConversation(conversationId: string, updateData: Partial<DyFM_Msg_Conversation>, userId: string, issuer: string): Promise<DyFM_Msg_Conversation>;
-  async deleteConversation(conversationId: string, userId: string, issuer: string): Promise<void>;
-  
-  // Participants
-  async addParticipant(conversationId: string, newUserId: string, role: DyFM_Msg_ParticipantRole, requesterId: string, issuer: string): Promise<void>;
-  async removeParticipant(conversationId: string, userIdToRemove: string, requesterId: string, issuer: string): Promise<void>;
-}
-```
-
-**Usage Example:**
-```typescript
-const controlService = DyNTS_Msg_Main_ControlService.getInstance();
-
-// Send a message
-const message = await controlService.sendMessage(
-  'conv-123',
-  { content: 'Hello!' },
-  'user-456',
-  'user-456'
-);
-
-// Add reaction
-await controlService.addReaction(
-  'msg-789',
-  '👍',
-  'user-456',
-  'user-456'
-);
-```
-
-#### `DyNTS_Msg_Integration_ControlService`
-
-Handles integration with bot and assistant modules:
-
-```typescript
-class DyNTS_Msg_Integration_ControlService extends DyNTS_SingletonService {
-  static getInstance(): DyNTS_Msg_Integration_ControlService;
-  
-  // Bot integration
-  async syncBotMessage<T>(botMessage: DyNTS_Bot_MessageWrapper<T>, conversationId: string, issuer: string): Promise<DyFM_Msg_Message>;
-  
-  // Assistant integration
-  async syncAssistantMessage(content: string, conversationId: string, aiProvider: string, aiModel: string, senderId: string, issuer: string): Promise<DyFM_Msg_Message>;
-  
-  // Find or create bot conversation
-  async findOrCreateBotConversation(channelId: string, platformSource: string, issuer: string): Promise<DyFM_Msg_Conversation>;
-}
-```
-
-#### `DyNTS_Msg_Events_Service`
-
-Handles real-time socket events:
-
-```typescript
-class DyNTS_Msg_Events_Service extends DyNTS_SingletonService {
-  static getInstance(): DyNTS_Msg_Events_Service;
-  
-  // Event emission
-  emitMessageSent(message: DyFM_Msg_Message, conversationId: string): void;
-  emitMessageUpdated(message: DyFM_Msg_Message, conversationId: string): void;
-  emitMessageDeleted(messageId: string, conversationId: string): void;
-  emitMessageRead(messageId: string, userId: string, conversationId: string): void;
-  emitTypingIndicator(userId: string, conversationId: string, isTyping: boolean): void;
-  emitConversationCreated(conversation: DyFM_Msg_Conversation, participantIds: string[]): void;
-  emitConversationUpdated(conversation: DyFM_Msg_Conversation): void;
-  emitConversationDeleted(conversationId: string): void;
-  emitParticipantAdded(conversationId: string, userId: string): void;
-  emitParticipantRemoved(conversationId: string, userId: string): void;
-  emitReactionAdded(messageId: string, reaction: DyFM_Msg_Reaction): void;
-  emitReactionRemoved(messageId: string, userId: string, emoji: string): void;
-}
-```
-
-### Controllers
-
-#### `DyNTS_Msg_Controller`
-
-HTTP API controller for messaging endpoints:
-
-**Endpoints:**
-- `POST /api/messaging/messages` - Send a message
-- `PUT /api/messaging/messages/:id` - Edit a message
-- `DELETE /api/messaging/messages/:id` - Delete a message
-- `POST /api/messaging/messages/:id/read` - Mark messages as read
-- `POST /api/messaging/messages/:id/reactions` - Add reaction
-- `DELETE /api/messaging/messages/:id/reactions` - Remove reaction
-- `GET /api/messaging/conversations` - Get conversations
-- `POST /api/messaging/conversations` - Create conversation
-- `PUT /api/messaging/conversations/:id` - Update conversation
-- `DELETE /api/messaging/conversations/:id` - Delete conversation
-- `POST /api/messaging/conversations/:id/participants` - Add participant
-- `DELETE /api/messaging/conversations/:id/participants/:userId` - Remove participant
-
-## Configuration
-
-### Global Settings
-
-Configure messaging settings in your global configuration:
-
-```typescript
-export const DyNTS_global_settings = {
-  messaging_settings: {
-    enableRealtimeEvents: true,
-    maxMessagesPerLoad: 50,
-    enableThreading: true,
-    enableReactions: true,
-    enableAttachments: true,
-    enableMentions: true,
-    enableReadReceipts: true,
-    enableTypingIndicators: true,
-    retry: {
-      maxRetries: 3,
-      retryDelay: 1000
-    }
-  }
-};
-```
-
-## Routing
-
-Add the messaging routing module to your application:
-
-```typescript
-import { DyNTS_getMessagingRoutingModule } from '@futdevpro/dynamo-nts/messaging';
-
-const messagingRoutes = DyNTS_getMessagingRoutingModule(
-  DyNTS_RouteSecurity.authenticated
-);
-
-// Add to your routing configuration
-```
-
-## Integration
-
-### Bot Integration
-
-The messaging system integrates with the bot module to sync messages:
-
-```typescript
-import { DyNTS_Msg_Integration_ControlService } from '@futdevpro/dynamo-nts/messaging';
-import { DyNTS_Bot_MessageWrapper } from '@futdevpro/dynamo-nts/bot';
-
-const integrationService = DyNTS_Msg_Integration_ControlService.getInstance();
-
-// Sync bot message to messaging system
-const message = await integrationService.syncBotMessage(
-  botMessage,
-  conversationId,
-  'bot-service'
-);
-```
-
-### Assistant Integration
-
-Sync AI assistant responses:
-
-```typescript
-// Sync AI assistant message
-const aiMessage = await integrationService.syncAssistantMessage(
-  'AI response text',
-  'conv-123',
-  'openai',
-  'gpt-4',
-  'ai-assistant-id',
-  'ai-service'
-);
-```
-
-## Usage Examples
-
-### Sending a Message
-
-```typescript
-import { DyNTS_Msg_Main_ControlService } from '@futdevpro/dynamo-nts/messaging';
-
-const controlService = DyNTS_Msg_Main_ControlService.getInstance();
-
-const message = await controlService.sendMessage(
-  'conv-123',
-  {
-    content: 'Hello from the backend!',
-    type: DyFM_Msg_Type.text
-  },
-  'user-456',
-  'backend-service'
-);
-```
-
-### Creating a Conversation
-
-```typescript
-const conversation = await controlService.createConversation(
-  {
-    type: DyFM_Msg_ConversationType.direct,
-    participants: [
-      { userId: 'user-123', role: DyFM_Msg_ParticipantRole.member, joinedAt: new Date() },
-      { userId: 'user-456', role: DyFM_Msg_ParticipantRole.member, joinedAt: new Date() }
-    ]
-  },
-  'user-123',
-  'backend-service'
-);
-```
-
-### Adding a Reaction
-
-```typescript
-const message = await controlService.addReaction(
-  'msg-123',
-  '👍',
-  'user-456',
-  'user-456'
-);
-```
-
-## Error Handling
-
-The module uses comprehensive error handling:
-
-```typescript
-try {
-  await controlService.sendMessage(...);
-} catch (error) {
-  if (error instanceof DyFM_Error) {
-    console.error('Error code:', error.errorCode);
-    console.error('User message:', error.userMessage);
-    console.error('Technical message:', error.technicalMessage);
-  }
-}
-```
-
-## Related Documentation
-
-- [Dynamo FSM Messaging Module](../dynamo-fsm/messaging/README.md)
-- [Dynamo NGX Messaging Module](../dynamo-ngx/messaging/README.md)
-- [Bot Module Integration](./bot/README.md)
-- [Assistant Module Integration](./assistant/README.md)
+# Dynamo NTS Messaging Module [DyNTS-MSG]
+
+TODO: The Entire Messaging system is AI generated, therefore we need to clean it up, and remove the unnecessary elements
+
+## Overview
+
+The DyNTS Messaging module provides the **backend implementation** for the unified messaging system. It handles all server-side operations including data persistence, business logic, real-time events, and API endpoints. The module integrates with bot and assistant modules to provide AI-powered messaging capabilities.
+
+## Import
+
+```typescript
+import * from '@futdevpro/dynamo-nts/messaging';
+```
+
+## Key Features
+
+- **Data Services**: CRUD operations for messages and conversations
+- **Control Services**: Business logic orchestration and validation
+- **Event Handling**: Real-time socket communication
+- **API Endpoints**: RESTful HTTP endpoints for all messaging operations
+- **Bot Integration**: Seamless integration with AI bot modules
+- **Assistant Integration**: Support for AI assistant workflows
+- **Authentication**: User authentication and authorization
+- **Error Handling**: Comprehensive error handling and logging
+- **Real-time Events**: Socket-based live updates
+- **Agent Process Tracking**: AI reasoning and tool usage recording
+
+## Architecture
+
+The messaging module follows a layered architecture:
+
+```
+┌─────────────────────────────────────┐
+│     HTTP Controller (API)          │
+└────────────────┬──────────────────┘
+                 │
+┌────────────────▼──────────────────┐
+│     Control Services             │
+│  • Main Control                  │
+│  • Integration Control           │
+│  • Events Service                │
+└────────────────┬──────────────────┘
+                 │
+┌────────────────▼──────────────────┐
+│     Data Services                │
+│  • Message Data Service          │
+│  • Conversation Data Service     │
+└────────────────┬──────────────────┘
+                 │
+┌────────────────▼──────────────────┐
+│     Database Layer               │
+└─────────────────────────────────┘
+```
+
+## Services
+
+### Data Services
+
+#### `DyNTS_Msg_Message_DataService`
+
+Handles all message data operations:
+
+```typescript
+class DyNTS_Msg_Message_DataService {
+  async saveData(message: DyFM_Msg_Message): Promise<void>;
+  async getDataById(messageId: string): Promise<DyFM_Msg_Message>;
+  async markAsRead(messageId: string, userId: string): Promise<void>;
+  async deleteData(messageId: string): Promise<void>;
+}
+```
+
+**Usage Example:**
+```typescript
+const messageService = new DyNTS_Msg_Message_DataService({
+  issuer: 'user-id',
+});
+
+const message = await messageService.getDataById('msg-123');
+await messageService.markAsRead('msg-123', 'user-id');
+```
+
+#### `DyNTS_Msg_Conversation_DataService`
+
+Handles all conversation data operations:
+
+```typescript
+class DyNTS_Msg_Conversation_DataService {
+  async saveData(conversation: DyFM_Msg_Conversation): Promise<void>;
+  async getDataById(conversationId: string): Promise<DyFM_Msg_Conversation>;
+  async updateLastMessage(conversationId: string, messageId: string, content: string): Promise<void>;
+  async addParticipant(conversationId: string, participant: DyFM_Msg_Participant): Promise<void>;
+  async removeParticipant(conversationId: string, userId: string): Promise<void>;
+}
+```
+
+### Control Services
+
+#### `DyNTS_Msg_Main_ControlService`
+
+Singleton service for orchestration and business logic:
+
+```typescript
+class DyNTS_Msg_Main_ControlService extends DyNTS_SingletonService {
+  static getInstance(): DyNTS_Msg_Main_ControlService;
+  
+  // Messages
+  async sendMessage(conversationId: string, messageData: Partial<DyFM_Msg_Message>, senderId: string, issuer: string): Promise<DyFM_Msg_Message>;
+  async editMessage(messageId: string, content: string, userId: string, issuer: string): Promise<DyFM_Msg_Message>;
+  async deleteMessage(messageId: string, userId: string, issuer: string): Promise<void>;
+  async markMessagesAsRead(messageIds: string[], userId: string, issuer: string): Promise<{ success: boolean; count: number }>;
+  
+  // Reactions
+  async addReaction(messageId: string, emoji: string, userId: string, issuer: string): Promise<DyFM_Msg_Message>;
+  async removeReaction(messageId: string, emoji: string, userId: string, issuer: string): Promise<DyFM_Msg_Message>;
+  
+  // Conversations
+  async createConversation(conversationData: Partial<DyFM_Msg_Conversation>, creatorId: string, issuer: string): Promise<DyFM_Msg_Conversation>;
+  async updateConversation(conversationId: string, updateData: Partial<DyFM_Msg_Conversation>, userId: string, issuer: string): Promise<DyFM_Msg_Conversation>;
+  async deleteConversation(conversationId: string, userId: string, issuer: string): Promise<void>;
+  
+  // Participants
+  async addParticipant(conversationId: string, newUserId: string, role: DyFM_Msg_ParticipantRole, requesterId: string, issuer: string): Promise<void>;
+  async removeParticipant(conversationId: string, userIdToRemove: string, requesterId: string, issuer: string): Promise<void>;
+}
+```
+
+**Usage Example:**
+```typescript
+const controlService = DyNTS_Msg_Main_ControlService.getInstance();
+
+// Send a message
+const message = await controlService.sendMessage(
+  'conv-123',
+  { content: 'Hello!' },
+  'user-456',
+  'user-456'
+);
+
+// Add reaction
+await controlService.addReaction(
+  'msg-789',
+  '👍',
+  'user-456',
+  'user-456'
+);
+```
+
+#### `DyNTS_Msg_Integration_ControlService`
+
+Handles integration with bot and assistant modules:
+
+```typescript
+class DyNTS_Msg_Integration_ControlService extends DyNTS_SingletonService {
+  static getInstance(): DyNTS_Msg_Integration_ControlService;
+  
+  // Bot integration
+  async syncBotMessage<T>(botMessage: DyNTS_Bot_MessageWrapper<T>, conversationId: string, issuer: string): Promise<DyFM_Msg_Message>;
+  
+  // Assistant integration
+  async syncAssistantMessage(content: string, conversationId: string, aiProvider: string, aiModel: string, senderId: string, issuer: string): Promise<DyFM_Msg_Message>;
+  
+  // Find or create bot conversation
+  async findOrCreateBotConversation(channelId: string, platformSource: string, issuer: string): Promise<DyFM_Msg_Conversation>;
+}
+```
+
+#### `DyNTS_Msg_Events_Service`
+
+Handles real-time socket events:
+
+```typescript
+class DyNTS_Msg_Events_Service extends DyNTS_SingletonService {
+  static getInstance(): DyNTS_Msg_Events_Service;
+  
+  // Event emission
+  emitMessageSent(message: DyFM_Msg_Message, conversationId: string): void;
+  emitMessageUpdated(message: DyFM_Msg_Message, conversationId: string): void;
+  emitMessageDeleted(messageId: string, conversationId: string): void;
+  emitMessageRead(messageId: string, userId: string, conversationId: string): void;
+  emitTypingIndicator(userId: string, conversationId: string, isTyping: boolean): void;
+  emitConversationCreated(conversation: DyFM_Msg_Conversation, participantIds: string[]): void;
+  emitConversationUpdated(conversation: DyFM_Msg_Conversation): void;
+  emitConversationDeleted(conversationId: string): void;
+  emitParticipantAdded(conversationId: string, userId: string): void;
+  emitParticipantRemoved(conversationId: string, userId: string): void;
+  emitReactionAdded(messageId: string, reaction: DyFM_Msg_Reaction): void;
+  emitReactionRemoved(messageId: string, userId: string, emoji: string): void;
+}
+```
+
+### Controllers
+
+#### `DyNTS_Msg_Controller`
+
+HTTP API controller for messaging endpoints:
+
+**Endpoints:**
+- `POST /api/messaging/messages` - Send a message
+- `PUT /api/messaging/messages/:id` - Edit a message
+- `DELETE /api/messaging/messages/:id` - Delete a message
+- `POST /api/messaging/messages/:id/read` - Mark messages as read
+- `POST /api/messaging/messages/:id/reactions` - Add reaction
+- `DELETE /api/messaging/messages/:id/reactions` - Remove reaction
+- `GET /api/messaging/conversations` - Get conversations
+- `POST /api/messaging/conversations` - Create conversation
+- `PUT /api/messaging/conversations/:id` - Update conversation
+- `DELETE /api/messaging/conversations/:id` - Delete conversation
+- `POST /api/messaging/conversations/:id/participants` - Add participant
+- `DELETE /api/messaging/conversations/:id/participants/:userId` - Remove participant
+
+## Configuration
+
+### Global Settings
+
+Configure messaging settings in your global configuration:
+
+```typescript
+export const DyNTS_global_settings = {
+  messaging_settings: {
+    enableRealtimeEvents: true,
+    maxMessagesPerLoad: 50,
+    enableThreading: true,
+    enableReactions: true,
+    enableAttachments: true,
+    enableMentions: true,
+    enableReadReceipts: true,
+    enableTypingIndicators: true,
+    retry: {
+      maxRetries: 3,
+      retryDelay: 1000
+    }
+  }
+};
+```
+
+## Routing
+
+Add the messaging routing module to your application:
+
+```typescript
+import { DyNTS_getMessagingRoutingModule } from '@futdevpro/dynamo-nts/messaging';
+
+const messagingRoutes = DyNTS_getMessagingRoutingModule(
+  DyNTS_RouteSecurity.authenticated
+);
+
+// Add to your routing configuration
+```
+
+## Integration
+
+### Bot Integration
+
+The messaging system integrates with the bot module to sync messages:
+
+```typescript
+import { DyNTS_Msg_Integration_ControlService } from '@futdevpro/dynamo-nts/messaging';
+import { DyNTS_Bot_MessageWrapper } from '@futdevpro/dynamo-nts/bot';
+
+const integrationService = DyNTS_Msg_Integration_ControlService.getInstance();
+
+// Sync bot message to messaging system
+const message = await integrationService.syncBotMessage(
+  botMessage,
+  conversationId,
+  'bot-service'
+);
+```
+
+### Assistant Integration
+
+Sync AI assistant responses:
+
+```typescript
+// Sync AI assistant message
+const aiMessage = await integrationService.syncAssistantMessage(
+  'AI response text',
+  'conv-123',
+  'openai',
+  'gpt-4',
+  'ai-assistant-id',
+  'ai-service'
+);
+```
+
+## Usage Examples
+
+### Sending a Message
+
+```typescript
+import { DyNTS_Msg_Main_ControlService } from '@futdevpro/dynamo-nts/messaging';
+
+const controlService = DyNTS_Msg_Main_ControlService.getInstance();
+
+const message = await controlService.sendMessage(
+  'conv-123',
+  {
+    content: 'Hello from the backend!',
+    type: DyFM_Msg_Type.text
+  },
+  'user-456',
+  'backend-service'
+);
+```
+
+### Creating a Conversation
+
+```typescript
+const conversation = await controlService.createConversation(
+  {
+    type: DyFM_Msg_ConversationType.direct,
+    participants: [
+      { userId: 'user-123', role: DyFM_Msg_ParticipantRole.member, joinedAt: new Date() },
+      { userId: 'user-456', role: DyFM_Msg_ParticipantRole.member, joinedAt: new Date() }
+    ]
+  },
+  'user-123',
+  'backend-service'
+);
+```
+
+### Adding a Reaction
+
+```typescript
+const message = await controlService.addReaction(
+  'msg-123',
+  '👍',
+  'user-456',
+  'user-456'
+);
+```
+
+## Error Handling
+
+The module uses comprehensive error handling:
+
+```typescript
+try {
+  await controlService.sendMessage(...);
+} catch (error) {
+  if (error instanceof DyFM_Error) {
+    console.error('Error code:', error.errorCode);
+    console.error('User message:', error.userMessage);
+    console.error('Technical message:', error.technicalMessage);
+  }
+}
+```
+
+## Related Documentation
+
+- [Dynamo FSM Messaging Module](../dynamo-fsm/messaging/README.md)
+- [Dynamo NGX Messaging Module](../dynamo-ngx/messaging/README.md)
+- [Bot Module Integration](./bot/README.md)
+- [Assistant Module Integration](./assistant/README.md)