wexa-chat 0.2.9 → 0.3.0

package/README.md

@@ -125,6 +125,9 @@ export type InitOptions = {
   - `listMessages({ organizationId, conversationId, limit?, cursor? })`
   - `listMessagesWithSenders({ organizationId, conversationId, limit?, cursor?, populateSenders: true, populateOptions? })`
   - `markRead({ organizationId, conversationId, participantModel, participantId, messageId })`
+  - `receiveWhatsappMessage({ whatsappChatId, message })`
+  - `receiveLinkedinMessage({ linkedinChatId, message })`
+  - `receiveEmailMessage({ emailChatId, message })`
 
 DTO types live in `src/types/dto.ts`.
 
@@ -226,7 +229,90 @@ export type SourceType = (typeof sourceType)[keyof typeof sourceType];
 
 When sending a message via `sendMessage`, you must provide `source: SourceType[]`. For internal server‑generated messages, use `[sourceType.CORE]`.
 
-If you include external connectors in the `source` (e.g., `linkedin`, `whatsapp`), you can optionally pass `connectorIds` to perform the external send and to persist identifiers for quick follow‑ups:
+If you include external connectors in the `source` (e.g., `linkedin`, `whatsapp`, `email`), you can optionally pass `connectorIds` to perform the external send and to persist identifiers for quick follow‑ups.
+
+#### Email with Rich Metadata
+
+Email supports advanced features like subject lines, CC/BCC, attachments, and tracking:
+
+```ts
+// Simple email
+await chat.services.messages.sendMessage({
+  organizationId: 'org-123',
+  conversationId: 'conv-456',
+  senderModel: 'User',
+  senderId: 'user-1',
+  text: 'Hi John,\n\nInterested in discussing a role?\n\nBest,\nJane',
+  source: [sourceType.EMAIL],
+  connectorIds: {
+    email: { connectorId: 'em-connector-1', contactId: 'john@candidate.com' },
+  },
+  metadata: {
+    email: {
+      subject: 'Job Opportunity at TechCorp',
+      recipientName: 'John Doe',
+    }
+  }
+});
+
+// Full-featured email with all options
+await chat.services.messages.sendMessage({
+  organizationId: 'org-123',
+  conversationId: 'conv-456',
+  senderModel: 'User',
+  senderId: 'user-1',
+  text: 'Dear John,\n\nWe are looking for a Senior Software Engineer...',
+  source: [sourceType.EMAIL],
+  connectorIds: {
+    email: { connectorId: 'em-connector-1', contactId: 'john@candidate.com' },
+  },
+  metadata: {
+    email: {
+      subject: 'Senior Software Engineer Position - TechCorp',
+      recipientName: 'John Doe',
+      cc: [
+        { display_name: 'HR Manager', identifier: 'hr@techcorp.com' }
+      ],
+      bcc: [
+        { display_name: 'Recruiting Lead', identifier: 'lead@techcorp.com' }
+      ],
+      attachments: [
+        'https://storage.company.com/job-description.pdf',
+        'https://storage.company.com/company-overview.pdf'
+      ],
+      tracking: {
+        opens: true,
+        links: true,
+        label: 'q1_2024_recruitment'
+      }
+    }
+  }
+});
+
+// Email reply (threading)
+await chat.services.messages.sendMessage({
+  organizationId: 'org-123',
+  conversationId: 'conv-456',
+  senderModel: 'User',
+  senderId: 'user-1',
+  text: 'Hi John,\n\nThank you for your response!...',
+  source: [sourceType.EMAIL],
+  connectorIds: {
+    email: { connectorId: 'em-connector-1', contactId: 'john@candidate.com' },
+  },
+  metadata: {
+    email: {
+      subject: 'Re: Senior Software Engineer Position',
+      recipientName: 'John Doe',
+      replyTo: 'email_provider_id_abc123xyz'  // From previous email
+    }
+  },
+  parentMessageId: 'msg-previous-id',
+  rootThreadId: 'msg-root-id'
+});
+```
+
+#### Multi-Platform Messages
 
 ```ts
 await chat.services.messages.sendMessage({
@@ -245,14 +331,93 @@ await chat.services.messages.sendMessage({
 
 Under the hood (`src/services/messages.service.ts`):
 
-- LinkedIn: posts to the LinkedIn connector with `{ linkedin_url, text }`.
-- WhatsApp: posts to the WhatsApp connector with `{ phone_numbers, text }` (phone is sanitized to remove spaces and a leading `+`).
+- **LinkedIn**: posts to the LinkedIn connector with `{ linkedin_url, text }`.
+- **WhatsApp**: posts to the WhatsApp connector with `{ phone_numbers, text }` (phone is sanitized to remove spaces and a leading `+`).
+- **Email**: posts to `/mail/send_email/:connectorId` with complete payload including `to` (array of recipients with display_name and identifier), `body`, `subject`, `cc`, `bcc`, `attachments` (URLs), `reply_to` (for threading), and `tracking_options`.
 - Each external task runs concurrently. A successful task's `source` remains in the stored message. Failures are collected into a `failed_source` array attached to the returned message instance at runtime: `message.failed_source: Array<{ source: string; message: string }>`.
 - The conversation document is updated with last message metadata and, when applicable, with connector identifiers:
   - `lastLinkedInId: string` — set from `connectorIds.linkedin.contactId` when `source` includes `linkedin`.
   - `lastWhatsAppId: string` — set from a sanitized `connectorIds.whatsapp.contactId` when `source` includes `whatsapp`.
+  - `lastEmailId: string` — set from `connectorIds.email.contactId` when `source` includes `email`.
+- Message metadata (subjects, CC/BCC, attachments, tracking info) is stored in the `metadata.email` field for reference and UI rendering.
+
+This allows subsequent UI actions to prefill the last known contact handles for LinkedIn, WhatsApp, and Email.
+
+### Receiving inbound connector messages
+
+When an external connector delivers a new inbound message, you can persist it directly using the chat ID stored on the conversation.
+
+**Important: Deduplication** - All receive methods support automatic deduplication via `messageId`. If a message with the same `messageId` already exists in the conversation, the existing message is returned instead of creating a duplicate. This prevents duplicate messages from webhooks that retry or are delivered multiple times.
+
+#### WhatsApp Messages
+
+```ts
+await chat.services.messages.receiveWhatsappMessage({
+  whatsappChatId: 'wa-chat-123',
+  message: 'Hello from WhatsApp',
+  messageId: 'wamid.HBgNMTIzNDU2Nzg5...',  // For deduplication
+  senderName: 'John Doe',  // Optional
+});
+```
+
+#### LinkedIn Messages
+
+```ts
+await chat.services.messages.receiveLinkedinMessage({
+  linkedinChatId: 'li-chat-456',
+  message: 'Hello from LinkedIn',
+  messageId: 'msg-abc123',  // For deduplication
+  senderName: 'Jane Smith',  // Optional
+  senderProfileUrl: 'https://linkedin.com/in/janesmith',  // Optional
+});
+```
+
+#### Email with Full Metadata
+
+Email receives support enhanced metadata including subject, sender info, and threading:
+
+```ts
+// Simple email reply
+await chat.services.messages.receiveEmailMessage({
+  emailChatId: 'em-chat-789',
+  message: 'Hi! I\'m interested in the role.',
+  subject: 'Re: Job Opportunity',
+  senderEmail: 'candidate@example.com',
+  senderName: 'John Doe',
+  messageId: '<CANn6MZN...@mail.gmail.com>',  // For deduplication
+});
+
+// Full email with threading and attachments
+await chat.services.messages.receiveEmailMessage({
+  emailChatId: 'em-chat-789',
+  message: 'Hi Jane,\n\nThank you for reaching out...',
+  subject: 'Re: Senior Developer Position',
+  senderEmail: 'candidate@example.com',
+  senderName: 'John Doe',
+  providerId: '19bfed8cdc1d7148',  // For threading - important!
+  messageId: '<CANn6MZN...@mail.gmail.com>',  // For deduplication - important!
+  attachments: [
+    {
+      name: 'resume.pdf',
+      url: 'https://storage.example.com/resume.pdf',
+      size: 245000,
+      mimeType: 'application/pdf'
+    }
+  ]
+});
+```
 
-This allows subsequent UI actions to prefill the last known contact handles for LinkedIn and WhatsApp.
+All helpers will:
+
+1. **Check for duplicates** - If `messageId` is provided, check if a message with that ID already exists in the conversation and return it if found.
+2. Locate the conversation by the given chat ID.
+3. Use the `Application` participant from the conversation as the sender.
+4. Create a new message with `kind: 'text'` and `source` set to the respective connector.
+5. Store platform-specific metadata:
+   - **Email**: subject, sender info, attachments, threading data in `metadata.email`
+   - **LinkedIn**: sender name and profile URL in `metadata.linkedin`
+   - **WhatsApp**: sender name in `metadata.whatsapp`
+6. Update the conversation summary fields (`lastMessageAt`, `lastMessagePreview`, `lastMessageSenderId`, `lastMessageSenderModel`).
 
 ## Models
 

package/dist/index.d.cts

@@ -137,6 +137,52 @@ interface IMessage extends Document {
         source: string;
         message: string;
     }>;
+    externalMessageId?: string;
+    metadata?: {
+        email?: {
+            subject?: string;
+            to?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            cc?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            bcc?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            from?: {
+                display_name: string;
+                identifier: string;
+            };
+            attachments?: Array<{
+                name: string;
+                url: string;
+                size?: number;
+                mimeType?: string;
+            }>;
+            providerId?: string;
+            messageId?: string;
+            replyTo?: string;
+            tracking?: {
+                opens?: boolean;
+                links?: boolean;
+                label?: string;
+                custom_domain?: string;
+            };
+        };
+        linkedin?: {
+            subject?: string;
+            isInMail?: boolean;
+            senderName?: string;
+            senderProfileUrl?: string;
+        };
+        whatsapp?: {
+            senderName?: string;
+        };
+    };
     parentMessageId?: string;
     rootThreadId?: string;
     editedAt?: Date;
@@ -202,6 +248,36 @@ type SendMessageArgs = {
         contactId: string;
         connectorId: string;
     }>;
+    metadata?: {
+        email?: {
+            subject?: string;
+            recipientName?: string;
+            additionalRecipients?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            cc?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            bcc?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            attachments?: string[];
+            replyTo?: string;
+            tracking?: {
+                opens?: boolean;
+                links?: boolean;
+                label?: string;
+                custom_domain?: string;
+            };
+        };
+        linkedin?: {
+            subject?: string;
+            isInMail?: boolean;
+        };
+    };
 };
 type ListMessagesArgs = {
     organizationId: string;
@@ -221,6 +297,34 @@ type MarkReadArgs = {
     participantId: string;
     messageId: string;
 };
+type ReceiveWhatsappMessageArgs = {
+    whatsappChatId: string;
+    message: string;
+    messageId?: string;
+    senderName?: string;
+};
+type ReceiveLinkedinMessageArgs = {
+    linkedinChatId: string;
+    message: string;
+    messageId?: string;
+    senderName?: string;
+    senderProfileUrl?: string;
+};
+type ReceiveEmailMessageArgs = {
+    emailChatId: string;
+    message: string;
+    subject?: string;
+    senderEmail?: string;
+    senderName?: string;
+    providerId?: string;
+    messageId?: string;
+    attachments?: Array<{
+        name: string;
+        url: string;
+        size?: number;
+        mimeType?: string;
+    }>;
+};
 type SearchMessagesArgs = {
     organizationId: string;
     query?: string;
@@ -277,8 +381,10 @@ interface IConversation extends Document {
     lastMessageSenderModel?: string;
     lastLinkedInId?: string;
     lastWhatsAppId?: string;
+    lastEmailId?: string;
     linkedinChatId?: string;
     whatsappChatId?: string;
+    emailChatId?: string;
     metadata?: Record<string, any>;
     createdAt: Date;
     updatedAt: Date;
@@ -375,6 +481,9 @@ interface MessagesService {
         populateSenders: true;
     }): Promise<PaginatedResult<MessageWithSender>>;
     markRead(args: MarkReadArgs): Promise<void>;
+    receiveWhatsappMessage(args: ReceiveWhatsappMessageArgs): Promise<IMessage>;
+    receiveLinkedinMessage(args: ReceiveLinkedinMessageArgs): Promise<IMessage>;
+    receiveEmailMessage(args: ReceiveEmailMessageArgs): Promise<IMessage>;
 }
 /**
  * Create messages service
@@ -598,4 +707,4 @@ interface ChatServices {
  */
 declare function initChat(mongooseInstance: typeof mongoose, options: InitOptions, server?: Server): Promise<ChatServices>;
 
-export { type Actor, type ChatApiResponse, type ChatServices, type ChatStartedResponse, type ConversationModel, type ConversationReadEvent, type ConversationsService, type CreateConversationArgs, type EnvironmentConfig, type IConversation, type IMessage, type InitOptions, type ListMessagesArgs, type MarkReadArgs, type MessageCreatedEvent, type MessageModel, type MessageServiceHooks, type MessageWithSender, type MessagesService, type PaginatedResult, type PresenceEvent, type RedisConfig, type RuntimeConfig, type SearchConversationsArgs, type SearchMessagesArgs, type SendMessageArgs, type SocketConfig$1 as SocketConfig, type SourceType, type Transport, type TransportConfig, type TypingEvent, createConversationId, createConversationModel, createConversationsService, createCursor, createMessageId, createMessageModel, createMessagesService, createModels, createPaginatedResponse, createThreadId, createTransport, ensureIndexes, generateId, getRedisConfig, getRuntimeConfig, initChat, modelRegistry, parseCursor, searchByParticipantPair, searchConversations, searchMessages, setRuntimeConfig, sourceType, validateCreateConversationArgs, validateInitOptions, validateMarkReadArgs, validatePagination, validateSendMessageArgs };
+export { type Actor, type ChatApiResponse, type ChatServices, type ChatStartedResponse, type ConversationModel, type ConversationReadEvent, type ConversationsService, type CreateConversationArgs, type EnvironmentConfig, type IConversation, type IMessage, type InitOptions, type ListMessagesArgs, type MarkReadArgs, type MessageCreatedEvent, type MessageModel, type MessageServiceHooks, type MessageWithSender, type MessagesService, type PaginatedResult, type PresenceEvent, type ReceiveEmailMessageArgs, type ReceiveLinkedinMessageArgs, type ReceiveWhatsappMessageArgs, type RedisConfig, type RuntimeConfig, type SearchConversationsArgs, type SearchMessagesArgs, type SendMessageArgs, type SocketConfig$1 as SocketConfig, type SourceType, type Transport, type TransportConfig, type TypingEvent, createConversationId, createConversationModel, createConversationsService, createCursor, createMessageId, createMessageModel, createMessagesService, createModels, createPaginatedResponse, createThreadId, createTransport, ensureIndexes, generateId, getRedisConfig, getRuntimeConfig, initChat, modelRegistry, parseCursor, searchByParticipantPair, searchConversations, searchMessages, setRuntimeConfig, sourceType, validateCreateConversationArgs, validateInitOptions, validateMarkReadArgs, validatePagination, validateSendMessageArgs };

package/dist/index.d.ts

@@ -137,6 +137,52 @@ interface IMessage extends Document {
         source: string;
         message: string;
     }>;
+    externalMessageId?: string;
+    metadata?: {
+        email?: {
+            subject?: string;
+            to?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            cc?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            bcc?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            from?: {
+                display_name: string;
+                identifier: string;
+            };
+            attachments?: Array<{
+                name: string;
+                url: string;
+                size?: number;
+                mimeType?: string;
+            }>;
+            providerId?: string;
+            messageId?: string;
+            replyTo?: string;
+            tracking?: {
+                opens?: boolean;
+                links?: boolean;
+                label?: string;
+                custom_domain?: string;
+            };
+        };
+        linkedin?: {
+            subject?: string;
+            isInMail?: boolean;
+            senderName?: string;
+            senderProfileUrl?: string;
+        };
+        whatsapp?: {
+            senderName?: string;
+        };
+    };
     parentMessageId?: string;
     rootThreadId?: string;
     editedAt?: Date;
@@ -202,6 +248,36 @@ type SendMessageArgs = {
         contactId: string;
         connectorId: string;
     }>;
+    metadata?: {
+        email?: {
+            subject?: string;
+            recipientName?: string;
+            additionalRecipients?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            cc?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            bcc?: Array<{
+                display_name: string;
+                identifier: string;
+            }>;
+            attachments?: string[];
+            replyTo?: string;
+            tracking?: {
+                opens?: boolean;
+                links?: boolean;
+                label?: string;
+                custom_domain?: string;
+            };
+        };
+        linkedin?: {
+            subject?: string;
+            isInMail?: boolean;
+        };
+    };
 };
 type ListMessagesArgs = {
     organizationId: string;
@@ -221,6 +297,34 @@ type MarkReadArgs = {
     participantId: string;
     messageId: string;
 };
+type ReceiveWhatsappMessageArgs = {
+    whatsappChatId: string;
+    message: string;
+    messageId?: string;
+    senderName?: string;
+};
+type ReceiveLinkedinMessageArgs = {
+    linkedinChatId: string;
+    message: string;
+    messageId?: string;
+    senderName?: string;
+    senderProfileUrl?: string;
+};
+type ReceiveEmailMessageArgs = {
+    emailChatId: string;
+    message: string;
+    subject?: string;
+    senderEmail?: string;
+    senderName?: string;
+    providerId?: string;
+    messageId?: string;
+    attachments?: Array<{
+        name: string;
+        url: string;
+        size?: number;
+        mimeType?: string;
+    }>;
+};
 type SearchMessagesArgs = {
     organizationId: string;
     query?: string;
@@ -277,8 +381,10 @@ interface IConversation extends Document {
     lastMessageSenderModel?: string;
     lastLinkedInId?: string;
     lastWhatsAppId?: string;
+    lastEmailId?: string;
     linkedinChatId?: string;
     whatsappChatId?: string;
+    emailChatId?: string;
     metadata?: Record<string, any>;
     createdAt: Date;
     updatedAt: Date;
@@ -375,6 +481,9 @@ interface MessagesService {
         populateSenders: true;
     }): Promise<PaginatedResult<MessageWithSender>>;
     markRead(args: MarkReadArgs): Promise<void>;
+    receiveWhatsappMessage(args: ReceiveWhatsappMessageArgs): Promise<IMessage>;
+    receiveLinkedinMessage(args: ReceiveLinkedinMessageArgs): Promise<IMessage>;
+    receiveEmailMessage(args: ReceiveEmailMessageArgs): Promise<IMessage>;
 }
 /**
  * Create messages service
@@ -598,4 +707,4 @@ interface ChatServices {
  */
 declare function initChat(mongooseInstance: typeof mongoose, options: InitOptions, server?: Server): Promise<ChatServices>;
 
-export { type Actor, type ChatApiResponse, type ChatServices, type ChatStartedResponse, type ConversationModel, type ConversationReadEvent, type ConversationsService, type CreateConversationArgs, type EnvironmentConfig, type IConversation, type IMessage, type InitOptions, type ListMessagesArgs, type MarkReadArgs, type MessageCreatedEvent, type MessageModel, type MessageServiceHooks, type MessageWithSender, type MessagesService, type PaginatedResult, type PresenceEvent, type RedisConfig, type RuntimeConfig, type SearchConversationsArgs, type SearchMessagesArgs, type SendMessageArgs, type SocketConfig$1 as SocketConfig, type SourceType, type Transport, type TransportConfig, type TypingEvent, createConversationId, createConversationModel, createConversationsService, createCursor, createMessageId, createMessageModel, createMessagesService, createModels, createPaginatedResponse, createThreadId, createTransport, ensureIndexes, generateId, getRedisConfig, getRuntimeConfig, initChat, modelRegistry, parseCursor, searchByParticipantPair, searchConversations, searchMessages, setRuntimeConfig, sourceType, validateCreateConversationArgs, validateInitOptions, validateMarkReadArgs, validatePagination, validateSendMessageArgs };
+export { type Actor, type ChatApiResponse, type ChatServices, type ChatStartedResponse, type ConversationModel, type ConversationReadEvent, type ConversationsService, type CreateConversationArgs, type EnvironmentConfig, type IConversation, type IMessage, type InitOptions, type ListMessagesArgs, type MarkReadArgs, type MessageCreatedEvent, type MessageModel, type MessageServiceHooks, type MessageWithSender, type MessagesService, type PaginatedResult, type PresenceEvent, type ReceiveEmailMessageArgs, type ReceiveLinkedinMessageArgs, type ReceiveWhatsappMessageArgs, type RedisConfig, type RuntimeConfig, type SearchConversationsArgs, type SearchMessagesArgs, type SendMessageArgs, type SocketConfig$1 as SocketConfig, type SourceType, type Transport, type TransportConfig, type TypingEvent, createConversationId, createConversationModel, createConversationsService, createCursor, createMessageId, createMessageModel, createMessagesService, createModels, createPaginatedResponse, createThreadId, createTransport, ensureIndexes, generateId, getRedisConfig, getRuntimeConfig, initChat, modelRegistry, parseCursor, searchByParticipantPair, searchConversations, searchMessages, setRuntimeConfig, sourceType, validateCreateConversationArgs, validateInitOptions, validateMarkReadArgs, validatePagination, validateSendMessageArgs };