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

package/src/types.ts

@@ -1,328 +1,653 @@
 // ============================================================
 // react-native-email-imap-smtp — Shared Type Definitions
+//
+// 这里是库对外暴露的全部公共类型。bob build 会把本文件编译成
+// lib/typescript/src/types.d.ts，供使用方的 TypeScript 直接消费，
+// 因此每个字段都带有 JSDoc 说明，悬停即可查看用途。
 // ============================================================
 
 // ─── Auth & Connection ───────────────────────────────────────
 
+/**
+ * 认证方式。
+ *
+ * - `'password'`：用户名 + 密码认证（默认）
+ * - `'oauth2'`：OAuth2 令牌认证，需配合 `accessToken` 使用
+ * - `'none'`：无需认证（匿名服务器 / 本地测试环境）
+ */
 export type AuthType = 'password' | 'oauth2' | 'none';
+
+/**
+ * 连接加密方式。
+ *
+ * - `'tls'`：直连 TLS（隐式加密，如 IMAP 993 / SMTP 465）
+ * - `'starttls'`：先明文后升级为 TLS（显式加密）
+ * - `'plain'`：不加密
+ */
 export type ConnectionType = 'tls' | 'starttls' | 'plain';
 
+/**
+ * IMAP 服务器连接配置。
+ * 传给 `imapConnect()` 建立 IMAP 会话。
+ */
 export interface IMAPConfig {
+  /** 邮件服务器主机名或 IP，例如 `imap.gmail.com` */
   host: string;
+  /** 服务器端口。TLS 通常 993，明文通常 143 */
   port: number;
+  /** 登录用户名（通常是完整邮箱地址） */
   username: string;
+  /** 登录密码 */
   password: string;
+  /** 是否使用 SSL/TLS 加密连接，默认 `true` */
   tls?: boolean;
+  /** 认证方式，默认 `'password'` */
   authType?: AuthType;
+  /** OAuth2 访问令牌；当 `authType === 'oauth2'` 时必填 */
   accessToken?: string;
+  /** 连接超时（毫秒），默认由平台决定（通常 10000） */
   timeout?: number;
+  /** 是否校验服务器证书；自签名证书环境可设为 `false` */
   checkCertificate?: boolean;
+  /** 是否在控制台输出调试日志 */
   debug?: boolean;
 }
 
+/**
+ * SMTP 服务器连接配置。
+ * 传给 `smtpConnect()` 建立 SMTP 会话。
+ */
 export interface SMTPConfig {
+  /** 邮件服务器主机名或 IP，例如 `smtp.gmail.com` */
   host: string;
+  /** 服务器端口。TLS 通常 465，明文通常 587 */
   port: number;
+  /** 登录用户名（通常是完整邮箱地址） */
   username: string;
+  /** 登录密码 */
   password: string;
+  /** 是否使用 SSL/TLS 加密连接，默认 `true` */
   tls?: boolean;
+  /** 认证方式，默认 `'password'` */
   authType?: AuthType;
+  /** OAuth2 访问令牌；当 `authType === 'oauth2'` 时必填 */
   accessToken?: string;
+  /** 连接超时（毫秒），默认由平台决定（通常 10000） */
   timeout?: number;
+  /** 是否校验服务器证书；自签名证书环境可设为 `false` */
   checkCertificate?: boolean;
+  /** EHLO 问候中的主机名；某些服务器要求与反向 DNS 一致 */
   helloName?: string;
+  /** 是否在控制台输出调试日志 */
   debug?: boolean;
 }
 
+/**
+ * `imapConnect()` 的返回结果。
+ */
 export interface IMAPConnectionResult {
+  /** 连接是否成功 */
   success: boolean;
+  /** 连接成功后服务器返回的信息（失败时为 undefined） */
   serverInfo?: {
+    /** 服务器标识名 */
     serverName: string;
+    /** 服务器支持的 IMAP 能力列表，如 `IMAP4rev1`、`IDLE`、`AUTH=PLAIN` */
     capabilities: string[];
+    /** 连接是否启用了压缩（COMPRESS=DEFLATE） */
     isCompressed: boolean;
   };
+  /** 连接失败时的错误信息（成功时为空） */
   error?: string;
 }
 
