tempmail-sdk 1.0.2 → 1.1.0

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/kuKrmuKDpgZPlr7nlupTkuIDkuKrnrKzkuInmlrnkuLTml7bpgq7nrrHmnI3liqHllYZcbiAqL1xuZXhwb3J0IHR5cGUgQ2hhbm5lbCA9ICd0ZW1wbWFpbCcgfCAnbGluc2hpLWVtYWlsJyB8ICd0ZW1wbWFpbC1sb2wnIHwgJ2NoYXRncHQtb3JnLXVrJyB8ICd0ZW1wbWFpbC1sYScgfCAndGVtcC1tYWlsLWlvJyB8ICdhd2FtYWlsJyB8ICdtYWlsLXRtJyB8ICdkcm9wbWFpbCcgfCAnZ3VlcnJpbGxhbWFpbCcgfCAnbWFpbGRyb3AnO1xuXG4vKipcbiAqIOWIm+W7uuS4tOaXtumCrueuseWQjui/lOWbnueahOmCrueuseS/oeaBr1xuICog5YyF5ZCr6YKu566x5Zyw5Z2A44CB6K6k6K+B5Luk54mM5ZKM55Sf5ZG95ZGo5pyf5L+h5oGvXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgRW1haWxJbmZvIHtcbiAgLyoqIOWIm+W7uuivpemCrueuseaJgOS9v+eUqOeahOa4oOmBkyAqL1xuICBjaGFubmVsOiBDaGFubmVsO1xuICAvKiog5Li05pe26YKu566x5Zyw5Z2AICovXG4gIGVtYWlsOiBzdHJpbmc7XG4gIC8qKiDorqTor4Hku6TniYzvvIzpg6jliIbmuKDpgZPlnKjojrflj5bpgq7ku7bml7bpnIDopoHmraTku6TniYwgKi9cbiAgdG9rZW4/OiBzdHJpbmc7XG4gIC8qKiDpgq7nrrHov4fmnJ/ml7bpl7TvvIhJU08gODYwMSDlrZfnrKbkuLLmiJYgVW5peCDml7bpl7TmiLPvvIkgKi9cbiAgZXhwaXJlc0F0Pzogc3RyaW5nIHwgbnVtYmVyO1xuICAvKiog6YKu566x5Yib5bu65pe26Ze077yISVNPIDg2MDEg5a2X56ym5Liy77yJICovXG4gIGNyZWF0ZWRBdD86IHN0cmluZztcbn1cblxuLyoqXG4gKiDmoIflh4bljJbpgq7ku7bpmYTku7ZcbiAqIOS4jeWQjOa4oOmBk+eahOmZhOS7tuWtl+auteWQjeS4jeWQjO+8jFNESyDnu5/kuIDlvZLkuIDljJbkuLrmraTnu5PmnoRcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBFbWFpbEF0dGFjaG1lbnQge1xuICAvKiog6ZmE5Lu25paH5Lu25ZCNICovXG4gIGZpbGVuYW1lOiBzdHJpbmc7XG4gIC8qKiDpmYTku7blpKflsI/vvIjlrZfoioLvvIkgKi9cbiAgc2l6ZT86IG51bWJlcjtcbiAgLyoqIE1JTUUg57G75Z6L77yM5aaCIGFwcGxpY2F0aW9uL3BkZiAqL1xuICBjb250ZW50VHlwZT86IHN0cmluZztcbiAgLyoqIOmZhOS7tuS4i+i9veWcsOWdgCAqL1xuICB1cmw/OiBzdHJpbmc7XG59XG5cbi8qKlxuICog5qCH5YeG5YyW6YKu5Lu25qC85byPIC0g5omA5pyJ5o+Q5L6b5ZWG6L+U5Zue57uf5LiA57uT5p6EXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgRW1haWwge1xuICAvKiog6YKu5Lu25ZSv5LiA5qCH6K+GICovXG4gIGlkOiBzdHJpbmc7XG4gIC8qKiDlj5Hku7bkurrpgq7nrrHlnLDlnYAgKi9cbiAgZnJvbTogc3RyaW5nO1xuICAvKiog5pS25Lu25Lq66YKu566x5Zyw5Z2AICovXG4gIHRvOiBzdHJpbmc7XG4gIC8qKiDpgq7ku7bkuLvpopggKi9cbiAgc3ViamVjdDogc3RyaW5nO1xuICAvKiog57qv5paH5pys5YaF5a65ICovXG4gIHRleHQ6IHN0cmluZztcbiAgLyoqIEhUTUwg5YaF5a65ICovXG4gIGh0bWw6IHN0cmluZztcbiAgLyoqIElTTyA4NjAxIOagvOW8j+eahOaXpeacn+Wtl+espuS4siAqL1xuICBkYXRlOiBzdHJpbmc7XG4gIC8qKiDmmK/lkKblt7Lor7sgKi9cbiAgaXNSZWFkOiBib29sZWFuO1xuICAvKiog6ZmE5Lu25YiX6KGoICovXG4gIGF0dGFjaG1lbnRzOiBFbWFpbEF0dGFjaG1lbnRbXTtcbn1cblxuLyoqXG4gKiDojrflj5bpgq7ku7bliJfooajnmoTov5Tlm57nu5PmnpxcbiAqIHN1Y2Nlc3Mg5Li6IGZhbHNlIOaXtuihqOekuuivt+axguWksei0pe+8iOmHjeivleiAl+Wwve+8ie+8jGVtYWlscyDkuLrnqbrmlbDnu4RcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBHZXRFbWFpbHNSZXN1bHQge1xuICAvKiog5omA5L2/55So55qE5rig6YGTICovXG4gIGNoYW5uZWw6IENoYW5uZWw7XG4gIC8qKiDmn6Xor6LnmoTpgq7nrrHlnLDlnYAgKi9cbiAgZW1haWw6IHN0cmluZztcbiAgLyoqIOmCruS7tuWIl+ihqO+8jOWksei0peaXtuS4uuepuuaVsOe7hCAqL1xuICBlbWFpbHM6IEVtYWlsW107XG4gIC8qKiDor7fmsYLmmK/lkKbmiJDlip/vvIxmYWxzZSDooajnpLrph43or5XogJflsL3lkI7ku43lpLHotKUgKi9cbiAgc3VjY2VzczogYm9vbGVhbjtcbn1cblxuLyoqXG4gKiDph43or5XphY3nva5cbiAqIFNESyDlhoXpg6jlr7nnvZHnu5zplJnor6/jgIHotoXml7bjgIE1eHgg5pyN5Yqh56uv6ZSZ6K+v6Ieq5Yqo6YeN6K+VXG4gKiA0eHgg5a6i5oi356uv6ZSZ6K+v77yI5aaC5Y+C5pWw6ZSZ6K+v77yJ5LiN5Lya6YeN6K+VXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHRzXG4gKiAvLyDoh6rlrprkuYnph43or5XnrZbnlaXvvJrmnIDlpJrph43or5UgMyDmrKHvvIzpppbmrKHlu7bov58gMiDnp5JcbiAqIGNvbnN0IGVtYWlsID0gYXdhaXQgZ2VuZXJhdGVFbWFpbCh7XG4gKiAgIGNoYW5uZWw6ICdtYWlsLXRtJyxcbiAqICAgcmV0cnk6IHsgbWF4UmV0cmllczogMywgaW5pdGlhbERlbGF5OiAyMDAwIH0sXG4gKiB9KTtcbiAqIGBgYFxuICovXG5leHBvcnQgaW50ZXJmYWNlIFJldHJ5Q29uZmlnIHtcbiAgLyoqIOacgOWkp+mHjeivleasoeaVsO+8iOS4jeWQq+mmluasoeivt+axgu+8ie+8jOm7mOiupCAyICovXG4gIG1heFJldHJpZXM/OiBudW1iZXI7XG4gIC8qKiDliJ3lp4vph43or5Xlu7bov5/vvIjmr6vnp5LvvInvvIzph4fnlKjmjIfmlbDpgIDpgb/nrZbnlaXvvIzpu5jorqQgMTAwMCAqL1xuICBpbml0aWFsRGVsYXk/OiBudW1iZXI7XG4gIC8qKiDmnIDlpKfph43or5Xlu7bov5/kuIrpmZDvvIjmr6vnp5LvvInvvIzpu5jorqQgNTAwMCAqL1xuICBtYXhEZWxheT86IG51bWJlcjtcbiAgLyoqIOWNleasoeivt+axgui2heaXtuaXtumXtO+8iOavq+enku+8ie+8jOm7mOiupCAxNTAwMCAqL1xuICB0aW1lb3V0PzogbnVtYmVyO1xufVxuXG4vKipcbiAqIOWIm+W7uuS4tOaXtumCrueuseeahOmAiemhuVxuICpcbiAqIEBleGFtcGxlXG4gKiBgYGB0c1xuICogLy8g5L2/55So5oyH5a6a5rig6YGT5Yib5bu66YKu566xXG4gKiBjb25zdCBlbWFpbCA9IGF3YWl0IGdlbmVyYXRlRW1haWwoeyBjaGFubmVsOiAnbWFpbC10bScgfSk7XG4gKlxuICogLy8g6ZqP5py66YCJ5oup5rig6YGTXG4gKiBjb25zdCBlbWFpbCA9IGF3YWl0IGdlbmVyYXRlRW1haWwoKTtcbiAqIGBgYFxuICovXG5leHBvcnQgaW50ZXJmYWNlIEdlbmVyYXRlRW1haWxPcHRpb25zIHtcbiAgLyoqIOaMh+Wumua4oOmBk++8jOS4jeS8oOWImemaj+acuumAieaLqSAqL1xuICBjaGFubmVsPzogQ2hhbm5lbDtcbiAgLyoqIOmCrueuseacieaViOaXtumVvyAqL1xuICBkdXJhdGlvbj86IG51bWJlcjtcbiAgLyoqIOaMh+WumumCrueuseWfn+WQjSAqL1xuICBkb21haW4/OiBzdHJpbmcgfCBudWxsO1xuICAvKiog6YeN6K+V6YWN572u77yM5LiN5Lyg5YiZ5L2/55So6buY6K6k5YC877yI5pyA5aSa6YeN6K+VIDIg5qyh77yJICovXG4gIHJldHJ5PzogUmV0cnlDb25maWc7XG59XG5cbi8qKlxuICog6I635Y+W6YKu5Lu25YiX6KGo55qE6YCJ6aG5XG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHRzXG4gKiBjb25zdCByZXN1bHQgPSBhd2FpdCBnZXRFbWFpbHMoe1xuICogICBjaGFubmVsOiBlbWFpbEluZm8uY2hhbm5lbCxcbiAqICAgZW1haWw6IGVtYWlsSW5mby5lbWFpbCxcbiAqICAgdG9rZW46IGVtYWlsSW5mby50b2tlbixcbiAqIH0pO1xuICogaWYgKHJlc3VsdC5zdWNjZXNzICYmIHJlc3VsdC5lbWFpbHMubGVuZ3RoID4gMCkge1xuICogICBjb25zb2xlLmxvZygn5pS25Yiw6YKu5Lu2OicsIHJlc3VsdC5lbWFpbHMpO1xuICogfVxuICogYGBgXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgR2V0RW1haWxzT3B0aW9ucyB7XG4gIC8qKiDmuKDpgZPmoIfor4bvvIzlv4XloasgKi9cbiAgY2hhbm5lbDogQ2hhbm5lbDtcbiAgLyoqIOmCrueuseWcsOWdgO+8jOW/heWhqyAqL1xuICBlbWFpbDogc3RyaW5nO1xuICAvKiog6K6k6K+B5Luk54mMICovXG4gIHRva2VuPzogc3RyaW5nO1xuICAvKiog6YeN6K+V6YWN572u77yM5LiN5Lyg5YiZ5L2/55So6buY6K6k5YC877yI5pyA5aSa6YeN6K+VIDIg5qyh77yJICovXG4gIHJldHJ5PzogUmV0cnlDb25maWc7XG59XG4iXX0=

