@builderbot/provider-email 1.3.15-alpha.8

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Leifer Mendez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# @builderbot/provider-email
+
+Email provider for BuilderBot using IMAP/SMTP. Receive emails in real-time using IMAP IDLE and send emails via SMTP.
+
+## Installation
+
+```bash
+npm install @builderbot/provider-email
+# or
+pnpm add @builderbot/provider-email
+```
+
+## Features
+
+- Real-time email reception using IMAP IDLE
+- Send emails via SMTP
+- Thread/conversation tracking
+- Attachment support (send and receive)
+- Compatible with any IMAP/SMTP server (Gmail, Outlook, custom servers, etc.)
+
+## Quick Start
+
+```typescript
+import { createBot, createProvider, createFlow, addKeyword } from '@builderbot/bot'
+import { EmailProvider } from '@builderbot/provider-email'
+
+const emailProvider = createProvider(EmailProvider, {
+    imap: {
+        host: 'imap.gmail.com',
+        port: 993,
+        secure: true,
+        auth: {
+            user: 'your-email@gmail.com',
+            pass: 'your-app-password'
+        }
+    },
+    smtp: {
+        host: 'smtp.gmail.com',
+        port: 465,
+        secure: true,
+        auth: {
+            user: 'your-email@gmail.com',
+            pass: 'your-app-password'
+        }
+    }
+})
+
+const welcomeFlow = addKeyword(['hello', 'hi'])
+    .addAnswer('Hello! I received your email.')
+    .addAction(async (ctx, { provider }) => {
+        console.log('Email from:', ctx.from)
+        console.log('Subject:', ctx.subject)
+        console.log('Body:', ctx.body)
+        console.log('Is reply:', ctx.isReply)
+    })
+
+const main = async () => {
+    await createBot({
+        flow: createFlow([welcomeFlow]),
+        provider: emailProvider,
+        database: new MemoryDB()
+    })
+}
+
+main()
+```
+
+## Configuration
+
+### IEmailProviderArgs
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `imap` | `ImapConfig` | Yes | - | IMAP server configuration |
+| `smtp` | `SmtpConfig` | Yes | - | SMTP server configuration |
+| `mailbox` | `string` | No | `'INBOX'` | Mailbox to monitor |
+| `markAsRead` | `boolean` | No | `true` | Mark emails as read after processing |
+| `fromEmail` | `string` | No | SMTP user | From address for outgoing emails |
+| `fromName` | `string` | No | - | Display name for outgoing emails |
+
+### ImapConfig / SmtpConfig
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `host` | `string` | Yes | Server hostname |
+| `port` | `number` | Yes | Server port |
+| `secure` | `boolean` | No | Use SSL/TLS (default: true) |
+| `auth.user` | `string` | Yes | Username |
+| `auth.pass` | `string` | Yes | Password or app password |
+
+## Email Context (ctx)
+
+When an email is received, the context object includes:
+
+```typescript
+interface EmailBotContext {
+    from: string           // Sender's email address
+    name: string           // Sender's display name
+    body: string           // Email body (plain text)
+    subject: string        // Email subject
+    messageId: string      // Unique message ID
+    threadId?: string      // Thread ID for conversations
+    inReplyTo?: string     // ID of email being replied to
+    isReply: boolean       // Whether this is a reply
+    attachments?: Array<{
+        filename: string
+        contentType: string
+        size: number
+    }>
+    html?: string          // HTML content (if available)
+    to?: string[]          // Recipients
+    cc?: string[]          // CC recipients
+    date?: Date            // Email date
+}
+```
+
+## API Methods
+
+### sendMessage(to, message, options?)
+
+Send an email to a recipient.
+
+```typescript
+await provider.sendMessage('recipient@example.com', 'Hello!', {
+    subject: 'Greeting',
+    html: '<h1>Hello!</h1>'
+})
+```
+
+### sendMedia(to, message, mediaPath, options?)
+
+Send an email with an attachment.
+
+```typescript
+await provider.sendMedia(
+    'recipient@example.com',
+    'Please find the document attached.',
+    '/path/to/document.pdf',
+    { subject: 'Document' }
+)
+```
+
+### reply(ctx, message, options?)
+
+Reply to an existing email thread.
+
+```typescript
+.addAction(async (ctx, { provider }) => {
+    await provider.reply(ctx, 'Thank you for your message!')
+})
+```
+
+### saveFile(ctx, options?)
+
+Save an email attachment to disk.
+
+```typescript
+.addAction(async (ctx, { provider }) => {
+    if (ctx.attachments?.length) {
+        const filePath = await provider.saveFile(ctx, {
+            path: './downloads',
+            attachmentIndex: 0
+        })
+        console.log('Saved to:', filePath)
+    }
+})
+```
+
+### getAttachments(ctx)
+
+Get all attachments from an email.
+
+```typescript
+const attachments = provider.getAttachments(ctx)
+```
+
+### isReply(ctx)
+
+Check if the email is a reply.
+
+```typescript
+if (provider.isReply(ctx)) {
+    console.log('This is a reply to:', ctx.inReplyTo)
+}
+```
+
+### getThreadId(ctx)
+
+Get the thread ID for conversation tracking.
+
+```typescript
+const threadId = provider.getThreadId(ctx)
+```
+
+## Gmail Configuration
+
+For Gmail, you need to use an App Password:
+
+1. Enable 2-Factor Authentication on your Google account
+2. Go to [Google App Passwords](https://myaccount.google.com/apppasswords)
+3. Generate a new app password for "Mail"
+4. Use this password in the configuration
+
+```typescript
+{
+    imap: {
+        host: 'imap.gmail.com',
+        port: 993,
+        secure: true,
+        auth: {
+            user: 'your-email@gmail.com',
+            pass: 'xxxx xxxx xxxx xxxx' // App password
+        }
+    },
+    smtp: {
+        host: 'smtp.gmail.com',
+        port: 465,
+        secure: true,
+        auth: {
+            user: 'your-email@gmail.com',
+            pass: 'xxxx xxxx xxxx xxxx' // App password
+        }
+    }
+}
+```
+
+## Outlook/Office 365 Configuration
+
+```typescript
+{
+    imap: {
+        host: 'outlook.office365.com',
+        port: 993,
+        secure: true,
+        auth: {
+            user: 'your-email@outlook.com',
+            pass: 'your-password'
+        }
+    },
+    smtp: {
+        host: 'smtp.office365.com',
+        port: 587,
+        secure: false, // Use STARTTLS
+        auth: {
+            user: 'your-email@outlook.com',
+            pass: 'your-password'
+        }
+    }
+}
+```
+
+## License
+
+MIT

package/dist/email/core.d.ts

@@ -0,0 +1,77 @@
+import EventEmitter from 'node:events';
+import type { IEmailProviderArgs, EmailBotContext, EmailSendOptions } from '../types';
+/**
+ * Class representing EmailCoreVendor, handles IMAP/SMTP operations.
+ * @extends EventEmitter
+ */
+export declare class EmailCoreVendor extends EventEmitter {
+    private imapClient;
+    private smtpTransporter;
+    private config;
+    private isConnected;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    constructor(config: IEmailProviderArgs);
+    /**
+     * Initialize SMTP transporter for sending emails
+     */
+    private initializeSmtp;
+    /**
+     * Connect to IMAP server and start listening for new emails
+     */
+    connect(): Promise<void>;
+    /**
+     * Handle disconnection and attempt reconnection
+     */
+    private handleDisconnect;
+    /**
+     * Start IMAP IDLE listener for real-time email notifications
+     */
+    private startIdleListener;
+    /**
+     * Fetch new emails from a sequence range
+     */
+    private fetchNewEmails;
+    /**
+     * Parse a mailparser ParsedMail object to EmailBotContext
+     */
+    private parseEmailToContext;
+    /**
+     * Extract single address from AddressObject
+     */
+    private extractAddress;
+    /**
+     * Extract array of addresses from AddressObject
+     */
+    private extractAddresses;
+    /**
+     * Send an email via SMTP
+     */
+    sendEmail(to: string, subject: string, text: string, options?: EmailSendOptions): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * Reply to an existing email thread
+     */
+    replyToEmail(originalContext: EmailBotContext, text: string, options?: Omit<EmailSendOptions, 'inReplyTo' | 'references'>): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * Download attachment content
+     */
+    downloadAttachment(ctx: EmailBotContext, attachmentIndex: number): Promise<Buffer | null>;
+    /**
+     * Disconnect from IMAP server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if connected to IMAP server
+     */
+    isImapConnected(): boolean;
+    /**
+     * Verify SMTP connection
+     */
+    verifySmtp(): Promise<boolean>;
+}
+//# sourceMappingURL=core.d.ts.map

package/dist/email/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/email/core.ts"],"names":[],"mappings":"AAGA,OAAO,YAAY,MAAM,aAAa,CAAA;AAGtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAmB,MAAM,UAAU,CAAA;AAEtG;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IAC7C,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,eAAe,CAA2B;IAClD,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,iBAAiB,CAAY;IACrC,OAAO,CAAC,oBAAoB,CAAa;IACzC,OAAO,CAAC,cAAc,CAAe;gBAEzB,MAAM,EAAE,kBAAkB;IAMtC;;OAEG;IACH,OAAO,CAAC,cAAc;IAkBtB;;OAEG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+CrC;;OAEG;YACW,gBAAgB;IAuB9B;;OAEG;YACW,iBAAiB;IAyC/B;;OAEG;YACW,cAAc;IAqC5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgE3B;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAmBxB;;OAEG;IACU,SAAS,CAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,gBAAgB,GAC3B,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAuDjC;;OAEG;IACU,YAAY,CACrB,eAAe,EAAE,eAAe,EAChC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,YAAY,CAAC,GAC7D,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAuBjC;;OAEG;IACU,kBAAkB,CAAC,GAAG,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAetG;;OAEG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBxC;;OAEG;IACI,eAAe,IAAI,OAAO;IAIjC;;OAEG;IACU,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;CAU9C"}

package/dist/email/provider.d.ts

@@ -0,0 +1,92 @@
+import { ProviderClass } from '@builderbot/bot';
+import type { BotContext, SendOptions } from '@builderbot/bot/dist/types';
+import { EmailCoreVendor } from './core';
+import type { IEmailProviderArgs, EmailBotContext, EmailSendOptions } from '../types';
+/**
+ * Email Provider for BuilderBot
+ * Supports receiving emails via IMAP (with IDLE) and sending via SMTP
+ * @extends ProviderClass
+ */
+declare class EmailProvider extends ProviderClass<EmailCoreVendor> {
+    globalVendorArgs: IEmailProviderArgs;
+    constructor(args: IEmailProviderArgs);
+    /**
+     * Initialize the email vendor (IMAP/SMTP connections)
+     */
+    protected initVendor(): Promise<EmailCoreVendor>;
+    /**
+     * Called before HTTP server initialization
+     */
+    protected beforeHttpServerInit(): void;
+    /**
+     * Called after HTTP server initialization
+     */
+    protected afterHttpServerInit(): void;
+    /**
+     * Index home endpoint
+     */
+    private indexHome;
+    /**
+     * Webhook handler for external email notifications (optional)
+     */
+    private webhookHandler;
+    /**
+     * Map vendor events to provider events
+     */
+    protected busEvents: () => {
+        event: string;
+        func: (payload: any) => void;
+    }[];
+    /**
+     * Send an email message
+     * @param to - Recipient email address
+     * @param message - Email body content
+     * @param options - Send options (subject, attachments, etc.)
+     */
+    sendMessage(to: string, message: string, options?: SendOptions & EmailSendOptions): Promise<any>;
+    /**
+     * Send an email with media attachment
+     * @param to - Recipient email address
+     * @param message - Email body content
+     * @param mediaPath - Path to media file
+     * @param options - Additional email options
+     */
+    sendMedia(to: string, message: string, mediaPath: string, options?: EmailSendOptions): Promise<any>;
+    /**
+     * Reply to an existing email thread
+     * @param ctx - Original email context
+     * @param message - Reply message content
+     * @param options - Additional email options
+     */
+    reply(ctx: EmailBotContext, message: string, options?: Omit<EmailSendOptions, 'inReplyTo' | 'references'>): Promise<any>;
+    /**
+     * Save an attachment from an email to disk
+     * @param ctx - Email context containing attachments
+     * @param options - Save options (path, attachment index)
+     */
+    saveFile(ctx: Partial<EmailBotContext & BotContext>, options?: {
+        path?: string;
+        attachmentIndex?: number;
+    }): Promise<string>;
+    /**
+     * Get all attachments from an email
+     * @param ctx - Email context
+     */
+    getAttachments(ctx: EmailBotContext): import("../types").EmailAttachment[];
+    /**
+     * Check if the email is a reply
+     * @param ctx - Email context
+     */
+    isReply(ctx: EmailBotContext): boolean;
+    /**
+     * Get the thread ID from an email
+     * @param ctx - Email context
+     */
+    getThreadId(ctx: EmailBotContext): string | undefined;
+    /**
+     * Disconnect the email provider
+     */
+    disconnect(): Promise<void>;
+}
+export { EmailProvider };
+//# sourceMappingURL=provider.d.ts.map

package/dist/email/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/email/provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AAKzE,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAErF;;;;GAIG;AACH,cAAM,aAAc,SAAQ,aAAa,CAAC,eAAe,CAAC;IACtD,gBAAgB,EAAE,kBAAkB,CAAA;gBAExB,IAAI,EAAE,kBAAkB;IA2BpC;;OAEG;cACa,UAAU,IAAI,OAAO,CAAC,eAAe,CAAC;IAUtD;;OAEG;IACH,SAAS,CAAC,oBAAoB,IAAI,IAAI;IAUtC;;OAEG;IACH,SAAS,CAAC,mBAAmB,IAAI,IAAI;IAErC;;OAEG;IACH,OAAO,CAAC,SAAS,CAEhB;IAED;;OAEG;IACH,OAAO,CAAC,cAAc,CAKrB;IAED;;OAEG;IACH,SAAS,CAAC,SAAS;;wBAGK,GAAG;QAwB1B;IAED;;;;;OAKG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC;IAmBtG;;;;;;OAMG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC;IAgBzG;;;;;OAKG;IACG,KAAK,CACP,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,YAAY,CAAC,GAC7D,OAAO,CAAC,GAAG,CAAC;IAIf;;;;OAIG;IACG,QAAQ,CACV,GAAG,EAAE,OAAO,CAAC,eAAe,GAAG,UAAU,CAAC,EAC1C,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,GACtD,OAAO,CAAC,MAAM,CAAC;IA+BlB;;;OAGG;IACH,cAAc,CAAC,GAAG,EAAE,eAAe;IAInC;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO;IAItC;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS;IAIrD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAKpC;AAED,OAAO,EAAE,aAAa,EAAE,CAAA"}