@zhin.js/adapter-email 1.0.0 → 1.1.0

package/src/protocol.ts

@@ -0,0 +1,384 @@
+/**
+ * Email SMTP/IMAP helpers (no legacy Adapter/Endpoint / segment-mapper).
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+
+import type { Attachment } from 'mailparser';
+import { htmlToPlainTextWithBlockBreaks, isMediaRef, type MediaRef } from '@zhin.js/core';
+import type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationRef } from '@zhin.js/im-contract';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('email');
+
+export interface SmtpConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly secure: boolean;
+  readonly auth: {
+    readonly user: string;
+    readonly pass: string;
+  };
+}
+
+export interface ImapConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly tls: boolean;
+  readonly user: string;
+  readonly password: string;
+  readonly checkInterval?: number;
+  /** IMAP 断线重连基础间隔（指数退避基数），毫秒。 */
+  readonly reconnectInterval?: number;
+  readonly mailbox?: string;
+  readonly markSeen?: boolean;
+}
+
+export interface EmailAttachmentsConfig {
+  readonly enabled: boolean;
+  readonly downloadPath?: string;
+  readonly maxFileSize?: number;
+  readonly allowedTypes?: readonly string[];
+}
+
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface EmailAdapterConfig {
+  readonly id?: string;
+  readonly smtp?: SmtpConfig;
+  readonly imap?: ImapConfig;
+  readonly attachments?: EmailAttachmentsConfig;
+  /** Transitional: legacy root `endpoints[]` with `context: email`. */
+  readonly endpoints?: ReadonlyArray<Partial<ResolvedEmailConfig> & {
+    readonly context?: string;
+  }>;
+}
+
+export interface ResolvedEmailConfig {
+  readonly context: 'email';
+  readonly id: string;
+  readonly smtp: SmtpConfig;
+  readonly imap: Required<Pick<ImapConfig, 'checkInterval' | 'reconnectInterval' | 'mailbox' | 'markSeen'>> & ImapConfig;
+  readonly attachments?: {
+    readonly enabled: boolean;
+    readonly downloadPath: string;
+    readonly maxFileSize: number;
+    readonly allowedTypes?: readonly string[];
+  };
+}
+
+export interface EmailMessage {
+  readonly messageId: string;
+  readonly from: string;
+  readonly to: readonly string[];
+  readonly cc?: readonly string[];
+  readonly bcc?: readonly string[];
+  readonly subject: string;
+  readonly text?: string;
+  readonly html?: string;
+  readonly attachments: readonly Attachment[];
+  readonly date: Date;
+  readonly uid: number;
+}
+
+export interface EmailWireSegment {
+  readonly type: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export function resolveEmailConfig(config: EmailAdapterConfig = {}): ResolvedEmailConfig {
+  const entry = config.endpoints?.find((item) => item.context === 'email');
+  const smtp = config.smtp ?? entry?.smtp;
+  const imap = config.imap ?? entry?.imap;
+  if (!smtp?.host || !smtp.auth?.user || !imap?.host || !imap.user) {
+    throw new TypeError(
+      'Email adapter requires smtp + imap config (plugins.<key>.smtp/imap or endpoints with context: email)',
+    );
+  }
+  const id = (typeof config.id === 'string' && config.id)
+    || (typeof entry?.id === 'string' && entry.id)
+    || process.env.EMAIL_BOT_NAME
+    || 'email-bot';
+  const attachmentsSource = config.attachments ?? entry?.attachments;
+  const attachments = attachmentsSource?.enabled
+    ? {
+      enabled: true as const,
+      downloadPath: attachmentsSource.downloadPath || './downloads/email',
+      maxFileSize: Math.max(attachmentsSource.maxFileSize || 10 * 1024 * 1024, 1),
+      allowedTypes: attachmentsSource.allowedTypes,
+    }
+    : undefined;
+  return {
+    context: 'email',
+    id,
+    smtp,
+    imap: {
+      ...imap,
+      // 数值下限：0/负数会导致 setInterval(0) 风暴
+      checkInterval: Math.max(imap.checkInterval ?? 60_000, 1_000),
+      reconnectInterval: Math.max(imap.reconnectInterval ?? 5_000, 1_000),
+      mailbox: imap.mailbox ?? 'INBOX',
+      markSeen: imap.markSeen !== false,
+    },
+    attachments,
+  };
+}
+
+export function htmlToText(html: string): string {
+  return htmlToPlainTextWithBlockBreaks(html);
+}
+
+export function addressListText(addr: unknown): string[] {
+  if (!addr) return [];
+  if (Array.isArray(addr)) {
+    return addr.map((item) => addressText(item));
+  }
+  return [addressText(addr)];
+}
+
+function addressText(addr: unknown): string {
+  if (!addr || typeof addr !== 'object') return String(addr ?? '');
+  const record = addr as { text?: string; address?: string };
+  return record.text || record.address || String(addr);
+}
+
+export function parseEmailMessage(
+  parsed: {
+    messageId?: string;
+    from?: unknown;
+    to?: unknown;
+    cc?: unknown;
+    bcc?: unknown;
+    subject?: string;
+    text?: string;
+    html?: string | false;
+    attachments?: Attachment[];
+    date?: Date;
+  },
+  uid: number,
+): EmailMessage {
+  return {
+    messageId: parsed.messageId || '',
+    from: parsed.from ? addressListText(parsed.from)[0] || '' : '',
+    to: addressListText(parsed.to),
+    cc: addressListText(parsed.cc),
+    bcc: addressListText(parsed.bcc),
+    subject: parsed.subject || '',
+    text: parsed.text || '',
+    html: parsed.html ? String(parsed.html) : '',
+    attachments: parsed.attachments || [],
+    date: parsed.date || new Date(),
+    uid,
+  };
+}
+
+/** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */
+export function formatInboundContent(email: EmailMessage): string {
+  const parts: string[] = [];
+  if (email.subject) parts.push(`Subject: ${email.subject}`, '');
+  if (email.text) {
+    parts.push(email.text);
+  } else if (email.html) {
+    const fromHtml = htmlToText(email.html);
+    if (fromHtml) parts.push(fromHtml);
+  }
+  for (const attachment of email.attachments) {
+    const kind = attachment.contentType?.startsWith('image/') ? 'image' : 'file';
+    const name = attachment.filename || 'attachment';
+    parts.push(`[${kind}: ${name}]`);
+  }
+  const text = parts.join('\n').trim();
+  return text || '(Empty email)';
+}
+
+/** 已落盘的入站附件（attachments.enabled 下载结果）。 */
+export interface SavedEmailAttachment {
+  readonly filename: string;
+  readonly path: string;
+  readonly contentType?: string;
+  readonly size?: number;
+}
+
+/**
+ * 入站邮件 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 已落盘附件映射为 image/file 段，MediaRef kind=path 指向下载路径；
+ * 未下载的附件（disabled / 被过滤）只保留 content 里的占位文本。
+ */
+export function formatInboundSegments(
+  email: EmailMessage,
+  savedAttachments: readonly SavedEmailAttachment[] = [],
+): Segment[] {
+  const out: Segment[] = [];
+  const content = formatInboundContent(email);
+  if (content) out.push({ type: 'text', data: { text: content } });
+  for (const saved of savedAttachments) {
+    const type = saved.contentType?.startsWith('image/') ? 'image' : 'file';
+    out.push({
+      type,
+      data: {
+        media: {
+          kind: 'path',
+          value: saved.path,
+          ...(saved.contentType ? { mime_type: saved.contentType } : {}),
+        },
+        name: saved.filename,
+        ...(type === 'image' ? { alt: saved.filename } : {}),
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * 入站归一化 → ConversationRef：Email 无群/频道概念，所有入站邮件都是
+ * 与发件人地址的 private 会话（id = 发件人地址）。
+ */
+export function emailInboundConversation(endpointKey: string, email: EmailMessage): ConversationRef {
+  return {
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    kind: 'private',
+    id: email.from,
+  };
+}
+
+export function senderDisplayName(from: string): string {
+  const name = from.split('<')[0]?.trim();
+  return name || from;
+}
+
+/**
+ * nodemailer 附件的最小形状：url/path 走 `path`（URL 由 nodemailer 拉流、
+ * 本地路径读盘），base64 走 `content` + `encoding: 'base64'` 直发。
+ */
+export type EmailOutboundAttachment =
+  | { filename: string; path: string }
+  | { filename: string; content: string; encoding: 'base64' };
+
+/**
+ * image/audio/video/file 段 → nodemailer 附件（canonical MediaRef 唯一来源）：
+ * - kind=url / path → attachment.path；
+ * - kind=base64 → attachment.content（data: URL 前缀剥离）；
+ * - kind=file（平台不透明引用）邮件无对应概念，丢弃留痕；
+ * - 缺 media 同样 warn + 丢弃。
+ */
+function mediaSegmentToAttachment(
+  type: string,
+  data: Record<string, unknown>,
+): EmailOutboundAttachment | null {
+  const media = data.media;
+  if (!isMediaRef(media)) {
+    logger.warn(formatCompact({
+      op: 'email_outbound_media_dropped',
+      type,
+      reason: 'missing_media_ref',
+    }));
+    return null;
+  }
+  if (media.kind === 'file') {
+    logger.warn(formatCompact({
+      op: 'email_outbound_media_dropped',
+      type,
+      reason: 'unsupported_kind',
+      kind: media.kind,
+    }));
+    return null;
+  }
+  const filename = attachmentFileName(type, data, media);
+  if (media.kind === 'base64') {
+    const value = media.value.startsWith('data:')
+      ? media.value.slice(media.value.indexOf(',') + 1)
+      : media.value;
+    return { filename, content: value, encoding: 'base64' };
+  }
+  return { filename, path: media.value };
+}
+
+function attachmentFileName(
+  type: string,
+  data: Record<string, unknown>,
+  media: MediaRef,
+): string {
+  if (media.file_name) return media.file_name;
+  if (typeof data.name === 'string' && data.name) return data.name;
+  if (typeof data.alt === 'string' && data.alt) return data.alt;
+  return type === 'image' ? 'image.png' : 'file';
+}
+
+/**
+ * Wire-encode an already-rendered outbound payload into nodemailer options.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundMail(
+  payload: unknown,
+  options: { readonly from: string; readonly to: string; readonly subject?: string },
+): {
+  from: string;
+  to: string;
+  subject: string;
+  text?: string;
+  html?: string;
+  attachments?: EmailOutboundAttachment[];
+} {
+  const mail = {
+    from: options.from,
+    to: options.to,
+    subject: options.subject ?? 'Message from Bot',
+  };
+
+  if (typeof payload === 'string') {
+    return { ...mail, text: payload };
+  }
+
+  const segments: Array<string | EmailWireSegment> = Array.isArray(payload)
+    ? payload as Array<string | EmailWireSegment>
+    : payload && typeof payload === 'object' && 'type' in (payload as object)
+      ? [payload as EmailWireSegment]
+      : [];
+
+  if (segments.length === 0) {
+    return {
+      ...mail,
+      text: payload == null ? '' : typeof payload === 'object'
+        ? JSON.stringify(payload)
+        : String(payload),
+    };
+  }
+
+  const textParts: string[] = [];
+  const htmlParts: string[] = [];
+  const attachments: EmailOutboundAttachment[] = [];
+
+  for (const item of segments) {
+    if (typeof item === 'string') {
+      textParts.push(item);
+      htmlParts.push(item.replace(/\n/g, '<br>'));
+      continue;
+    }
+    const data = item.data ?? {};
+    switch (item.type) {
+      case 'text': {
+        const textContent = String(data.text ?? data.content ?? '');
+        textParts.push(textContent);
+        htmlParts.push(textContent.replace(/\n/g, '<br>'));
+        break;
+      }
+      case 'image':
+      case 'audio':
+      case 'video':
+      case 'file': {
+        const attachment = mediaSegmentToAttachment(item.type, data);
+        if (attachment) attachments.push(attachment);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  return {
+    ...mail,
+    ...(textParts.length > 0
+      ? { text: textParts.join('\n'), html: htmlParts.join('<br>') }
+      : {}),
+    ...(attachments.length > 0 ? { attachments } : {}),
+  };
+}

package/src/transport.ts

@@ -0,0 +1,65 @@
+/**
+ * Email SMTP/IMAP transport factories (nodemailer + imap).
+ */
+import nodemailer from 'nodemailer';
+import Imap from 'imap';
+import type { ResolvedEmailConfig } from './protocol.js';
+
+export interface EmailSmtpTransport {
+  verify(): Promise<void>;
+  sendMail(options: unknown): Promise<{ messageId?: string }>;
+  close(): void;
+}
+
+export interface EmailImapTransport {
+  once(event: 'ready' | 'error', listener: (...args: unknown[]) => void): void;
+  on(event: string, listener: (...args: unknown[]) => void): void;
+  connect(): void;
+  end(): void;
+  openBox(
+    mailbox: string,
+    openReadWrite: boolean,
+    callback: (error: Error | null, box?: unknown) => void,
+  ): void;
+  search(
+    criteria: string[],
+    callback: (error: Error | null, results: number[]) => void,
+  ): void;
+  fetch(
+    results: number[],
+    options: { bodies: string; markSeen?: boolean },
+  ): {
+    on(event: 'message', listener: (msg: EmailImapFetchMessage, seqno: number) => void): void;
+    once(event: 'error' | 'end', listener: (error?: Error) => void): void;
+  };
+}
+
+export interface EmailImapFetchMessage {
+  on(event: 'body', listener: (stream: NodeJS.ReadableStream) => void): void;
+  once(event: 'attributes', listener: (attrs: { uid?: number }) => void): void;
+  once(event: 'end', listener: () => void): void;
+}
+
+export function defaultCreateSmtp(config: ResolvedEmailConfig['smtp']): EmailSmtpTransport {
+  const transporter = nodemailer.createTransport({
+    host: config.host,
+    port: config.port,
+    secure: config.secure,
+    auth: { user: config.auth.user, pass: config.auth.pass },
+  });
+  return {
+    verify: () => transporter.verify().then(() => undefined),
+    sendMail: (options) => transporter.sendMail(options as nodemailer.SendMailOptions),
+    close: () => transporter.close(),
+  };
+}
+
+export function defaultCreateImap(config: ResolvedEmailConfig['imap']): EmailImapTransport {
+  return new Imap({
+    user: config.user,
+    password: config.password,
+    host: config.host,
+    port: config.port,
+    tls: config.tls,
+  }) as unknown as EmailImapTransport;
+}

package/lib/adapter.d.ts

@@ -1,11 +0,0 @@
-/**
- * Email 适配器
- */
-import { Adapter, Plugin } from "zhin.js";
-import { EmailBot } from "./bot.js";
-import type { EmailBotConfig } from "./types.js";
-export declare class EmailAdapter extends Adapter<EmailBot> {
-    constructor(plugin: Plugin);
-    createBot(config: EmailBotConfig): EmailBot;
-}
-//# sourceMappingURL=adapter.d.ts.map

package/lib/adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,qBAAa,YAAa,SAAQ,OAAO,CAAC,QAAQ,CAAC;gBACnC,MAAM,EAAE,MAAM;IAI1B,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ;CAG9C"}

package/lib/adapter.js

@@ -1,14 +0,0 @@
-/**
- * Email 适配器
- */
-import { Adapter } from "zhin.js";
-import { EmailBot } from "./bot.js";
-export class EmailAdapter extends Adapter {
-    constructor(plugin) {
-        super(plugin, 'email', []);
-    }
-    createBot(config) {
-        return new EmailBot(this, config);
-    }
-}
-//# sourceMappingURL=adapter.js.map

package/lib/adapter.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,OAAO,EAAU,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGpC,MAAM,OAAO,YAAa,SAAQ,OAAiB;IAC/C,YAAY,MAAc;QACtB,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,SAAS,CAAC,MAAsB;QAC5B,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;CACJ"}

package/lib/bot.d.ts

@@ -1,33 +0,0 @@
-import { Bot, Message, MessageSegment, SendOptions } from 'zhin.js';
-import { EventEmitter } from "events";
-import type { EmailBotConfig, EmailMessage } from "./types.js";
-import type { EmailAdapter } from "./adapter.js";
-export declare class EmailBot extends EventEmitter implements Bot<EmailBotConfig, EmailMessage> {
-    adapter: EmailAdapter;
-    $config: EmailBotConfig;
-    $connected: boolean;
-    private smtpTransporter;
-    private imapConnection;
-    private checkTimer;
-    get logger(): import("zhin.js").Logger;
-    get $id(): string;
-    constructor(adapter: EmailAdapter, config: EmailBotConfig);
-    $connect(): Promise<void>;
-    $disconnect(): Promise<void>;
-    private setupImapListeners;
-    private startEmailCheck;
-    private checkForNewEmails;
-    private handleImapMessage;
-    private parseEmailMessage;
-    $formatMessage(emailMsg: EmailMessage): Message<EmailMessage>;
-    static parseEmailContent(email: EmailMessage): MessageSegment[];
-    $sendMessage(options: SendOptions): Promise<string>;
-    $recallMessage(id: string): Promise<void>;
-    private formatSendContent;
-    private downloadAttachment;
-    /**
-     * HTML → 纯文本转换，处理常见标签和实体
-     */
-    static htmlToText(html: string): string;
-}
-//# sourceMappingURL=bot.d.ts.map

package/lib/bot.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAMA,OAAO,EAAiB,GAAG,EAAE,OAAO,EAAE,cAAc,EAAwB,WAAW,EAAkC,MAAM,SAAS,CAAC;AACzI,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,qBAAa,QAAS,SAAQ,YAAa,YAAW,GAAG,CAAC,cAAc,EAAE,YAAY,CAAC;IAehE,OAAO,EAAE,YAAY;IAdxC,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,OAAO,CAAS;IAC5B,OAAO,CAAC,eAAe,CAAuC;IAC9D,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,UAAU,CAA+B;IAEjD,IAAI,MAAM,6BAEX;IAED,IAAI,GAAG,WAEJ;gBAEkB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc;IAe1D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA6CzB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBlC,OAAO,CAAC,kBAAkB;IAiB1B,OAAO,CAAC,eAAe;YAWT,iBAAiB;IAoC/B,OAAO,CAAC,iBAAiB;IA0BzB,OAAO,CAAC,iBAAiB;IAwBzB,cAAc,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAwC7D,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,EAAE;IAyCzD,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBnD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAIjC,iBAAiB;YA+DjB,kBAAkB;IAqBhC;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAG1C"}