@zhin.js/adapter-email 1.0.0 → 1.1.0

package/lib/protocol.js

@@ -0,0 +1,245 @@
+/**
+ * Email SMTP/IMAP helpers (no legacy Adapter/Endpoint / segment-mapper).
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { htmlToPlainTextWithBlockBreaks, isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('email');
+export function resolveEmailConfig(config = {}) {
+    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,
+            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) {
+    return htmlToPlainTextWithBlockBreaks(html);
+}
+export function addressListText(addr) {
+    if (!addr)
+        return [];
+    if (Array.isArray(addr)) {
+        return addr.map((item) => addressText(item));
+    }
+    return [addressText(addr)];
+}
+function addressText(addr) {
+    if (!addr || typeof addr !== 'object')
+        return String(addr ?? '');
+    const record = addr;
+    return record.text || record.address || String(addr);
+}
+export function parseEmailMessage(parsed, uid) {
+    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) {
+    const parts = [];
+    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)';
+}
+/**
+ * 入站邮件 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 已落盘附件映射为 image/file 段，MediaRef kind=path 指向下载路径；
+ * 未下载的附件（disabled / 被过滤）只保留 content 里的占位文本。
+ */
+export function formatInboundSegments(email, savedAttachments = []) {
+    const out = [];
+    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, email) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: 'private',
+        id: email.from,
+    };
+}
+export function senderDisplayName(from) {
+    const name = from.split('<')[0]?.trim();
+    return name || from;
+}
+/**
+ * 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, data) {
+    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, data, media) {
+    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, options) {
+    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.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (segments.length === 0) {
+        return {
+            ...mail,
+            text: payload == null ? '' : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload),
+        };
+    }
+    const textParts = [];
+    const htmlParts = [];
+    const attachments = [];
+    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/lib/transport.d.ts

@@ -0,0 +1,32 @@
+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 declare function defaultCreateSmtp(config: ResolvedEmailConfig['smtp']): EmailSmtpTransport;
+export declare function defaultCreateImap(config: ResolvedEmailConfig['imap']): EmailImapTransport;

package/lib/transport.js

@@ -0,0 +1,27 @@
+/**
+ * Email SMTP/IMAP transport factories (nodemailer + imap).
+ */
+import nodemailer from 'nodemailer';
+import Imap from 'imap';
+export function defaultCreateSmtp(config) {
+    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),
+        close: () => transporter.close(),
+    };
+}
+export function defaultCreateImap(config) {
+    return new Imap({
+        user: config.user,
+        password: config.password,
+        host: config.host,
+        port: config.port,
+        tls: config.tls,
+    });
+}

package/package.json

@@ -1,25 +1,38 @@
 {
   "name": "@zhin.js/adapter-email",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
-  "description": "Zhin.js adapter for Email (SMTP/IMAP)",
+  "description": "Zhin.js Email adapter for Plugin Runtime (SMTP/IMAP)",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "dependencies": {
     "imap": "^0.8.19",
-    "mailparser": "^3.9.9",
-    "nodemailer": "^8.0.10"
+    "mailparser": "^3.9.14",
+    "nodemailer": "^9.0.3",
+    "@zhin.js/adapter": "1.1.12",
+    "@zhin.js/core": "1.1.35",
+    "@zhin.js/feature-kit": "1.1.0",
+    "@zhin.js/im-contract": "1.1.0",
+    "@zhin.js/logger": "1.1.0"
   },
   "peerDependencies": {
-    "zhin.js": "2.0.0"
+    "@zhin.js/adapter": "^1.1.12",
+    "@zhin.js/core": "^1.1.35",
+    "zhin.js": "^1.1.0"
+  },
+  "peerDependenciesMeta": {
+    "zhin.js": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@types/imap": "^0.8.40",
+    "@types/imap": "^0.8.43",
     "@types/mailparser": "^3.4.6",
-    "@types/node": "^25.9.1",
-    "@types/nodemailer": "^8.0.0",
+    "@types/node": "^26.1.2",
+    "@types/nodemailer": "^8.0.1",
     "typescript": "^6.0.3",
-    "zhin.js": "2.0.0"
+    "vitest": "^4.1.10",
+    "zhin.js": "1.1.0"
   },
   "keywords": [
     "zhin",
@@ -43,9 +56,12 @@
     "directory": "plugins/adapters/email"
   },
   "files": [
+    "adapters",
+    "plugin.js",
+    "schema.json",
     "src",
     "lib",
-    "skills",
+    "agent",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -60,9 +76,26 @@
       "import": "./lib/index.js"
     }
   },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "pnpm build:node",
+    "build": "tsc",
     "clean": "rimraf lib",
-    "build:node": "tsc"
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/email/tests"
   }
 }

package/plugin.js

@@ -0,0 +1,8 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { definePlugin } from 'zhin.js';
+export default definePlugin({
+    name: 'email',
+    metadata: {
+        displayName: 'Email Adapter',
+    },
+});

package/schema.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（email address；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted email address"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（email address）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted email address"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "smtp": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "host": {
+                "type": "string"
+              },
+              "port": {
+                "type": "number"
+              },
+              "secure": {
+                "type": "boolean"
+              },
+              "auth": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "user": {
+                    "type": "string"
+                  },
+                  "pass": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "user",
+                  "pass"
+                ]
+              }
+            },
+            "required": [
+              "host",
+              "port",
+              "secure",
+              "auth"
+            ]
+          },
+          "imap": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "host": {
+                "type": "string"
+              },
+              "port": {
+                "type": "number"
+              },
+              "tls": {
+                "type": "boolean"
+              },
+              "user": {
+                "type": "string"
+              },
+              "password": {
+                "type": "string"
+              },
+              "checkInterval": {
+                "type": "number",
+                "default": 60000
+              },
+              "mailbox": {
+                "type": "string",
+                "default": "INBOX"
+              },
+              "markSeen": {
+                "type": "boolean",
+                "default": true
+              }
+            },
+            "required": [
+              "host",
+              "port",
+              "tls",
+              "user",
+              "password"
+            ]
+          },
+          "attachments": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": false
+              },
+              "downloadPath": {
+                "type": "string"
+              },
+              "maxFileSize": {
+                "type": "number"
+              },
+              "allowedTypes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "id": {
+            "type": "string",
+            "description": "Email bot name"
+          }
+        },
+        "required": [
+          "id",
+          "smtp",
+          "imap"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,40 @@
+import type { EmailImapTransport, EmailSmtpTransport } from './transport.js';
+import { defineEndpointClient } from 'zhin.js/adapter';
+
+/** Live SMTP + IMAP client pair exposed to event handlers and plugins. */
+export class EmailClient {
+  constructor(
+    private readonly resolveSmtp: () => EmailSmtpTransport | null,
+    private readonly resolveImap: () => EmailImapTransport | null,
+  ) {}
+
+  get smtp(): EmailSmtpTransport {
+    const transport = this.resolveSmtp();
+    if (!transport) throw new Error('SMTP transporter not connected');
+    return transport;
+  }
+
+  get imap(): EmailImapTransport {
+    const transport = this.resolveImap();
+    if (!transport) throw new Error('IMAP client not connected');
+    return transport;
+  }
+
+  verify(): Promise<void> {
+    return this.smtp.verify();
+  }
+
+  sendMail(options: unknown): Promise<{ messageId?: string }> {
+    return this.smtp.sendMail(options);
+  }
+}
+
+export type EmailClientEventMap = Record<string, unknown>;
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly email: { readonly client: EmailClient; readonly events: EmailClientEventMap };
+  }
+}
+
+export const emailClient = defineEndpointClient<EmailClient, EmailClientEventMap>('email');