@zhin.js/adapter-email 3.0.2 → 3.0.3

package/lib/protocol.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Email SMTP/IMAP helpers (no legacy Adapter/Endpoint / segment-mapper).
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import type { Attachment } from 'mailparser';
+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;
+    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 name?: 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 name: string;
+    readonly smtp: SmtpConfig;
+    readonly imap: Required<Pick<ImapConfig, 'checkInterval' | '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 MessageGateway.receive (gateway owns reply routing). */
+export declare function formatInboundContent(email: EmailMessage): string;
+export declare function senderDisplayName(from: string): string;
+/**
+ * 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?: Array<{
+        filename: string;
+        path: string;
+    }>;
+};

package/lib/protocol.js

@@ -0,0 +1,160 @@
+/**
+ * Email SMTP/IMAP helpers (no legacy Adapter/Endpoint / segment-mapper).
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { htmlToPlainTextWithBlockBreaks } from '@zhin.js/core';
+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 name = (typeof config.name === 'string' && config.name)
+        || (typeof entry?.name === 'string' && entry.name)
+        || 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: attachmentsSource.maxFileSize || 10 * 1024 * 1024,
+            allowedTypes: attachmentsSource.allowedTypes,
+        }
+        : undefined;
+    return {
+        context: 'email',
+        name,
+        smtp,
+        imap: {
+            ...imap,
+            checkInterval: imap.checkInterval ?? 60_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 MessageGateway.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)';
+}
+export function senderDisplayName(from) {
+    const name = from.split('<')[0]?.trim();
+    return name || from;
+}
+/**
+ * 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 'file': {
+                if (typeof data.url === 'string' && data.url) {
+                    attachments.push({
+                        filename: String(data.filename || (item.type === 'image' ? 'image.png' : 'file')),
+                        path: data.url,
+                    });
+                }
+                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,17 +1,29 @@
 {
   "name": "@zhin.js/adapter-email",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "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.14",
-    "nodemailer": "^9.0.3"
+    "nodemailer": "^9.0.3",
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/plugin-runtime": "1.0.1"
   },
   "peerDependencies": {
-    "zhin.js": "4.1.2"
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/plugin-runtime": "1.0.1",
+    "zhin.js": "4.1.3"
+  },
+  "peerDependenciesMeta": {
+    "zhin.js": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/imap": "^0.8.40",
@@ -19,7 +31,7 @@
     "@types/node": "^26.1.0",
     "@types/nodemailer": "^8.0.0",
     "typescript": "^6.0.3",
-    "zhin.js": "4.1.2"
+    "vitest": "^4.1.10"
   },
   "keywords": [
     "zhin",
@@ -43,6 +55,9 @@
     "directory": "plugins/adapters/email"
   },
   "files": [
+    "adapters",
+    "plugin.ts",
+    "schema.json",
     "src",
     "lib",
     "agent",
@@ -63,9 +78,23 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.ts",
+    "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.ts

@@ -0,0 +1,8 @@
+import { definePlugin } from '@zhin.js/plugin-runtime';
+
+export default definePlugin({
+  name: 'email',
+  metadata: {
+    displayName: 'Email Adapter',
+  },
+});

package/schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "default": "email-bot"
+    },
+    "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" }
+        }
+      }
+    }
+  }
+}