react-native-email-imap-smtp 0.3.20 → 0.3.21

package/src/EmailImapSmtp.nitro.ts

@@ -6,94 +6,188 @@
 import type { HybridObject } from 'react-native-nitro-modules';
 
 // ─── Shared Types ─────────────────────────────────────────
-
+//
+// 注意：本文件的类型是「原生层」结构，通过 JSON 序列化与 JS 层通信，
+// 与 src/types.ts 中的公共类型语义一一对应（但字段更底层）。
+// 修改时请保持与 src/types.ts 同步。
+
+/**
+ * 邮件地址（发件人 / 收件人等）。
+ */
 export interface EmailAddress {
+  /** 显示名称 */
   name: string;
+  /** 邮箱地址 */
   email: string;
 }
 
+/**
+ * IMAP 服务器连接配置（原生层）。
+ */
 export interface ConnectionConfig {
+  /** 服务器主机名或 IP */
   host: string;
+  /** 服务器端口 */
   port: number;
+  /** 登录用户名 */
   username: string;
+  /** 登录密码 */
   password: string;
+  /** 是否使用 SSL/TLS */
   tls: boolean;
+  /** 认证方式：`password` / `oauth2` / `none` */
   authType: string;
+  /** OAuth2 访问令牌 */
   accessToken?: string;
+  /** 连接超时（毫秒） */
   timeout: number;
+  /** 是否校验服务器证书 */
   checkCertificate: boolean;
+  /** 是否输出调试日志 */
   debug: boolean;
 }
 
+/**
+ * SMTP 服务器连接配置（原生层）。
+ */
 export interface SmtpConnectionConfig {
+  /** 服务器主机名或 IP */
   host: string;
+  /** 服务器端口 */
   port: number;
+  /** 登录用户名 */
   username: string;
+  /** 登录密码 */
   password: string;
+  /** 是否使用 SSL/TLS */
   tls: boolean;
+  /** 认证方式：`password` / `oauth2` / `none` */
   authType: string;
+  /** OAuth2 访问令牌 */
   accessToken?: string;
+  /** 连接超时（毫秒） */
   timeout: number;
+  /** 是否校验服务器证书 */
   checkCertificate: boolean;
+  /** EHLO 问候主机名 */
   helloName?: string;
+  /** 是否输出调试日志 */
   debug: boolean;
 }
 
+/**
+ * IMAP 服务器信息（连接成功后）。
+ */
 export interface ImapServerInfo {
+  /** 服务器标识名 */
   serverName: string;
+  /** 支持的 IMAP 能力列表 */
   capabilities: string[];
+  /** 是否启用压缩 */
   isCompressed: boolean;
 }
 
+/**
+ * SMTP 服务器信息（连接成功后）。
+ */
 export interface SmtpServerInfo {
+  /** 服务器标识名 */
   serverName: string;
+  /** 支持的 SMTP 扩展能力列表 */
   capabilities: string[];
+  /** 支持的认证方法列表 */
   supportedAuthMethods: string[];
 }
 
+/**
+ * 连接结果（IMAP / SMTP 通用）。
+ */
 export interface ConnectionResult {
+  /** 连接是否成功 */
   success: boolean;
+  /** 服务器信息（失败时为空） */
   serverInfo?: ImapServerInfo | SmtpServerInfo;
+  /** 失败时的错误信息 */
   error?: string;
 }
 
+/**
+ * 邮箱列表项（IMAP mailbox）。
+ */
 export interface MailboxListItem {
+  /** 邮箱名称 */
   name: string;
+  /** 邮箱完整路径 */
   path: string;
+  /** 路径分隔符 */
   delimiter: string;
+  /** 属性标记 */
   flags: string[];
+  /** 是否已订阅 */
   subscribed: boolean;
 }
 
+/**
+ * 邮箱状态信息（原生层）。
+ */
 export interface MailboxInfo {
+  /** 邮箱名称 */
   name: string;
+  /** 邮箱完整路径 */
   path: string;
+  /** 下一个可用的 UID */
   uidNext: number;
+  /** UID 有效性标识 */
   uidValidity: number;
+  /** 邮件总数 */
   messageCount: number;
+  /** 新邮件（\Recent）数 */
   recentCount: number;
+  /** 未读邮件数 */
   unseenCount: number;
+  /** 第一封未读邮件的 UID */
   firstUnseenUid: number;
+  /** 最新修改序号 MODSEQ */
   highestModSeq: number;
+  /** 支持的标记列表 */
   flags: string[];
+  /** 可持久化的标记列表 */
   permanentFlags: string[];
 }
 
