@zhin.js/adapter-email 1.0.1 → 1.1.0

package/lib/endpoint.js

@@ -1,368 +1,335 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
- * Email Endpoint 实现
+ * EmailEndpoint — lifecycle, SMTP outbound, IMAP inbound polling.
  */
-import nodemailer from "nodemailer";
-import Imap from "imap";
-import { simpleParser } from "mailparser";
-import { formatCompact, Message, segment, htmlToPlainTextWithBlockBreaks } from 'zhin.js';
-import { EventEmitter } from "events";
-import { createWriteStream, promises as fs } from "fs";
-import path from "path";
-export class EmailEndpoint extends EventEmitter {
-    adapter;
-    $config;
-    $connected = false;
-    smtpTransporter = null;
-    imapConnection = null;
-    checkTimer = null;
-    get logger() {
-        return this.adapter.plugin.logger;
-    }
-    get $id() {
-        return this.$config.name;
-    }
-    constructor(adapter, config) {
+import { mkdir, writeFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { simpleParser } from 'mailparser';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { emailInboundConversation, formatInboundContent, formatInboundSegments, formatOutboundMail, parseEmailMessage, senderDisplayName, } from './protocol.js';
+import { defaultCreateImap, defaultCreateSmtp, } from './transport.js';
+import { EmailClient } from './client.js';
+/**
+ * Email（SMTP/IMAP）无好友/群/频道等社交图谱概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
+export class EmailEndpoint extends Endpoint {
+    client;
+    #logger;
+    #options;
+    #smtp = null;
+    #imap = null;
+    #checkTimer = null;
+    #reconnectTimer = null;
+    #reconnectAttempts = 0;
+    #checking = false;
+    #open = false;
+    #started = false;
+    constructor(options) {
         super();
-        this.adapter = adapter;
-        this.$config = config;
-        // 设置默认值
-        this.$config.imap.checkInterval = this.$config.imap.checkInterval || 60000; // 1分钟
-        this.$config.imap.mailbox = this.$config.imap.mailbox || 'INBOX';
-        this.$config.imap.markSeen = this.$config.imap.markSeen !== false;
-        if (this.$config.attachments?.enabled) {
-            this.$config.attachments.downloadPath = this.$config.attachments.downloadPath || './downloads/email';
-            this.$config.attachments.maxFileSize = this.$config.attachments.maxFileSize || 10 * 1024 * 1024; // 10MB
-        }
+        this.#logger = getAdapterLogger('email', options.config.id);
+        this.#options = options;
+        this.client = new EmailClient(() => this.#smtp, () => this.#imap);
     }
-    async $connect() {
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        const { smtp, imap, id } = this.#options.config;
         try {
-            // 初始化 SMTP 传输器
-            this.smtpTransporter = nodemailer.createTransport({
-                host: this.$config.smtp.host,
-                port: this.$config.smtp.port,
-                secure: this.$config.smtp.secure,
-                auth: this.$config.smtp.auth
-            });
-            // 验证 SMTP 连接
-            await this.smtpTransporter.verify();
-            this.logger.info(formatCompact({ endpoint: this.$id, mode: "smtp" }));
-            // 初始化 IMAP 连接
-            this.imapConnection = new Imap({
-                user: this.$config.imap.user,
-                password: this.$config.imap.password,
-                host: this.$config.imap.host,
-                port: this.$config.imap.port,
-                tls: this.$config.imap.tls
-            });
-            // 设置 IMAP 事件监听
-            this.setupImapListeners();
-            // 连接 IMAP
+            this.#smtp = await (this.#options.createSmtp?.(smtp) ?? defaultCreateSmtp(smtp));
+            await this.#smtp.verify();
+            this.#logger.debug(formatCompact({ mode: 'smtp' }));
+            this.#imap = this.#options.createImap?.(imap) ?? defaultCreateImap(imap);
+            this.#setupImapListeners(this.#imap);
             await new Promise((resolve, reject) => {
-                this.imapConnection.once('ready', resolve);
-                this.imapConnection.once('error', reject);
-                this.imapConnection.connect();
+                this.#imap.once('ready', () => {
+                    void this.#emitPlatformEvent('imap.ready', Object.freeze({}));
+                    resolve();
+                });
+                this.#imap.once('error', (error) => reject(error));
+                this.#imap.connect();
             });
-            this.logger.info(formatCompact({ endpoint: this.$id, mode: "imap" }));
-            // 开始检查邮件
-            this.startEmailCheck();
-            this.$connected = true;
+            this.#logger.debug(formatCompact({ mode: 'imap' }));
+            this.#reconnectAttempts = 0;
+            this.#startEmailCheck();
         }
         catch (error) {
-            this.logger.error('Failed to connect email services:', error);
+            await this.stop();
+            this.#logger.error('Failed to connect email services:', error);
             throw error;
         }
     }
-    async $disconnect() {
-        this.$connected = false;
-        // 停止定时检查
-        if (this.checkTimer) {
-            clearInterval(this.checkTimer);
-            this.checkTimer = null;
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        // 先复位 #started，避免 imap.end() 触发的 'end' 事件又武装重连定时器
+        this.#started = false;
+        if (this.#checkTimer) {
+            clearInterval(this.#checkTimer);
+            this.#checkTimer = null;
+        }
+        if (this.#reconnectTimer) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = null;
         }
-        // 关闭 IMAP 连接
-        if (this.imapConnection) {
-            this.imapConnection.end();
-            this.imapConnection = null;
+        if (this.#imap) {
+            try {
+                this.#imap.end();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#imap = null;
         }
-        // 关闭 SMTP 连接
-        if (this.smtpTransporter) {
-            this.smtpTransporter.close();
-            this.smtpTransporter = null;
+        if (this.#smtp) {
+            try {
+                this.#smtp.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#smtp = null;
         }
-        this.logger.info(formatCompact({ op: "disconnect", endpoint: this.$id }));
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    setupImapListeners() {
-        if (!this.imapConnection)
+    async send({ conversation, payload }) {
+        const target = conversation.id;
+        const mailOptions = formatOutboundMail(payload, {
+            from: this.#options.config.smtp.auth.user,
+            to: target,
+        });
+        const info = await this.client.sendMail(mailOptions);
+        this.#logger.debug(formatCompact({ op: 'email_send', target, messageId: info.messageId }));
+        return info.messageId || '';
+    }
+    /** Test / internal: admit a parsed mail when the endpoint is open. */
+    admit(email) {
+        if (!this.#open)
             return;
-        this.imapConnection.on('mail', (numNewMsgs) => {
-            this.logger.debug(`Received ${numNewMsgs} new emails`);
-            this.checkForNewEmails();
+        void this.#emitPlatformEvent('mail', email);
+        void this.#admitWithAttachments(email).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'email_gateway_receive_failed',
+                target: email.from,
+                error: err instanceof Error ? err.message : String(err),
+            }));
         });
-        this.imapConnection.on('error', (error) => {
-            this.logger.error('IMAP error:', error);
+    }
+    async #admitWithAttachments(email) {
+        const savedAttachments = await this.#downloadAttachments(email);
+        const content = formatInboundContent(email);
+        const sender = email.from;
+        const conversation = emailInboundConversation(String(this.#options.id), email);
+        await this.emit('message.receive', {
+            conversation,
+            ...(email.messageId ? { message: { conversation, id: email.messageId } } : {}),
+            content,
+            segments: formatInboundSegments(email, savedAttachments),
+            sender: { id: sender, name: senderDisplayName(sender) || undefined },
+            endpointId: this.#options.config.id,
+            metadata: Object.freeze({
+                subject: email.subject,
+                to: email.to,
+                cc: email.cc,
+                uid: email.uid,
+                date: email.date.toISOString(),
+                ...(savedAttachments.length ? { attachments: savedAttachments } : {}),
+            }),
         });
-        this.imapConnection.on('end', () => {
-            this.logger.info(formatCompact({ op: "disconnect", endpoint: this.$id, mode: "imap" }));
+    }
+    /**
+     * attachments.enabled 时把入站附件落盘（恢复旧 downloadAttachment 行为，
+     * 附加 maxFileSize / allowedTypes 过滤）；返回落盘结果供 admit segments/metadata 使用。
+     */
+    async #downloadAttachments(email) {
+        const config = this.#options.config.attachments;
+        if (!config?.enabled || email.attachments.length === 0)
+            return [];
+        await mkdir(config.downloadPath, { recursive: true });
+        const downloadRoot = path.resolve(config.downloadPath);
+        const saved = [];
+        for (const attachment of email.attachments) {
+            // 防路径穿越：发件人可构造 ../../ 等文件名，basename + resolve 后必须落在 downloadPath 内
+            const rawName = attachment.filename || `attachment_${Date.now()}`;
+            const filename = path.basename(rawName) || `attachment_${Date.now()}`;
+            const filepath = path.resolve(downloadRoot, filename);
+            if (filepath !== downloadRoot && !filepath.startsWith(downloadRoot + path.sep)) {
+                this.#logger.warn(formatCompact({ op: 'email_attachment_skipped', filename: rawName, reason: 'path' }));
+                continue;
+            }
+            if (config.allowedTypes?.length && !config.allowedTypes.includes(attachment.contentType ?? '')) {
+                this.#logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'type' }));
+                continue;
+            }
+            if (attachment.size != null && attachment.size > config.maxFileSize) {
+                this.#logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'size' }));
+                continue;
+            }
+            try {
+                await writeFile(filepath, attachment.content);
+                saved.push({ filename, path: filepath, contentType: attachment.contentType, size: attachment.size });
+            }
+            catch (error) {
+                this.#logger.warn(formatCompact({
+                    op: 'email_attachment_download_failed',
+                    filename,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+        }
+        return saved;
+    }
+    #setupImapListeners(imap) {
+        imap.on('mail', () => {
+            void this.#emitPlatformEvent('imap.mail', Object.freeze({}));
+            void this.#checkForNewEmails();
+        });
+        imap.on('error', (error) => {
+            void this.#emitPlatformEvent('imap.error', error);
+            this.#logger.error('IMAP error:', error);
+            // imap 通常在 error 后紧跟 end；两处都调度，靠已有定时器去重
+            this.#scheduleImapReconnect(imap);
+        });
+        imap.on('end', () => {
+            void this.#emitPlatformEvent('imap.end', Object.freeze({}));
+            this.#logger.debug(formatCompact({
+                op: 'disconnect',
+                mode: 'imap',
+            }));
+            this.#scheduleImapReconnect(imap);
+        });
+    }
+    async #emitPlatformEvent(name, event) {
+        await this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'email_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
         });
     }
