@zhin.js/adapter-email 1.0.0 → 1.1.0

package/src/endpoint.ts

@@ -0,0 +1,364 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * EmailEndpoint — lifecycle, SMTP outbound, IMAP inbound polling.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { simpleParser } from 'mailparser';
+import { type EndpointSendRequest } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import type { CapabilityId } from 'zhin.js';
+import {
+  emailInboundConversation,
+  formatInboundContent,
+  formatInboundSegments,
+  formatOutboundMail,
+  parseEmailMessage,
+  senderDisplayName,
+  type EmailMessage,
+  type ResolvedEmailConfig,
+  type SavedEmailAttachment,
+} from './protocol.js';
+import {
+  defaultCreateImap,
+  defaultCreateSmtp,
+  type EmailImapFetchMessage,
+  type EmailImapTransport,
+  type EmailSmtpTransport,
+} from './transport.js';
+import { EmailClient } from './client.js';
+
+export interface EmailEndpointOptions {
+  readonly id: CapabilityId;
+  readonly config: ResolvedEmailConfig;
+  readonly createSmtp?: (config: ResolvedEmailConfig['smtp']) => EmailSmtpTransport | Promise<EmailSmtpTransport>;
+  readonly createImap?: (config: ResolvedEmailConfig['imap']) => EmailImapTransport;
+}
+
+/**
+ * Email（SMTP/IMAP）无好友/群/频道等社交图谱概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
+export class EmailEndpoint extends Endpoint<EmailClient> {
+  readonly client: EmailClient;
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
+  readonly #options: EmailEndpointOptions;
+  #smtp: EmailSmtpTransport | null = null;
+  #imap: EmailImapTransport | null = null;
+  #checkTimer: NodeJS.Timeout | null = null;
+  #reconnectTimer: NodeJS.Timeout | null = null;
+  #reconnectAttempts = 0;
+  #checking = false;
+  #open = false;
+  #started = false;
+
+  constructor(options: EmailEndpointOptions) {
+    super();
+    this.#logger = getAdapterLogger('email', options.config.id);
+    this.#options = options;
+    this.client = new EmailClient(() => this.#smtp, () => this.#imap);
+  }
+
+  async start(): Promise<void> {
+    if (this.#started) return;
+    this.#started = true;
+    const { smtp, imap, id } = this.#options.config;
+    try {
+      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<void>((resolve, reject) => {
+        this.#imap!.once('ready', () => {
+          void this.#emitPlatformEvent('imap.ready', Object.freeze({}));
+          resolve();
+        });
+        this.#imap!.once('error', (error) => reject(error));
+        this.#imap!.connect();
+      });
+      this.#logger.debug(formatCompact({ mode: 'imap' }));
+      this.#reconnectAttempts = 0;
+      this.#startEmailCheck();
+    } catch (error) {
+      await this.stop();
+      this.#logger.error('Failed to connect email services:', error);
+      throw error;
+    }
+  }
+
+  open(): void {
+    this.#open = true;
+  }
+
+  close(): void {
+    this.#open = false;
+  }
+
+  async stop(): Promise<void> {
+    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;
+    }
+    if (this.#imap) {
+      try {
+        this.#imap.end();
+      } catch {
+        /* ignore */
+      }
+      this.#imap = null;
+    }
+    if (this.#smtp) {
+      try {
+        this.#smtp.close();
+      } catch {
+        /* ignore */
+      }
+      this.#smtp = null;
+    }
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
+  }
+
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+    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: EmailMessage): void {
+    if (!this.#open) return;
+    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),
+      }));
+    });
+  }
+
+  async #admitWithAttachments(email: EmailMessage): Promise<void> {
+    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 } : {}),
+      }),
+    });
+  }
+
+  /**
+   * attachments.enabled 时把入站附件落盘（恢复旧 downloadAttachment 行为，
+   * 附加 maxFileSize / allowedTypes 过滤）；返回落盘结果供 admit segments/metadata 使用。
+   */
+  async #downloadAttachments(
+    email: EmailMessage,
+  ): Promise<SavedEmailAttachment[]> {
+    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: SavedEmailAttachment[] = [];
+    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: EmailImapTransport): void {
+    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: string, event: unknown): Promise<void> {
+    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),
+      }));
+    });
+  }
+
+  /** IMAP 断线后按指数退避重建连接并恢复监听（基数 reconnectInterval，封顶 5 分钟）。 */
+  #scheduleImapReconnect(source?: EmailImapTransport): void {
+    // 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;
+    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 #reconnectImap(): Promise<void> {
+    if (!this.#started) return;
+    let imap: EmailImapTransport | undefined;
+    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<void>((resolve, reject) => {
+        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(): void {
+    if (this.#checkTimer) return;
+    this.#checkTimer = setInterval(() => {
+      void this.#checkForNewEmails();
+    }, this.#options.config.imap.checkInterval);
+    void this.#checkForNewEmails();
+  }
+
+  async #checkForNewEmails(): Promise<void> {
+    if (!this.#imap || !this.#started || this.#checking) return;
+    // 在飞锁：定时器与 mail 事件可能并发触发，串行化避免重复 admit
+    this.#checking = true;
+    try {
+      await new Promise<void>((resolve, reject) => {
+        this.#imap!.openBox(this.#options.config.imap.mailbox, false, (error) => {
+          if (error) return reject(error);
+          this.#imap!.search(['UNSEEN'], (searchError, results) => {
+            if (searchError) return reject(searchError);
+            if (!results.length) return resolve();
+            const fetch = this.#imap!.fetch(results, {
+              bodies: '',
+              markSeen: this.#options.config.imap.markSeen,
+            });
+            fetch.on('message', (msg, seqno) => {
+              this.#handleImapMessage(msg, seqno);
+            });
+            fetch.once('error', (fetchError) => reject(fetchError));
+            fetch.once('end', () => resolve());
+          });
+        });
+      });
+    } catch (error) {
+      this.#logger.error('Error checking for new emails:', error);
+    } finally {
+      this.#checking = false;
+    }
+  }
+
+  #handleImapMessage(msg: EmailImapFetchMessage, _seqno: number): void {
+    let body = '';
+    let uid = 0;
+    msg.on('body', (stream) => {
+      stream.on('data', (chunk: Buffer | string) => {
+        body += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+      });
+    });
+    msg.once('attributes', (attrs) => {
+      uid = attrs.uid ?? 0;
+    });
+    msg.once('end', () => {
+      void simpleParser(body).then((parsed) => {
+        this.admit(parseEmailMessage(parsed, uid));
+      }).catch((error) => {
+        this.#logger.error('Error parsing email:', error);
+      });
+    });
+  }
+}

package/src/index.ts

@@ -1,31 +1,38 @@
-/**
- * Email 适配器入口：类型扩展、导出、注册
- */
-import { usePlugin, type Plugin, type Context } from "zhin.js";
-import { EmailAdapter } from "./adapter.js";
+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';
 
-declare module "zhin.js" {
-  interface Adapters {
-    email: EmailAdapter;
-  }
-}
+export {
+  EmailClient,
+  emailClient,
+  type EmailClientEventMap,
+} from './client.js';
 
-export * from "./types.js";
-export { EmailBot } from "./bot.js";
-export { EmailAdapter } from "./adapter.js";
+export {
+  EmailEndpoint,
+  type EmailEndpointOptions,
+} from './endpoint.js';
 
-const plugin = usePlugin();
-const { provide } = plugin;
-
-provide({
-  name: "email",
-  description: "Email Bot Adapter",
-  mounted: async (p: Plugin) => {
-    const adapter = new EmailAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: EmailAdapter) => {
-    await adapter.stop();
-  },
-} as Context<"email">);
+export {
+  defaultCreateImap,
+  defaultCreateSmtp,
+  type EmailImapFetchMessage,
+  type EmailImapTransport,
+  type EmailSmtpTransport,
+} from './transport.js';