+/**
+ * 文件夹信息（原生层）。
+ */
 export interface FolderInfo {
+  /** 文件夹名称 */
   name: string;
+  /** 完整路径 */
   path: string;
+  /** 路径分隔符 */
   delimiter: string;
+  /** 父文件夹路径 */
   parent: string;
+  /** 直接子文件夹路径列表 */
   children: string[];
+  /** 属性标记 */
   flags: string[];
+  /** 是否已订阅 */
   subscribed: boolean;
+  /** 邮件总数 */
   messageCount: number;
+  /** 未读邮件数 */
   unseenCount: number;
 }
 
+/**
+ * 邮件正文（原生层）。
+ */
 export interface EmailBody {
+  /** 纯文本正文 */
   text: string;
+  /** HTML 正文 */
   html: string;
+  /** 内嵌资源的附件对象 ID 列表 */
   embeddedAttachments: string[];
 }
 
@@ -122,25 +216,47 @@ export interface EmailMessage {
   charset: string;
 }
 
+/**
+ * `imapFetchEmails` 的查询选项（原生层，与 src/types.ts 的 FetchEmailsOptions 对应）。
+ */
 export interface FetchEmailsOptions {
+  /** 范围起始 */
   from?: number;
+  /** 范围结束 */
   to?: number;
+  /** `uid` 按 UID，`sequence` 按序号 */
   rangeType?: string;
+  /** 页码（从最新往旧翻） */
   page?: number;
+  /** 每页数量 */
   pageSize?: number;
+  /** 只取晚于该时间的邮件（ISO 8601） */
   since?: string;
+  /** 只取早于该时间的邮件（ISO 8601） */
   before?: string;
+  /** 目标邮箱路径，默认 INBOX */
   mailbox?: string;
+  /** 是否下载正文 */
   fetchBody: boolean;
+  /** 是否下载附件 */
   fetchAttachments: boolean;
+  /** 是否返回标记 */
   fetchFlags: boolean;
+  /** 是否返回头字段 */
   fetchHeaders: boolean;
+  /** 是否返回完整原始内容 */
   fetchFullContent: boolean;
+  /** 正文大小上限（字节） */
   maxBodySize: number;
 }
 
+/**
+ * 按自定义头字段搜索。
+ */
 export interface SearchHeader {
+  /** 头字段名，如 `X-Tag` */
   key: string;
+  /** 期望值 */
   value: string;
 }
 
@@ -177,86 +293,167 @@ export interface SearchCriteria {
   maxBodySize: number;
 }
 
+/**
+ * 批量操作结果（原生层）。
+ */
 export interface DeleteResult {
+  /** 成功的 UID 列表 */
   success: number[];
+  /** 失败的 UID 列表 */
   failed: number[];
+  /** 失败时的错误信息 */
   error?: string;
 }
 
+/**
+ * 邮件附件（原生层）。
+ */
 export interface AttachmentInfo {
+  /** 附件文件名 */
   filename: string;
+  /** MIME 类型 */
   mimeType: string;
+  /** 在邮件体中的部分 ID */
   partId: string;
+  /** 大小（字节） */
   size: number;
+  /** 二进制内容 */
   data: ArrayBuffer;
+  /** 内嵌资源 content-id */
   contentId?: string;
+  /** 是否内嵌显示 */
   isInline: boolean;
+  /** 字符集 */
   charset?: string;
+  /** MIME 内容处置 */
   contentDisposition: string;
-  /** 附件缓存在本地的文件路径（如果有），避免大附件全部加载到内存 */
+  /** 本地缓存路径（大附件） */
   localPath?: string;
 }
 
+/**
+ * IDLE 实时通知（原生层）。
+ */
 export interface IdleNotification {
+  /** 通知类型：newMessage / messageDeleted / messageFlagged / mailboxChanged / connectionLost */
   type: string;
+  /** 发生变化的邮箱路径 */
   mailbox: string;
+  /** 涉及邮件的 UID */
   uid?: number;
+  /** 涉及的新标记名 */
   flag?: string;
+  /** 变化后的邮件总数 */
   messageCount?: number;
+  /** 通知时间戳（毫秒） */
   timestamp: number;
 }
 
+/**
+ * 配额信息（原生层）。
+ */
 export interface QuotaInfo {
+  /** 已用存储（字节） */
   storageUsed: number;
+  /** 存储上限（字节） */
   storageLimit: number;
+  /** 存储单位 */
   storageUnit: string;
+  /** 已用邮件数 */
   messagesUsed?: number;
+  /** 邮件数上限 */
   messagesLimit?: number;
+  /** 配额根名称 */
   root: string;
 }
 