+/**
+ * `smtpConnect()` 的返回结果。
+ */
 export interface SMTPConnectionResult {
+  /** 连接是否成功 */
   success: boolean;
+  /** 连接成功后服务器返回的信息（失败时为 undefined） */
   serverInfo?: {
+    /** 服务器标识名 */
     serverName: string;
+    /** 服务器支持的 SMTP 扩展能力列表，如 `STARTTLS`、`SIZE` */
     capabilities: string[];
+    /** 服务器支持的认证方法，如 `PLAIN`、`LOGIN`、`XOAUTH2` */
     supportedAuthMethods: string[];
   };
+  /** 连接失败时的错误信息（成功时为空） */
   error?: string;
 }
 
 // ─── Mailbox / Folder ───────────────────────────────────────
 
+/**
+ * 邮箱/文件夹的标记（flag）名称。
+ * 常见值：`\\Seen`、`\\Answered`、`\\Flagged`、`\\Draft`、`\\Deleted`、`\\Junk` 等。
+ */
 export type MailboxFlag = string;
 
+/**
+ * 邮箱列表中的一个邮箱（IMAP mailbox）。
+ * 由 `imapListMailboxes()` 返回。
+ */
 export interface Mailbox {
+  /** 邮箱名称（不含路径分隔符） */
   name: string;
+  /** 邮箱完整路径，例如 `INBOX`、`Work/Project A` */
   path: string;
+  /** 路径分隔符（通常 `/` 或 `.`） */
   delimiter: string;
+  /** 邮箱属性标记，如 `\\Noselect`、`\\HasNoChildren` */
   flags: MailboxFlag[];
+  /** 是否已被订阅 */
   subscribed: boolean;
 }
 
+/**
+ * 文件夹树中的一个文件夹。
+ * 由 `imapFetchFolders()` 返回。
+ */
 export interface Folder {
+  /** 文件夹名称（不含路径分隔符） */
   name: string;
+  /** 文件夹完整路径 */
   path: string;
+  /** 路径分隔符（通常 `/` 或 `.`） */
   delimiter: string;
+  /** 父文件夹路径；顶层文件夹为 `''` */
   parent: string;
+  /** 直接子文件夹路径列表 */
   children: string[];
+  /** 文件夹属性标记，如 `\\Noselect` */
   flags: MailboxFlag[];
+  /** 是否已被订阅 */
   subscribed: boolean;
+  /** 文件夹内邮件总数 */
   messageCount: number;
+  /** 文件夹内未读邮件数 */
   unseenCount: number;
 }
 
 // ─── Mailbox Status ─────────────────────────────────────────
 
+/**
+ * 邮箱状态信息。
+ * 由 `imapSelectMailbox()` / `imapRefreshMailbox()` 返回。
+ */
 export interface MailboxStatus {
+  /** 邮箱名称 */
   name: string;
+  /** 邮箱完整路径 */
   path: string;
+  /** 下一个可用的 UID（新邮件会获得此 UID） */
   uidNext: number;
+  /** UID 有效性标识；该值变化说明邮箱的 UID 已重置 */
   uidValidity: number;
+  /** 邮箱内邮件总数 */
   messageCount: number;
+  /** 标记为 `\\Recent` 的邮件数（仅在本次会话内有效） */
   recentCount: number;
+  /** 未读邮件数 */
   unseenCount: number;
+  /** 第一封未读邮件的 UID；没有未读时为 0 */
   firstUnseenUid: number;
+  /** 最新修改序号（MODSEQ），用于增量同步；服务器不支持时为 undefined */
   highestModSeq?: number;
+  /** 邮箱支持的标记列表 */
   flags: string[];
+  /** 可持久化保存的标记列表 */
   permanentFlags: string[];
 }
 
 // ─── Email ──────────────────────────────────────────────────
 
