tempmail-sdk 1.0.1 → 1.0.3

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

@@ -0,0 +1,125 @@
+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 {
+    id: normalizeId(raw),
+    from: normalizeFrom(raw),
+    to: normalizeTo(raw, recipientEmail),
+    subject: normalizeSubject(raw),
+    text: normalizeText(raw),
+    html: normalizeHtml(raw),
+    date: normalizeDate(raw),
+    isRead: normalizeIsRead(raw),
+    attachments: normalizeAttachments(raw.attachments),
+  };
+}
+
+/**
+ * 提取邮件 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();
+    if (raw.created_at) return new Date(raw.created_at).toISOString();
+    if (raw.createdAt) return new Date(raw.createdAt).toISOString();
+    if (raw.date) {
+      if (typeof raw.date === 'number') return new Date(raw.date).toISOString();
+      return new Date(raw.date).toISOString();
+    }
+    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;
+  if (typeof raw.isRead === 'boolean') return raw.isRead;
+  if (typeof raw.is_read === 'number') return raw.is_read === 1;
+  if (typeof raw.is_read === 'string') return raw.is_read === '1';
+  if (typeof raw.is_read === 'boolean') return raw.is_read;
+  return false;
+}
+
+/**
+ * 提取并标准化附件列表
+ * 每个附件的字段也采用多候选策略映射
+ */
+function normalizeAttachments(attachments: any): EmailAttachment[] {
+  if (!attachments || !Array.isArray(attachments)) return [];
+  return attachments.map((a: any) => ({
+    filename: a.filename || a.name || '',
+    size: a.size || a.filesize || undefined,
+    contentType: a.contentType || a.content_type || a.mimeType || a.mime_type || undefined,
+    url: a.url || a.download_url || a.downloadUrl || undefined,
+  }));
+}

package/src/providers/awamail.ts

