tempmail-sdk 1.0.2 → 1.1.0

package/src/providers/maildrop.ts

@@ -0,0 +1,210 @@
+/**
+ * Maildrop 渠道实现
+ * API: GraphQL endpoint https://api.maildrop.cc/graphql
+ * 
+ * 特点:
+ * - 无需认证，公开 GraphQL API
+ * - 自带反垃圾过滤
+ * - 邮箱名即用户名（任意字符串@maildrop.cc）
+ * - 无过期时间限制
+ */
+
+import { EmailInfo, Email, Channel } from '../types';
+
+const CHANNEL: Channel = 'maildrop';
+const GRAPHQL_URL = 'https://api.maildrop.cc/graphql';
+const DOMAIN = 'maildrop.cc';
+
+/**
+ * 解码 RFC 2047 编码的邮件头（如发件人、主题）
+ * 支持 Base64 (B) 和 Quoted-Printable (Q) 编码
+ */
+function decodeRfc2047(str: string): string {
+  if (!str) return '';
+  return str.replace(/=\?([^?]+)\?(B|Q)\?([^?]*)\?=/gi, (_, charset, encoding, encoded) => {
+    try {
+      if (encoding.toUpperCase() === 'B') {
+        return Buffer.from(encoded, 'base64').toString('utf-8');
+      }
+      /* Quoted-Printable: _=空格，=XX=十六进制字节 */
+      const decoded = encoded
+        .replace(/_/g, ' ')
+        .replace(/=([0-9A-Fa-f]{2})/g, (_m: string, hex: string) => String.fromCharCode(parseInt(hex, 16)));
+      return decoded;
+    } catch {
+      return encoded;
+    }
+  });
+}
+
+/**
+ * 从原始 MIME 邮件源码中提取纯文本正文
+ * maildrop 的 data 字段返回完整 MIME 源码，需要解析出 text/plain 部分
+ */
+function extractTextFromMime(raw: string): string {
+  if (!raw) return '';
+
+  /* 分离邮件头和正文（双换行分隔） */
+  const headerBodySplit = raw.indexOf('\r\n\r\n');
+  if (headerBodySplit === -1) return raw;
+
+  const headers = raw.substring(0, headerBodySplit);
+  const body = raw.substring(headerBodySplit + 4);
+
+  /* 检查是否为 multipart 邮件 */
+  const boundaryMatch = headers.match(/boundary="?([^";\r\n]+)"?/i);
+  if (boundaryMatch) {
+    const boundary = boundaryMatch[1];
+    const parts = body.split('--' + boundary);
+
+    for (const part of parts) {
+      /* 查找 text/plain 部分 */
+      if (part.match(/Content-Type:\s*text\/plain/i)) {
+        const partHeaderEnd = part.indexOf('\r\n\r\n');
+        if (partHeaderEnd === -1) continue;
+
+        const partHeaders = part.substring(0, partHeaderEnd);
+        let content = part.substring(partHeaderEnd + 4).replace(/\r\n$/, '').replace(/--$/, '').trim();
+
+        /* 处理 Content-Transfer-Encoding */
+        if (partHeaders.match(/Content-Transfer-Encoding:\s*base64/i)) {
+          try {
+            content = Buffer.from(content.replace(/\s/g, ''), 'base64').toString('utf-8');
+          } catch { /* 解码失败则保留原文 */ }
+        } else if (partHeaders.match(/Content-Transfer-Encoding:\s*quoted-printable/i)) {
+          content = content
+            .replace(/=\r?\n/g, '')
+            .replace(/=([0-9A-Fa-f]{2})/g, (_, hex: string) => String.fromCharCode(parseInt(hex, 16)));
+        }
+
+        return content.trim();
+      }
+    }
+  }
+
+  /* 非 multipart：检查整体编码 */
+  if (headers.match(/Content-Transfer-Encoding:\s*base64/i)) {
+    try {
+      return Buffer.from(body.replace(/\s/g, ''), 'base64').toString('utf-8').trim();
+    } catch { /* 解码失败 */ }
+  }
+
+  return body.trim();
+}
+
+/**
+ * 生成随机用户名
+ */
+function randomUsername(length: number = 10): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+/**
+ * 发送 GraphQL 请求
+ * 使用 operationName + variables 的标准 GraphQL 格式
+ */
+async function graphqlRequest(
+  operationName: string,
+  query: string,
+  variables: Record<string, string> = {},
+): Promise<any> {
+  const response = await fetch(GRAPHQL_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Origin': 'https://maildrop.cc',
+      'Referer': 'https://maildrop.cc/',
+      'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+    },
+    body: JSON.stringify({ operationName, variables, query }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Maildrop GraphQL request failed: ${response.status}`);
+  }
+
+  const data = await response.json();
+  if (data.errors && data.errors.length > 0) {
+    throw new Error(`Maildrop GraphQL error: ${data.errors[0].message}`);
+  }
+
+  return data.data;
+}
+
+/**
+ * 创建临时邮箱
+ * Maildrop 无需注册，任意用户名即可接收邮件
+ */
+export async function generateEmail(): Promise<EmailInfo> {
+  const username = randomUsername();
+  const email = `${username}@${DOMAIN}`;
+
+  /* 验证邮箱可用：查询一次 inbox 确认 API 正常 */
+  await graphqlRequest(
+    'GetInbox',
+    'query GetInbox($mailbox: String!) { inbox(mailbox: $mailbox) { id } }',
+    { mailbox: username },
+  );
+
+  return {
+    channel: CHANNEL,
+    email,
+    token: username,
+  };
+}
+
+/**
+ * 获取邮件列表
+ * 先查 inbox 获取邮件 ID 列表，再逐封获取完整内容
+ */
+export async function getEmails(token: string, email: string): Promise<Email[]> {
+  const mailbox = token || email.split('@')[0];
+
+  /* 查询收件箱列表 */
+  const inboxData = await graphqlRequest(
+    'GetInbox',
+    'query GetInbox($mailbox: String!) { inbox(mailbox: $mailbox) { id headerfrom subject date } }',
+    { mailbox },
+  );
+
+  const inbox = inboxData?.inbox;
+  if (!Array.isArray(inbox) || inbox.length === 0) {
+    return [];
+  }
+
+  /* 逐封获取完整邮件内容 */
+  const emails: Email[] = [];
+  for (const item of inbox) {
+    try {
+      const msgData = await graphqlRequest(
+        'GetMessage',
+        'query GetMessage($mailbox: String!, $id: String!) { message(mailbox: $mailbox, id: $id) { id headerfrom subject date data html } }',
+        { mailbox, id: item.id },
+      );
+
+      const msg = msgData?.message;
+      if (msg) {
+        emails.push({
+          id: msg.id || item.id,
+          from: decodeRfc2047(msg.headerfrom || item.headerfrom || ''),
+          to: email,
+          subject: decodeRfc2047(msg.subject || item.subject || ''),
+          text: extractTextFromMime(msg.data || ''),
+          html: msg.html || '',
+          date: msg.date || item.date || '',
+          isRead: false,
+          attachments: [],
+        });
+      }
+    } catch {
+      /* 单封邮件获取失败不影响整体 */
+    }
+  }
+
+  return emails;
+}

package/src/providers/temp-mail-io.ts

@@ -3,25 +3,56 @@ import { normalizeEmail } from '../normalize';
 
 const CHANNEL: Channel = 'temp-mail-io';
 const BASE_URL = 'https://api.internal.temp-mail.io/api/v3';
+const PAGE_URL = 'https://temp-mail.io/en';
 
-const DEFAULT_HEADERS: Record<string, string> = {
-  'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36 Edg/144.0.0.0',
-  'Content-Type': 'application/json',
-  'accept-language': 'zh-CN,zh;q=0.9,en;q=0.8,en-GB;q=0.7,en-US;q=0.6',
-  'application-name': 'web',
-  'application-version': '4.0.0',
-  'cache-control': 'no-cache',
-  'dnt': '1',
-  'origin': 'https://temp-mail.io',
-  'pragma': 'no-cache',
-  'referer': 'https://temp-mail.io/',
-  'sec-ch-ua': '"Not(A:Brand";v="8", "Chromium";v="144", "Microsoft Edge";v="144"',
-  'sec-ch-ua-mobile': '?0',
-  'sec-ch-ua-platform': '"Windows"',
-  'sec-fetch-dest': 'empty',
-  'sec-fetch-mode': 'cors',
-  'sec-fetch-site': 'same-site',
-};
+/**
+ * 缓存从页面动态获取的 mobileTestingHeader 值（用于 X-CORS-Header）
+ */
+let cachedCorsHeader: string | null = null;
+
+/**
+ * 从 temp-mail.io 页面的 __NUXT__ 运行时配置中提取 mobileTestingHeader
+ * 该值用于 API 请求的 X-CORS-Header 头，缺少此头会导致 400 错误
+ */
+async function fetchCorsHeader(): Promise<string> {
+  if (cachedCorsHeader) return cachedCorsHeader;
+
+  try {
+    const response = await fetch(PAGE_URL, {
+      headers: {
+        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36',
+      },
+    });
+    const html = await response.text();
+    const match = html.match(/mobileTestingHeader\s*:\s*"([^"]+)"/);
+    if (match) {
+      cachedCorsHeader = match[1];
+      return cachedCorsHeader;
+    }
+  } catch {
+    /* 提取失败时使用默认值 */
+  }
+
+  cachedCorsHeader = '1';
+  return cachedCorsHeader;
+}
+
+/**
+ * 构建 API 请求头
+ * 关键头: Content-Type, Application-Name, Application-Version, X-CORS-Header
+ */
+async function getApiHeaders(): Promise<Record<string, string>> {
+  const corsHeader = await fetchCorsHeader();
+  return {
+    'Content-Type': 'application/json',
+    'Application-Name': 'web',
+    'Application-Version': '4.0.0',
+    'X-CORS-Header': corsHeader,
+    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36 Edg/144.0.0.0',
+    'origin': 'https://temp-mail.io',
+    'referer': 'https://temp-mail.io/',
+  };
+}
 
 /**
  * 创建临时邮箱
@@ -29,10 +60,11 @@ const DEFAULT_HEADERS: Record<string, string> = {
  * 返回: { email, token }
  */
 export async function generateEmail(): Promise<EmailInfo> {
+  const headers = await getApiHeaders();
   const response = await fetch(`${BASE_URL}/email/new`, {
     method: 'POST',
-    headers: DEFAULT_HEADERS,
-    body: JSON.stringify({ min_name_length: 100, max_name_length: 100 }),
+    headers,
+    body: JSON.stringify({ min_name_length: 10, max_name_length: 10 }),
   });
 
   if (!response.ok) {
@@ -58,10 +90,10 @@ export async function generateEmail(): Promise<EmailInfo> {
  * 返回: [ { id, from, to, cc, subject, body_text, body_html, created_at, attachments } ]
  */
 export async function getEmails(email: string): Promise<Email[]> {
-  const encodedEmail = encodeURIComponent(email);
-  const response = await fetch(`${BASE_URL}/email/${encodedEmail}/messages`, {
+  const headers = await getApiHeaders();
+  const response = await fetch(`${BASE_URL}/email/${email}/messages`, {
     method: 'GET',
-    headers: DEFAULT_HEADERS,
+    headers,
   });
 
   if (!response.ok) {

package/src/retry.ts

@@ -0,0 +1,146 @@
+/**
+ * 通用重试工具
+ * 提供请求重试、超时控制、指数退避等错误恢复机制
+ */
+
+import { logger } from './logger';
+
+/**
+ * 重试配置选项
+ */
+export interface RetryOptions {
+  /** 最大重试次数（不含首次请求），默认 2 */
+  maxRetries?: number;
+  /** 初始重试延迟（毫秒），默认 1000 */
+  initialDelay?: number;
+  /** 最大重试延迟（毫秒），默认 5000 */
+  maxDelay?: number;
+  /** 请求超时时间（毫秒），默认 15000 */
+  timeout?: number;
+  /** 是否对该错误进行重试的判断函数 */
+  shouldRetry?: (error: any) => boolean;
+}
+
+const DEFAULT_RETRY_OPTIONS: Required<RetryOptions> = {
+  maxRetries: 2,
+  initialDelay: 1000,
+  maxDelay: 5000,
+  timeout: 15000,
+  shouldRetry: defaultShouldRetry,
+};
+
+/**
+ * 默认重试判断
+ * 网络错误、超时、HTTP 4xx/5xx 错误均可重试
+ * 仅参数校验类错误（由 SDK 内部抛出）不重试
+ */
+function defaultShouldRetry(error: any): boolean {
+  if (!error) return false;
+
+  const message = String(error.message || error || '').toLowerCase();
+
+  /* 网络级别错误 → 重试 */
+  if (message.includes('fetch failed') ||
+      message.includes('network') ||
+      message.includes('econnrefused') ||
+      message.includes('econnreset') ||
+      message.includes('etimedout') ||
+      message.includes('timeout') ||
+      message.includes('socket hang up') ||
+      message.includes('dns') ||
+      message.includes('abort')) {
+    return true;
+  }
+
+  /* HTTP 4xx/5xx 错误 → 重试 */
+  const statusMatch = message.match(/:\s*(\d{3})/);
+  if (statusMatch) {
+    const status = parseInt(statusMatch[1], 10);
+    return status >= 400;
+  }
+
+  return false;
+}
+
+/**
+ * 休眠指定毫秒
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * 带重试的异步操作执行器
+ * - 自动重试可恢复的错误（网络错误、超时、5xx）
+ * - 指数退避避免过度请求
+ * - 不可恢复的错误（4xx 参数错误等）直接抛出不重试
+ *
+ * @param fn 要执行的异步操作
+ * @param options 重试配置
+ */
+export async function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T> {
+  const opts = { ...DEFAULT_RETRY_OPTIONS, ...options };
+  let lastError: any;
+
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    try {
+      const result = await fn();
+      if (attempt > 0) {
+        logger.info(`第 ${attempt + 1} 次尝试成功`);
+      }
+      return result;
+    } catch (error: any) {
+      lastError = error;
+      const errorMsg = error.message || String(error);
+
+      /* 最后一次尝试失败或不可重试的错误 → 直接抛出 */
+      if (attempt >= opts.maxRetries || !opts.shouldRetry(error)) {
+        if (attempt >= opts.maxRetries && opts.maxRetries > 0) {
+          logger.error(`重试 ${opts.maxRetries} 次后仍失败: ${errorMsg}`);
+        } else if (!opts.shouldRetry(error)) {
+          logger.debug(`不可重试的错误: ${errorMsg}`);
+        }
+        throw error;
+      }
+
+      /* 指数退避等待 */
+      const delay = Math.min(opts.initialDelay * Math.pow(2, attempt), opts.maxDelay);
+      logger.warn(`请求失败 (${errorMsg})，${delay}ms 后第 ${attempt + 2} 次重试...`);
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * 带超时控制的 fetch 包装
+ * 在原生 fetch 基础上添加超时中断能力
+ *
+ * @param url 请求 URL
+ * @param init fetch 选项
+ * @param timeoutMs 超时时间（毫秒）
+ */
+export async function fetchWithTimeout(
+  url: string,
+  init?: RequestInit,
+  timeoutMs: number = DEFAULT_RETRY_OPTIONS.timeout,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, {
+      ...init,
+      signal: controller.signal,
+    });
+    return response;
+  } catch (error: any) {
+    if (error.name === 'AbortError') {
+      throw new Error(`Request timeout after ${timeoutMs}ms: ${url}`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/types.ts

@@ -1,20 +1,38 @@
-export type Channel = 'tempmail' | 'linshi-email' | 'tempmail-lol' | 'chatgpt-org-uk' | 'tempmail-la' | 'temp-mail-io' | 'awamail' | 'mail-tm' | 'dropmail';
+/**
+ * 支持的临时邮箱渠道标识
+ * 每个渠道对应一个第三方临时邮箱服务商
+ */
+export type Channel = 'tempmail' | 'linshi-email' | 'tempmail-lol' | 'chatgpt-org-uk' | 'tempmail-la' | 'temp-mail-io' | 'awamail' | 'mail-tm' | 'dropmail' | 'guerrillamail' | 'maildrop';
 
+/**
+ * 创建临时邮箱后返回的邮箱信息
+ * 包含邮箱地址、认证令牌和生命周期信息
+ */
 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;
 }
 
@@ -42,21 +60,91 @@ 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;
 }