@zhin.js/adapter-email 1.0.0 → 1.1.0

package/lib/client.js

@@ -0,0 +1,29 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+/** Live SMTP + IMAP client pair exposed to event handlers and plugins. */
+export class EmailClient {
+    resolveSmtp;
+    resolveImap;
+    constructor(resolveSmtp, resolveImap) {
+        this.resolveSmtp = resolveSmtp;
+        this.resolveImap = resolveImap;
+    }
+    get smtp() {
+        const transport = this.resolveSmtp();
+        if (!transport)
+            throw new Error('SMTP transporter not connected');
+        return transport;
+    }
+    get imap() {
+        const transport = this.resolveImap();
+        if (!transport)
+            throw new Error('IMAP client not connected');
+        return transport;
+    }
+    verify() {
+        return this.smtp.verify();
+    }
+    sendMail(options) {
+        return this.smtp.sendMail(options);
+    }
+}
+export const emailClient = defineEndpointClient('email');

package/lib/endpoint.d.ts

@@ -0,0 +1,28 @@
+import { Endpoint } from 'zhin.js/adapter';
+import { type EndpointSendRequest } from 'zhin.js/adapter';
+import type { CapabilityId } from 'zhin.js';
+import { type EmailMessage, type ResolvedEmailConfig } from './protocol.js';
+import { 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 declare class EmailEndpoint extends Endpoint<EmailClient> {
+    #private;
+    readonly client: EmailClient;
+    constructor(options: EmailEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    /** Test / internal: admit a parsed mail when the endpoint is open. */
+    admit(email: EmailMessage): void;
+}

package/lib/endpoint.js

@@ -0,0 +1,335 @@
+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 { 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.#logger = getAdapterLogger('email', options.config.id);
+        this.#options = options;
+        this.client = new EmailClient(() => this.#smtp, () => this.#imap);
+    }
+    async start() {
+        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((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() {
+        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;
+        }
+        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 }) {
+        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;
+        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) {
+        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) {
+        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),
+            }));
+        });
+    }
+    /** 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;
+        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() {
+        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) => {
+                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.#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, _seqno) {
+        let body = '';
+        let uid = 0;
+        msg.on('body', (stream) => {
+            stream.on('data', (chunk) => {
+                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/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 { EmailBot } from "./bot.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';

package/lib/index.js

@@ -1,23 +1,4 @@
-/**
- * Email 适配器入口：类型扩展、导出、注册
- */
-import { usePlugin } from "zhin.js";
-import { EmailAdapter } from "./adapter.js";
-export * from "./types.js";
-export { EmailBot } from "./bot.js";
-export { EmailAdapter } from "./adapter.js";
-const plugin = usePlugin();
-const { provide } = plugin;
-provide({
-    name: "email",
-    description: "Email Bot Adapter",
-    mounted: async (p) => {
-        const adapter = new EmailAdapter(p);
-        await adapter.start();
-        return adapter;
-    },
-    dispose: async (adapter) => {
-        await adapter.stop();
-    },
-});
-//# sourceMappingURL=index.js.map
+export { addressListText, emailInboundConversation, formatInboundContent, formatInboundSegments, formatOutboundMail, htmlToText, parseEmailMessage, resolveEmailConfig, senderDisplayName, } from './protocol.js';
+export { EmailClient, emailClient, } from './client.js';
+export { EmailEndpoint, } from './endpoint.js';
+export { defaultCreateImap, defaultCreateSmtp, } from './transport.js';

package/lib/protocol.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 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 type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationRef } from '@zhin.js/im-contract';
+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 declare function resolveEmailConfig(config?: EmailAdapterConfig): ResolvedEmailConfig;
+export declare function htmlToText(html: string): string;
+export declare function addressListText(addr: unknown): string[];
+export declare 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;
+/** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */
+export declare function formatInboundContent(email: EmailMessage): string;
+/** 已落盘的入站附件（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 declare function formatInboundSegments(email: EmailMessage, savedAttachments?: readonly SavedEmailAttachment[]): Segment[];
+/**
+ * 入站归一化 → ConversationRef：Email 无群/频道概念，所有入站邮件都是
+ * 与发件人地址的 private 会话（id = 发件人地址）。
+ */
+export declare function emailInboundConversation(endpointKey: string, email: EmailMessage): ConversationRef;
+export declare function senderDisplayName(from: string): string;
+/**
+ * nodemailer 附件的最小形状：url/path 走 `path`（URL 由 nodemailer 拉流、
+ * 本地路径读盘），base64 走 `content` + `encoding: 'base64'` 直发。
+ */
+export type EmailOutboundAttachment = {
+    filename: string;
+    path: string;
+} | {
+    filename: string;
+    content: string;
+    encoding: 'base64';
+};
+/**
+ * Wire-encode an already-rendered outbound payload into nodemailer options.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare 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[];
+};