+/**
+ * 追加邮件结果（原生层）。
+ */
 export interface AppendResult {
+  /** 新邮件 UID */
   uid: number;
+  /** uidValidity */
   uidValidity: number;
+  /** 追加时间（ISO 8601） */
   date: string;
 }
 
+/**
+ * 发送邮件附件（原生层）。
+ */
 export interface SmtpAttachment {
+  /** 附件文件名 */
   filename: string;
+  /** MIME 类型 */
   mimeType: string;
+  /** 二进制内容 */
   data: ArrayBuffer;
+  /** 是否内嵌显示 */
   isInline: boolean;
+  /** 内嵌资源 content-id */
   contentId?: string;
+  /** 内容处置：attachment / inline */
   disposition?: string;
 }
 
+/**
+ * 发信选项（原生层，与 src/types.ts 的 SendMailOptions 对应）。
+ */
 export interface SendMailOptions {
+  /** 发件人 */
   from: EmailAddress;
+  /** 收件人列表 */
   to: EmailAddress[];
+  /** 抄送列表 */
   cc?: EmailAddress[];
+  /** 密送列表 */
   bcc?: EmailAddress[];
+  /** 回复地址列表 */
   replyTo?: EmailAddress[];
+  /** 主题 */
   subject: string;
+  /** 纯文本正文 */
   textBody?: string;
+  /** HTML 正文 */
   htmlBody?: string;
+  /** 附件列表 */
   attachments?: SmtpAttachment[];
+  /** 优先级：low / normal / high */
   priority?: string;
+  /** 自定义头字段 */
   headers?: Record<string, string>;
+  /** 回复的父邮件 Message-ID */
   inReplyTo?: string;
+  /** 引用链 */
   references?: string;
+  /** 阅读回执收件人 */
   readReceiptTo?: EmailAddress;
+  /** 字符集 */
   charset?: string;
+  /** 传输编码 */
   encoding?: string;
 }
 
+/**
+ * 发信结果（原生层）。
+ */
 export interface SendMailResult {
+  /** 是否成功 */
   success: boolean;
+  /** 服务器生成的 Message-ID */
   messageId?: string;
+  /** 发送时间（ISO 8601） */
   date?: string;
+  /** 服务器响应码 */
   serverResponseCode?: number;
+  /** 原始 MIME 数据 */
   rawMimeData?: ArrayBuffer;
+  /** 队列 ID */
   queueId?: string;
+  /** 错误信息 */
   error?: string;
+  /** 是否可重试 */
   retryable?: boolean;
 }
 