package/package.json

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

package/src/index.ts

@@ -7,11 +7,18 @@ import * as tempMailIO from './providers/temp-mail-io';
 import * as awamail from './providers/awamail';
 import * as mailTm from './providers/mail-tm';
 import * as dropmail from './providers/dropmail';
+import * as guerrillamail from './providers/guerrillamail';
+import * as maildropProvider from './providers/maildrop';
 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,
@@ -22,16 +29,26 @@ const providers = {
   'awamail': awamail,
   'mail-tm': mailTm,
   'dropmail': dropmail,
+  'guerrillamail': guerrillamail,
+  'maildrop': maildropProvider,
 };
 
-const allChannels: Channel[] = ['tempmail', 'linshi-email', 'tempmail-lol', 'chatgpt-org-uk', 'tempmail-la', 'temp-mail-io', 'awamail', 'mail-tm', 'dropmail'];
+/** 所有支持的渠道列表，用于随机选择和遍历 */
+const allChannels: Channel[] = ['tempmail', 'linshi-email', 'tempmail-lol', 'chatgpt-org-uk', 'tempmail-la', 'temp-mail-io', 'awamail', 'mail-tm', 'dropmail', 'guerrillamail', 'maildrop'];
 
+/**
+ * 渠道信息，包含渠道标识、显示名称和对应网站
+ */
 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' },
