react-native-email-imap-smtp 0.3.26 → 0.3.28

package/src/web.ts

@@ -1,544 +1,544 @@
-// ============================================================
-// Web implementation — HTTP Proxy Client
-// 浏览器通过 HTTP API 与代理服务器通信，代理使用 imapflow + nodemailer
-// ============================================================
-//
-// 需要启动代理服务器:
-//   npx email-imap-proxy           # 启动代理
-//   npx email-imap-proxy & vite    # 与 Vite 并行启动
-//
-// 或在 package.json 的 dev 脚本中加入:
-//   "dev": "email-imap-proxy & next dev"
-//
-// 自定义代理地址:
-//   import { setProxyUrl } from 'react-native-email-imap-smtp';
-//   setProxyUrl('http://localhost:3987');
-// ============================================================
-
-import type {
-  IMAPConfig,
-  SMTPConfig,
-  IMAPConnectionResult,
-  SMTPConnectionResult,
-  Mailbox,
-  MailboxStatus,
-  Folder,
-  Email,
-  Attachment,
-  FetchEmailsOptions,
-  SearchCriteria,
-  BatchResult,
-  IMAPNotification,
-  QuotaInfo,
-  AppendResult,
-  SendMailOptions,
-  SendMailResult,
-} from './types';
-
-// ─── 代理服务器配置 ─────────────────────────────────────────
-
-const DEFAULT_PROXY_URL = 'http://localhost:3987';
-// 60s：附件下载可能较慢/含多个 part，15s 容易误超时
-const API_TIMEOUT = 60000;
-
-let PROXY_URL = DEFAULT_PROXY_URL;
-let _ws: WebSocket | null = null;
-
-export function setProxyUrl(url: string): void {
-  PROXY_URL = url.replace(/\/+$/, '');
-}
-
-export function getProxyUrl(): string {
-  return PROXY_URL;
-}
-
-// ─── 内部辅助 ───────────────────────────────────────────────
-
-export class ImapNotConnectedError extends Error {
-  constructor() {
-    super('IMAP not connected. Call imapConnect first.');
-    this.name = 'ImapNotConnectedError';
-  }
-}
-
-export class SmtpNotConnectedError extends Error {
-  constructor() {
-    super('SMTP not connected. Call smtpConnect first.');
-    this.name = 'SmtpNotConnectedError';
-  }
-}
-
-interface ConnectResult {
-  success: boolean;
-  sessionId?: string;
-}
-
-let _imapSessionId: string | null = null;
-let _smtpSessionId: string | null = null;
-let _proxyChecked = false;
-
-/** 首次调用时检测代理是否可达，不可达则抛明确指引 */
-async function checkProxyOrThrow(): Promise<void> {
-  if (_proxyChecked) return;
-  _proxyChecked = true;
-
-  try {
-    const res = await fetch(`${PROXY_URL}/api/health`, {
-      signal: new AbortController().signal as any,
-    });
-    if (res.ok) return;
-  } catch {
-    // 代理不可达
-  }
-
-  _proxyChecked = false; // 允许后续重试
-  throw new Error(
-    `[EmailImapSmtp] 代理服务器未启动！
-
-IMAP/SMTP 在浏览器中需要借助一个本地代理服务来连接邮件服务器。
-
-请在项目配置中启动代理：
-
-  ${'A. Vite 项目 — 在 vite.config.ts 中添加:'}
-     import { startEmailProxy } from 'react-native-email-imap-smtp/server/proxy';
-     startEmailProxy();
-
-  ${'B. Next.js / Webpack 等 — 在 dev 脚本中添加:'}
-     "dev": "email-imap-proxy & next dev"
-
-  ${'C. 或手动启动（会自动安装依赖）:'}
-     npx email-imap-proxy
-
-  ${'D. 如果已启动但端口不同，请设置:'}
-     import { setProxyUrl } from 'react-native-email-imap-smtp';
-     setProxyUrl('http://localhost:你的端口号');
-`
-  );
-}
-
-function getImapSessionId(): string {
-  if (!_imapSessionId) throw new ImapNotConnectedError();
-  return _imapSessionId;
-}
-
-function getSmtpSessionId(): string {
-  if (!_smtpSessionId) throw new SmtpNotConnectedError();
-  return _smtpSessionId;
-}
-
-function extractSession<T extends ConnectResult>(result: T): T {
-  if (result.success && result.sessionId) {
-    _imapSessionId = result.sessionId;
-  }
-  return result;
-}
-
-function extractSmtpSession<T extends ConnectResult>(result: T): T {
-  if (result.success && result.sessionId) {
-    _smtpSessionId = result.sessionId;
-  }
-  return result;
-}
-
-/** ArrayBuffer → base64 */
-function arrayBufferToBase64(buf: ArrayBuffer): string {
-  const bytes = new Uint8Array(buf);
-  let binary = '';
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]!);
-  }
-  return btoa(binary);
-}
-
-/** base64 → ArrayBuffer（服务器经 JSON 传输附件时为 base64 字符串，需解码回二进制） */
-function base64ToArrayBuffer(base64: string): ArrayBuffer {
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) {
-    bytes[i] = binary.charCodeAt(i);
-  }
-  return bytes.buffer;
-}
-
-/** 归一化服务器返回的附件：若 data 是 base64 字符串则解码为 ArrayBuffer */
-function normalizeAttachment(att: Attachment): Attachment {
-  const data = att.data as unknown;
-  if (typeof data === 'string') {
-    return { ...att, data: base64ToArrayBuffer(data) };
-  }
-  return att;
-}
-
-async function apiPost<T>(
-  path: string,
-  body: any,
-  errorMessage?: string
-): Promise<T> {
-  await checkProxyOrThrow();
-
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), API_TIMEOUT);
-
-  try {
-    const url = `${PROXY_URL}${path}`;
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(body),
-      signal: controller.signal as any,
-    });
-
-    if (!res.ok) {
-      const text = await res.text().catch(() => '');
-      throw new Error(
-        errorMessage ?? `HTTP ${res.status}: ${text || res.statusText}`
-      );
-    }
-
-    return res.json() as Promise<T>;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-// ─── IMAP ────────────────────────────────────────────────────
-
-export async function imapConnect(
-  config: IMAPConfig
-): Promise<IMAPConnectionResult> {
-  _imapSessionId = null;
-  const result = await apiPost<IMAPConnectionResult & { sessionId?: string }>(
-    '/api/imap/connect',
-    config,
-    'IMAP connection failed'
-  );
-  return extractSession(result);
-}
-
-export async function imapDisconnect(): Promise<void> {
-  const sid = _imapSessionId;
-  _imapSessionId = null;
-  if (sid) {
-    await apiPost('/api/imap/disconnect', { sessionId: sid }).catch(() => {});
-  }
-}
-
-export async function imapListMailboxes(): Promise<Mailbox[]> {
-  return apiPost<Mailbox[]>('/api/imap/listMailboxes', {
-    sessionId: getImapSessionId(),
-  });
-}
-
-export async function imapSelectMailbox(
-  mailbox: string,
-  readOnly?: boolean
-): Promise<MailboxStatus> {
-  return apiPost<MailboxStatus>('/api/imap/selectMailbox', {
-    sessionId: getImapSessionId(),
-    mailbox,
-    readOnly: readOnly ?? false,
-  });
-}
-
-export async function imapRefreshMailbox(): Promise<MailboxStatus> {
-  return apiPost<MailboxStatus>('/api/imap/refreshMailbox', {
-    sessionId: getImapSessionId(),
-  });
-}
-
-export async function imapFetchFolders(): Promise<Folder[]> {
-  return apiPost<Folder[]>('/api/imap/fetchFolders', {
-    sessionId: getImapSessionId(),
-  });
-}
-
-export async function imapCreateFolder(folderName: string): Promise<void> {
-  await apiPost('/api/imap/createFolder', {
-    sessionId: getImapSessionId(),
-    folderName,
-  });
-}
-
-export async function imapDeleteFolder(folderName: string): Promise<void> {
-  await apiPost('/api/imap/deleteFolder', {
-    sessionId: getImapSessionId(),
-    folderName,
-  });
-}
-
-export async function imapRenameFolder(
-  oldName: string,
-  newName: string
-): Promise<void> {
-  await apiPost('/api/imap/renameFolder', {
-    sessionId: getImapSessionId(),
-    oldName,
-    newName,
-  });
-}
-
-export async function imapSubscribeFolder(folderName: string): Promise<void> {
-  await apiPost('/api/imap/subscribeFolder', {
-    sessionId: getImapSessionId(),
-    folderName,
-  });
-}
-
-export async function imapUnsubscribeFolder(folderName: string): Promise<void> {
-  await apiPost('/api/imap/unsubscribeFolder', {
-    sessionId: getImapSessionId(),
-    folderName,
-  });
-}
-
-export async function imapFetchEmails(
-  options: FetchEmailsOptions
-): Promise<Email[]> {
-  return apiPost<Email[]>('/api/imap/fetchEmails', {
-    sessionId: getImapSessionId(),
-    options,
-  });
-}
-
-export async function imapFetchEmailByUID(uid: number): Promise<Email | null> {
-  return apiPost<Email | null>('/api/imap/fetchEmailByUID', {
-    sessionId: getImapSessionId(),
-    uid,
-  });
-}
-
-export async function imapSearchEmails(
-  criteria: SearchCriteria
-): Promise<Email[]> {
-  return apiPost<Email[]>('/api/imap/searchEmails', {
-    sessionId: getImapSessionId(),
-    criteria,
-  });
-}
-
-export async function imapMarkAsRead(
-  uids: number[],
-  silent?: boolean
-): Promise<void> {
-  await apiPost('/api/imap/markAsRead', {
-    sessionId: getImapSessionId(),
-    uids,
-    silent: silent ?? true,
-  });
-}
-
-export async function imapMarkAsFlagged(
-  uids: number[],
-  flagged: boolean
-): Promise<void> {
-  await apiPost('/api/imap/markAsFlagged', {
-    sessionId: getImapSessionId(),
-    uids,
-    flagged,
-  });
-}
-
-export async function imapMoveEmails(
-  uids: number[],
-  destinationMailbox: string
-): Promise<void> {
-  await apiPost('/api/imap/moveEmails', {
-    sessionId: getImapSessionId(),
-    uids,
-    destinationMailbox,
-  });
-}
-
-export async function imapCopyEmails(
-  uids: number[],
-  destinationMailbox: string
-): Promise<void> {
-  await apiPost('/api/imap/copyEmails', {
-    sessionId: getImapSessionId(),
-    uids,
-    destinationMailbox,
-  });
-}
-
-export async function imapDeleteEmails(uids: number[]): Promise<BatchResult> {
-  return apiPost<BatchResult>('/api/imap/deleteEmails', {
-    sessionId: getImapSessionId(),
-    uids,
-  });
-}
-
-export async function imapExpunge(): Promise<void> {
-  await apiPost('/api/imap/expunge', {
-    sessionId: getImapSessionId(),
-  });
-}
-
-export async function imapFetchAttachments(
-  uid: number,
-  partId: string
-): Promise<Attachment | null> {
-  const result = await apiPost<Attachment | null>('/api/imap/fetchAttachment', {
-    sessionId: getImapSessionId(),
-    uid,
-    partId,
-  });
-  return result ? normalizeAttachment(result) : null;
-}
-
-export async function imapFetchAllAttachments(
-  uid: number
-): Promise<Attachment[]> {
-  const result = await apiPost<Attachment[]>('/api/imap/fetchAllAttachments', {
-    sessionId: getImapSessionId(),
-    uid,
-  });
-  return result.map(normalizeAttachment);
-}
-
-export async function imapIdle(
-  callback: (notification: IMAPNotification) => void
-): Promise<void> {
-  const sid = getImapSessionId();
-
-  // 启动空闲监听
-  await apiPost('/api/imap/idle', { sessionId: sid });
-
-  // 建立或复用 WebSocket 连接
-  if (!_ws || _ws.readyState !== WebSocket.OPEN) {
-    // 关闭旧连接（如有）
-    if (_ws) {
-      _ws.onclose = null;
-      _ws.onerror = null;
-      _ws.close();
-    }
-
-    const wsUrl = PROXY_URL.replace(/^http/, 'ws');
-    const ws = new WebSocket(
-      `${wsUrl}/ws?sessionId=${sid}`
-    ) as unknown as WebSocket;
-
-    ws.onclose = () => {
-      _ws = null;
-    };
-
-    ws.onerror = () => {
-      _ws = null;
-    };
-
-    _ws = ws;
-  }
-
-  // 始终绑定当前回调，无论是否复用连接
-  _ws.onmessage = (event) => {
-    try {
-      const data = JSON.parse(event.data as string);
-      if (data.type === 'connected') return;
-      callback(data as IMAPNotification);
-    } catch {
-      // ignore parse errors
-    }
-  };
-}
-
-export async function imapStopIdle(): Promise<void> {
-  const sid = _imapSessionId;
-  if (sid) {
-    await apiPost('/api/imap/stopIdle', { sessionId: sid }).catch(() => {});
-  }
-  if (_ws) {
-    _ws.close();
-    _ws = null;
-  }
-}
-
-export async function imapGetQuota(root?: string): Promise<QuotaInfo> {
-  return apiPost<QuotaInfo>('/api/imap/getQuota', {
-    sessionId: getImapSessionId(),
-    root: root ?? null,
-  });
-}
-
-export async function imapAppendMessage(
-  mailbox: string,
-  rawMimeData: ArrayBuffer,
-  flags?: string[]
-): Promise<AppendResult> {
-  return apiPost<AppendResult>('/api/imap/appendMessage', {
-    sessionId: getImapSessionId(),
-    mailbox,
-    rawMimeData: arrayBufferToBase64(rawMimeData),
-    flags: flags ?? null,
-  });
-}
-
-// ─── SMTP ────────────────────────────────────────────────────
-
-export async function smtpConnect(
-  config: SMTPConfig
-): Promise<SMTPConnectionResult> {
-  _smtpSessionId = null;
-  const result = await apiPost<SMTPConnectionResult & { sessionId?: string }>(
-    '/api/smtp/connect',
-    config,
-    'SMTP connection failed'
-  );
-  return extractSmtpSession(result);
-}
-
-export async function smtpDisconnect(): Promise<void> {
-  const sid = _smtpSessionId;
-  _smtpSessionId = null;
-  if (sid) {
-    await apiPost('/api/smtp/disconnect', { sessionId: sid }).catch(() => {});
-  }
-}
-
-export async function smtpSendMail(
-  options: SendMailOptions
-): Promise<SendMailResult> {
-  // 先处理附件中的 ArrayBuffer → base64，再序列化
-  const processedOptions: any = {
-    from: options.from,
-    to: options.to,
-    cc: options.cc,
-    bcc: options.bcc,
-    replyTo: options.replyTo,
-    subject: options.subject,
-    textBody: options.textBody,
-    htmlBody: options.htmlBody,
-    priority: options.priority,
-    headers: options.headers,
-    inReplyTo: options.inReplyTo,
-    references: options.references,
-    readReceiptTo: options.readReceiptTo,
-    charset: options.charset,
-    encoding: options.encoding,
-  };
-
-  if (options.attachments && options.attachments.length > 0) {
-    processedOptions.attachments = options.attachments.map((att) => ({
-      filename: att.filename,
-      mimeType: att.mimeType,
-      isInline: att.isInline,
-      contentId: att.contentId,
-      disposition: (att as any).disposition,
-      data:
-        att.data instanceof ArrayBuffer
-          ? arrayBufferToBase64(att.data)
-          : att.data,
-    }));
-  }
-
-  return apiPost<SendMailResult>('/api/smtp/sendMail', {
-    sessionId: getSmtpSessionId(),
-    options: processedOptions,
-  });
-}
-
-export async function smtpVerifyConnection(): Promise<boolean> {
-  const result = await apiPost<{ success: boolean }>(
-    '/api/smtp/verifyConnection',
-    { sessionId: getSmtpSessionId() }
-  );
-  return result.success;
-}
+// ============================================================
+// Web implementation — HTTP Proxy Client
+// 浏览器通过 HTTP API 与代理服务器通信，代理使用 imapflow + nodemailer
+// ============================================================
+//
+// 需要启动代理服务器:
+//   npx email-imap-proxy           # 启动代理
+//   npx email-imap-proxy & vite    # 与 Vite 并行启动
+//
+// 或在 package.json 的 dev 脚本中加入:
+//   "dev": "email-imap-proxy & next dev"
+//
+// 自定义代理地址:
+//   import { setProxyUrl } from 'react-native-email-imap-smtp';
+//   setProxyUrl('http://localhost:3987');
+// ============================================================
+
+import type {
+  IMAPConfig,
+  SMTPConfig,
+  IMAPConnectionResult,
+  SMTPConnectionResult,
+  Mailbox,
+  MailboxStatus,
+  Folder,
+  Email,
+  Attachment,
+  FetchEmailsOptions,
+  SearchCriteria,
+  BatchResult,
+  IMAPNotification,
+  QuotaInfo,
+  AppendResult,
+  SendMailOptions,
+  SendMailResult,
+} from './types';
+
+// ─── 代理服务器配置 ─────────────────────────────────────────
+
+const DEFAULT_PROXY_URL = 'http://localhost:3987';
+// 60s：附件下载可能较慢/含多个 part，15s 容易误超时
+const API_TIMEOUT = 60000;
+
+let PROXY_URL = DEFAULT_PROXY_URL;
+let _ws: WebSocket | null = null;
+
+export function setProxyUrl(url: string): void {
+  PROXY_URL = url.replace(/\/+$/, '');
+}
+
+export function getProxyUrl(): string {
+  return PROXY_URL;
+}
+
+// ─── 内部辅助 ───────────────────────────────────────────────
+
+export class ImapNotConnectedError extends Error {
+  constructor() {
+    super('IMAP not connected. Call imapConnect first.');
+    this.name = 'ImapNotConnectedError';
+  }
+}
+
+export class SmtpNotConnectedError extends Error {
+  constructor() {
+    super('SMTP not connected. Call smtpConnect first.');
+    this.name = 'SmtpNotConnectedError';
+  }
+}
+
+interface ConnectResult {
+  success: boolean;
+  sessionId?: string;
+}
+
+let _imapSessionId: string | null = null;
+let _smtpSessionId: string | null = null;
+let _proxyChecked = false;
+
+/** 首次调用时检测代理是否可达，不可达则抛明确指引 */
+async function checkProxyOrThrow(): Promise<void> {
+  if (_proxyChecked) return;
+  _proxyChecked = true;
+
+  try {
+    const res = await fetch(`${PROXY_URL}/api/health`, {
+      signal: new AbortController().signal as any,
+    });
+    if (res.ok) return;
+  } catch {
+    // 代理不可达
+  }
+
+  _proxyChecked = false; // 允许后续重试
+  throw new Error(
+    `[EmailImapSmtp] 代理服务器未启动！
+
+IMAP/SMTP 在浏览器中需要借助一个本地代理服务来连接邮件服务器。
+
+请在项目配置中启动代理：
+
+  ${'A. Vite 项目 — 在 vite.config.ts 中添加:'}
+     import { startEmailProxy } from 'react-native-email-imap-smtp/server/proxy';
+     startEmailProxy();
+
+  ${'B. Next.js / Webpack 等 — 在 dev 脚本中添加:'}
+     "dev": "email-imap-proxy & next dev"
+
+  ${'C. 或手动启动（会自动安装依赖）:'}
+     npx email-imap-proxy
+
+  ${'D. 如果已启动但端口不同，请设置:'}
+     import { setProxyUrl } from 'react-native-email-imap-smtp';
+     setProxyUrl('http://localhost:你的端口号');
+`
+  );
+}
+
+function getImapSessionId(): string {
+  if (!_imapSessionId) throw new ImapNotConnectedError();
+  return _imapSessionId;
+}
+
+function getSmtpSessionId(): string {
+  if (!_smtpSessionId) throw new SmtpNotConnectedError();
+  return _smtpSessionId;
+}
+
+function extractSession<T extends ConnectResult>(result: T): T {
+  if (result.success && result.sessionId) {
+    _imapSessionId = result.sessionId;
+  }
+  return result;
+}
+
+function extractSmtpSession<T extends ConnectResult>(result: T): T {
+  if (result.success && result.sessionId) {
+    _smtpSessionId = result.sessionId;
+  }
+  return result;
+}
+
+/** ArrayBuffer → base64 */
+function arrayBufferToBase64(buf: ArrayBuffer): string {
+  const bytes = new Uint8Array(buf);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]!);
+  }
+  return btoa(binary);
+}
+
+/** base64 → ArrayBuffer（服务器经 JSON 传输附件时为 base64 字符串，需解码回二进制） */
+function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+
+/** 归一化服务器返回的附件：若 data 是 base64 字符串则解码为 ArrayBuffer */
+function normalizeAttachment(att: Attachment): Attachment {
+  const data = att.data as unknown;
+  if (typeof data === 'string') {
+    return { ...att, data: base64ToArrayBuffer(data) };
+  }
+  return att;
+}
+
+async function apiPost<T>(
+  path: string,
+  body: any,
+  errorMessage?: string
+): Promise<T> {
+  await checkProxyOrThrow();
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), API_TIMEOUT);
+
+  try {
+    const url = `${PROXY_URL}${path}`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: controller.signal as any,
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(
+        errorMessage ?? `HTTP ${res.status}: ${text || res.statusText}`
+      );
+    }
+
+    return res.json() as Promise<T>;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ─── IMAP ────────────────────────────────────────────────────
+
+export async function imapConnect(
+  config: IMAPConfig
+): Promise<IMAPConnectionResult> {
+  _imapSessionId = null;
+  const result = await apiPost<IMAPConnectionResult & { sessionId?: string }>(
+    '/api/imap/connect',
+    config,
+    'IMAP connection failed'
+  );
+  return extractSession(result);
+}
+
+export async function imapDisconnect(): Promise<void> {
+  const sid = _imapSessionId;
+  _imapSessionId = null;
+  if (sid) {
+    await apiPost('/api/imap/disconnect', { sessionId: sid }).catch(() => {});
+  }
+}
+
+export async function imapListMailboxes(): Promise<Mailbox[]> {
+  return apiPost<Mailbox[]>('/api/imap/listMailboxes', {
+    sessionId: getImapSessionId(),
+  });
+}
+
+export async function imapSelectMailbox(
+  mailbox: string,
+  readOnly?: boolean
+): Promise<MailboxStatus> {
+  return apiPost<MailboxStatus>('/api/imap/selectMailbox', {
+    sessionId: getImapSessionId(),
+    mailbox,
+    readOnly: readOnly ?? false,
+  });
+}
+
+export async function imapRefreshMailbox(): Promise<MailboxStatus> {
+  return apiPost<MailboxStatus>('/api/imap/refreshMailbox', {
+    sessionId: getImapSessionId(),
+  });
+}
+
+export async function imapFetchFolders(): Promise<Folder[]> {
+  return apiPost<Folder[]>('/api/imap/fetchFolders', {
+    sessionId: getImapSessionId(),
+  });
+}
+
+export async function imapCreateFolder(folderName: string): Promise<void> {
+  await apiPost('/api/imap/createFolder', {
+    sessionId: getImapSessionId(),
+    folderName,
+  });
+}
+
+export async function imapDeleteFolder(folderName: string): Promise<void> {
+  await apiPost('/api/imap/deleteFolder', {
+    sessionId: getImapSessionId(),
+    folderName,
+  });
+}
+
+export async function imapRenameFolder(
+  oldName: string,
+  newName: string
+): Promise<void> {
+  await apiPost('/api/imap/renameFolder', {
+    sessionId: getImapSessionId(),
+    oldName,
+    newName,
+  });
+}
+
+export async function imapSubscribeFolder(folderName: string): Promise<void> {
+  await apiPost('/api/imap/subscribeFolder', {
+    sessionId: getImapSessionId(),
+    folderName,
+  });
+}
+
+export async function imapUnsubscribeFolder(folderName: string): Promise<void> {
+  await apiPost('/api/imap/unsubscribeFolder', {
+    sessionId: getImapSessionId(),
+    folderName,
+  });
+}
+
+export async function imapFetchEmails(
+  options: FetchEmailsOptions
+): Promise<Email[]> {
+  return apiPost<Email[]>('/api/imap/fetchEmails', {
+    sessionId: getImapSessionId(),
+    options,
+  });
+}
+
+export async function imapFetchEmailByUID(uid: number): Promise<Email | null> {
+  return apiPost<Email | null>('/api/imap/fetchEmailByUID', {
+    sessionId: getImapSessionId(),
+    uid,
+  });
+}
+
+export async function imapSearchEmails(
+  criteria: SearchCriteria
+): Promise<Email[]> {
+  return apiPost<Email[]>('/api/imap/searchEmails', {
+    sessionId: getImapSessionId(),
+    criteria,
+  });
+}
+
+export async function imapMarkAsRead(
+  uids: number[],
+  silent?: boolean
+): Promise<void> {
+  await apiPost('/api/imap/markAsRead', {
+    sessionId: getImapSessionId(),
+    uids,
+    silent: silent ?? true,
+  });
+}
+
+export async function imapMarkAsFlagged(
+  uids: number[],
+  flagged: boolean
+): Promise<void> {
+  await apiPost('/api/imap/markAsFlagged', {
+    sessionId: getImapSessionId(),
+    uids,
+    flagged,
+  });
+}
+
+export async function imapMoveEmails(
+  uids: number[],
+  destinationMailbox: string
+): Promise<void> {
+  await apiPost('/api/imap/moveEmails', {
+    sessionId: getImapSessionId(),
+    uids,
+    destinationMailbox,
+  });
+}
+
+export async function imapCopyEmails(
+  uids: number[],
+  destinationMailbox: string
+): Promise<void> {
+  await apiPost('/api/imap/copyEmails', {
+    sessionId: getImapSessionId(),
+    uids,
+    destinationMailbox,
+  });
+}
+
+export async function imapDeleteEmails(uids: number[]): Promise<BatchResult> {
+  return apiPost<BatchResult>('/api/imap/deleteEmails', {
+    sessionId: getImapSessionId(),
+    uids,
+  });
+}
+
+export async function imapExpunge(): Promise<void> {
+  await apiPost('/api/imap/expunge', {
+    sessionId: getImapSessionId(),
+  });
+}
+
+export async function imapFetchAttachments(
+  uid: number,
+  partId: string
+): Promise<Attachment | null> {
+  const result = await apiPost<Attachment | null>('/api/imap/fetchAttachment', {
+    sessionId: getImapSessionId(),
+    uid,
+    partId,
+  });
+  return result ? normalizeAttachment(result) : null;
+}
+
+export async function imapFetchAllAttachments(
+  uid: number
+): Promise<Attachment[]> {
+  const result = await apiPost<Attachment[]>('/api/imap/fetchAllAttachments', {
+    sessionId: getImapSessionId(),
+    uid,
+  });
+  return result.map(normalizeAttachment);
+}
+
+export async function imapIdle(
+  callback: (notification: IMAPNotification) => void
+): Promise<void> {
+  const sid = getImapSessionId();
+
+  // 启动空闲监听
+  await apiPost('/api/imap/idle', { sessionId: sid });
+
+  // 建立或复用 WebSocket 连接
+  if (!_ws || _ws.readyState !== WebSocket.OPEN) {
+    // 关闭旧连接（如有）
+    if (_ws) {
+      _ws.onclose = null;
+      _ws.onerror = null;
+      _ws.close();
+    }
+
+    const wsUrl = PROXY_URL.replace(/^http/, 'ws');
+    const ws = new WebSocket(
+      `${wsUrl}/ws?sessionId=${sid}`
+    ) as unknown as WebSocket;
+
+    ws.onclose = () => {
+      _ws = null;
+    };
+
+    ws.onerror = () => {
+      _ws = null;
+    };
+
+    _ws = ws;
+  }
+
+  // 始终绑定当前回调，无论是否复用连接
+  _ws.onmessage = (event) => {
+    try {
+      const data = JSON.parse(event.data as string);
+      if (data.type === 'connected') return;
+      callback(data as IMAPNotification);
+    } catch {
+      // ignore parse errors
+    }
+  };
+}
+
+export async function imapStopIdle(): Promise<void> {
+  const sid = _imapSessionId;
+  if (sid) {
+    await apiPost('/api/imap/stopIdle', { sessionId: sid }).catch(() => {});
+  }
+  if (_ws) {
+    _ws.close();
+    _ws = null;
+  }
+}
+
+export async function imapGetQuota(root?: string): Promise<QuotaInfo> {
+  return apiPost<QuotaInfo>('/api/imap/getQuota', {
+    sessionId: getImapSessionId(),
+    root: root ?? null,
+  });
+}
+
+export async function imapAppendMessage(
+  mailbox: string,
+  rawMimeData: ArrayBuffer,
+  flags?: string[]
+): Promise<AppendResult> {
+  return apiPost<AppendResult>('/api/imap/appendMessage', {
+    sessionId: getImapSessionId(),
+    mailbox,
+    rawMimeData: arrayBufferToBase64(rawMimeData),
+    flags: flags ?? null,
+  });
+}
+
+// ─── SMTP ────────────────────────────────────────────────────
+
+export async function smtpConnect(
+  config: SMTPConfig
+): Promise<SMTPConnectionResult> {
+  _smtpSessionId = null;
+  const result = await apiPost<SMTPConnectionResult & { sessionId?: string }>(
+    '/api/smtp/connect',
+    config,
+    'SMTP connection failed'
+  );
+  return extractSmtpSession(result);
+}
+
+export async function smtpDisconnect(): Promise<void> {
+  const sid = _smtpSessionId;
+  _smtpSessionId = null;
+  if (sid) {
+    await apiPost('/api/smtp/disconnect', { sessionId: sid }).catch(() => {});
+  }
+}
+
+export async function smtpSendMail(
+  options: SendMailOptions
+): Promise<SendMailResult> {
+  // 先处理附件中的 ArrayBuffer → base64，再序列化
+  const processedOptions: any = {
+    from: options.from,
+    to: options.to,
+    cc: options.cc,
+    bcc: options.bcc,
+    replyTo: options.replyTo,
+    subject: options.subject,
+    textBody: options.textBody,
+    htmlBody: options.htmlBody,
+    priority: options.priority,
+    headers: options.headers,
+    inReplyTo: options.inReplyTo,
+    references: options.references,
+    readReceiptTo: options.readReceiptTo,
+    charset: options.charset,
+    encoding: options.encoding,
+  };
+
+  if (options.attachments && options.attachments.length > 0) {
+    processedOptions.attachments = options.attachments.map((att) => ({
+      filename: att.filename,
+      mimeType: att.mimeType,
+      isInline: att.isInline,
+      contentId: att.contentId,
+      disposition: (att as any).disposition,
+      data:
+        att.data instanceof ArrayBuffer
+          ? arrayBufferToBase64(att.data)
+          : att.data,
+    }));
+  }
+
+  return apiPost<SendMailResult>('/api/smtp/sendMail', {
+    sessionId: getSmtpSessionId(),
+    options: processedOptions,
+  });
+}
+
+export async function smtpVerifyConnection(): Promise<boolean> {
+  const result = await apiPost<{ success: boolean }>(
+    '/api/smtp/verifyConnection',
+    { sessionId: getSmtpSessionId() }
+  );
+  return result.success;
+}