-    startEmailCheck() {
-        if (this.checkTimer)
+    /** IMAP 断线后按指数退避重建连接并恢复监听（基数 reconnectInterval，封顶 5 分钟）。 */
+    #scheduleImapReconnect(source) {
+        // A replaced transport may emit a late `end` after its earlier `error`
+        // already caused a successful reconnect. Only the currently owned IMAP
+        // connection may arm the next generation's reconnect timer.
+        if (!this.#started || this.#reconnectTimer || (source && this.#imap !== source))
             return;
-        this.checkTimer = setInterval(() => {
-            this.checkForNewEmails();
-        }, this.$config.imap.checkInterval);
-        // 立即检查一次
-        this.checkForNewEmails();
+        const base = this.#options.config.imap.reconnectInterval;
+        const delay = Math.min(base * 2 ** this.#reconnectAttempts, 300_000);
+        this.#reconnectAttempts += 1;
+        this.#logger.warn(formatCompact({
+            op: 'imap_reconnect_scheduled',
+            endpoint: this.#options.config.id,
+            reconnect_ms: delay,
+        }));
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = null;
+            void this.#reconnectImap();
+        }, delay);
     }
-    async checkForNewEmails() {
-        if (!this.imapConnection || !this.$connected)
+    async #reconnectImap() {
+        if (!this.#started)
             return;
+        let imap;
         try {
+            const nextImap = this.#options.createImap?.(this.#options.config.imap)
+                ?? defaultCreateImap(this.#options.config.imap);
+            imap = nextImap;
+            this.#imap = nextImap;
+            this.#setupImapListeners(nextImap);
             await new Promise((resolve, reject) => {
-                this.imapConnection.openBox(this.$config.imap.mailbox, false, (error, box) => {
+                nextImap.once('ready', () => {
+                    void this.#emitPlatformEvent('imap.ready', Object.freeze({ reconnect: true }));
+                    resolve();
+                });
+                nextImap.once('error', (error) => reject(error));
+                nextImap.connect();
+            });
+            this.#reconnectAttempts = 0;
+            this.#logger.info(formatCompact({
+                op: 'imap_reconnect',
+                endpoint: this.#options.config.id,
+                ok: true,
+            }));
+            void this.#checkForNewEmails();
+        }
+        catch (error) {
+            this.#logger.warn(formatCompact({
+                op: 'imap_reconnect',
+                endpoint: this.#options.config.id,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+            this.#scheduleImapReconnect(imap);
+        }
+    }
+    #startEmailCheck() {
+        if (this.#checkTimer)
+            return;
+        this.#checkTimer = setInterval(() => {
+            void this.#checkForNewEmails();
+        }, this.#options.config.imap.checkInterval);
+        void this.#checkForNewEmails();
+    }
+    async #checkForNewEmails() {
+        if (!this.#imap || !this.#started || this.#checking)
+            return;
+        // 在飞锁：定时器与 mail 事件可能并发触发，串行化避免重复 admit
+        this.#checking = true;
+        try {
+            await new Promise((resolve, reject) => {
+                this.#imap.openBox(this.#options.config.imap.mailbox, false, (error) => {
                     if (error)
                         return reject(error);
-                    // 搜索未读邮件
-                    this.imapConnection.search(['UNSEEN'], (error, results) => {
-                        if (error)
-                            return reject(error);
-                        if (results.length === 0) {
+                    this.#imap.search(['UNSEEN'], (searchError, results) => {
+                        if (searchError)
+                            return reject(searchError);
+                        if (!results.length)
                             return resolve();
-                        }
-                        // 获取邮件
-                        const fetch = this.imapConnection.fetch(results, {
+                        const fetch = this.#imap.fetch(results, {
                             bodies: '',
-                            markSeen: this.$config.imap.markSeen
+                            markSeen: this.#options.config.imap.markSeen,
                         });
                         fetch.on('message', (msg, seqno) => {
-                            this.handleImapMessage(msg, seqno);
+                            this.#handleImapMessage(msg, seqno);
                         });
-                        fetch.once('error', reject);
-                        fetch.once('end', resolve);
+                        fetch.once('error', (fetchError) => reject(fetchError));
+                        fetch.once('end', () => resolve());
                     });
                 });
             });
         }
         catch (error) {
-            this.logger.error('Error checking for new emails:', error);
+            this.#logger.error('Error checking for new emails:', error);
+        }
+        finally {
+            this.#checking = false;
         }
     }