@@ -42,25 +59,66 @@ const channelInfoMap: Record<Channel, ChannelInfo> = {
   'awamail': { channel: 'awamail', name: 'AwaMail', website: 'awamail.com' },
   'mail-tm': { channel: 'mail-tm', name: 'Mail.tm', website: 'mail.tm' },
   'dropmail': { channel: 'dropmail', name: 'DropMail', website: 'dropmail.me' },
+  'guerrillamail': { channel: 'guerrillamail', name: 'Guerrilla Mail', website: 'guerrillamail.com' },
+  'maildrop': { channel: 'maildrop', name: 'Maildrop', website: 'maildrop.cc' },
 };
 
 /**
  * 获取所有支持的渠道列表
+ *
+ * @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);
@@ -80,14 +138,44 @@ export async function generateEmail(options: GenerateEmailOptions = {}): Promise
       return mailTm.generateEmail();
     case 'dropmail':
       return dropmail.generateEmail();
+    case 'guerrillamail':
+      return guerrillamail.generateEmail();
+    case 'maildrop':
+      return maildropProvider.generateEmail();
     default:
       throw new Error(`Unknown channel: ${channel}`);
   }
 }
 
+/**
+ * 获取邮件列表
+ *
+ * 错误处理策略：
+ * - 网络错误、超时、服务端 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 +183,99 @@ 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);
+    case 'guerrillamail':
+      if (!token) throw new Error('Token is required for guerrillamail channel');
+      return guerrillamail.getEmails(token, email);
+    case 'maildrop':
+      if (!token) throw new Error('Token is required for maildrop channel');
+      return maildropProvider.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 +288,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/guerrillamail.ts

@@ -0,0 +1,78 @@
+/**
+ * Guerrilla Mail 渠道实现
+ * API 文档: https://www.guerrillamail.com/GuerrillaMailAPI.html
+ * 
+ * 特点:
+ * - 无需认证，公开 JSON API
+ * - 通过 sid_token 维持会话
+ * - 邮箱有效期 60 分钟
+ */
+
+import { EmailInfo, Email, Channel } from '../types';
+import { normalizeEmail } from '../normalize';
+
+const CHANNEL: Channel = 'guerrillamail';
+const BASE_URL = 'https://api.guerrillamail.com/ajax.php';
+
+/**
+ * 创建临时邮箱
+ * API: GET ajax.php?f=get_email_address
+ * 返回 email_addr + sid_token（用于后续获取邮件）
+ */
+export async function generateEmail(): Promise<EmailInfo> {
+  const response = await fetch(`${BASE_URL}?f=get_email_address&lang=en`, {
+    method: 'GET',
+    headers: {
+      'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to generate email: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  if (!data.email_addr || !data.sid_token) {
+    throw new Error('Failed to generate email: missing email_addr or sid_token');
+  }
+
+  return {
+    channel: CHANNEL,
+    email: data.email_addr,
+    token: data.sid_token,
+    expiresAt: data.email_timestamp ? (data.email_timestamp + 3600) * 1000 : undefined,
+  };
+}
+
+/**
+ * 获取邮件列表
+ * API: GET ajax.php?f=check_email&seq=0&sid_token=xxx
+ * 返回 list 数组，每个元素包含 mail_id, mail_from, mail_subject, mail_body 等
+ */
+export async function getEmails(token: string, email: string): Promise<Email[]> {
+  const response = await fetch(`${BASE_URL}?f=check_email&seq=0&sid_token=${encodeURIComponent(token)}`, {
+    method: 'GET',
+    headers: {
+      'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to get emails: ${response.status}`);
+  }
+
+  const data = await response.json();
+  const list = Array.isArray(data.list) ? data.list : [];
+
+  return list.map((item: any) => normalizeEmail({
+    id: item.mail_id,
+    from: item.mail_from,
+    to: email,
+    subject: item.mail_subject,
+    text: item.mail_body || item.mail_excerpt || '',
+    html: item.mail_body || '',
+    date: item.mail_date || '',
+    isRead: item.mail_read === 1,
+  }, email));
+}

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 [];