tempmail-sdk 1.0.2 → 1.0.3

package/dist/types.d.ts

@@ -1,18 +1,36 @@
+/**
+ * 支持的临时邮箱渠道标识
+ * 每个渠道对应一个第三方临时邮箱服务商
+ */
 export type Channel = 'tempmail' | 'linshi-email' | 'tempmail-lol' | 'chatgpt-org-uk' | 'tempmail-la' | 'temp-mail-io' | 'awamail' | 'mail-tm' | 'dropmail';
+/**
+ * 创建临时邮箱后返回的邮箱信息
+ * 包含邮箱地址、认证令牌和生命周期信息
+ */
 export interface EmailInfo {
+    /** 创建该邮箱所使用的渠道 */
     channel: Channel;
+    /** 临时邮箱地址 */
     email: string;
+    /** 认证令牌，部分渠道在获取邮件时需要此令牌 */
     token?: string;
+    /** 邮箱过期时间（ISO 8601 字符串或 Unix 时间戳） */
     expiresAt?: string | number;
+    /** 邮箱创建时间（ISO 8601 字符串） */
     createdAt?: string;
 }
 /**
  * 标准化邮件附件
+ * 不同渠道的附件字段名不同，SDK 统一归一化为此结构
  */
 export interface EmailAttachment {
+    /** 附件文件名 */
     filename: string;
+    /** 附件大小（字节） */
     size?: number;
+    /** MIME 类型，如 application/pdf */
     contentType?: string;
+    /** 附件下载地址 */
     url?: string;
 }
 /**
@@ -38,19 +56,88 @@ export interface Email {
     /** 附件列表 */
     attachments: EmailAttachment[];
 }
+/**
+ * 获取邮件列表的返回结果
+ * success 为 false 时表示请求失败（重试耗尽），emails 为空数组
+ */
 export interface GetEmailsResult {
+    /** 所使用的渠道 */
     channel: Channel;
+    /** 查询的邮箱地址 */
     email: string;
+    /** 邮件列表，失败时为空数组 */
     emails: Email[];
+    /** 请求是否成功，false 表示重试耗尽后仍失败 */
     success: boolean;
 }
+/**
+ * 重试配置
+ * SDK 内部对网络错误、超时、5xx 服务端错误自动重试
+ * 4xx 客户端错误（如参数错误）不会重试
+ *
+ * @example
+ * ```ts
+ * // 自定义重试策略：最多重试 3 次，首次延迟 2 秒
+ * const email = await generateEmail({
+ *   channel: 'mail-tm',
+ *   retry: { maxRetries: 3, initialDelay: 2000 },
+ * });
+ * ```
+ */
+export interface RetryConfig {
+    /** 最大重试次数（不含首次请求），默认 2 */
+    maxRetries?: number;
+    /** 初始重试延迟（毫秒），采用指数退避策略，默认 1000 */
+    initialDelay?: number;
+    /** 最大重试延迟上限（毫秒），默认 5000 */
+    maxDelay?: number;
+    /** 单次请求超时时间（毫秒），默认 15000 */
+    timeout?: number;
+}
+/**
+ * 创建临时邮箱的选项
+ *
+ * @example
+ * ```ts
+ * // 使用指定渠道创建邮箱
+ * const email = await generateEmail({ channel: 'mail-tm' });
+ *
+ * // 随机选择渠道
+ * const email = await generateEmail();
+ * ```
+ */
 export interface GenerateEmailOptions {
+    /** 指定渠道，不传则随机选择 */
     channel?: Channel;
+    /** 邮箱有效时长 */
     duration?: number;
+    /** 指定邮箱域名 */
     domain?: string | null;
+    /** 重试配置，不传则使用默认值（最多重试 2 次） */
+    retry?: RetryConfig;
 }
+/**
+ * 获取邮件列表的选项
+ *
+ * @example
+ * ```ts
+ * const result = await getEmails({
+ *   channel: emailInfo.channel,
+ *   email: emailInfo.email,
+ *   token: emailInfo.token,
+ * });
+ * if (result.success && result.emails.length > 0) {
+ *   console.log('收到邮件:', result.emails);
+ * }
+ * ```
+ */
 export interface GetEmailsOptions {
+    /** 渠道标识，必填 */
     channel: Channel;
+    /** 邮箱地址，必填 */
     email: string;
+    /** 认证令牌 */
     token?: string;
+    /** 重试配置，不传则使用默认值（最多重试 2 次） */
+    retry?: RetryConfig;
 }

