tempmail-sdk 1.0.3 → 1.1.1

package/src/providers/chatgpt-org-uk.ts

@@ -1,4 +1,4 @@
-import { EmailInfo, Email, Channel } from '../types';
+import { InternalEmailInfo, Email, Channel } from '../types';
 import { normalizeEmail } from '../normalize';
 
 const CHANNEL: Channel = 'chatgpt-org-uk';
@@ -15,7 +15,7 @@ const DEFAULT_HEADERS = {
   'DNT': '1',
 };
 
-export async function generateEmail(): Promise<EmailInfo> {
+export async function generateEmail(): Promise<InternalEmailInfo> {
   const response = await fetch(`${BASE_URL}/generate-email`, {
     method: 'GET',
     headers: DEFAULT_HEADERS,

package/src/providers/dropmail.ts

@@ -1,4 +1,4 @@
-import { EmailInfo, Email, Channel } from '../types';
+import { InternalEmailInfo, Email, Channel } from '../types';
 import { normalizeEmail } from '../normalize';
 
 const CHANNEL: Channel = 'dropmail';
@@ -53,7 +53,7 @@ async function graphqlRequest(query: string, variables?: Record<string, any>): P
  * GraphQL mutation: introduceSession
  * 返回 session ID (存入 token) 和邮箱地址
  */
-export async function generateEmail(): Promise<EmailInfo> {
+export async function generateEmail(): Promise<InternalEmailInfo> {
   const data = await graphqlRequest(CREATE_SESSION_QUERY);
 
   const session = data?.introduceSession;

package/src/providers/guerrillamail.ts

@@ -0,0 +1,78 @@
+/**
+ * Guerrilla Mail 渠道实现
+ * API 文档: https://www.guerrillamail.com/GuerrillaMailAPI.html
+ * 
+ * 特点:
+ * - 无需认证，公开 JSON API
+ * - 通过 sid_token 维持会话
+ * - 邮箱有效期 60 分钟
+ */
+
+import { InternalEmailInfo, 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<InternalEmailInfo> {
+  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/linshi-email.ts

@@ -1,4 +1,4 @@
-import { EmailInfo, Email, Channel } from '../types';
+import { InternalEmailInfo, Email, Channel } from '../types';
 import { normalizeEmail } from '../normalize';
 
 const CHANNEL: Channel = 'linshi-email';
@@ -16,7 +16,7 @@ const DEFAULT_HEADERS = {
   'DNT': '1',
 };
 
-export async function generateEmail(): Promise<EmailInfo> {
+export async function generateEmail(): Promise<InternalEmailInfo> {
   const response = await fetch(`${BASE_URL}/email/${API_KEY}`, {
     method: 'POST',
     headers: DEFAULT_HEADERS,

package/src/providers/mail-tm.ts

@@ -1,4 +1,4 @@
-import { EmailInfo, Email, Channel } from '../types';
+import { InternalEmailInfo, Email, Channel } from '../types';
 import { normalizeEmail } from '../normalize';
 
 const CHANNEL: Channel = 'mail-tm';
@@ -88,7 +88,7 @@ async function getToken(address: string, password: string): Promise<string> {
  * 创建临时邮箱
  * 流程: 获取域名 → 生成随机邮箱/密码 → 创建账号 → 获取 Token
  */
-export async function generateEmail(): Promise<EmailInfo> {
+export async function generateEmail(): Promise<InternalEmailInfo> {
   // 1. 获取可用域名
   const domains = await getDomains();
   if (domains.length === 0) {

package/src/providers/maildrop.ts

@@ -0,0 +1,210 @@
+/**
+ * Maildrop 渠道实现
+ * API: GraphQL endpoint https://api.maildrop.cc/graphql
+ * 
+ * 特点:
+ * - 无需认证，公开 GraphQL API
+ * - 自带反垃圾过滤
+ * - 邮箱名即用户名（任意字符串@maildrop.cc）
+ * - 无过期时间限制
+ */
+
+import { InternalEmailInfo, 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<InternalEmailInfo> {
+  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

@@ -1,4 +1,4 @@
-import { EmailInfo, Email, Channel } from '../types';
+import { InternalEmailInfo, Email, Channel } from '../types';
 import { normalizeEmail } from '../normalize';
 
 const CHANNEL: Channel = 'temp-mail-io';
@@ -59,7 +59,7 @@ async function getApiHeaders(): Promise<Record<string, string>> {
  * API: POST /api/v3/email/new
  * 返回: { email, token }
  */
-export async function generateEmail(): Promise<EmailInfo> {
+export async function generateEmail(): Promise<InternalEmailInfo> {
   const headers = await getApiHeaders();
   const response = await fetch(`${BASE_URL}/email/new`, {
     method: 'POST',

package/src/providers/tempmail-la.ts

@@ -1,4 +1,4 @@
-import { EmailInfo, Email, Channel } from '../types';
+import { InternalEmailInfo, Email, Channel } from '../types';
 import { normalizeEmail } from '../normalize';
 
 const CHANNEL: Channel = 'tempmail-la';
@@ -30,7 +30,7 @@ const DEFAULT_HEADERS: Record<string, string> = {
  * API: POST /api/mail/create
  * 返回: { code: 0, data: { mailId, address, type, startAt, endAt } }
  */
-export async function generateEmail(): Promise<EmailInfo> {
+export async function generateEmail(): Promise<InternalEmailInfo> {
   const response = await fetch(`${BASE_URL}/mail/create`, {
     method: 'POST',
     headers: DEFAULT_HEADERS,

package/src/providers/tempmail-lol.ts

@@ -1,4 +1,4 @@
-import { EmailInfo, Email, Channel } from '../types';
+import { InternalEmailInfo, Email, Channel } from '../types';
 import { normalizeEmail } from '../normalize';
 
 const CHANNEL: Channel = 'tempmail-lol';
@@ -14,7 +14,7 @@ const DEFAULT_HEADERS = {
   'DNT': '1',
 };
 
-export async function generateEmail(domain: string | null = null): Promise<EmailInfo> {
+export async function generateEmail(domain: string | null = null): Promise<InternalEmailInfo> {
   const response = await fetch(`${BASE_URL}/inbox/create`, {
     method: 'POST',
     headers: DEFAULT_HEADERS,

package/src/providers/tempmail.ts

@@ -1,4 +1,4 @@
-import { EmailInfo, Email, Channel } from '../types';
+import { InternalEmailInfo, Email, Channel } from '../types';
 import { normalizeEmail } from '../normalize';
 
 const CHANNEL: Channel = 'tempmail';
@@ -14,7 +14,7 @@ const DEFAULT_HEADERS = {
   'DNT': '1',
 };
 
-export async function generateEmail(duration: number = 30): Promise<EmailInfo> {
+export async function generateEmail(duration: number = 30): Promise<InternalEmailInfo> {
   const response = await fetch(`${BASE_URL}/generate`, {
     method: 'POST',
     headers: DEFAULT_HEADERS,

package/src/retry.ts

@@ -4,6 +4,7 @@
  */
 
 import { logger } from './logger';
+import { getConfig } from './config';
 
 /**
  * 重试配置选项
@@ -52,6 +53,11 @@ function defaultShouldRetry(error: any): boolean {
     return true;
   }
 
+  /* HTTP 429 限流 → 重试 */
+  if (message.includes('429') || message.includes('too many requests') || message.includes('rate limit')) {
+    return true;
+  }
+
   /* HTTP 4xx/5xx 错误 → 重试 */
   const statusMatch = message.match(/:\s*(\d{3})/);
   if (statusMatch) {
@@ -124,20 +130,25 @@ export async function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions)
 export async function fetchWithTimeout(
   url: string,
   init?: RequestInit,
-  timeoutMs: number = DEFAULT_RETRY_OPTIONS.timeout,
+  timeoutMs?: number,
 ): Promise<Response> {
+  const config = getConfig();
+  const effectiveTimeout = timeoutMs ?? config.timeout ?? DEFAULT_RETRY_OPTIONS.timeout;
   const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  const timeoutId = setTimeout(() => controller.abort(), effectiveTimeout);
+
+  /* 使用自定义 fetch 或原生 fetch */
+  const fetchFn = config.customFetch || fetch;
 
   try {
-    const response = await fetch(url, {
+    const response = await fetchFn(url, {
       ...init,
       signal: controller.signal,
     });
     return response;
   } catch (error: any) {
     if (error.name === 'AbortError') {
-      throw new Error(`Request timeout after ${timeoutMs}ms: ${url}`);
+      throw new Error(`Request timeout after ${effectiveTimeout}ms: ${url}`);
     }
     throw error;
   } finally {

package/src/types.ts

@@ -2,25 +2,33 @@
  * 支持的临时邮箱渠道标识
  * 每个渠道对应一个第三方临时邮箱服务商
  */
-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';
 
 /**
  * 创建临时邮箱后返回的邮箱信息
- * 包含邮箱地址、认证令牌和生命周期信息
+ * Token 等认证信息由 SDK 内部维护，不对外暴露
  */
 export interface EmailInfo {
   /** 创建该邮箱所使用的渠道 */
   channel: Channel;
   /** 临时邮箱地址 */
   email: string;
-  /** 认证令牌，部分渠道在获取邮件时需要此令牌 */
-  token?: string;
   /** 邮箱过期时间（ISO 8601 字符串或 Unix 时间戳） */
   expiresAt?: string | number;
   /** 邮箱创建时间（ISO 8601 字符串） */
   createdAt?: string;
 }
 
+/**
+ * SDK 内部使用的邮箱信息，包含 token 等认证数据
+ * 不对外导出，用户无法访问
+ * @internal
+ */
+export interface InternalEmailInfo extends EmailInfo {
+  /** 认证令牌，由 SDK 内部维护 */
+  token?: string;
+}
+
 /**
  * 标准化邮件附件
  * 不同渠道的附件字段名不同，SDK 统一归一化为此结构
@@ -125,26 +133,18 @@ export interface GenerateEmailOptions {
 
 /**
  * 获取邮件列表的选项
+ * Channel/Email/Token 等由 SDK 从 EmailInfo 中自动获取，用户无需手动传递
  *
  * @example
  * ```ts
- * const result = await getEmails({
- *   channel: emailInfo.channel,
- *   email: emailInfo.email,
- *   token: emailInfo.token,
- * });
+ * const info = await generateEmail({ channel: 'mail-tm' });
+ * const result = await getEmails(info);
  * if (result.success && result.emails.length > 0) {
  *   console.log('收到邮件:', result.emails);
  * }
  * ```
  */
 export interface GetEmailsOptions {
-  /** 渠道标识，必填 */
-  channel: Channel;
-  /** 邮箱地址，必填 */
-  email: string;
-  /** 认证令牌 */
-  token?: string;
   /** 重试配置，不传则使用默认值（最多重试 2 次） */
   retry?: RetryConfig;
 }