@@ -264,59 +461,185 @@ export interface SendMailResult {
 //  HybridObject Interface
 // ═══════════════════════════════════════════════════════════
 
+/**
+ * 原生（Android / iOS）IMAP + SMTP 混合对象。
+ * 通过 NitroModules 暴露给 JS 层；Web / Windows 不经过此接口。
+ * 方法语义与公共 API（scripts/index.d.ts.template）一致。
+ */
 export interface EmailImapSmtp extends HybridObject<{
   ios: 'swift';
   android: 'kotlin';
 }> {
   // ─── Connection ─────────────────────────────────────────
+
+  /**
+   * 建立 IMAP 连接。
+   * @param config 服务器连接配置
+   */
   imapConnect(config: ConnectionConfig): Promise<ConnectionResult>;
+
+  /** 断开 IMAP 连接。 */
   imapDisconnect(): Promise<void>;
 
   // ─── Mailbox ────────────────────────────────────────────
+
+  /** 列出所有邮箱。 */
   imapListMailboxes(): Promise<MailboxListItem[]>;
+
+  /**
+   * 选择（打开）邮箱。
+   * @param mailbox 邮箱完整路径
+   * @param readOnly 是否只读打开
+   */
   imapSelectMailbox(mailbox: string, readOnly: boolean): Promise<MailboxInfo>;
+
+  /** 刷新当前邮箱状态。 */
   imapRefreshMailbox(): Promise<MailboxInfo>;
 
   // ─── Folders ────────────────────────────────────────────
+
+  /** 获取文件夹树。 */
   imapFetchFolders(): Promise<FolderInfo[]>;
+
+  /**
+   * 创建文件夹。
+   * @param folderName 新文件夹完整路径
+   */
   imapCreateFolder(folderName: string): Promise<void>;
+
+  /**
+   * 删除文件夹。
+   * @param folderName 待删除文件夹完整路径
+   */
   imapDeleteFolder(folderName: string): Promise<void>;
+
+  /**
+   * 重命名文件夹。
+   * @param oldName 原路径
+   * @param newName 新路径
+   */
   imapRenameFolder(oldName: string, newName: string): Promise<void>;
+
+  /**
+   * 订阅文件夹。
+   * @param folderName 文件夹完整路径
+   */
   imapSubscribeFolder(folderName: string): Promise<void>;
+
+  /**
+   * 取消订阅文件夹。
+   * @param folderName 文件夹完整路径
+   */
   imapUnsubscribeFolder(folderName: string): Promise<void>;
 
   // ─── Fetch Emails ────────────────────────────────────────
+
+  /**
+   * 拉取邮件列表。
+   * @param options 查询条件
+   */
   imapFetchEmails(options: FetchEmailsOptions): Promise<EmailMessage[]>;
+
+  /**
+   * 按 UID 获取单封邮件。
+   * @param uid 邮件 UID
+   */
   imapFetchEmailByUID(uid: number): Promise<EmailMessage | null>;
 
   // ─── Search ─────────────────────────────────────────────
+
+  /**
+   * 搜索邮件。
+   * @param criteria 搜索条件
+   */
   imapSearchEmails(criteria: SearchCriteria): Promise<EmailMessage[]>;
 
   // ─── Flags ──────────────────────────────────────────────
+
+  /**
+   * 标记为已读。
+   * @param uids 目标 UID 列表
+   * @param silent 是否静默
+   */
   imapMarkAsRead(uids: number[], silent: boolean): Promise<void>;
+
+  /**
+   * 添加 / 移除星标。
+   * @param uids 目标 UID 列表
+   * @param flagged true 加星标，false 取消
+   */
   imapMarkAsFlagged(uids: number[], flagged: boolean): Promise<void>;
 
   // ─── Move / Copy / Delete ───────────────────────────────
+
+  /**
+   * 移动邮件。
+   * @param uids 目标 UID 列表
+   * @param destinationMailbox 目标文件夹路径
+   */
   imapMoveEmails(uids: number[], destinationMailbox: string): Promise<void>;
+
+  /**
+   * 复制邮件。
+   * @param uids 目标 UID 列表
+   * @param destinationMailbox 目标文件夹路径
+   */
   imapCopyEmails(uids: number[], destinationMailbox: string): Promise<void>;
+
+  /**
+   * 删除邮件。
+   * @param uids 目标 UID 列表
+   */
   imapDeleteEmails(uids: number[]): Promise<DeleteResult>;
+
+  /** 永久清除标记为删除的邮件。 */
   imapExpunge(): Promise<void>;
 
   // ─── Attachments ───────────────────────────────────────
+
+  /**
+   * 获取单个附件。
+   * @param uid 所属邮件 UID
+   * @param partId 附件部分 ID
+   */
   imapFetchAttachments(
     uid: number,
     partId: string
   ): Promise<AttachmentInfo | null>;
+
+  /**
+   * 获取一封邮件的全部附件。
+   * @param uid 邮件 UID
+   */
   imapFetchAllAttachments(uid: number): Promise<AttachmentInfo[]>;
 
   // ─── IDLE ──────────────────────────────────────────────
+
+  /**
+   * 开启 IDLE 实时监听。
+   * @param callback 新通知回调
+   */
   imapIdle(callback: (notification: IdleNotification) => void): Promise<void>;
+
+  /** 停止 IDLE 监听。 */
   imapStopIdle(): Promise<void>;
 
   // ─── Quota ──────────────────────────────────────────────
+
+  /**
+   * 查询配额。
+   * @param root 配额根名称
+   */
   imapGetQuota(root?: string): Promise<QuotaInfo>;
 
   // ─── Append ────────────────────────────────────────────
+
+  /**
+   * 追加原始 MIME 邮件。
+   * @param mailbox 目标文件夹路径
+   * @param rawMimeData 原始 MIME 内容
+   * @param flags 附加标记
+   */
   imapAppendMessage(
     mailbox: string,
     rawMimeData: ArrayBuffer,
@@ -326,8 +649,22 @@ export interface EmailImapSmtp extends HybridObject<{
   // ═══════════════════════════════════════════════════════
   //  SMTP
   // ═══════════════════════════════════════════════════════
+
+  /**
+   * 建立 SMTP 连接。
+   * @param config 服务器连接配置
+   */
   smtpConnect(config: SmtpConnectionConfig): Promise<ConnectionResult>;
+
+  /** 断开 SMTP 连接。 */
   smtpDisconnect(): Promise<void>;
+
+  /**
+   * 发送邮件。
+   * @param options 发信选项
+   */
   smtpSendMail(options: SendMailOptions): Promise<SendMailResult>;
+
+  /** 验证 SMTP 连接是否可用。 */
   smtpVerifyConnection(): Promise<boolean>;
 }