# 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)