+/**
+ * 邮件标记（flag）。
+ * 对应 IMAP 系统标记，映射到 `\\Seen` 等。
+ */
 export type EmailFlag =
+  /** 已读 */
   | 'seen'
+  /** 已回复 */
   | 'answered'
+  /** 已标记（星标） */
   | 'flagged'
+  /** 已删除（标记删除，需 expunge 才真正删除） */
   | 'deleted'
+  /** 草稿 */
   | 'draft'
+  /** 新邮件 */
   | 'recent'
+  /** 垃圾邮件 */
   | 'junk'
+  /** 已转发 */
   | 'forwarded';
 
+/**
+ * 邮件优先级。
+ */
 export type EmailPriority = 'low' | 'normal' | 'high';
 
+/**
+ * 邮件地址（发件人 / 收件人等）。
+ */
 export interface EmailAddress {
+  /** 显示名称，例如 `张三`；无名称时为 `''` */
   name: string;
+  /** 邮箱地址，例如 `zhangsan@example.com` */
   email: string;
 }
 
+/**
+ * 邮件附件。
+ */
 export interface Attachment {
+  /** 附件文件名 */
   filename: string;
+  /** MIME 类型，例如 `image/png`、`application/pdf` */
   mimeType: string;
+  /** 附件在邮件体中的部分 ID，可用于 `imapFetchAttachments()` 重新获取 */
   partId: string;
+  /** 附件大小（字节） */
   size: number;
+  /** 附件二进制内容 */
   data: ArrayBuffer;
+  /** 内嵌资源（CID）的 content-id；非内嵌时为 undefined */
   contentId?: string;
+  /** 是否内嵌在邮件正文中显示（如邮件内的图片） */
   isInline: boolean;
+  /** 附件字符集（文本类附件） */
   charset?: string;
+  /** MIME 内容处置，通常为 `attachment` 或 `inline` */
   contentDisposition: string;
-  /** 附件缓存在本地的文件路径（如果有），避免大附件全部加载到内存 */
+  /** 附件在本地缓存的文件路径（大附件避免全部加载到内存） */
   localPath?: string;
 }
 
+/**
+ * 邮件正文。
+ */
 export interface EmailBody {
+  /** 纯文本正文；无时为 undefined */
   text?: string;
+  /** HTML 正文；无时为 undefined */
   html?: string;
+  /** 内嵌在正文中的资源（图片等） */
   embeddedAttachments: Attachment[];
 }
 
+/**
+ * 邮件线程（会话）信息。
+ */
 export interface ThreadInfo {
+  /** 线程唯一 ID */
   threadId: string;
+  /** 父邮件的 Message-ID；根邮件为 `null` */
   parentMessageId: string | null;
+  /** 在线程树中的深度（根为 0） */
   depth: number;
+  /** 子线程列表 */
   children: ThreadInfo[];
 }
 
+/**
+ * 一封完整的邮件。
+ */
 export interface Email {
+  /** 邮件的唯一 UID（在同一邮箱内稳定） */
   uid: number;
+  /** 邮件在当前邮箱中的序号（会随删除邮件变化，仅当次会话有效） */
   sequenceNumber: number;
+  /** 邮件主题 */
   subject: string;
+  /** 发件人 */
   from: EmailAddress;
+  /** 收件人列表 */
   to: EmailAddress[];
+  /** 抄送列表 */
   cc: EmailAddress[];
+  /** 密送列表（通常为空，因服务器不返回） */
   bcc: EmailAddress[];
+  /** 回复地址列表 */
   replyTo: EmailAddress[];
+  /** 发送时间（ISO 8601 字符串） */
   date: string;
+  /** 服务器接收时间（ISO 8601 字符串） */
   receivedDate: string;
+  /** 邮件正文 */
   body: EmailBody;
+  /** 附件列表 */
   attachments: Attachment[];
+  /** 邮件标记列表 */
   flags: EmailFlag[];
+  /** 全部原始头字段（key 为头名小写） */
   headers: Record<string, string>;
+  /** 邮件大小（字节） */
   size: number;
+  /** Message-ID 头 */
   messageId: string;
+  /** 回复的父邮件 Message-ID；无时为 undefined */
   inReplyTo?: string;
+  /** 引用链（空格分隔的 Message-ID 列表） */
   references?: string;
+  /** 优先级 */
   priority: EmailPriority;
+  /** 是否加密（如 S/MIME、PGP 标记） */
   isEncrypted: boolean;
+  /** 邮件 MIME 类型，如 `text/plain`、`multipart/mixed` */
   mimeType: string;
+  /** 邮件字符集，如 `UTF-8` */
   charset: string;
 }
 
 // ─── Fetch Options ──────────────────────────────────────────
 