@@ -0,0 +1,101 @@
+import { EmailInfo, Email, Channel } from '../types';
+import { normalizeEmail } from '../normalize';
+
+const CHANNEL: Channel = 'awamail';
+const BASE_URL = 'https://awamail.com/welcome';
+
+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/javascript, */*; q=0.01',
+  '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',
+  'origin': 'https://awamail.com',
+  'pragma': 'no-cache',
+  'referer': 'https://awamail.com/?lang=zh',
+  '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',
+};
+
+/**
+ * 从 Set-Cookie 响应头中提取 awamail_session 值
+ */
+function extractSessionCookie(response: Response): string {
+  const setCookie = response.headers.get('set-cookie') || '';
+  const match = setCookie.match(/awamail_session=([^;]+)/);
+  return match ? `awamail_session=${match[1]}` : '';
+}
+
+/**
+ * 创建临时邮箱
+ * API: POST /welcome/change_mailbox (空 body)
+ * 返回: { success, data: { email_address, expired_at, created_at, ... } }
+ * 需要保存响应中的 Set-Cookie (awamail_session) 用于后续获取邮件
+ */
+export async function generateEmail(): Promise<EmailInfo> {
+  const response = await fetch(`${BASE_URL}/change_mailbox`, {
+    method: 'POST',
+    headers: {
+      ...DEFAULT_HEADERS,
+      'Content-Length': '0',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to generate email: ${response.status}`);
+  }
+
+  // 提取 session cookie
+  const sessionCookie = extractSessionCookie(response);
+  if (!sessionCookie) {
+    throw new Error('Failed to extract session cookie');
+  }
+
+  const data = await response.json();
+
+  if (!data.success || !data.data) {
+    throw new Error('Failed to generate email');
+  }
+
+  return {
+    channel: CHANNEL,
+    email: data.data.email_address,
+    token: sessionCookie,
+    expiresAt: data.data.expired_at,
+    createdAt: data.data.created_at,
+  };
+}
+
+/**
+ * 获取邮件列表
+ * API: GET /welcome/get_emails
+ * 需要传入 Cookie (awamail_session) 和 x-requested-with 头
+ * 返回: { success, data: { emails: [...], latest: {...} } }
+ */
+export async function getEmails(token: string, email: string): Promise<Email[]> {
+  const response = await fetch(`${BASE_URL}/get_emails`, {
+    method: 'GET',
+    headers: {
+      ...DEFAULT_HEADERS,
+      'Cookie': token,
+      'x-requested-with': 'XMLHttpRequest',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to get emails: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  if (!data.success || !data.data) {
+    throw new Error('Failed to get emails');
+  }
+
+  const rawEmails = data.data.emails || [];
+  return rawEmails.map((raw: any) => normalizeEmail(raw, email));
+}

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

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

package/src/providers/dropmail.ts

@@ -0,0 +1,98 @@
+import { EmailInfo, Email, Channel } from '../types';
+import { normalizeEmail } from '../normalize';
+
+const CHANNEL: Channel = 'dropmail';
+const BASE_URL = 'https://dropmail.me/api/graphql/MY_TOKEN';
+
+const DEFAULT_HEADERS: Record<string, string> = {
+  'Content-Type': 'application/x-www-form-urlencoded',
+};
+
+const CREATE_SESSION_QUERY = 'mutation {introduceSession {id, expiresAt, addresses{id, address}}}';
+
+const GET_MAILS_QUERY = `query ($id: ID!) {
+  session(id:$id) {
+    mails {
+      id, rawSize, fromAddr, toAddr, receivedAt,
+      text, headerFrom, headerSubject, html
+    }
+  }
+}`;
+
+/**
+ * 执行 GraphQL 请求
+ */
+async function graphqlRequest(query: string, variables?: Record<string, any>): Promise<any> {
+  const params = new URLSearchParams();
+  params.set('query', query);
+  if (variables) {
+    params.set('variables', JSON.stringify(variables));
+  }
+
+  const response = await fetch(BASE_URL, {
+    method: 'POST',
+    headers: DEFAULT_HEADERS,
+    body: params.toString(),
+  });
+
+  if (!response.ok) {
+    throw new Error(`GraphQL request failed: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  if (data.errors) {
+    throw new Error(`GraphQL error: ${data.errors[0]?.message || 'Unknown error'}`);
+  }
+
+  return data.data;
+}
+
+/**
+ * 创建临时邮箱
+ * GraphQL mutation: introduceSession
+ * 返回 session ID (存入 token) 和邮箱地址
+ */
+export async function generateEmail(): Promise<EmailInfo> {
+  const data = await graphqlRequest(CREATE_SESSION_QUERY);
+
+  const session = data?.introduceSession;
+  if (!session || !session.addresses || session.addresses.length === 0) {
+    throw new Error('Failed to generate email');
+  }
+
+  return {
+    channel: CHANNEL,
+    email: session.addresses[0].address,
+    token: session.id,
+    expiresAt: session.expiresAt,
+  };
+}
+
+/**
+ * 将 dropmail 的邮件格式扁平化为 normalizeEmail 可处理的格式
+ */
+function flattenMessage(mail: any, recipientEmail: string): any {
+  return {
+    id: mail.id || '',
+    from: mail.fromAddr || '',
+    to: mail.toAddr || recipientEmail,
+    subject: mail.headerSubject || '',
+    text: mail.text || '',
+    html: mail.html || '',
+    received_at: mail.receivedAt || '',
+    attachments: [],
+  };
+}
+
+/**
+ * 获取邮件列表
+ * GraphQL query: session(id) { mails {...} }
+ * token 中存储的是 session ID
+ */
+export async function getEmails(token: string, email: string): Promise<Email[]> {
+  const data = await graphqlRequest(GET_MAILS_QUERY, { id: token });
+
+  const mails = data?.session?.mails || [];
+  return mails.map((mail: any) => normalizeEmail(flattenMessage(mail, email), email));
+}

package/src/providers/linshi-email.ts

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

package/src/providers/mail-tm.ts

@@ -0,0 +1,193 @@
+import { EmailInfo, Email, Channel } from '../types';
+import { normalizeEmail } from '../normalize';
+
+const CHANNEL: Channel = 'mail-tm';
+const BASE_URL = 'https://api.mail.tm';
+
+const DEFAULT_HEADERS: Record<string, string> = {
+  'Content-Type': 'application/json',
+  'Accept': 'application/json',
+};
+
+/**
+ * 生成随机字符串
+ */
+function randomString(length: number): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return result;
+}
+
+/**
+ * 获取可用域名列表
+ * API: GET /domains
+ */
+async function getDomains(): Promise<string[]> {
+  const response = await fetch(`${BASE_URL}/domains`, {
+    method: 'GET',
+    headers: DEFAULT_HEADERS,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to get domains: ${response.status}`);
+  }
+
+  const data = await response.json();
+  /* 兼容两种响应格式：
+   * - 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);
+}
+
+/**
+ * 创建账号
+ * API: POST /accounts
+ */
+async function createAccount(address: string, password: string): Promise<any> {
+  const response = await fetch(`${BASE_URL}/accounts`, {
+    method: 'POST',
+    headers: { ...DEFAULT_HEADERS, 'Content-Type': 'application/ld+json' },
+    body: JSON.stringify({ address, password }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Failed to create account: ${response.status} ${text}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * 获取 Bearer Token
+ * API: POST /token
+ */
+async function getToken(address: string, password: string): Promise<string> {
+  const response = await fetch(`${BASE_URL}/token`, {
+    method: 'POST',
+    headers: DEFAULT_HEADERS,
+    body: JSON.stringify({ address, password }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to get token: ${response.status}`);
+  }
+
+  const data = await response.json();
+  return data.token;
+}
+
+/**
+ * 创建临时邮箱
+ * 流程: 获取域名 → 生成随机邮箱/密码 → 创建账号 → 获取 Token
+ */
+export async function generateEmail(): Promise<EmailInfo> {
+  // 1. 获取可用域名
+  const domains = await getDomains();
+  if (domains.length === 0) {
+    throw new Error('No available domains');
+  }
+
+  // 2. 生成随机邮箱和密码
+  const domain = domains[Math.floor(Math.random() * domains.length)];
+  const username = randomString(12);
+  const address = `${username}@${domain}`;
+  const password = randomString(16);
+
+  // 3. 创建账号
+  const account = await createAccount(address, password);
+
+  // 4. 获取 Bearer Token
+  const token = await getToken(address, password);
+
+  return {
+    channel: CHANNEL,
+    email: address,
+    token: token,
+    createdAt: account.createdAt,
+  };
+}
+
+/**
+ * 将 mail.tm 的消息格式扁平化为 normalizeEmail 可处理的格式
+ * mail.tm 的 from 是 {name, address} 对象，to 是数组，html 是字符串数组
+ */
+function flattenMessage(msg: any, recipientEmail: string): any {
+  return {
+    id: msg.id || '',
+    from: msg.from?.address || '',
+    to: msg.to?.[0]?.address || recipientEmail,
+    subject: msg.subject || '',
+    text: msg.text || '',
+    html: Array.isArray(msg.html) ? msg.html.join('') : (msg.html || ''),
+    createdAt: msg.createdAt || '',
+    seen: msg.seen ?? false,
+    attachments: (msg.attachments || []).map((a: any) => ({
+      filename: a.filename || '',
+      size: a.size || undefined,
+      contentType: a.contentType || undefined,
+      downloadUrl: a.downloadUrl ? `${BASE_URL}${a.downloadUrl}` : undefined,
+    })),
+  };
+}
+
+/**
+ * 获取邮件列表
+ * 流程: GET /messages 获取列表 → 对每封邮件 GET /messages/{id} 获取详情（含 text/html）
+ */
+export async function getEmails(token: string, email: string): Promise<Email[]> {
+  // 1. 获取邮件列表
+  const listResponse = await fetch(`${BASE_URL}/messages`, {
+    method: 'GET',
+    headers: {
+      ...DEFAULT_HEADERS,
+      'Authorization': `Bearer ${token}`,
+    },
+  });
+
+  if (!listResponse.ok) {
+    throw new Error(`Failed to get emails: ${listResponse.status}`);
+  }
+
+  const listData = await listResponse.json();
+  /* 兼容 Hydra 格式和纯数组格式 */
+  const messages = Array.isArray(listData) ? listData : (listData['hydra:member'] || []);
+
+  if (messages.length === 0) {
+    return [];
+  }
+
+  // 2. 并行获取每封邮件的详情（含 text/html/attachments）
+  const detailPromises = messages.map(async (msg: any) => {
+    try {
+      const detailResponse = await fetch(`${BASE_URL}/messages/${msg.id}`, {
+        method: 'GET',
+        headers: {
+          ...DEFAULT_HEADERS,
+          'Authorization': `Bearer ${token}`,
+        },
+      });
+
+      if (!detailResponse.ok) {
+        // 如果详情获取失败，退回使用列表数据
+        return flattenMessage(msg, email);
+      }
+
+      const detail = await detailResponse.json();
+      return flattenMessage(detail, email);
+    } catch {
+      // 出错时退回使用列表数据
+      return flattenMessage(msg, email);
+    }
+  });
+
+  const flatMessages = await Promise.all(detailPromises);
+  return flatMessages.map((raw: any) => normalizeEmail(raw, email));
+}