@futdevpro/nts-dynamo 1.14.23 → 1.14.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/nts-dynamo",
-  "version": "01.14.23",
+  "version": "01.14.24",
   "description": "Dynamic NodeTS (NodeJS-Typescript), MongoDB Backend System Framework by Future Development Program Ltd.",
   "DyBu_settings": {
     "packageType": "server-package",
@@ -68,6 +68,13 @@
       "typings": "./build/_modules/ai/_modules/open-ai/index.d.ts"
     },
 
+    "./assistant": {
+      "default": "./build/_modules/assistant/index.js",
+      "module": "./build/_modules/assistant/index.js",
+      "types": "./build/_modules/assistant/index.d.ts",
+      "typings": "./build/_modules/assistant/index.d.ts"
+    },
+
     "./bot": {
       "default": "./build/_modules/bot/index.js",
       "module": "./build/_modules/bot/index.js",
@@ -188,6 +195,10 @@
         "build/_modules/ai/_modules/open-ai/index.d.ts"
       ],
 
+      "assistant": [
+        "build/_modules/assistant/index.d.ts"
+      ],
+
       "bot": [
         "build/_modules/bot/index.d.ts"
       ],

package/src/_modules/messaging/README.md

@@ -0,0 +1,359 @@
+# 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_Message<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,
+    integration: {
+      syncBotMessages: true,
+      syncAssistantMessages: true,
+      enableAgentProcessViz: 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_Message } 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)