tempmail-sdk 1.0.1 → 1.0.3

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

@@ -0,0 +1,108 @@
+import { EmailInfo, Email, Channel } from '../types';
+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';
+
+/**
+ * 缓存从页面动态获取的 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/',
+  };
+}
+
+/**
+ * 创建临时邮箱
+ * API: POST /api/v3/email/new
+ * 返回: { email, token }
+ */
+export async function generateEmail(): Promise<EmailInfo> {
+  const headers = await getApiHeaders();
+  const response = await fetch(`${BASE_URL}/email/new`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ min_name_length: 10, max_name_length: 10 }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to generate email: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  if (!data.email || !data.token) {
+    throw new Error('Failed to generate email');
+  }
+
+  return {
+    channel: CHANNEL,
+    email: data.email,
+    token: data.token,
+  };
+}
+
+/**
+ * 获取邮件列表
+ * API: GET /api/v3/email/{email}/messages
+ * 返回: [ { id, from, to, cc, subject, body_text, body_html, created_at, attachments } ]
+ */
+export async function getEmails(email: string): Promise<Email[]> {
+  const headers = await getApiHeaders();
+  const response = await fetch(`${BASE_URL}/email/${email}/messages`, {
+    method: 'GET',
+    headers,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to get emails: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  // API 直接返回邮件数组
+  const rawEmails = Array.isArray(data) ? data : [];
+  return rawEmails.map((raw: any) => normalizeEmail(raw, email));
+}

package/src/providers/tempmail-la.ts

@@ -0,0 +1,99 @@
+import { EmailInfo, Email, Channel } from '../types';
+import { normalizeEmail } from '../normalize';
+
+const CHANNEL: Channel = 'tempmail-la';
+const BASE_URL = 'https://tempmail.la/api';
+
+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',
+  'Accept': 'application/json, text/plain, */*',
+  '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',
+  'cache-control': 'no-cache',
+  'dnt': '1',
+  'locale': 'zh-CN',
+  'origin': 'https://tempmail.la',
+  'platform': 'PC',
+  'pragma': 'no-cache',
+  'product': 'TEMP_MAIL',
+  'referer': 'https://tempmail.la/zh-CN/tempmail',
+  '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-origin',
+};
+
+/**
+ * 创建临时邮箱
+ * API: POST /api/mail/create
+ * 返回: { code: 0, data: { mailId, address, type, startAt, endAt } }
+ */
+export async function generateEmail(): Promise<EmailInfo> {
+  const response = await fetch(`${BASE_URL}/mail/create`, {
+    method: 'POST',
+    headers: DEFAULT_HEADERS,
+    body: JSON.stringify({ turnstile: '' }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to generate email: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  if (data.code !== 0 || !data.data) {
+    throw new Error('Failed to generate email');
+  }
+
+  return {
+    channel: CHANNEL,
+    email: data.data.address,
+    expiresAt: data.data.endAt,
+    createdAt: data.data.startAt,
+  };
+}
+
+/**
+ * 获取邮件列表
+ * API: POST /api/mail/box
+ * 请求: { address, cursor }
+ * 返回: { code: 0, data: { rows: [...], cursor, hasMore } }
+ * 每封邮件: { mailboxId, messageFrom, subject, createdAt, html, attachments, read }
+ */
+export async function getEmails(email: string): Promise<Email[]> {
+  const allEmails: any[] = [];
+  let cursor: string | null = null;
+  let hasMore = true;
+
+  // 支持分页，循环获取所有邮件
+  while (hasMore) {
+    const response: Response = await fetch(`${BASE_URL}/mail/box`, {
+      method: 'POST',
+      headers: DEFAULT_HEADERS,
+      body: JSON.stringify({ address: email, cursor }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to get emails: ${response.status}`);
+    }
+
+    const data: any = await response.json();
+
+    if (data.code !== 0 || !data.data) {
+      throw new Error('Failed to get emails');
+    }
+
+    const rows = data.data.rows || [];
+    allEmails.push(...rows);
+
+    if (data.data.hasMore && data.data.cursor) {
+      cursor = data.data.cursor;
+    } else {
+      hasMore = false;
+    }
+  }
+
+  return allEmails.map((raw: any) => normalizeEmail(raw, email));
+}

package/src/providers/tempmail-lol.ts

@@ -1,4 +1,5 @@
 import { EmailInfo, Email, Channel } from '../types';
+import { normalizeEmail } from '../normalize';
 
 const CHANNEL: Channel = 'tempmail-lol';
 const BASE_URL = 'https://api.tempmail.lol/v2';
@@ -37,7 +38,7 @@ export async function generateEmail(domain: string | null = null): Promise<Email
   };
 }
 
-export async function getEmails(token: string): Promise<Email[]> {
+export async function getEmails(token: string, recipientEmail: string = ''): Promise<Email[]> {
   const response = await fetch(`${BASE_URL}/inbox?token=${encodeURIComponent(token)}`, {
     method: 'GET',
     headers: DEFAULT_HEADERS,
@@ -49,5 +50,6 @@ export async function getEmails(token: string): Promise<Email[]> {
 
   const data = await response.json();
   
-  return data.emails || [];
+  const rawEmails = data.emails || [];
+  return rawEmails.map((raw: any) => normalizeEmail(raw, recipientEmail));
 }

package/src/providers/tempmail.ts

@@ -1,4 +1,5 @@
 import { EmailInfo, Email, Channel } from '../types';
+import { normalizeEmail } from '../normalize';
 
 const CHANNEL: Channel = 'tempmail';
 const BASE_URL = 'https://api.tempmail.ing/api';
@@ -55,5 +56,6 @@ export async function getEmails(email: string): Promise<Email[]> {
     throw new Error('Failed to get emails');
   }
 
-  return data.emails || [];
+  const rawEmails = data.emails || [];
+  return rawEmails.map((raw: any) => normalizeEmail(raw, email));
 }

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,58 +1,150 @@
-export type Channel = 'tempmail' | 'linshi-email' | 'tempmail-lol' | 'chatgpt-org-uk';
+/**
+ * 支持的临时邮箱渠道标识
+ * 每个渠道对应一个第三方临时邮箱服务商
+ */
+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;
+}
+
+/**
+ * 标准化邮件格式 - 所有提供商返回统一结构
+ */
 export interface Email {
-  id?: string | number;
-  eid?: string;
-  _id?: string;
-  from?: string;
-  from_address?: string;
-  from_name?: string;
-  address_from?: string;
-  name_from?: string;
-  to?: string;
-  name_to?: string;
-  email_address?: string;
-  subject?: string;
-  e_subject?: string;
-  body?: string;
-  text?: string;
-  content?: string;
-  html?: string;
-  html_content?: string;
-  date?: string | number;
-  e_date?: number;
-  timestamp?: number;
-  received_at?: string;
-  created_at?: string;
-  createdAt?: string;
-  is_read?: number;
-  has_html?: boolean;
-  [key: string]: any;
+  /** 邮件唯一标识 */
+  id: string;
+  /** 发件人邮箱地址 */
+  from: string;
+  /** 收件人邮箱地址 */
+  to: string;
+  /** 邮件主题 */
+  subject: string;
+  /** 纯文本内容 */
+  text: string;
+  /** HTML 内容 */
+  html: string;
+  /** ISO 8601 格式的日期字符串 */
+  date: string;
+  /** 是否已读 */
+  isRead: boolean;
+  /** 附件列表 */
+  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/test/example.ts

@@ -4,7 +4,7 @@ async function testGenerateEmail() {
   console.log('=== Test Generate Email ===\n');
 
   // Test each channel
-  const channels: Channel[] = ['tempmail', 'linshi-email', 'tempmail-lol', 'chatgpt-org-uk'];
+  const channels: Channel[] = ['tempmail', 'linshi-email', 'tempmail-lol', 'chatgpt-org-uk', 'tempmail-la', 'temp-mail-io', 'awamail', 'mail-tm', 'dropmail'];
   
   for (const channel of channels) {
     try {
@@ -14,6 +14,7 @@ async function testGenerateEmail() {
       console.log(`  Email: ${emailInfo.email}`);
       if (emailInfo.token) console.log(`  Token: ${emailInfo.token}`);
       if (emailInfo.expiresAt) console.log(`  Expires: ${emailInfo.expiresAt}`);
+      if (emailInfo.createdAt) console.log(`  Created: ${emailInfo.createdAt}`);
       console.log();
     } catch (error) {
       console.error(`  Error: ${error}`);
@@ -34,6 +35,20 @@ async function testGetEmails() {
     
     const result = await client.getEmails();
     console.log(`Emails count: ${result.emails.length}`);
+
+    // 展示标准化的邮件格式
+    for (const email of result.emails) {
+      console.log(`  ID: ${email.id}`);
+      console.log(`  From: ${email.from}`);
+      console.log(`  To: ${email.to}`);
+      console.log(`  Subject: ${email.subject}`);
+      console.log(`  Date: ${email.date}`);
+      console.log(`  IsRead: ${email.isRead}`);
+      console.log(`  Text: ${email.text.substring(0, 100)}`);
+      console.log(`  HTML: ${email.html.substring(0, 100)}`);
+      console.log(`  Attachments: ${email.attachments.length}`);
+      console.log();
+    }
     console.log();
   } catch (error) {
     console.error(`Error: ${error}`);