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

package/lib/typescript/src/index.d.ts

@@ -1,4 +1,20 @@
+/**
+ * react-native-email-imap-smtp — 公共 API 类型声明
+ *
+ * 本文件在 bob build 后被 scripts/fix-types.js 复制为
+ * `lib/typescript/src/index.d.ts`，是使用方看到的完整 API 签名。
+ * 修改公共 API 时，请保持 `src/index.tsx` 的实现导出与之同步。
+ */
 import type {
+  AuthType,
+  ConnectionType,
+  MailboxFlag,
+  EmailFlag,
+  EmailPriority,
+  EmailAddress,
+  EmailBody,
+  ThreadInfo,
+  FetchOptions,
   IMAPConfig,
   IMAPConnectionResult,
   Mailbox,
@@ -14,11 +30,22 @@ import type {
   AppendResult,
   SMTPConfig,
   SMTPConnectionResult,
+  SendAttachment,
   SendMailOptions,
   SendMailResult,
+  EmailError,
 } from './types';
 
 export {
+  AuthType,
+  ConnectionType,
+  MailboxFlag,
+  EmailFlag,
+  EmailPriority,
+  EmailAddress,
+  EmailBody,
+  ThreadInfo,
+  FetchOptions,
   IMAPConfig,
   IMAPConnectionResult,
   Mailbox,
@@ -34,99 +61,260 @@ export {
   AppendResult,
   SMTPConfig,
   SMTPConnectionResult,
+  SendAttachment,
   SendMailOptions,
   SendMailResult,
+  EmailError,
 }
 
 // ─── IMAP ──────────────────────────────────────────────────
 
+/**
+ * 建立 IMAP 连接。
+ *
+ * @param config 服务器连接配置（主机、端口、账号、加密方式等）
+ * @returns 连接结果，含服务器能力信息；`success === false` 时带 `error`
+ */
 export declare function imapConnect(
   config: IMAPConfig
 ): Promise<IMAPConnectionResult>;
 
+/**
+ * 断开当前 IMAP 连接并清理服务端会话。
+ *
+ * @returns 连接断开后 resolve；未连接时调用也安全
+ */
 export declare function imapDisconnect(): Promise<void>;
 
+/**
+ * 列出所有邮箱（IMAP mailboxes）。
+ *
+ * @returns 邮箱列表，含订阅状态与属性标记
+ */
 export declare function imapListMailboxes(): Promise<Mailbox[]>;
 
+/**
+ * 选择（打开）一个邮箱，之后的大多数 IMAP 操作都作用于该邮箱。
+ *
+ * @param mailbox 邮箱完整路径，例如 `'INBOX'`、`'Work/Project'`
+ * @param readOnly 是否以只读方式打开（不更新 `\\Seen` 标记），默认 false
+ * @returns 邮箱状态（UID、邮件数、未读数等）
+ */
 export declare function imapSelectMailbox(
   mailbox: string,
   readOnly?: boolean
 ): Promise<MailboxStatus>;
 
+/**
+ * 刷新当前邮箱的状态（重新获取邮件数、未读数等）。
+ *
+ * @returns 刷新后的邮箱状态
+ */
 export declare function imapRefreshMailbox(): Promise<MailboxStatus>;
 
+/**
+ * 获取文件夹树（含父子关系、邮件数、未读数）。
+ *
+ * @returns 文件夹列表
+ */
 export declare function imapFetchFolders(): Promise<Folder[]>;
 
+/**
+ * 创建一个新文件夹。
+ *
+ * @param folderName 新文件夹的完整路径，例如 `'Archive/2026'`
+ * @returns 创建完成后 resolve
+ */
 export declare function imapCreateFolder(folderName: string): Promise<void>;
 
+/**
+ * 删除一个文件夹及其中的所有邮件。
+ *
+ * @param folderName 待删除文件夹的完整路径
+ * @returns 删除完成后 resolve
+ */
 export declare function imapDeleteFolder(folderName: string): Promise<void>;
 
+/**
+ * 重命名 / 移动一个文件夹。
+ *
+ * @param oldName 原文件夹完整路径
+ * @param newName 新文件夹完整路径
+ * @returns 重命名完成后 resolve
+ */
 export declare function imapRenameFolder(
   oldName: string,
   newName: string
 ): Promise<void>;
 
+/**
+ * 订阅一个文件夹（出现在大多数客户端的默认列表中）。
+ *
+ * @param folderName 待订阅文件夹的完整路径
+ * @returns 订阅完成后 resolve
+ */
 export declare function imapSubscribeFolder(folderName: string): Promise<void>;
 
+/**
+ * 取消订阅一个文件夹。
+ *
+ * @param folderName 待取消订阅文件夹的完整路径
+ * @returns 取消订阅完成后 resolve
+ */
 export declare function imapUnsubscribeFolder(
   folderName: string
 ): Promise<void>;
 
+/**
+ * 拉取邮件列表。
+ *
+ * @param options 查询条件（范围 / 分页 / 时间过滤 / 加载哪些部分）
+ * @returns 匹配的邮件列表（按 UID 从新到旧排序）
+ */
 export declare function imapFetchEmails(
   options: FetchEmailsOptions
 ): Promise<Email[]>;
 
+/**
+ * 按 UID 获取单封邮件。
+ *
+ * @param uid 邮件的 UID
+ * @returns 邮件内容；UID 不存在时返回 `null`
+ */
 export declare function imapFetchEmailByUID(
   uid: number
 ): Promise<Email | null>;
 
+/**
+ * 按条件搜索邮件。
+ *
+ * @param criteria 搜索条件（关键字、发件人、时间、标记等，多个条件为「且」）
+ * @returns 匹配的邮件列表（默认按 UID 从新到旧排序）
+ */
 export declare function imapSearchEmails(
   criteria: SearchCriteria
 ): Promise<Email[]>;
 
+/**
+ * 将指定邮件标记为已读。
+ *
+ * @param uids 目标邮件的 UID 列表
+ * @param silent 是否不触发服务器回调（避免其他客户端重复提醒），默认 false
+ * @returns 标记完成后 resolve
+ */
 export declare function imapMarkAsRead(
   uids: number[],
   silent?: boolean
 ): Promise<void>;
 
+/**
+ * 添加或移除星标（`\\Flagged`）。
+ *
+ * @param uids 目标邮件的 UID 列表
+ * @param flagged `true` 加星标，`false` 取消星标
+ * @returns 标记完成后 resolve
+ */
 export declare function imapMarkAsFlagged(
   uids: number[],
   flagged: boolean
 ): Promise<void>;
 
+/**
+ * 将邮件移动到另一个文件夹（原文件夹中的邮件被移除）。
+ *
+ * @param uids 目标邮件的 UID 列表
+ * @param destinationMailbox 目标文件夹的完整路径
+ * @returns 移动完成后 resolve
+ */
 export declare function imapMoveEmails(
   uids: number[],
   destinationMailbox: string
 ): Promise<void>;
 
+/**
+ * 将邮件复制到另一个文件夹（原邮件保留）。
+ *
+ * @param uids 目标邮件的 UID 列表
+ * @param destinationMailbox 目标文件夹的完整路径
+ * @returns 复制完成后 resolve
+ */
 export declare function imapCopyEmails(
   uids: number[],
   destinationMailbox: string
 ): Promise<void>;
 
+/**
+ * 删除指定邮件（标记 `\\Deleted` 并执行 expunge）。
+ *
+ * @param uids 目标邮件的 UID 列表
+ * @returns 逐封操作的结果统计
+ */
 export declare function imapDeleteEmails(
   uids: number[]
 ): Promise<BatchResult>;
 
+/**
+ * 永久清除当前邮箱中被标记为删除的邮件。
+ *
+ * @returns 清理完成后 resolve
+ */
 export declare function imapExpunge(): Promise<void>;
 
+/**
+ * 获取单个附件内容。
+ *
+ * @param uid 所属邮件的 UID
+ * @param partId 附件在邮件体中的部分 ID（来自 `Email.attachments[].partId`）
+ * @returns 附件内容；不存在时返回 `null`
+ */
 export declare function imapFetchAttachments(
   uid: number,
   partId: string
 ): Promise<Attachment | null>;
 
+/**
+ * 获取一封邮件的全部附件。
+ *
+ * @param uid 邮件的 UID
+ * @returns 附件列表
+ */
 export declare function imapFetchAllAttachments(
   uid: number
 ): Promise<Attachment[]>;
 
+/**
+ * 开启 IMAP IDLE 实时监听，邮箱发生变化时触发回调。
+ *
+ * @param callback 收到新通知时调用（新邮件、删除、标记变化、连接断开等）
+ * @returns 监听建立后 resolve
+ */
 export declare function imapIdle(
   callback: (notification: IMAPNotification) => void
 ): Promise<void>;
 
+/**
+ * 停止 IDLE 实时监听。
+ *
+ * @returns 监听停止后 resolve
+ */
 export declare function imapStopIdle(): Promise<void>;
 
+/**
+ * 查询邮箱配额。
+ *
+ * @param root 配额根名称；不传时使用服务器默认根
+ * @returns 配额信息（存储用量 / 上限）
+ */
 export declare function imapGetQuota(root?: string): Promise<QuotaInfo>;
 
+/**
+ * 将一封原始 MIME 邮件追加到指定文件夹。
+ *
+ * @param mailbox 目标文件夹完整路径
+ * @param rawMimeData 原始 MIME 二进制内容
+ * @param flags 附加的标记列表，如 `['\\Seen']`
+ * @returns 追加成功后服务器分配的 UID 等元数据
+ */
 export declare function imapAppendMessage(
   mailbox: string,
   rawMimeData: ArrayBuffer,
@@ -135,21 +323,67 @@ export declare function imapAppendMessage(
 
 // ─── SMTP ──────────────────────────────────────────────────
 
+/**
+ * 建立 SMTP 连接。
+ *
+ * @param config 服务器连接配置（主机、端口、账号、加密方式等）
+ * @returns 连接结果，含服务器能力与支持的认证方法信息
+ */
 export declare function smtpConnect(
   config: SMTPConfig
 ): Promise<SMTPConnectionResult>;
 
+/**
+ * 断开当前 SMTP 连接并清理会话。
+ *
+ * @returns 断开完成后 resolve；未连接时调用也安全
+ */
 export declare function smtpDisconnect(): Promise<void>;
 
+/**
+ * 发送一封邮件。
+ *
+ * @param options 发信选项（发件人、收件人、主题、正文、附件、优先级等）
+ * @returns 发送结果；`success === false` 时带 `error`
+ */
 export declare function smtpSendMail(
   options: SendMailOptions
 ): Promise<SendMailResult>;
 
+/**
+ * 验证当前 SMTP 连接是否仍可用。
+ *
+ * @returns `true` 表示连接正常可用
+ */
 export declare function smtpVerifyConnection(): Promise<boolean>;
 
 // ─── Web 专属（原生平台为 undefined） ─────────────────────
 
+/**
+ * 设置 Web 端代理服务器地址。
+ *
+ * 仅在 Web 平台可用；原生平台此值为 `undefined`。
+ * 例如 `setProxyUrl('http://localhost:3987')`。
+ */
 export declare const setProxyUrl: ((url: string) => void) | undefined;
+
+/**
+ * 获取当前 Web 端代理服务器地址。
+ *
+ * 仅在 Web 平台可用；原生平台此值为 `undefined`。
+ */
 export declare const getProxyUrl: (() => string) | undefined;
+
+/**
+ * IMAP 未连接错误类，可用于 `instanceof` 判断。
+ *
+ * 仅在 Web 平台可用；原生平台此值为 `undefined`。
+ */
 export declare const ImapNotConnectedError: (new () => Error) | undefined;
+
+/**
+ * SMTP 未连接错误类，可用于 `instanceof` 判断。
+ *
+ * 仅在 Web 平台可用；原生平台此值为 `undefined`。
+ */
 export declare const SmtpNotConnectedError: (new () => Error) | undefined;