-    handleImapMessage(msg, seqno) {
+    #handleImapMessage(msg, _seqno) {
         let body = '';
         let uid = 0;
         msg.on('body', (stream) => {
             stream.on('data', (chunk) => {
-                body += chunk.toString('utf8');
+                body += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
             });
         });
         msg.once('attributes', (attrs) => {
-            uid = attrs.uid;
-        });
-        msg.once('end', async () => {
-            try {
-                const parsed = await simpleParser(body);
-                const emailMessage = this.parseEmailMessage(parsed, uid);
-                const formattedMessage = this.$formatMessage(emailMessage);
-                this.adapter.emit('message.receive', formattedMessage);
-            }
-            catch (error) {
-                this.logger.error('Error parsing email:', error);
-            }
+            uid = attrs.uid ?? 0;
         });
-    }
-    parseEmailMessage(parsed, uid) {
-        const getAddressText = (addr) => {
-            if (!addr)
-                return [];
-            if (Array.isArray(addr)) {
-                return addr.map((a) => a.text || a.address || a.toString());
-            }
-            return [addr.text || addr.address || addr.toString()];
-        };
-        return {
-            messageId: parsed.messageId || '',
-            from: parsed.from ? getAddressText(parsed.from)[0] || '' : '',
-            to: getAddressText(parsed.to),
-            cc: getAddressText(parsed.cc),
-            bcc: getAddressText(parsed.bcc),
-            subject: parsed.subject || '',
-            text: parsed.text || '',
-            html: parsed.html ? parsed.html.toString() : '',
-            attachments: parsed.attachments || [],
-            date: parsed.date || new Date(),
-            uid
-        };
-    }
-    $formatMessage(emailMsg) {
-        // 确定频道类型和ID
-        const channelType = 'private';
-        const channelId = emailMsg.from;
-        // 解析邮件内容
-        const content = EmailEndpoint.parseEmailContent(emailMsg);
-        const result = Message.from(emailMsg, {
-            $id: emailMsg.messageId,
-            $adapter: 'email',
-            $endpoint: this.$config.name,
-            $sender: {
-                id: emailMsg.from,
-                name: emailMsg.from.split('<')[0].trim() || emailMsg.from
-            },
-            $channel: {
-                id: channelId,
-                type: channelType
-            },
-            $raw: JSON.stringify(emailMsg),
-            $timestamp: emailMsg.date.getTime(),
-            $content: content,
-            $recall: async () => {
-                // 邮件适配器暂时不支持撤回消息
-            },
-            $reply: async (content) => {
-                return await this.adapter.sendMessage({
-                    context: this.$config.context,
-                    endpoint: this.$config.name,
-                    id: emailMsg.from,
-                    type: 'private',
-                    content
-                });
-            }
-        });
-        return result;
-    }
-    static parseEmailContent(email) {
-        const segments = [];
-        // 添加主题（如果有且不为空）
-        if (email.subject) {
-            segments.push(segment.text(`Subject: ${email.subject}\n\n`));
-        }
-        // 添加文本内容
-        if (email.text) {
-            segments.push(segment.text(email.text));
-        }
-        // 如果没有纯文本但有HTML，尝试转换
-        if (!email.text && email.html) {
-            const textFromHtml = EmailEndpoint.htmlToText(email.html);
-            if (textFromHtml) {
-                segments.push(segment.text(textFromHtml));
-            }
-        }
-        // 处理附件
-        for (const attachment of email.attachments) {
-            if (attachment.contentType?.startsWith('image/')) {
-                segments.push(segment('image', {
-                    filename: attachment.filename,
-                    contentType: attachment.contentType,
-                    size: attachment.size
-                }));
-            }
-            else {
-                segments.push(segment('file', {
-                    filename: attachment.filename,
-                    contentType: attachment.contentType,
-                    size: attachment.size
-                }));
-            }
-        }
-        return segments.length > 0 ? segments : [segment.text('(Empty email)')];
-    }
-    async $sendMessage(options) {
-        if (!this.smtpTransporter) {
-            throw new Error('SMTP transporter not initialized');
-        }
-        try {
-            const mailOptions = await this.formatSendContent(options);
-            const info = await this.smtpTransporter.sendMail(mailOptions);
-            this.logger.debug('Email sent:', info.messageId);
-            return info.messageId || '';
-        }
-        catch (error) {
-            this.logger.error('Failed to send email:', error);
-            throw error;
-        }
-    }
-    async $recallMessage(id) {
-        // 邮件适配器暂时不支持撤回消息
-    }
-    async formatSendContent(options) {
-        const mailOptions = {
-            from: this.$config.smtp.auth.user,
-            to: options.id,
-            subject: 'Message from Bot'
-        };
-        if (typeof options.content === 'string') {
-            mailOptions.text = options.content;
-        }
-        else if (Array.isArray(options.content)) {
-            const textParts = [];
-            const htmlParts = [];
-            const attachments = [];
-            for (const item of options.content) {
-                if (typeof item === 'string') {
-                    textParts.push(item);
-                    htmlParts.push(item.replace(/\n/g, '<br>'));
-                }
-                else {
-                    const segment = item;
-                    switch (segment.type) {
-                        case 'text':
-                            const textContent = segment.data.text || segment.data.content || '';
-                            textParts.push(textContent);
-                            htmlParts.push(textContent.replace(/\n/g, '<br>'));
-                            break;
-                        case 'image':
-                            if (segment.data.url) {
-                                attachments.push({
-                                    filename: segment.data.filename || 'image.png',
-                                    path: segment.data.url
-                                });
-                            }
-                            break;
-                        case 'file':
-                            if (segment.data.url) {
-                                attachments.push({
-                                    filename: segment.data.filename || 'file',
-                                    path: segment.data.url
-                                });
-                            }
-                            break;
-                    }
-                }
-            }
-            if (textParts.length > 0) {
-                mailOptions.text = textParts.join('\n');
-                mailOptions.html = htmlParts.join('<br>');
-            }
-            if (attachments.length > 0) {
-                mailOptions.attachments = attachments;
-            }
-        }
-        // 如果有回复对象，可以在这里处理
-        // 邮件适配器暂时不支持回复对象
-        return mailOptions;
-    }
-    // 下载附件到本地
-    async downloadAttachment(attachment) {
-        if (!this.$config.attachments?.enabled || !this.$config.attachments.downloadPath) {
-            throw new Error('Attachment download is not enabled');
-        }
-        const downloadPath = this.$config.attachments.downloadPath;
-        await fs.mkdir(downloadPath, { recursive: true });
-        const filename = attachment.filename || `attachment_${Date.now()}`;
-        const filepath = path.join(downloadPath, filename);
-        return new Promise((resolve, reject) => {
-            const writeStream = createWriteStream(filepath);
-            writeStream.write(attachment.content);
-            writeStream.end();
-            writeStream.on('finish', () => resolve(filepath));
-            writeStream.on('error', reject);
+        msg.once('end', () => {
+            void simpleParser(body).then((parsed) => {
+                this.admit(parseEmailMessage(parsed, uid));
+            }).catch((error) => {
+                this.#logger.error('Error parsing email:', error);
+            });
         });
     }
-    /**
-     * HTML → 纯文本转换，处理常见标签和实体
-     */
-    static htmlToText(html) {
-        return htmlToPlainTextWithBlockBreaks(html);
-    }
 }
-// 创建和注册适配器
-//# sourceMappingURL=endpoint.js.map

package/lib/index.d.ts

@@ -1,10 +1,4 @@
-import { EmailAdapter } from "./adapter.js";
-declare module "zhin.js" {
-    interface Adapters {
-        email: EmailAdapter;
-    }
-}
-export * from "./types.js";
-export { EmailEndpoint } from "./endpoint.js";
-export { EmailAdapter } from "./adapter.js";
-//# sourceMappingURL=index.d.ts.map
+export { addressListText, emailInboundConversation, formatInboundContent, formatInboundSegments, formatOutboundMail, htmlToText, parseEmailMessage, resolveEmailConfig, senderDisplayName, type EmailAdapterConfig, type EmailAttachmentsConfig, type EmailMessage, type EmailWireSegment, type ImapConfig, type ResolvedEmailConfig, type SavedEmailAttachment, type SmtpConfig, } from './protocol.js';
+export { EmailClient, emailClient, type EmailClientEventMap, } from './client.js';
+export { EmailEndpoint, type EmailEndpointOptions, } from './endpoint.js';
+export { defaultCreateImap, defaultCreateSmtp, type EmailImapFetchMessage, type EmailImapTransport, type EmailSmtpTransport, } from './transport.js';