+/**
+ * 控制获取邮件时加载哪些部分。
+ */
 export interface FetchOptions {
+  /** 是否下载正文（纯文本/HTML），默认 `true` */
   fetchBody?: boolean;
+  /** 是否下载附件，默认 `true` */
   fetchAttachments?: boolean;
+  /** 是否返回标记，默认 `true` */
   fetchFlags?: boolean;
+  /** 是否返回完整头字段，默认 `true` */
   fetchHeaders?: boolean;
+  /** 是否返回完整原始邮件内容，默认 `false` */
   fetchFullContent?: boolean;
+  /** 正文大小上限（字节），超过则截断/不下载 */
   maxBodySize?: number;
 }
 
+/**
+ * `imapFetchEmails()` 的查询选项。
+ *
+ * 支持三种「范围模式」，按以下优先级生效：
+ * 1. `from` + `to`（指定 UID / 序号区间）
+ * 2. `page` + `pageSize`（分页，从最新邮件往前翻）
+ * 3. 默认：最近的 `pageSize ?? 20` 封
+ */
 export interface FetchEmailsOptions {
-  // 范围模式
+  /** 范围起始（UID 或序号） */
   from?: number;
+  /** 范围结束（UID 或序号） */
   to?: number;
+  /**
+   * 范围按 UID 还是按序号解释：
+   * - `'uid'`：按 UID（推荐，稳定不随删除变化）
+   * - `'sequence'`：按邮箱内序号（会随删除变化）
+   */
   rangeType?: 'uid' | 'sequence';
-  // 分页模式
+  /** 页码（从 1 开始，第 1 页为最新邮件） */
   page?: number;
+  /** 每页数量 */
   pageSize?: number;
-  // 时间模式
+  /** 只取晚于该时间的邮件（ISO 8601 字符串） */
   since?: string;
+  /** 只取早于该时间的邮件（ISO 8601 字符串） */
   before?: string;
-  // 通用
+  /** 目标邮箱路径，默认 `'INBOX'` */
   mailbox?: string;
-  // 获取选项（扁平化）
+  /** 是否下载正文，默认 `true` */
   fetchBody?: boolean;
+  /** 是否下载附件，默认 `true` */
   fetchAttachments?: boolean;
+  /** 是否返回标记，默认 `true` */
   fetchFlags?: boolean;
+  /** 是否返回完整头字段，默认 `true` */
   fetchHeaders?: boolean;
+  /** 是否返回完整原始邮件内容，默认 `false` */
   fetchFullContent?: boolean;
+  /** 正文大小上限（字节） */
   maxBodySize?: number;
 }
 
 // ─── Search ─────────────────────────────────────────────────
 
