@zhin.js/adapter-email 6.0.0 → 6.0.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @zhin.js/adapter-email
 
+## 6.0.2
+
+### Patch Changes
+
+- Updated dependencies [ba7e17a]
+- Updated dependencies [7108d0b]
+  - @zhin.js/core@1.5.15
+  - zhin.js@6.0.15
+
+## 6.0.1
+
+### Patch Changes
+
+- e9c6a73: Ignore late disconnect events from replaced IMAP transports so reconnect does not leak duplicate connections.
+- 1fc78bc: Unify native platform Client access behind the literal `adapter` discriminant. Handlers infer both native events and Clients, while command, inbound/outbound middleware, and both Agent tool authoring surfaces expose the exact operation-scoped Client through a lazy `$client` getter. Definitions without `adapter` keep `$client` typed as `unknown`, and runtime dispatch rejects adapter mismatches before resolving the Client. Bundled platform tools now use this single path instead of model-provided endpoint ids and adapter-specific dependency wrappers. Every adapter registers one Client/EventMap contract, and protocol adapters including NapCat, Milky, OneBot and Satori now produce transport-independent Client objects rather than letting Endpoint instances impersonate Clients.
+- Updated dependencies [4e8117c]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @zhin.js/adapter@1.2.1
+  - @zhin.js/core@1.5.14
+  - @zhin.js/logger@1.0.77
+  - zhin.js@6.0.14
+  - @zhin.js/feature-kit@1.0.13
+
 ## 6.0.0
 
 ### Patch Changes

package/README.md

@@ -19,7 +19,7 @@ pnpm add @zhin.js/adapter-email
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/email.ts`（`defineAdapter`）
-- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`（`smtp` / `imap`）
 

package/adapters/email.js

