@z_06/relay-temp-mail 1.0.0

package/README.md

@@ -0,0 +1,226 @@
+# relay-temp-mail
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+A TypeScript/JavaScript package for managing Firefox Relay email aliases and retrieving temporary emails via a CloudFlare temp email API.
+
+## Features
+
+- **Create Firefox Relay aliases** - Generate new email aliases on demand
+- **List existing aliases** - View all your configured email aliases
+- **Get emails for specific aliases** - Fetch and parse emails sent to specific addresses
+- **Delete aliases** - Clean up unused aliases programmatically
+- **TypeScript support** - Full type definitions for all APIs
+- **ESM + CommonJS support** - Works with both module systems
+
+## Installation
+
+```bash
+npm install @z_06/relay-temp-mail
+# or
+pnpm add @z_06/relay-temp-mail
+# or
+bun add @z_06/relay-temp-mail
+```
+
+## Quick Start
+
+```typescript
+import { RelayClient } from '@z_06/relay-temp-mail';
+
+const client = new RelayClient({
+  csrfToken: 'your-csrf-token',
+  sessionId: 'your-session-id',
+  cfApiUrl: 'https://your-cf-api.com',
+  cfToken: 'your-cf-token',
+});
+
+// Create a new alias
+const alias = await client.createAlias();
+console.log('New alias:', alias.fullAddress);
+
+// List all aliases
+const aliases = await client.listAliases();
+
+// Get emails for a specific alias
+const emails = await client.getEmails(alias.fullAddress, { limit: 10 });
+```
+
+## Configuration
+
+### Firefox Relay Tokens
+
+To get your `csrfToken` and `sessionId`:
+
+1. Login to [relay.firefox.com](https://relay.firefox.com)
+2. Open your browser's developer tools (F12)
+3. Go to the Application/Storage tab
+4. Find Cookies for `relay.firefox.com`
+5. Copy the values for `csrftoken` and `sessionid`
+
+### CF Temp Email
+
+本项目使�?[cloudflare_temp_email](https://github.com/dreamhunter2333/cloudflare_temp_email) 作为临时邮箱后端，你需要先部署该服务才能使用�?
+#### 快速部署步�?
+1. **Fork 仓库**
+   - 访问 [cloudflare_temp_email](https://github.com/dreamhunter2333/cloudflare_temp_email)
+   - 点击右上�?"Fork" 按钮，将仓库复制到你�?GitHub 账户
+
+2. **一键部署到 Cloudflare**
+   - 点击仓库 README 中的 "Deploy to Cloudflare Workers" 按钮
+   - 或参�?[部署文档](https://temp-mail-docs.awsl.uk) 进行手动部署
+
+3. **配置域名和邮件路�?*
+   - �?Cloudflare Dashboard 中添加你的域�?   - 配置 Email Routing（邮件路由）
+   - 创建 catch-all 规则将所有邮件转发到 Worker
+
+4. **获取 API 地址�?Token**
+   - 部署完成后，你的 API 地址格式为：`https://<你的worker名称>.<你的子域>.workers.dev`
+   - 登录前端界面（部署后会有 Pages 地址�?   - 在用户设置或 Admin 后台生成 API Token
+   - �?API 地址�?Token 填入 `RelayClient` 配置
+
+#### 获取 `cfApiUrl` �?`cfToken`
+
+```typescript
+const client = new RelayClient({
+  csrfToken: 'your-csrf-token',
+  sessionId: 'your-session-id',
+  cfApiUrl: 'https://your-worker-name.your-subdomain.workers.dev', // CF Worker API 地址
+  cfToken: 'your-api-token', // �?Admin 后台或用户设置中生成
+});
+```
+
+更多详细配置请参�?[cloudflare_temp_email 官方文档](https://temp-mail-docs.awsl.uk)�?
+## API Documentation
+
+### RelayClient
+
+The main class for interacting with both Firefox Relay and CloudFlare temp email services.
+
+#### Constructor Options
+
+```typescript
+interface RelayConfig {
+  csrfToken: string;    // Firefox Relay CSRF token
+  sessionId: string;    // Firefox Relay session ID
+  cfApiUrl: string;     // CloudFlare temp email API URL
+  cfToken: string;      // CloudFlare API token
+  timeout?: number;     // Request timeout in ms (default: 30000)
+}
+```
+
+#### Methods
+
+##### `listAliases()`
+
+Lists all Firefox Relay email aliases.
+
+```typescript
+const aliases = await client.listAliases();
+// Returns: RelayAlias[]
+```
+
+##### `createAlias()`
+
+Creates a new random Firefox Relay email alias.
+
+```typescript
+const alias = await client.createAlias();
+// Returns: RelayAlias
+console.log(alias.fullAddress); // e.g., "random123@mozmail.com"
+```
+
+##### `deleteAlias(id)`
+
+Deletes an alias by its ID.
+
+```typescript
+await client.deleteAlias(12345);
+```
+
+##### `getEmails(aliasAddress?, options?)`
+
+Retrieves and parses emails from the CloudFlare temp email API. If `aliasAddress` is provided, only emails sent to that address are returned.
+
+```typescript
+// Get all emails (up to default limit)
+const allEmails = await client.getEmails();
+
+// Get emails for a specific alias
+const emails = await client.getEmails('alias@mozmail.com', { limit: 10 });
+
+// With pagination
+const page2 = await client.getEmails('alias@mozmail.com', { limit: 10, offset: 10 });
+```
+
+Options:
+
+- `limit` - Maximum number of emails to return (default: 20)
+- `offset` - Offset for pagination, 0-indexed (default: 0)
+
+## Error Handling
+
+The package exports several error classes for handling different failure scenarios:
+
+```typescript
+import {
+  RelayTempMailError,
+  NetworkError,
+  AuthError,
+  NotFoundError,
+  ParseError,
+  RateLimitError,
+} from '@z_06/relay-temp-mail';
+
+try {
+  const alias = await client.createAlias();
+} catch (error) {
+  if (error instanceof AuthError) {
+    console.error('Authentication failed:', error.message);
+  } else if (error instanceof NetworkError) {
+    console.error('Network problem:', error.message);
+  } else if (error instanceof RateLimitError) {
+    console.error('Rate limited. Retry after:', error.response?.retryAfter);
+  } else if (error instanceof RelayTempMailError) {
+    console.error('Relay error:', error.code, error.message);
+  }
+}
+```
+
+### Error Classes
+
+| Class | Description | Status Code |
+|-------|-------------|-------------|
+| `RelayTempMailError` | Base error class for all package errors | - |
+| `NetworkError` | Network connectivity issues | - |
+| `AuthError` | Authentication or authorization failures | 401/403 |
+| `NotFoundError` | Requested resource not found | 404 |
+| `ParseError` | Email MIME parsing failures | - |
+| `RateLimitError` | API rate limit exceeded | 429 |
+
+All error classes extend `RelayTempMailError` and provide:
+
+- `code` - Machine-readable error code
+- `statusCode` - HTTP status code (if applicable)
+- `response` - Raw response data from the API (if available)
+
+## TypeScript
+
+All types are fully exported for use in your TypeScript projects:
+
+```typescript
+import type {
+  RelayConfig,
+  RelayAlias,
+  Email,
+  ParsedEmail,
+  ListAliasesOptions,
+  GetEmailsOptions,
+} from '@z_06/relay-temp-mail';
+```
+
+The package is built with strict TypeScript settings and provides comprehensive type definitions for all APIs.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,195 @@
+# relay-temp-mail
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+一个用于管�?Firefox Relay 邮箱别名和通过 Cloudflare 临时邮箱 API 接收邮件�?TypeScript/JavaScript 包�?
+## 功能特�?
+- **创建 Firefox Relay 别名** - 按需生成新的邮箱别名
+- **列出已有别名** - 查看所有已配置的邮箱别�?- **获取指定别名的邮�?* - 获取并解析发送到特定地址的邮�?- **删除别名** - 以编程方式清理未使用的别�?- **TypeScript 支持** - 所�?API 都有完整的类型定�?- **支持 ESM + CommonJS** - 兼容两种模块系统
+
+## 安装
+
+```bash
+npm install @z_06/relay-temp-mail
+# �?pnpm add @z_06/relay-temp-mail
+# �?bun add @z_06/relay-temp-mail
+```
+
+## 快速开�?
+```typescript
+import { RelayClient } from '@z_06/relay-temp-mail';
+
+const client = new RelayClient({
+  csrfToken: 'your-csrf-token',
+  sessionId: 'your-session-id',
+  cfApiUrl: 'https://your-cf-api.com',
+  cfToken: 'your-cf-token',
+});
+
+// 创建新别�?const alias = await client.createAlias();
+console.log('新别�?', alias.fullAddress);
+
+// 列出所有别�?const aliases = await client.listAliases();
+
+// 获取指定别名的邮�?const emails = await client.getEmails(alias.fullAddress, { limit: 10 });
+```
+
+## 配置
+
+### Firefox Relay Token
+
+获取 `csrfToken` �?`sessionId` 的方法：
+
+1. 登录 [relay.firefox.com](https://relay.firefox.com)
+2. 打开浏览器开发者工�?(F12)
+3. 切换�?Application/Storage 标签�?4. 找到 `relay.firefox.com` �?Cookies
+5. 复制 `csrftoken` �?`sessionid` 的�?
+### CF 临时邮箱
+
+本项目使�?[cloudflare_temp_email](https://github.com/dreamhunter2333/cloudflare_temp_email) 作为临时邮箱后端，你需要先部署该服务才能使用�?
+#### 快速部署步�?
+1. **Fork 仓库**
+   - 访问 [cloudflare_temp_email](https://github.com/dreamhunter2333/cloudflare_temp_email)
+   - 点击右上�?"Fork" 按钮，将仓库复制到你�?GitHub 账户
+
+2. **一键部署到 Cloudflare**
+   - 点击仓库 README 中的 "Deploy to Cloudflare Workers" 按钮
+   - 或参�?[部署文档](https://temp-mail-docs.awsl.uk) 进行手动部署
+
+3. **配置域名和邮件路�?*
+   - �?Cloudflare Dashboard 中添加你的域�?   - 配置 Email Routing（邮件路由）
+   - 创建 catch-all 规则将所有邮件转发到 Worker
+
+4. **获取 API 地址�?Token**
+   - 部署完成后，你的 API 地址格式为：`https://<你的worker名称>.<你的子域>.workers.dev`
+   - 登录前端界面（部署后会有 Pages 地址�?   - 在用户设置或 Admin 后台生成 API Token
+   - �?API 地址�?Token 填入 `RelayClient` 配置
+
+#### 获取 `cfApiUrl` �?`cfToken`
+
+```typescript
+const client = new RelayClient({
+  csrfToken: 'your-csrf-token',
+  sessionId: 'your-session-id',
+  cfApiUrl: 'https://your-worker-name.your-subdomain.workers.dev', // CF Worker API 地址
+  cfToken: 'your-api-token', // �?Admin 后台或用户设置中生成
+});
+```
+
+更多详细配置请参�?[cloudflare_temp_email 官方文档](https://temp-mail-docs.awsl.uk)�?
+## API 文档
+
+### RelayClient
+
+用于�?Firefox Relay �?Cloudflare 临时邮箱服务交互的主类�?
+#### 构造函数选项
+
+```typescript
+interface RelayConfig {
+  csrfToken: string;    // Firefox Relay CSRF token
+  sessionId: string;    // Firefox Relay session ID
+  cfApiUrl: string;     // Cloudflare 临时邮箱 API 地址
+  cfToken: string;      // Cloudflare API token
+  timeout?: number;     // 请求超时时间，毫秒（默认: 30000�?}
+```
+
+#### 方法
+
+##### `listAliases()`
+
+列出所�?Firefox Relay 邮箱别名�?
+```typescript
+const aliases = await client.listAliases();
+// 返回: RelayAlias[]
+```
+
+##### `createAlias()`
+
+创建一个新的随�?Firefox Relay 邮箱别名�?
+```typescript
+const alias = await client.createAlias();
+// 返回: RelayAlias
+console.log(alias.fullAddress); // 例如: "random123@mozmail.com"
+```
+
+##### `deleteAlias(id)`
+
+根据 ID 删除别名�?
+```typescript
+await client.deleteAlias(12345);
+```
+
+##### `getEmails(aliasAddress?, options?)`
+
+�?Cloudflare 临时邮箱 API 检索和解析邮件。如果提供了 `aliasAddress`，则只返回发送到该地址的邮件�?
+```typescript
+// 获取所有邮件（默认数量限制�?const allEmails = await client.getEmails();
+
+// 获取指定别名的邮�?const emails = await client.getEmails('alias@mozmail.com', { limit: 10 });
+
+// 分页获取
+const page2 = await client.getEmails('alias@mozmail.com', { limit: 10, offset: 10 });
+```
+
+选项�?
+- `limit` - 返回的最大邮件数量（默认: 20�?- `offset` - 分页偏移量，�?0 开始（默认: 0�?
+## 错误处理
+
+本包导出了多个错误类，用于处理不同的失败场景�?
+```typescript
+import {
+  RelayTempMailError,
+  NetworkError,
+  AuthError,
+  NotFoundError,
+  ParseError,
+  RateLimitError,
+} from '@z_06/relay-temp-mail';
+
+try {
+  const alias = await client.createAlias();
+} catch (error) {
+  if (error instanceof AuthError) {
+    console.error('认证失败:', error.message);
+  } else if (error instanceof NetworkError) {
+    console.error('网络问题:', error.message);
+  } else if (error instanceof RateLimitError) {
+    console.error('请求过于频繁，请稍后重试:', error.response?.retryAfter);
+  } else if (error instanceof RelayTempMailError) {
+    console.error('Relay 错误:', error.code, error.message);
+  }
+}
+```
+
+### 错误�?
+| 类名 | 描述 | 状态码 |
+|------|------|--------|
+| `RelayTempMailError` | 所有包错误的基�?| - |
+| `NetworkError` | 网络连接问题 | - |
+| `AuthError` | 认证或授权失�?| 401/403 |
+| `NotFoundError` | 请求的资源不存在 | 404 |
+| `ParseError` | 邮件 MIME 解析失败 | - |
+| `RateLimitError` | API 请求频率限制 exceeded | 429 |
+
+所有错误类都继承自 `RelayTempMailError`，并提供以下属性：
+
+- `code` - 机器可读的错误代�?- `statusCode` - HTTP 状态码（如适用�?- `response` - API 返回的原始响应数据（如可用）
+
+## TypeScript
+
+所有类型都已导出，可在 TypeScript 项目中使用：
+
+```typescript
+import type {
+  RelayConfig,
+  RelayAlias,
+  Email,
+  ParsedEmail,
+  ListAliasesOptions,
+  GetEmailsOptions,
+} from 'relay-temp-mail';
+```
+
+本包使用严格�?TypeScript 设置构建，为所�?API 提供全面的类型定义�?
+## 许可�?
+MIT