+/**
+ * `imapSearchEmails()` 的搜索条件。
+ * 多个条件之间为「且」的关系。
+ */
 export interface SearchCriteria {
+  /** 全文搜索关键字 */
   text?: string;
+  /** 按主题搜索 */
   subject?: string;
+  /** 按发件人搜索 */
   from?: string;
+  /** 按收件人搜索 */
   to?: string;
+  /** 按正文搜索 */
   body?: string;
+  /** 只搜内部日期晚于该时间的邮件（ISO 8601） */
   since?: string;
+  /** 只搜内部日期早于该时间的邮件（ISO 8601） */
   before?: string;
+  /** 只搜内部日期等于该日的邮件（ISO 8601） */
   on?: string;
+  /** 只搜发送日期晚于该时间的邮件（ISO 8601） */
   sentSince?: string;
+  /** 只搜发送日期早于该时间的邮件（ISO 8601） */
   sentBefore?: string;
+  /** 是否只搜已加星标的邮件 */
   flagged?: boolean;
+  /** 是否只搜已读邮件 */
   seen?: boolean;
+  /** 是否只搜已回复邮件 */
   answered?: boolean;
+  /** 是否只搜草稿 */
   draft?: boolean;
+  /** 是否只搜已标记删除的邮件 */
   deleted?: boolean;
+  /** 是否只搜垃圾邮件 */
   junk?: boolean;
+  /** 是否只搜带附件的邮件 */
   hasAttachment?: boolean;
+  /** 只搜指定 UID 列表中的邮件 */
   uids?: number[];
+  /** 按自定义头字段搜索，如 `{ key: 'X-Tag', value: 'vip' }` */
   header?: { key: string; value: string };
+  /** 只搜大于该字节数的邮件 */
   larger?: number;
+  /** 只搜小于该字节数的邮件 */
   smaller?: number;
+  /** 目标邮箱路径，默认 `'INBOX'` */
   mailbox?: string;
+  /** 结果排序，默认 `'desc'`（新邮件在前） */
   sortOrder?: 'asc' | 'desc';
+  /** 最多返回的邮件数 */
   limit?: number;
-  // 获取选项（扁平化）
+  /** 是否下载正文，默认 `true` */
   fetchBody?: boolean;
+  /** 是否下载附件，默认 `true` */
   fetchAttachments?: boolean;
+  /** 是否返回标记，默认 `true` */
   fetchFlags?: boolean;
+  /** 是否返回完整头字段，默认 `true` */
   fetchHeaders?: boolean;
+  /** 是否返回完整原始邮件内容，默认 `false` */
   fetchFullContent?: boolean;
+  /** 正文大小上限（字节） */
   maxBodySize?: number;
 }
 
 // ─── Send Mail ──────────────────────────────────────────────
 
+/**
+ * 发送邮件时的附件描述。
+ */
 export interface SendAttachment {
+  /** 附件文件名 */
   filename: string;
+  /** MIME 类型，例如 `image/png` */
   mimeType: string;
+  /** 附件内容（二进制） */
   data: ArrayBuffer;
+  /** 是否内嵌在正文显示（如邮件内图片） */
   isInline?: boolean;
+  /** 内嵌资源的 content-id */
   contentId?: string;
+  /** 内容处置，默认根据 `isInline` 推断为 `inline` 或 `attachment` */
   disposition?: 'attachment' | 'inline';
 }
 
+/**
+ * `smtpSendMail()` 的发信选项。
+ */
 export interface SendMailOptions {
+  /** 发件人 */
   from: EmailAddress;
+  /** 收件人列表 */
   to: EmailAddress[];
+  /** 抄送列表 */
   cc?: EmailAddress[];
+  /** 密送列表（收件人不可见） */
   bcc?: EmailAddress[];
+  /** 回复地址列表（默认取 `from`） */
   replyTo?: EmailAddress[];
+  /** 邮件主题 */
   subject: string;
+  /** 纯文本正文 */
   textBody?: string;
+  /** HTML 正文 */
   htmlBody?: string;
+  /** 附件列表 */
   attachments?: SendAttachment[];
+  /** 优先级，会写入 `X-Priority` 头 */
   priority?: EmailPriority;
+  /** 自定义头字段 */
   headers?: Record<string, string>;
+  /** 回复的父邮件 Message-ID */
   inReplyTo?: string;
+  /** 引用链 */
   references?: string;
+  /** 阅读回执收件人（写入 `Disposition-Notification-To` 头） */
   readReceiptTo?: EmailAddress;
+  /** 邮件字符集，默认 `UTF-8` */
   charset?: string;
+  /** 正文传输编码 */
   encoding?: '7bit' | '8bit' | 'base64' | 'quoted-printable';
 }
 
