tempmail-sdk 1.0.1 → 1.0.3

package/README.md

@@ -1,10 +1,9 @@
-# temp-email-sdk
+# tempmail-sdk
 
-临时邮箱 SDK，支持多个邮箱服务提供商。
+[![npm version](https://badge.fury.io/js/tempmail-sdk.svg)](https://www.npmjs.com/package/tempmail-sdk)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 
-## 许可证
-
-GPL-3.0
+临时邮箱 SDK（TypeScript/Node.js），支持 9 个邮箱服务提供商，所有渠道返回**统一标准化格式**。
 
 ## 安装
 
@@ -14,40 +13,78 @@ npm install tempmail-sdk
 
 ## 支持的渠道
 
-| 渠道 | 服务商 |
-|------|--------|
-| `tempmail` | tempmail.ing |
-| `linshi-email` | linshi-email.com |
-| `tempmail-lol` | tempmail.lol |
-| `chatgpt-org-uk` | mail.chatgpt.org.uk |
+| 渠道 | 服务商 | 需要 Token | 说明 |
+|------|--------|:----------:|------|
+| `tempmail` | tempmail.ing | - | 支持自定义有效期 |
+| `linshi-email` | linshi-email.com | - | |
+| `tempmail-lol` | tempmail.lol | ✅ | 支持指定域名 |
+| `chatgpt-org-uk` | mail.chatgpt.org.uk | - | |
+| `tempmail-la` | tempmail.la | - | 支持分页 |
+| `temp-mail-io` | temp-mail.io | - | |
+| `awamail` | awamail.com | ✅ | Session Cookie 自动管理 |
+| `mail-tm` | mail.tm | ✅ | 自动注册账号获取 Bearer Token |
+| `dropmail` | dropmail.me | ✅ | GraphQL API |
+
+> **提示：** 使用 `TempEmailClient` 类时无需手动处理 Token，SDK 自动管理。
+
+## 快速开始
+
+### 使用 TempEmailClient（推荐）
+
+```typescript
+import { TempEmailClient } from 'tempmail-sdk';
+
+const client = new TempEmailClient();
+
+// 获取临时邮箱（可指定渠道，不指定则随机）
+const emailInfo = await client.generate({ channel: 'tempmail' });
+console.log(`渠道: ${emailInfo.channel}`);
+console.log(`邮箱: ${emailInfo.email}`);
+if (emailInfo.expiresAt) console.log(`过期时间: ${emailInfo.expiresAt}`);
+
+// 获取邮件（Token 自动传递，无需手动处理）
+const result = await client.getEmails();
+console.log(`收到 ${result.emails.length} 封邮件`);
 
-## 使用方法
+for (const email of result.emails) {
+  console.log(`发件人: ${email.from}`);
+  console.log(`主题: ${email.subject}`);
+  console.log(`内容: ${email.text}`);
+  console.log(`时间: ${email.date}`);
+  console.log(`已读: ${email.isRead}`);
+  console.log(`附件: ${email.attachments.length} 个`);
+}
+```
 
-### 列出所有提供商
+### 使用函数式 API
+
+#### 列出所有渠道
 
 ```typescript
-import { listChannels, getChannelInfo } from 'temp-email-sdk';
+import { listChannels, getChannelInfo } from 'tempmail-sdk';
 
-// 获取所有支持的渠道
 const channels = listChannels();
 console.log(channels);
 // [
 //   { channel: 'tempmail', name: 'TempMail', website: 'tempmail.ing' },
 //   { channel: 'linshi-email', name: '临时邮箱', website: 'linshi-email.com' },
 //   { channel: 'tempmail-lol', name: 'TempMail LOL', website: 'tempmail.lol' },
-//   { channel: 'chatgpt-org-uk', name: 'ChatGPT Mail', website: 'mail.chatgpt.org.uk' }
+//   { channel: 'chatgpt-org-uk', name: 'ChatGPT Mail', website: 'mail.chatgpt.org.uk' },
+//   { channel: 'tempmail-la', name: 'TempMail LA', website: 'tempmail.la' },
+//   { channel: 'temp-mail-io', name: 'Temp Mail IO', website: 'temp-mail.io' },
+//   { channel: 'awamail', name: 'AwaMail', website: 'awamail.com' },
+//   { channel: 'mail-tm', name: 'Mail.tm', website: 'mail.tm' },
+//   { channel: 'dropmail', name: 'DropMail', website: 'dropmail.me' }
 // ]
 
-// 获取指定渠道信息
 const info = getChannelInfo('tempmail');
-console.log(info);
 // { channel: 'tempmail', name: 'TempMail', website: 'tempmail.ing' }
 ```
 
-### 获取邮箱
+#### 获取邮箱
 
 ```typescript
-import { generateEmail } from 'temp-email-sdk';
+import { generateEmail } from 'tempmail-sdk';
 
 // 从随机渠道获取邮箱
 const emailInfo = await generateEmail();
@@ -56,66 +93,65 @@ console.log(emailInfo);
 
 // 从指定渠道获取邮箱
 const emailInfo2 = await generateEmail({ channel: 'linshi-email' });
-console.log(emailInfo2);
-// { channel: 'linshi-email', email: 'xxx@iwatermail.com', expiresAt: 1768283576295 }
+
+// tempmail 渠道支持自定义有效期（分钟）
+const emailInfo3 = await generateEmail({ channel: 'tempmail', duration: 60 });
+
+// tempmail-lol 渠道支持指定域名
+const emailInfo4 = await generateEmail({ channel: 'tempmail-lol', domain: 'example.com' });
 ```
 
-### 获取邮件
+#### 获取邮件
 
 ```typescript
-import { getEmails } from 'temp-email-sdk';
+import { getEmails } from 'tempmail-sdk';
 
-// 查询邮件（需要传递渠道和邮箱）
+// 不需要 Token 的渠道
 const result = await getEmails({
   channel: 'tempmail',
-  email: 'xxx@ibymail.com'
+  email: 'xxx@ibymail.com',
 });
-console.log(result);
-// { channel: 'tempmail', email: 'xxx@ibymail.com', emails: [...], success: true }
+console.log(result.emails); // 标准化邮件数组
 
-// tempmail-lol 渠道需要传递 token
+// 需要 Token 的渠道（token 由 generateEmail 返回）
 const result2 = await getEmails({
-  channel: 'tempmail-lol',
-  email: 'xxx@chessgameland.com',
-  token: 'your-token-here'
+  channel: 'mail-tm',
+  email: emailInfo.email,
+  token: emailInfo.token,    // Bearer Token
 });
-```
-
-### 使用 TempEmailClient 类
-
-```typescript
-import { TempEmailClient } from 'temp-email-sdk';
-
-const client = new TempEmailClient();
-
-// 获取邮箱
-const emailInfo = await client.generate({ channel: 'tempmail' });
-console.log(`渠道: ${emailInfo.channel}`);
-console.log(`邮箱: ${emailInfo.email}`);
 
-// 获取邮件
-const result = await client.getEmails();
-console.log(`收到 ${result.emails.length} 封邮件`);
+// 所有邮件使用统一格式，无需关心渠道差异
+for (const email of result2.emails) {
+  console.log(email.id);          // 邮件 ID
+  console.log(email.from);        // 发件人
+  console.log(email.to);          // 收件人
+  console.log(email.subject);     // 主题
+  console.log(email.text);        // 纯文本
+  console.log(email.html);        // HTML
+  console.log(email.date);        // ISO 日期
+  console.log(email.isRead);      // 是否已读
+  console.log(email.attachments); // 附件列表
+}
 ```
 
-## API
+## API 参考
 
 ### listChannels()
 
 获取所有支持的渠道列表。
 
 **返回值:** `ChannelInfo[]`
-- `channel` - 渠道标识
-- `name` - 渠道名称
-- `website` - 服务商网站
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `channel` | `Channel` | 渠道标识 |
+| `name` | `string` | 渠道显示名称 |
+| `website` | `string` | 服务商网站 |
 
 ### getChannelInfo(channel)
 
 获取指定渠道信息。
 
-**参数:**
-- `channel` - 渠道标识
-
 **返回值:** `ChannelInfo | undefined`
 
 ### generateEmail(options?)
@@ -123,31 +159,85 @@ console.log(`收到 ${result.emails.length} 封邮件`);
 生成临时邮箱地址。
 
 **参数:**
-- `channel` - 指定渠道（可选，不指定则随机选择）
-- `duration` - 邮箱有效期，单位分钟（仅 `tempmail` 渠道支持）
-- `domain` - 指定域名（仅 `tempmail-lol` 渠道支持）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `channel` | `Channel` | 指定渠道（可选，不指定则随机） |
+| `duration` | `number` | 有效期分钟数（仅 `tempmail` 渠道） |
+| `domain` | `string` | 指定域名（仅 `tempmail-lol` 渠道） |
 
 **返回值:** `EmailInfo`
-- `channel` - 渠道名称
-- `email` - 邮箱地址
-- `token` - 访问收件箱的令牌（仅 `tempmail-lol` 渠道返回）
-- `expiresAt` - 过期时间
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `channel` | `Channel` | 渠道标识 |
+| `email` | `string` | 邮箱地址 |
+| `token` | `string?` | 访问令牌（部分渠道返回） |
+| `expiresAt` | `string \| number?` | 过期时间 |
+| `createdAt` | `string?` | 创建时间 |
 
 ### getEmails(options)
 
-获取指定邮箱的邮件列表。
+获取邮件列表。
 
-**参数（必填）:**
-- `channel` - 渠道名称
-- `email` - 邮箱地址
-- `token` - 令牌（`tempmail-lol` 渠道必填）
+**参数:**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `channel` | `Channel` | ✅ | 渠道标识 |
+| `email` | `string` | ✅ | 邮箱地址 |
+| `token` | `string` | 部分 | 访问令牌（`tempmail-lol`、`awamail`、`mail-tm`、`dropmail` 必填） |
 
 **返回值:** `GetEmailsResult`
-- `channel` - 渠道名称
-- `email` - 邮箱地址
-- `emails` - 邮件数组
-- `success` - 是否成功
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `channel` | `Channel` | 渠道标识 |
+| `email` | `string` | 邮箱地址 |
+| `emails` | `Email[]` | 标准化邮件数组 |
+| `success` | `boolean` | 是否成功 |
+
+### 标准化邮件格式
+
+所有渠道返回的邮件均使用统一的 `Email` 格式：
+
+```typescript
+interface Email {
+  id: string;                      // 邮件唯一标识
+  from: string;                    // 发件人邮箱地址
+  to: string;                      // 收件人邮箱地址
+  subject: string;                 // 邮件主题
+  text: string;                    // 纯文本内容
+  html: string;                    // HTML 内容
+  date: string;                    // ISO 8601 格式日期
+  isRead: boolean;                 // 是否已读
+  attachments: EmailAttachment[];  // 附件列表
+}
+
+interface EmailAttachment {
+  filename: string;      // 文件名
+  size?: number;         // 文件大小（字节）
+  contentType?: string;  // MIME 类型
+  url?: string;          // 下载地址
+}
+```
+
+### TempEmailClient 类
+
+封装了 Token 自动管理的便捷客户端：
+
+```typescript
+const client = new TempEmailClient();
+await client.generate(options?);     // 生成邮箱
+await client.getEmails();            // 获取邮件（自动传递 token）
+client.getEmailInfo();               // 获取当前邮箱信息
+```
 
 ## 环境要求
 
-- Node.js 18+（需要原生 fetch 支持）
+- Node.js 18+（需要原生 `fetch` 支持）
+- TypeScript 5.0+（类型定义）
+
+## 许可证
+
+GPL-3.0

package/demo/poll-emails.ts

@@ -6,7 +6,7 @@
  */
 
 import * as readline from 'readline';
-import { generateEmail, getEmails, listChannels, getChannelInfo, Channel, EmailInfo, ChannelInfo } from '../src';
+import { generateEmail, getEmails, listChannels, getChannelInfo, Channel, EmailInfo, ChannelInfo, Email } from '../src';
 
 // 配置
 const POLL_INTERVAL = 5000;           // 轮询间隔（毫秒）
@@ -51,6 +51,29 @@ async function selectChannel(channels: ChannelInfo[]): Promise<Channel> {
   }
 }
 
+function printEmail(email: Email, index: number): void {
+  console.log(`\n邮件 #${index + 1}`);
+  console.log('━'.repeat(50));
+  console.log(`ID: ${email.id || '无'}`);
+  console.log(`发件人: ${email.from || '未知'}`);
+  console.log(`收件人: ${email.to || '未知'}`);
+  console.log(`主题: ${email.subject || '无主题'}`);
+  console.log(`时间: ${email.date || '未知'}`);
+  console.log(`已读: ${email.isRead ? '是' : '否'}`);
+  if (email.text) {
+    const preview = email.text.substring(0, 200);
+    console.log(`内容: ${preview}`);
+  }
+  if (email.html) {
+    const htmlPreview = email.html.replace(/<[^>]*>/g, '').substring(0, 100);
+    console.log(`HTML: ${htmlPreview}...`);
+  }
+  if (email.attachments.length > 0) {
+    console.log(`附件: ${email.attachments.map(a => a.filename).join(', ')}`);
+  }
+  console.log('━'.repeat(50));
+}
+
 async function pollEmails(emailInfo: EmailInfo): Promise<void> {
   console.log(`\n开始轮询邮件...（每 ${POLL_INTERVAL / 1000} 秒检查一次）`);
   console.log('按 Ctrl+C 停止轮询\n');
@@ -76,45 +99,7 @@ async function pollEmails(emailInfo: EmailInfo): Promise<void> {
         printJson('返回数据 (GetEmailsResult)', result);
 
         for (let i = 0; i < result.emails.length; i++) {
-          const email = result.emails[i];
-          console.log(`\n邮件 #${i + 1}`);
-          console.log('━'.repeat(50));
-          console.log(`ID: ${email.id || email.eid || email._id || '无'}`);
-          const fromAddr = email.from_address || email.address_from || email.from || '未知';
-          const fromName = email.from_name || email.name_from || '';
-          const fromDisplay = fromName ? `${fromName} <${fromAddr}>` : fromAddr;
-          console.log(`发件人: ${fromDisplay}`);
-          console.log(`收件人: ${email.to || email.name_to || email.email_address || result.email}`);
-          console.log(`主题: ${email.subject || email.e_subject || '无主题'}`);
-          let emailDate: string = '未知';
-          if (email.received_at) {
-            emailDate = email.received_at;
-          } else if (email.created_at) {
-            emailDate = email.created_at;
-          } else if (email.createdAt) {
-            emailDate = email.createdAt;
-          } else if (email.timestamp) {
-            emailDate = new Date(email.timestamp * 1000).toISOString();
-          } else if (email.e_date) {
-            emailDate = new Date(email.e_date).toISOString();
-          } else if (typeof email.date === 'number') {
-            emailDate = new Date(email.date).toISOString();
-          } else if (email.date) {
-            emailDate = email.date;
-          }
-          console.log(`时间: ${emailDate}`);
-          console.log(`已读: ${email.is_read ? '是' : '否'}`);
-          const body = email.text || email.body || email.content || '';
-          if (body) {
-            const preview = body.replace(/<[^>]*>/g, '').substring(0, 200);
-            console.log(`内容: ${preview}`);
-          }
-          const htmlContent = email.html_content || email.html || '';
-          if (htmlContent) {
-            const htmlPreview = htmlContent.replace(/<[^>]*>/g, '').substring(0, 100);
-            console.log(`HTML: ${htmlPreview}...`);
-          }
-          console.log('━'.repeat(50));
+          printEmail(result.emails[i], i);
         }
         
         // 收到邮件后可以选择继续轮询或退出

package/dist/index.d.ts

@@ -1,24 +1,118 @@
 import { Channel, EmailInfo, GetEmailsResult, GenerateEmailOptions, GetEmailsOptions } from './types';
-export { Channel, EmailInfo, Email, GetEmailsResult, GenerateEmailOptions, GetEmailsOptions } from './types';
+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';
+/**
+ * 渠道信息，包含渠道标识、显示名称和对应网站
+ */
 export interface ChannelInfo {
+    /** 渠道标识 */
     channel: Channel;
+    /** 渠道显示名称 */
     name: string;
+    /** 对应的临时邮箱服务网站 */
     website: string;
 }
 /**
  * 获取所有支持的渠道列表
+ *
+ * @returns 所有渠道的信息数组
+ *
+ * @example
+ * ```ts
+ * const channels = listChannels();
+ * channels.forEach(ch => console.log(`${ch.name} (${ch.website})`));
+ * ```
  */
 export declare function listChannels(): ChannelInfo[];
 /**
- * 获取指定渠道信息
+ * 获取指定渠道的详细信息
+ *
+ * @param channel - 渠道标识
+ * @returns 渠道信息，不存在时返回 undefined
  */
 export declare function getChannelInfo(channel: Channel): ChannelInfo | undefined;
+/**
+ * 创建临时邮箱
+ *
+ * 错误处理策略：
+ * - 网络错误、超时、服务端 5xx 错误 → 自动重试（默认 2 次，指数退避）
+ * - 4xx 客户端错误、参数错误 → 直接抛出异常
+ *
+ * @param options - 创建选项，可指定渠道、有效时长、域名等
+ * @returns 邮箱信息，包含地址、令牌等
+ * @throws 重试耗尽后仍失败时抛出异常
+ *
+ * @example
+ * ```ts
+ * const emailInfo = await generateEmail({ channel: 'temp-mail-io' });
+ * console.log(emailInfo.email); // 临时邮箱地址
+ * ```
+ */
 export declare function generateEmail(options?: GenerateEmailOptions): Promise<EmailInfo>;
+/**
+ * 获取邮件列表
+ *
+ * 错误处理策略：
+ * - 网络错误、超时、服务端 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 declare function getEmails(options: GetEmailsOptions): Promise<GetEmailsResult>;
+/**
+ * 临时邮箱客户端
+ * 封装了邮箱创建和邮件获取的完整流程，自动管理邮箱信息和认证令牌
+ *
+ * @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 declare class TempEmailClient {
     private emailInfo;
+    /**
+     * 创建临时邮箱并缓存邮箱信息
+     * 后续调用 getEmails() 时自动使用此邮箱的渠道、地址和令牌
+     */
     generate(options?: GenerateEmailOptions): Promise<EmailInfo>;
+    /**
+     * 获取当前邮箱的邮件列表
+     * 必须先调用 generate() 创建邮箱
+     *
+     * @throws 未调用 generate() 时抛出异常
+     */
     getEmails(): Promise<GetEmailsResult>;
+    /**
+     * 获取当前缓存的邮箱信息
+     * 未调用 generate() 时返回 null
+     */
     getEmailInfo(): EmailInfo | null;
 }
 declare const _default: {