package/dist/types.js

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCB0eXBlIENoYW5uZWwgPSAndGVtcG1haWwnIHwgJ2xpbnNoaS1lbWFpbCcgfCAndGVtcG1haWwtbG9sJyB8ICdjaGF0Z3B0LW9yZy11aycgfCAndGVtcG1haWwtbGEnIHwgJ3RlbXAtbWFpbC1pbycgfCAnYXdhbWFpbCcgfCAnbWFpbC10bScgfCAnZHJvcG1haWwnO1xuXG5leHBvcnQgaW50ZXJmYWNlIEVtYWlsSW5mbyB7XG4gIGNoYW5uZWw6IENoYW5uZWw7XG4gIGVtYWlsOiBzdHJpbmc7XG4gIHRva2VuPzogc3RyaW5nO1xuICBleHBpcmVzQXQ/OiBzdHJpbmcgfCBudW1iZXI7XG4gIGNyZWF0ZWRBdD86IHN0cmluZztcbn1cblxuLyoqXG4gKiDmoIflh4bljJbpgq7ku7bpmYTku7ZcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBFbWFpbEF0dGFjaG1lbnQge1xuICBmaWxlbmFtZTogc3RyaW5nO1xuICBzaXplPzogbnVtYmVyO1xuICBjb250ZW50VHlwZT86IHN0cmluZztcbiAgdXJsPzogc3RyaW5nO1xufVxuXG4vKipcbiAqIOagh+WHhuWMlumCruS7tuagvOW8jyAtIOaJgOacieaPkOS+m+WVhui/lOWbnue7n+S4gOe7k+aehFxuICovXG5leHBvcnQgaW50ZXJmYWNlIEVtYWlsIHtcbiAgLyoqIOmCruS7tuWUr+S4gOagh+ivhiAqL1xuICBpZDogc3RyaW5nO1xuICAvKiog5Y+R5Lu25Lq66YKu566x5Zyw5Z2AICovXG4gIGZyb206IHN0cmluZztcbiAgLyoqIOaUtuS7tuS6uumCrueuseWcsOWdgCAqL1xuICB0bzogc3RyaW5nO1xuICAvKiog6YKu5Lu25Li76aKYICovXG4gIHN1YmplY3Q6IHN0cmluZztcbiAgLyoqIOe6r+aWh+acrOWGheWuuSAqL1xuICB0ZXh0OiBzdHJpbmc7XG4gIC8qKiBIVE1MIOWGheWuuSAqL1xuICBodG1sOiBzdHJpbmc7XG4gIC8qKiBJU08gODYwMSDmoLzlvI/nmoTml6XmnJ/lrZfnrKbkuLIgKi9cbiAgZGF0ZTogc3RyaW5nO1xuICAvKiog5piv5ZCm5bey6K+7ICovXG4gIGlzUmVhZDogYm9vbGVhbjtcbiAgLyoqIOmZhOS7tuWIl+ihqCAqL1xuICBhdHRhY2htZW50czogRW1haWxBdHRhY2htZW50W107XG59XG5cbmV4cG9ydCBpbnRlcmZhY2UgR2V0RW1haWxzUmVzdWx0IHtcbiAgY2hhbm5lbDogQ2hhbm5lbDtcbiAgZW1haWw6IHN0cmluZztcbiAgZW1haWxzOiBFbWFpbFtdO1xuICBzdWNjZXNzOiBib29sZWFuO1xufVxuXG5leHBvcnQgaW50ZXJmYWNlIEdlbmVyYXRlRW1haWxPcHRpb25zIHtcbiAgY2hhbm5lbD86IENoYW5uZWw7XG4gIGR1cmF0aW9uPzogbnVtYmVyO1xuICBkb21haW4/OiBzdHJpbmcgfCBudWxsO1xufVxuXG5leHBvcnQgaW50ZXJmYWNlIEdldEVtYWlsc09wdGlvbnMge1xuICBjaGFubmVsOiBDaGFubmVsO1xuICBlbWFpbDogc3RyaW5nO1xuICB0b2tlbj86IHN0cmluZztcbn1cbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICog5pSv5oyB55qE5Li05pe26YKu566x5rig6YGT5qCH6K+GXG4gKiDmr4/kuKrmuKDpgZPlr7nlupTkuIDkuKrnrKzkuInmlrnkuLTml7bpgq7nrrHmnI3liqHllYZcbiAqL1xuZXhwb3J0IHR5cGUgQ2hhbm5lbCA9ICd0ZW1wbWFpbCcgfCAnbGluc2hpLWVtYWlsJyB8ICd0ZW1wbWFpbC1sb2wnIHwgJ2NoYXRncHQtb3JnLXVrJyB8ICd0ZW1wbWFpbC1sYScgfCAndGVtcC1tYWlsLWlvJyB8ICdhd2FtYWlsJyB8ICdtYWlsLXRtJyB8ICdkcm9wbWFpbCc7XG5cbi8qKlxuICog5Yib5bu65Li05pe26YKu566x5ZCO6L+U5Zue55qE6YKu566x5L+h5oGvXG4gKiDljIXlkKvpgq7nrrHlnLDlnYDjgIHorqTor4Hku6TniYzlkoznlJ/lkb3lkajmnJ/kv6Hmga9cbiAqL1xuZXhwb3J0IGludGVyZmFjZSBFbWFpbEluZm8ge1xuICAvKiog5Yib5bu66K+l6YKu566x5omA5L2/55So55qE5rig6YGTICovXG4gIGNoYW5uZWw6IENoYW5uZWw7XG4gIC8qKiDkuLTml7bpgq7nrrHlnLDlnYAgKi9cbiAgZW1haWw6IHN0cmluZztcbiAgLyoqIOiupOivgeS7pOeJjO+8jOmDqOWIhua4oOmBk+WcqOiOt+WPlumCruS7tuaXtumcgOimgeatpOS7pOeJjCAqL1xuICB0b2tlbj86IHN0cmluZztcbiAgLyoqIOmCrueusei/h+acn+aXtumXtO+8iElTTyA4NjAxIOWtl+espuS4suaIliBVbml4IOaXtumXtOaIs++8iSAqL1xuICBleHBpcmVzQXQ/OiBzdHJpbmcgfCBudW1iZXI7XG4gIC8qKiDpgq7nrrHliJvlu7rml7bpl7TvvIhJU08gODYwMSDlrZfnrKbkuLLvvIkgKi9cbiAgY3JlYXRlZEF0Pzogc3RyaW5nO1xufVxuXG4vKipcbiAqIOagh+WHhuWMlumCruS7tumZhOS7tlxuICog5LiN5ZCM5rig6YGT55qE6ZmE5Lu25a2X5q615ZCN5LiN5ZCM77yMU0RLIOe7n+S4gOW9kuS4gOWMluS4uuatpOe7k+aehFxuICovXG5leHBvcnQgaW50ZXJmYWNlIEVtYWlsQXR0YWNobWVudCB7XG4gIC8qKiDpmYTku7bmlofku7blkI0gKi9cbiAgZmlsZW5hbWU6IHN0cmluZztcbiAgLyoqIOmZhOS7tuWkp+Wwj++8iOWtl+iKgu+8iSAqL1xuICBzaXplPzogbnVtYmVyO1xuICAvKiogTUlNRSDnsbvlnovvvIzlpoIgYXBwbGljYXRpb24vcGRmICovXG4gIGNvbnRlbnRUeXBlPzogc3RyaW5nO1xuICAvKiog6ZmE5Lu25LiL6L295Zyw5Z2AICovXG4gIHVybD86IHN0cmluZztcbn1cblxuLyoqXG4gKiDmoIflh4bljJbpgq7ku7bmoLzlvI8gLSDmiYDmnInmj5DkvpvllYbov5Tlm57nu5/kuIDnu5PmnoRcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBFbWFpbCB7XG4gIC8qKiDpgq7ku7bllK/kuIDmoIfor4YgKi9cbiAgaWQ6IHN0cmluZztcbiAgLyoqIOWPkeS7tuS6uumCrueuseWcsOWdgCAqL1xuICBmcm9tOiBzdHJpbmc7XG4gIC8qKiDmlLbku7bkurrpgq7nrrHlnLDlnYAgKi9cbiAgdG86IHN0cmluZztcbiAgLyoqIOmCruS7tuS4u+mimCAqL1xuICBzdWJqZWN0OiBzdHJpbmc7XG4gIC8qKiDnuq/mlofmnKzlhoXlrrkgKi9cbiAgdGV4dDogc3RyaW5nO1xuICAvKiogSFRNTCDlhoXlrrkgKi9cbiAgaHRtbDogc3RyaW5nO1xuICAvKiogSVNPIDg2MDEg5qC85byP55qE5pel5pyf5a2X56ym5LiyICovXG4gIGRhdGU6IHN0cmluZztcbiAgLyoqIOaYr+WQpuW3suivuyAqL1xuICBpc1JlYWQ6IGJvb2xlYW47XG4gIC8qKiDpmYTku7bliJfooaggKi9cbiAgYXR0YWNobWVudHM6IEVtYWlsQXR0YWNobWVudFtdO1xufVxuXG4vKipcbiAqIOiOt+WPlumCruS7tuWIl+ihqOeahOi/lOWbnue7k+aenFxuICogc3VjY2VzcyDkuLogZmFsc2Ug5pe26KGo56S66K+35rGC5aSx6LSl77yI6YeN6K+V6ICX5bC977yJ77yMZW1haWxzIOS4uuepuuaVsOe7hFxuICovXG5leHBvcnQgaW50ZXJmYWNlIEdldEVtYWlsc1Jlc3VsdCB7XG4gIC8qKiDmiYDkvb/nlKjnmoTmuKDpgZMgKi9cbiAgY2hhbm5lbDogQ2hhbm5lbDtcbiAgLyoqIOafpeivoueahOmCrueuseWcsOWdgCAqL1xuICBlbWFpbDogc3RyaW5nO1xuICAvKiog6YKu5Lu25YiX6KGo77yM5aSx6LSl5pe25Li656m65pWw57uEICovXG4gIGVtYWlsczogRW1haWxbXTtcbiAgLyoqIOivt+axguaYr+WQpuaIkOWKn++8jGZhbHNlIOihqOekuumHjeivleiAl+WwveWQjuS7jeWksei0pSAqL1xuICBzdWNjZXNzOiBib29sZWFuO1xufVxuXG4vKipcbiAqIOmHjeivlemFjee9rlxuICogU0RLIOWGhemDqOWvuee9kee7nOmUmeivr+OAgei2heaXtuOAgTV4eCDmnI3liqHnq6/plJnor6/oh6rliqjph43or5VcbiAqIDR4eCDlrqLmiLfnq6/plJnor6/vvIjlpoLlj4LmlbDplJnor6/vvInkuI3kvJrph43or5VcbiAqXG4gKiBAZXhhbXBsZVxuICogYGBgdHNcbiAqIC8vIOiHquWumuS5iemHjeivleetlueVpe+8muacgOWkmumHjeivlSAzIOasoe+8jOmmluasoeW7tui/nyAyIOenklxuICogY29uc3QgZW1haWwgPSBhd2FpdCBnZW5lcmF0ZUVtYWlsKHtcbiAqICAgY2hhbm5lbDogJ21haWwtdG0nLFxuICogICByZXRyeTogeyBtYXhSZXRyaWVzOiAzLCBpbml0aWFsRGVsYXk6IDIwMDAgfSxcbiAqIH0pO1xuICogYGBgXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgUmV0cnlDb25maWcge1xuICAvKiog5pyA5aSn6YeN6K+V5qyh5pWw77yI5LiN5ZCr6aaW5qyh6K+35rGC77yJ77yM6buY6K6kIDIgKi9cbiAgbWF4UmV0cmllcz86IG51bWJlcjtcbiAgLyoqIOWIneWni+mHjeivleW7tui/n++8iOavq+enku+8ie+8jOmHh+eUqOaMh+aVsOmAgOmBv+etlueVpe+8jOm7mOiupCAxMDAwICovXG4gIGluaXRpYWxEZWxheT86IG51bWJlcjtcbiAgLyoqIOacgOWkp+mHjeivleW7tui/n+S4iumZkO+8iOavq+enku+8ie+8jOm7mOiupCA1MDAwICovXG4gIG1heERlbGF5PzogbnVtYmVyO1xuICAvKiog5Y2V5qyh6K+35rGC6LaF5pe25pe26Ze077yI5q+r56eS77yJ77yM6buY6K6kIDE1MDAwICovXG4gIHRpbWVvdXQ/OiBudW1iZXI7XG59XG5cbi8qKlxuICog5Yib5bu65Li05pe26YKu566x55qE6YCJ6aG5XG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHRzXG4gKiAvLyDkvb/nlKjmjIflrprmuKDpgZPliJvlu7rpgq7nrrFcbiAqIGNvbnN0IGVtYWlsID0gYXdhaXQgZ2VuZXJhdGVFbWFpbCh7IGNoYW5uZWw6ICdtYWlsLXRtJyB9KTtcbiAqXG4gKiAvLyDpmo/mnLrpgInmi6nmuKDpgZNcbiAqIGNvbnN0IGVtYWlsID0gYXdhaXQgZ2VuZXJhdGVFbWFpbCgpO1xuICogYGBgXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgR2VuZXJhdGVFbWFpbE9wdGlvbnMge1xuICAvKiog5oyH5a6a5rig6YGT77yM5LiN5Lyg5YiZ6ZqP5py66YCJ5oupICovXG4gIGNoYW5uZWw/OiBDaGFubmVsO1xuICAvKiog6YKu566x5pyJ5pWI5pe26ZW/ICovXG4gIGR1cmF0aW9uPzogbnVtYmVyO1xuICAvKiog5oyH5a6a6YKu566x5Z+f5ZCNICovXG4gIGRvbWFpbj86IHN0cmluZyB8IG51bGw7XG4gIC8qKiDph43or5XphY3nva7vvIzkuI3kvKDliJnkvb/nlKjpu5jorqTlgLzvvIjmnIDlpJrph43or5UgMiDmrKHvvIkgKi9cbiAgcmV0cnk/OiBSZXRyeUNvbmZpZztcbn1cblxuLyoqXG4gKiDojrflj5bpgq7ku7bliJfooajnmoTpgInpoblcbiAqXG4gKiBAZXhhbXBsZVxuICogYGBgdHNcbiAqIGNvbnN0IHJlc3VsdCA9IGF3YWl0IGdldEVtYWlscyh7XG4gKiAgIGNoYW5uZWw6IGVtYWlsSW5mby5jaGFubmVsLFxuICogICBlbWFpbDogZW1haWxJbmZvLmVtYWlsLFxuICogICB0b2tlbjogZW1haWxJbmZvLnRva2VuLFxuICogfSk7XG4gKiBpZiAocmVzdWx0LnN1Y2Nlc3MgJiYgcmVzdWx0LmVtYWlscy5sZW5ndGggPiAwKSB7XG4gKiAgIGNvbnNvbGUubG9nKCfmlLbliLDpgq7ku7Y6JywgcmVzdWx0LmVtYWlscyk7XG4gKiB9XG4gKiBgYGBcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBHZXRFbWFpbHNPcHRpb25zIHtcbiAgLyoqIOa4oOmBk+agh+ivhu+8jOW/heWhqyAqL1xuICBjaGFubmVsOiBDaGFubmVsO1xuICAvKiog6YKu566x5Zyw5Z2A77yM5b+F5aGrICovXG4gIGVtYWlsOiBzdHJpbmc7XG4gIC8qKiDorqTor4Hku6TniYwgKi9cbiAgdG9rZW4/OiBzdHJpbmc7XG4gIC8qKiDph43or5XphY3nva7vvIzkuI3kvKDliJnkvb/nlKjpu5jorqTlgLzvvIjmnIDlpJrph43or5UgMiDmrKHvvIkgKi9cbiAgcmV0cnk/OiBSZXRyeUNvbmZpZztcbn1cbiJdfQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempmail-sdk",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "临时邮箱 SDK - 支持多个临时邮箱服务商",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -8,10 +8,15 @@ import * as awamail from './providers/awamail';
 import * as mailTm from './providers/mail-tm';
 import * as dropmail from './providers/dropmail';
 import { Channel, EmailInfo, Email, EmailAttachment, GetEmailsResult, GenerateEmailOptions, GetEmailsOptions } from './types';