+/**
+ * `smtpSendMail()` 的返回结果。
+ */
 export interface SendMailResult {
+  /** 发送是否成功 */
   success: boolean;
+  /** 服务器生成的 Message-ID */
   messageId?: string;
+  /** 发送时间（ISO 8601） */
   date?: string;
+  /** 服务器响应码（通常 250） */
   serverResponseCode?: number;
+  /** 发送的原始 MIME 数据 */
   rawMimeData?: ArrayBuffer;
+  /** 队列 ID（与 `messageId` 相同，供排队服务使用） */
   queueId?: string;
+  /** 失败时的错误信息 */
   error?: string;
+  /** 该错误是否可重试（网络 / 超时类错误为 true） */
   retryable?: boolean;
 }
 
 // ─── IDLE ───────────────────────────────────────────────────
 
+/**
+ * IMAP IDLE 实时通知。
+ * 由 `imapIdle()` 的回调接收，表示邮箱发生了某种变化。
+ */
 export interface IMAPNotification {
+  /** 通知类型 */
   type:
+    /** 新邮件到达 */
     | 'newMessage'
+    /** 有邮件被删除 */
     | 'messageDeleted'
+    /** 有邮件被标记（如加星标） */
     | 'messageFlagged'
+    /** 邮箱整体发生变化（如 uidValidity 重置） */
     | 'mailboxChanged'
+    /** 连接意外断开 */
     | 'connectionLost';
+  /** 发生变化的邮箱路径 */
   mailbox: string;
+  /** 涉及邮件的 UID（`mailboxChanged` 时可能为空） */
   uid?: number;
+  /** 涉及的新标记名（`messageFlagged` 时） */
   flag?: string;
+  /** 变化后的邮件总数 */
   messageCount?: number;
+  /** 通知时间戳（毫秒） */
   timestamp: number;
 }
 
 // ─── Quota ──────────────────────────────────────────────────
 
+/**
+ * 邮箱配额信息。
+ * 由 `imapGetQuota()` 返回。
+ */
 export interface QuotaInfo {
+  /** 已用存储（字节） */
   storageUsed: number;
+  /** 存储上限（字节） */
   storageLimit: number;
+  /** 存储单位，通常为字节 `B` */
   storageUnit: string;
+  /** 已用邮件数（服务器支持时） */
   messagesUsed?: number;
+  /** 邮件数上限（服务器支持时） */
   messagesLimit?: number;
+  /** 配额根名称 */
   root: string;
 }
 
 // ─── Batch & Append Results ─────────────────────────────────
 
+/**
+ * 批量操作（如 `imapDeleteEmails`）的结果，按传入顺序逐封统计。
+ */
 export interface BatchResult {
+  /** 操作成功的 UID 列表 */
   success: number[];
+  /** 操作失败的 UID 列表 */
   failed: number[];
+  /** 失败时的错误信息 */
   error?: string;
 }
 
+/**
+ * `imapAppendMessage()` 的返回结果（追加成功后服务器分配的元数据）。
+ */
 export interface AppendResult {
+  /** 新邮件被分配的 UID */
   uid: number;
+  /** 追加时的 uidValidity */
   uidValidity: number;
+  /** 服务器记录的追加时间（ISO 8601） */
   date: string;
 }
 
 // ─── Error ──────────────────────────────────────────────────
 
+/**
+ * 邮件操作失败时抛出的错误对象。
+ */
 export interface EmailError {
+  /** 机器可读的错误码，如 `ECONNECTION`、`AUTH_FAILED` */
   code: string;
+  /** 人类可读的错误信息 */
   message: string;
+  /** 是否可重试（网络 / 超时类错误为 true） */
   retryable: boolean;
+  /** 服务器返回的响应原文 */
   serverResponse?: string;
+  /** 原始响应内容（与 `serverResponse` 可能相同） */
   originalResponse?: string;
+  /** 附加的详细错误数据（取决于具体实现） */
   details?: any;
 }