@@ -3,7 +3,6 @@
  * Convention entry: discover `adapters/email.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { EmailEndpoint } from "../lib/endpoint.js";
 import { resolveEmailConfig, } from "../lib/protocol.js";
 export { EmailEndpoint } from "../lib/endpoint.js";
@@ -20,8 +19,6 @@ export default defineAdapter({
     create(context) {
         return new EmailEndpoint({
             id: context.id,
-            gateway: context.use(messageGatewayToken),
-            sideEvents: context.use(sideEventGatewayToken),
             config: resolveEmailConfig(context.config),
         });
     },

package/adapters/email.ts

@@ -2,7 +2,6 @@
  * Convention entry: discover `adapters/email.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { EmailEndpoint } from '../src/endpoint.js';
 import {
   resolveEmailConfig,
@@ -30,8 +29,6 @@ export default defineAdapter<EmailAdapterConfig>({
   create(context) {
     return new EmailEndpoint({
       id: context.id,
-      gateway: context.use(messageGatewayToken),
-      sideEvents: context.use(sideEventGatewayToken),
       config: resolveEmailConfig(context.config),
     });
   },

package/lib/client.d.ts

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

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

@@ -1,12 +1,11 @@
-import type { EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+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 gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly config: ResolvedEmailConfig;
     readonly createSmtp?: (config: ResolvedEmailConfig['smtp']) => EmailSmtpTransport | Promise<EmailSmtpTransport>;
     readonly createImap?: (config: ResolvedEmailConfig['imap']) => EmailImapTransport;
@@ -15,8 +14,9 @@ export interface EmailEndpointOptions {
  * Email（SMTP/IMAP）无好友/群/频道等社交图谱概念，
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
-export declare class EmailEndpoint implements EndpointInstance {
+export declare class EmailEndpoint extends Endpoint<EmailClient> {
     #private;
+    readonly client: EmailClient;
     constructor(options: EmailEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/endpoint.js

@@ -1,3 +1,4 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * EmailEndpoint — lifecycle, SMTP outbound, IMAP inbound polling.
  */
@@ -7,11 +8,13 @@ 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 {
+export class EmailEndpoint extends Endpoint {
+    client;
     #logger;
     #options;
     #smtp = null;
@@ -23,8 +26,10 @@ export class EmailEndpoint {
     #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)
@@ -38,7 +43,10 @@ export class EmailEndpoint {
             this.#imap = this.#options.createImap?.(imap) ?? defaultCreateImap(imap);
             this.#setupImapListeners(this.#imap);
             await new Promise((resolve, reject) => {
-                this.#imap.once('ready', () => resolve());
+                this.#imap.once('ready', () => {
+                    void this.#emitPlatformEvent('imap.ready', Object.freeze({}));
+                    resolve();
+                });
                 this.#imap.once('error', (error) => reject(error));
                 this.#imap.connect();
             });
@@ -91,14 +99,12 @@ export class EmailEndpoint {
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
-        if (!this.#smtp)
-            throw new Error('SMTP transporter not initialized');
         const target = conversation.id;
         const mailOptions = formatOutboundMail(payload, {
             from: this.#options.config.smtp.auth.user,
             to: target,
         });
-        const info = await this.#smtp.sendMail(mailOptions);
+        const info = await this.client.sendMail(mailOptions);
         this.#logger.debug(formatCompact({ op: 'email_send', target, messageId: info.messageId }));
         return info.messageId || '';
     }
@@ -106,6 +112,7 @@ export class EmailEndpoint {
     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',
@@ -119,7 +126,7 @@ export class EmailEndpoint {
         const content = formatInboundContent(email);
         const sender = email.from;
         const conversation = emailInboundConversation(String(this.#options.id), email);
-        await this.#options.gateway.receive({
+        await this.emit('message.receive', {
             conversation,
             ...(email.messageId ? { message: { conversation, id: email.messageId } } : {}),
             content,
@@ -180,24 +187,39 @@ export class EmailEndpoint {
     }
     #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();
+            this.#scheduleImapReconnect(imap);
         });
         imap.on('end', () => {
+            void this.#emitPlatformEvent('imap.end', Object.freeze({}));
             this.#logger.debug(formatCompact({
                 op: 'disconnect',
                 mode: 'imap',
             }));
-            this.#scheduleImapReconnect();
+            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() {
-        if (!this.#started || this.#reconnectTimer)
+    #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);
@@ -215,15 +237,20 @@ export class EmailEndpoint {
     async #reconnectImap() {
         if (!this.#started)
             return;
+        let imap;
         try {
-            const imap = this.#options.createImap?.(this.#options.config.imap)
+            const nextImap = this.#options.createImap?.(this.#options.config.imap)
                 ?? defaultCreateImap(this.#options.config.imap);
-            this.#imap = imap;
-            this.#setupImapListeners(imap);
+            imap = nextImap;
+            this.#imap = nextImap;
+            this.#setupImapListeners(nextImap);
             await new Promise((resolve, reject) => {
-                imap.once('ready', () => resolve());
-                imap.once('error', (error) => reject(error));
-                imap.connect();
+                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({
@@ -240,7 +267,7 @@ export class EmailEndpoint {
                 ok: false,
                 error: error instanceof Error ? error.message : String(error),
             }));
-            this.#scheduleImapReconnect();
+            this.#scheduleImapReconnect(imap);
         }
     }
     #startEmailCheck() {

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 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,3 +1,4 @@
 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

@@ -87,7 +87,7 @@ export declare function parseEmailMessage(parsed: {
     attachments?: Attachment[];
     date?: Date;
 }, uid: number): EmailMessage;
-/** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
+/** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */
 export declare function formatInboundContent(email: EmailMessage): string;
 /** 已落盘的入站附件（attachments.enabled 下载结果）。 */
 export interface SavedEmailAttachment {

package/lib/protocol.js

@@ -72,7 +72,7 @@ export function parseEmailMessage(parsed, uid) {
         uid,
     };
 }
-/** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
+/** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */
 export function formatInboundContent(email) {
     const parts = [];
     if (email.subject)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-email",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "type": "module",
   "description": "Zhin.js Email adapter for Plugin Runtime (SMTP/IMAP)",
   "main": "./lib/index.js",
@@ -9,15 +9,16 @@
     "imap": "^0.8.19",
     "mailparser": "^3.9.14",
     "nodemailer": "^9.0.3",
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/core": "1.5.13",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/core": "1.5.15",
+    "@zhin.js/feature-kit": "1.0.13",
     "@zhin.js/im-contract": "1.0.4",
-    "@zhin.js/logger": "1.0.76"
+    "@zhin.js/logger": "1.0.77"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/core": "1.5.13",
-    "zhin.js": "6.0.13"
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/core": "1.5.15",
+    "zhin.js": "6.0.15"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -31,7 +32,7 @@
     "@types/nodemailer": "^8.0.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "zhin.js": "6.0.13"
+    "zhin.js": "6.0.15"
   },
   "keywords": [
     "zhin",

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');

package/src/endpoint.ts

@@ -1,11 +1,11 @@
+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 { EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { type EndpointSendRequest } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import {
@@ -26,11 +26,10 @@ import {
   type EmailImapTransport,
   type EmailSmtpTransport,
 } from './transport.js';
+import { EmailClient } from './client.js';
 
 export interface EmailEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly config: ResolvedEmailConfig;
   readonly createSmtp?: (config: ResolvedEmailConfig['smtp']) => EmailSmtpTransport | Promise<EmailSmtpTransport>;
   readonly createImap?: (config: ResolvedEmailConfig['imap']) => EmailImapTransport;
@@ -40,7 +39,8 @@ export interface EmailEndpointOptions {
  * Email（SMTP/IMAP）无好友/群/频道等社交图谱概念，
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
-export class EmailEndpoint implements EndpointInstance {
+export class EmailEndpoint extends Endpoint<EmailClient> {
+  readonly client: EmailClient;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: EmailEndpointOptions;
@@ -54,8 +54,10 @@ export class EmailEndpoint implements EndpointInstance {
   #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> {
@@ -70,7 +72,10 @@ export class EmailEndpoint implements EndpointInstance {
       this.#imap = this.#options.createImap?.(imap) ?? defaultCreateImap(imap);
       this.#setupImapListeners(this.#imap);
       await new Promise<void>((resolve, reject) => {
-        this.#imap!.once('ready', () => resolve());
+        this.#imap!.once('ready', () => {
+          void this.#emitPlatformEvent('imap.ready', Object.freeze({}));
+          resolve();
+        });
         this.#imap!.once('error', (error) => reject(error));
         this.#imap!.connect();
       });
@@ -124,13 +129,12 @@ export class EmailEndpoint implements EndpointInstance {
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
-    if (!this.#smtp) throw new Error('SMTP transporter not initialized');
     const target = conversation.id;
     const mailOptions = formatOutboundMail(payload, {
       from: this.#options.config.smtp.auth.user,
       to: target,
     });
-    const info = await this.#smtp.sendMail(mailOptions);
+    const info = await this.client.sendMail(mailOptions);
     this.#logger.debug(formatCompact({ op: 'email_send', target, messageId: info.messageId }));
     return info.messageId || '';
   }
@@ -138,6 +142,7 @@ export class EmailEndpoint implements EndpointInstance {
   /** 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',
@@ -152,7 +157,7 @@ export class EmailEndpoint implements EndpointInstance {
     const content = formatInboundContent(email);
     const sender = email.from;
     const conversation = emailInboundConversation(String(this.#options.id), email);
-    await this.#options.gateway.receive({
+    await this.emit('message.receive', {
       conversation,
       ...(email.messageId ? { message: { conversation, id: email.messageId } } : {}),
       content,
@@ -215,25 +220,41 @@ export class EmailEndpoint implements EndpointInstance {
 
   #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();
+      this.#scheduleImapReconnect(imap);
     });
     imap.on('end', () => {
+      void this.#emitPlatformEvent('imap.end', Object.freeze({}));
       this.#logger.debug(formatCompact({
           op: 'disconnect',
         mode: 'imap',
       }));
-      this.#scheduleImapReconnect();
+      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(): void {
-    if (!this.#started || this.#reconnectTimer) return;
+  #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;
@@ -250,15 +271,20 @@ export class EmailEndpoint implements EndpointInstance {
 
   async #reconnectImap(): Promise<void> {
     if (!this.#started) return;
+    let imap: EmailImapTransport | undefined;
     try {
-      const imap = this.#options.createImap?.(this.#options.config.imap)
+      const nextImap = this.#options.createImap?.(this.#options.config.imap)
         ?? defaultCreateImap(this.#options.config.imap);
-      this.#imap = imap;
-      this.#setupImapListeners(imap);
+      imap = nextImap;
+      this.#imap = nextImap;
+      this.#setupImapListeners(nextImap);
       await new Promise<void>((resolve, reject) => {
-        imap.once('ready', () => resolve());
-        imap.once('error', (error) => reject(error));
-        imap.connect();
+        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({
@@ -274,7 +300,7 @@ export class EmailEndpoint implements EndpointInstance {
         ok: false,
         error: error instanceof Error ? error.message : String(error),
       }));
-      this.#scheduleImapReconnect();
+      this.#scheduleImapReconnect(imap);
     }
   }
 

package/src/index.ts

@@ -18,6 +18,12 @@ export {
   type SmtpConfig,
 } from './protocol.js';
 
+export {
+  EmailClient,
+  emailClient,
+  type EmailClientEventMap,
+} from './client.js';
+
 export {
   EmailEndpoint,
   type EmailEndpointOptions,

package/src/protocol.ts

@@ -171,7 +171,7 @@ export function parseEmailMessage(
   };
 }
 
-/** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
+/** 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}`, '');