+import { withRetry, RetryOptions } from './retry';
+import { logger } from './logger';
 
 export { Channel, EmailInfo, Email, EmailAttachment, GetEmailsResult, GenerateEmailOptions, GetEmailsOptions } from './types';
 export { normalizeEmail } from './normalize';
+export { withRetry, fetchWithTimeout, RetryOptions } from './retry';
+export { LogLevel, LogHandler, setLogLevel, getLogLevel, setLogger, logger } from './logger';
 
+/** 渠道名称到 provider 实现的映射表 */
 const providers = {
   'tempmail': tempmail,
   'linshi-email': linshiEmail,
@@ -24,14 +29,22 @@ const providers = {
   'dropmail': dropmail,
 };
 
+/** 所有支持的渠道列表，用于随机选择和遍历 */
 const allChannels: Channel[] = ['tempmail', 'linshi-email', 'tempmail-lol', 'chatgpt-org-uk', 'tempmail-la', 'temp-mail-io', 'awamail', 'mail-tm', 'dropmail'];
 
+/**
+ * 渠道信息，包含渠道标识、显示名称和对应网站
+ */
 export interface ChannelInfo {
+  /** 渠道标识 */
   channel: Channel;
+  /** 渠道显示名称 */
   name: string;
+  /** 对应的临时邮箱服务网站 */
   website: string;
 }
 
+/** 渠道信息映射表 */
 const channelInfoMap: Record<Channel, ChannelInfo> = {
   'tempmail': { channel: 'tempmail', name: 'TempMail', website: 'tempmail.ing' },
   'linshi-email': { channel: 'linshi-email', name: '临时邮箱', website: 'linshi-email.com' },
@@ -46,21 +59,60 @@ const channelInfoMap: Record<Channel, ChannelInfo> = {
 
 /**
  * 获取所有支持的渠道列表
+ *
+ * @returns 所有渠道的信息数组
+ *
+ * @example
+ * ```ts
+ * const channels = listChannels();
+ * channels.forEach(ch => console.log(`${ch.name} (${ch.website})`));
+ * ```
  */
 export function listChannels(): ChannelInfo[] {
   return allChannels.map(ch => channelInfoMap[ch]);
 }
 
 /**
- * 获取指定渠道信息
+ * 获取指定渠道的详细信息
+ *
+ * @param channel - 渠道标识
+ * @returns 渠道信息，不存在时返回 undefined
  */
 export function getChannelInfo(channel: Channel): ChannelInfo | undefined {
   return channelInfoMap[channel];
 }
 
+/**
+ * 创建临时邮箱
+ *
+ * 错误处理策略：
+ * - 网络错误、超时、服务端 5xx 错误 → 自动重试（默认 2 次，指数退避）
+ * - 4xx 客户端错误、参数错误 → 直接抛出异常
+ *
+ * @param options - 创建选项，可指定渠道、有效时长、域名等
+ * @returns 邮箱信息，包含地址、令牌等
+ * @throws 重试耗尽后仍失败时抛出异常
+ *
+ * @example
+ * ```ts
+ * const emailInfo = await generateEmail({ channel: 'temp-mail-io' });
+ * console.log(emailInfo.email); // 临时邮箱地址
+ * ```
+ */
 export async function generateEmail(options: GenerateEmailOptions = {}): Promise<EmailInfo> {
   const channel = options.channel || allChannels[Math.floor(Math.random() * allChannels.length)];
-  
+
+  logger.info(`创建临时邮箱, 渠道: ${channel}`);
+  const result = await withRetry(() => generateEmailOnce(channel, options), options.retry);
+  logger.info(`邮箱创建成功: ${result.email}`);
+  return result;
+}
+
+/**
+ * 单次创建邮箱（不含重试逻辑）
+ * 根据渠道类型分发到对应的 provider 实现
+ */
+async function generateEmailOnce(channel: Channel, options: GenerateEmailOptions): Promise<EmailInfo> {
   switch (channel) {
     case 'tempmail':
       return tempmail.generateEmail(options.duration || 30);
@@ -85,9 +137,35 @@ export async function generateEmail(options: GenerateEmailOptions = {}): Promise
   }
 }
 
+/**
+ * 获取邮件列表
+ *
+ * 错误处理策略：
+ * - 网络错误、超时、服务端 5xx 错误 → 自动重试（默认 2 次）
+ * - 重试耗尽后返回 { success: false, emails: [] }，不抛异常
+ * - 参数校验错误（缺少 channel / token）直接抛出
+ *
+ * 这种设计让调用方在轮询场景下不会因网络波动而中断整个流程，
+ * 只需检查 success 字段即可判断本次请求是否成功。
+ *
+ * @param options - 获取选项，包含渠道、邮箱地址、令牌
+ * @returns 邮件结果，包含 success 标记和邮件列表
+ *
+ * @example
+ * ```ts
+ * const result = await getEmails({
+ *   channel: emailInfo.channel,
+ *   email: emailInfo.email,
+ *   token: emailInfo.token,
+ * });
+ * if (result.success && result.emails.length > 0) {
+ *   console.log('收到邮件:', result.emails[0].subject);
+ * }
+ * ```
+ */
 export async function getEmails(options: GetEmailsOptions): Promise<GetEmailsResult> {
   const { channel, email, token } = options;
-  
+
   if (!channel) {
     throw new Error('Channel is required');
   }
@@ -95,68 +173,93 @@ export async function getEmails(options: GetEmailsOptions): Promise<GetEmailsRes
     throw new Error('Email is required');
   }
 
-  let emails: Email[] = [];
+  logger.debug(`获取邮件, 渠道: ${channel}, 邮箱: ${email}`);
+  try {
+    const emails = await withRetry(() => getEmailsOnce(channel, email, token), options.retry);
+    if (emails.length > 0) {
+      logger.info(`获取到 ${emails.length} 封邮件, 渠道: ${channel}`);
+    } else {
+      logger.debug(`暂无邮件, 渠道: ${channel}`);
+    }
+    return { channel, email, emails, success: true };
+  } catch (err: any) {
+    /*
+     * 重试耗尽后仍然失败 → 返回空结果而非抛异常
+     * 这样调用方在轮询场景下不会因为一次网络波动而中断整个流程
+     */
+    logger.error(`获取邮件失败, 渠道: ${channel}, 错误: ${err.message || err}`);
+    return { channel, email, emails: [], success: false };
+  }
+}
 
+/**
+ * 单次获取邮件（不含重试逻辑）
+ * 根据渠道类型分发到对应的 provider 实现，并校验必需的 token 参数
+ */
+async function getEmailsOnce(channel: Channel, email: string, token?: string): Promise<Email[]> {
   switch (channel) {
     case 'tempmail':
-      emails = await tempmail.getEmails(email);
-      break;
+      return tempmail.getEmails(email);
     case 'linshi-email':
-      emails = await linshiEmail.getEmails(email);
-      break;
+      return linshiEmail.getEmails(email);
     case 'tempmail-lol':
-      if (!token) {
-        throw new Error('Token is required for tempmail-lol channel');
-      }
-      emails = await tempmailLol.getEmails(token, email);
-      break;
+      if (!token) throw new Error('Token is required for tempmail-lol channel');
+      return tempmailLol.getEmails(token, email);
     case 'chatgpt-org-uk':
-      emails = await chatgptOrgUk.getEmails(email);
-      break;
+      return chatgptOrgUk.getEmails(email);
     case 'tempmail-la':
-      emails = await tempmailLa.getEmails(email);
-      break;
+      return tempmailLa.getEmails(email);
     case 'temp-mail-io':
-      emails = await tempMailIO.getEmails(email);
-      break;
+      return tempMailIO.getEmails(email);
     case 'awamail':
-      if (!token) {
-        throw new Error('Token is required for awamail channel');
-      }
-      emails = await awamail.getEmails(token, email);
-      break;
+      if (!token) throw new Error('Token is required for awamail channel');
+      return awamail.getEmails(token, email);
     case 'mail-tm':
-      if (!token) {
-        throw new Error('Token is required for mail-tm channel');
-      }
-      emails = await mailTm.getEmails(token, email);
-      break;
+      if (!token) throw new Error('Token is required for mail-tm channel');
+      return mailTm.getEmails(token, email);
     case 'dropmail':
-      if (!token) {
-        throw new Error('Token is required for dropmail channel');
-      }
-      emails = await dropmail.getEmails(token, email);
-      break;
+      if (!token) throw new Error('Token is required for dropmail channel');
+      return dropmail.getEmails(token, email);
     default:
       throw new Error(`Unknown channel: ${channel}`);
   }
-
-  return {
-    channel,
-    email,
-    emails,
-    success: true,
-  };
 }
 
+/**
+ * 临时邮箱客户端
+ * 封装了邮箱创建和邮件获取的完整流程，自动管理邮箱信息和认证令牌
+ *
+ * @example
+ * ```ts
+ * const client = new TempEmailClient();
+ * const emailInfo = await client.generate({ channel: 'mail-tm' });
+ * console.log('邮箱:', emailInfo.email);
+ *
+ * // 轮询获取邮件
+ * const result = await client.getEmails();
+ * if (result.success) {
+ *   console.log('邮件数:', result.emails.length);
+ * }
+ * ```
+ */
 export class TempEmailClient {
   private emailInfo: EmailInfo | null = null;
 
+  /**
+   * 创建临时邮箱并缓存邮箱信息
+   * 后续调用 getEmails() 时自动使用此邮箱的渠道、地址和令牌
+   */
   async generate(options: GenerateEmailOptions = {}): Promise<EmailInfo> {
     this.emailInfo = await generateEmail(options);
     return this.emailInfo;
   }
 
+  /**
+   * 获取当前邮箱的邮件列表
+   * 必须先调用 generate() 创建邮箱
+   *
+   * @throws 未调用 generate() 时抛出异常
+   */
   async getEmails(): Promise<GetEmailsResult> {
     if (!this.emailInfo) {
       throw new Error('No email generated. Call generate() first.');
@@ -169,6 +272,10 @@ export class TempEmailClient {
     });
   }
 
+  /**
+   * 获取当前缓存的邮箱信息
+   * 未调用 generate() 时返回 null
+   */
   getEmailInfo(): EmailInfo | null {
     return this.emailInfo;
   }

package/src/logger.ts

@@ -0,0 +1,106 @@
+/**
+ * SDK 日志模块
+ * 提供分级日志能力，支持自定义日志处理器
+ * 默认静默不输出，用户可通过 setLogLevel / setLogger 启用
+ */
+
+/**
+ * 日志级别枚举
+ * 数值越小级别越高，设置某级别后只输出该级别及以上的日志
+ */
+export enum LogLevel {
+  /** 关闭所有日志 */
+  SILENT = 0,
+  /** 错误日志：请求失败、重试耗尽等 */
+  ERROR = 1,
+  /** 警告日志：重试中、降级处理等 */
+  WARN = 2,
+  /** 信息日志：请求开始、完成等关键流程 */
+  INFO = 3,
+  /** 调试日志：请求详情、响应内容等 */
+  DEBUG = 4,
+}
+
+/**
+ * 日志处理器接口
+ * 用户可实现此接口来自定义日志输出方式（如写文件、发送到远程等）
+ */
+export interface LogHandler {
+  error(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  debug(message: string, ...args: any[]): void;
+}
+
+/**
+ * 默认日志处理器，直接输出到 console
+ */
+const defaultHandler: LogHandler = {
+  error: (msg, ...args) => console.error(msg, ...args),
+  warn: (msg, ...args) => console.warn(msg, ...args),
+  info: (msg, ...args) => console.info(msg, ...args),
+  debug: (msg, ...args) => console.debug(msg, ...args),
+};
+
+let currentLevel: LogLevel = LogLevel.SILENT;
+let currentHandler: LogHandler = defaultHandler;
+
+/**
+ * 设置日志级别
+ * 默认 SILENT（不输出任何日志）
+ *
+ * @example
+ * ```ts
+ * import { setLogLevel, LogLevel } from 'tempmail-sdk';
+ * setLogLevel(LogLevel.DEBUG); // 开启所有日志
+ * setLogLevel(LogLevel.INFO);  // 只输出 INFO 及以上
+ * ```
+ */
+export function setLogLevel(level: LogLevel): void {
+  currentLevel = level;
+}
+
+/**
+ * 获取当前日志级别
+ */
+export function getLogLevel(): LogLevel {
+  return currentLevel;
+}
+
+/**
+ * 设置自定义日志处理器
+ * 替换默认的 console 输出
+ *
+ * @example
+ * ```ts
+ * import { setLogger } from 'tempmail-sdk';
+ * setLogger({
+ *   error: (msg, ...args) => myLogger.error(msg, ...args),
+ *   warn:  (msg, ...args) => myLogger.warn(msg, ...args),
+ *   info:  (msg, ...args) => myLogger.info(msg, ...args),
+ *   debug: (msg, ...args) => myLogger.debug(msg, ...args),
+ * });
+ * ```
+ */
+export function setLogger(handler: LogHandler): void {
+  currentHandler = handler;
+}
+
+/**
+ * SDK 内部日志工具
+ * 根据当前日志级别过滤输出
+ */
+export const logger = {
+  error(msg: string, ...args: any[]): void {
+    if (currentLevel >= LogLevel.ERROR) currentHandler.error(msg, ...args);
+  },
+  warn(msg: string, ...args: any[]): void {
+    if (currentLevel >= LogLevel.WARN) currentHandler.warn(msg, ...args);
+  },
+  info(msg: string, ...args: any[]): void {
+    if (currentLevel >= LogLevel.INFO) currentHandler.info(msg, ...args);
+  },
+  debug(msg: string, ...args: any[]): void {
+    if (currentLevel >= LogLevel.DEBUG) currentHandler.debug(msg, ...args);
+  },
+};

package/src/normalize.ts

@@ -2,6 +2,13 @@ import { Email, EmailAttachment } from './types';
 
 /**
  * 将各提供商返回的原始邮件数据标准化为统一的 Email 格式
+ *
+ * 不同渠道的 API 返回字段名各不相同，此函数通过多字段候选策略
+ * 将它们统一映射为标准的 Email 结构，保证 SDK 输出一致性。
+ *
+ * @param raw - 原始邮件数据（来自不同提供商的 API 响应）
+ * @param recipientEmail - 收件人邮箱地址，当原始数据中无收件人字段时用作回退值
+ * @returns 标准化的 Email 对象
  */
 export function normalizeEmail(raw: any, recipientEmail: string = ''): Email {
   return {
@@ -17,31 +24,60 @@ export function normalizeEmail(raw: any, recipientEmail: string = ''): Email {
   };
 }
 
+/**
+ * 提取邮件 ID
+ * 候选字段: id, eid, _id, mailboxId, messageId, mail_id
+ */
 function normalizeId(raw: any): string {
   const id = raw.id ?? raw.eid ?? raw._id ?? raw.mailboxId ?? raw.messageId ?? raw.mail_id ?? '';
   return String(id);
 }
 
+/**
+ * 提取发件人地址
+ * 候选字段: from_address, address_from, from, messageFrom, sender
+ */
 function normalizeFrom(raw: any): string {
   return raw.from_address || raw.address_from || raw.from || raw.messageFrom || raw.sender || '';
 }
 
+/**
+ * 提取收件人地址，无匹配字段时回退为 recipientEmail
+ * 候选字段: to, to_address, name_to, email_address, address
+ */
 function normalizeTo(raw: any, recipientEmail: string): string {
   return raw.to || raw.to_address || raw.name_to || raw.email_address || raw.address || recipientEmail || '';
 }
 
+/**
+ * 提取邮件主题
+ * 候选字段: subject, e_subject
+ */
 function normalizeSubject(raw: any): string {
   return raw.subject || raw.e_subject || '';
 }
 
+/**
+ * 提取纯文本内容
+ * 候选字段: text, body, content, body_text, text_content
+ */
 function normalizeText(raw: any): string {
   return raw.text || raw.body || raw.content || raw.body_text || raw.text_content || '';
 }
 
+/**
+ * 提取 HTML 内容
+ * 候选字段: html, html_content, body_html
+ */
 function normalizeHtml(raw: any): string {
   return raw.html || raw.html_content || raw.body_html || '';
 }
 
+/**
+ * 提取并统一日期格式为 ISO 8601
+ * 候选字段: received_at, created_at, createdAt, date, timestamp, e_date
+ * 其中 timestamp 为 Unix 秒级时间戳，需乘以 1000 转为毫秒
+ */
 function normalizeDate(raw: any): string {
   try {
     if (raw.received_at) return new Date(raw.received_at).toISOString();
@@ -54,11 +90,16 @@ function normalizeDate(raw: any): string {
     if (raw.timestamp) return new Date(raw.timestamp * 1000).toISOString();
     if (raw.e_date) return new Date(raw.e_date).toISOString();
   } catch {
-    // 日期解析失败，返回空字符串
+    /* 日期解析失败，返回空字符串 */
   }
   return '';
 }
 
+/**
+ * 提取已读状态
+ * 候选字段: seen, read, isRead, is_read
+ * 支持 boolean / number(0|1) / string('0'|'1') 多种类型
+ */
 function normalizeIsRead(raw: any): boolean {
   if (typeof raw.seen === 'boolean') return raw.seen;
   if (typeof raw.read === 'boolean') return raw.read;
@@ -69,6 +110,10 @@ function normalizeIsRead(raw: any): boolean {
   return false;
 }
 
+/**
+ * 提取并标准化附件列表
+ * 每个附件的字段也采用多候选策略映射
+ */
 function normalizeAttachments(attachments: any): EmailAttachment[] {
   if (!attachments || !Array.isArray(attachments)) return [];
   return attachments.map((a: any) => ({

package/src/providers/mail-tm.ts

@@ -36,7 +36,11 @@ async function getDomains(): Promise<string[]> {
   }
 
   const data = await response.json();
-  const members = data['hydra:member'] || [];
+  /* 兼容两种响应格式：
+   * - Accept: application/ld+json → Hydra 格式 { "hydra:member": [...] }
+   * - Accept: application/json   → 纯数组 [...]
+   */
+  const members = Array.isArray(data) ? data : (data['hydra:member'] || []);
   return members
     .filter((d: any) => d.isActive)
     .map((d: any) => d.domain);
@@ -153,7 +157,8 @@ export async function getEmails(token: string, email: string): Promise<Email[]>
   }
 
   const listData = await listResponse.json();
-  const messages = listData['hydra:member'] || [];
+  /* 兼容 Hydra 格式和纯数组格式 */
+  const messages = Array.isArray(listData) ? listData : (listData['hydra:member'] || []);
 
   if (messages.length === 0) {
     return [];