# moon-resend 项目申报书

## 基本信息

- 项目名称：moon-resend：面向 Resend 邮件平台的 MoonBit SDK
- 参赛者：**[请填写参赛者姓名或昵称]**
- 联系方式：**[请填写手机号、邮箱或赛事要求的联系方式]**
- GitHub 仓库链接：[https://github.com/hua1104/moon-resend.git](https://github.com/hua1104/moon-resend.git)
- 项目方向：MoonBit SaaS 基础 SDK / 事务邮件基础设施
- 是否为移植项目：否

## 项目简介

moon-resend 是一个面向 Resend 邮件平台的类型化 MoonBit SDK，为使用 MoonBit 构建 Web 应用、SaaS 服务、后台任务和自动化工具的开发者提供可复用的事务邮件能力。项目针对 MoonBit 生态中缺少成熟邮件平台 SDK 的现状，将邮件参数建模、输入校验、JSON 编码、鉴权、幂等请求、错误解析和邮件生命周期操作封装成稳定的 MoonBit API，并通过基于 moonfetch 的独立 HTTP adapter 完成真实 HTTPS 请求。

项目当前聚焦于“小而完整”的事务邮件闭环，而不是一次性追求 Resend 全部接口数量。开发者可以通过统一接口完成单封或批量发送、查询邮件与投递状态、修改定时发送时间以及取消发送；测试代码不依赖真实 API Key，也不会在 CI 中产生外部发信副作用。项目同时提供真实发信示例、架构说明、阶段规划和比赛演示材料，便于实际接入与复现验收。

## 核心功能范围

- 提供 Client、SendEmailParams、Attachment、RetrievedEmail、EmailId 等类型化 MoonBit 数据模型；
- 支持 Resend 单封邮件发送，覆盖 HTML、纯文本、CC、BCC、reply-to、附件、标签和定时发送；
- 支持最多 100 封邮件的批量发送，并提供批量邮件 ID 响应解析；
- 支持 Idempotency-Key，降低应用重试导致重复发信的风险；
- 支持查询已发送邮件及投递状态、修改定时邮件发送时间和取消定时邮件；
- 提供发件人、收件人、主题、正文、附件、邮件 ID 和批量数量等输入校验；
- 提供类型化成功响应、Resend API 错误、异常成功响应和非 JSON 错误解析；
- 提供 transport-neutral HttpRequest / HttpResponse 核心，使 API 语义与具体 HTTP 运行时解耦；
- 提供基于 moonbitstack/moonfetch 的真实 HTTPS adapter，覆盖 send、send_batch、retrieve、update、cancel 和底层 execute；
- 将 DNS、TCP、TLS、URL 和超时等传输失败统一映射为 ResendError::Transport；
- adapter 默认禁止 HTTP 重定向，避免 Bearer Token 被转发到非预期来源；
- 提供通过 RESEND_API_KEY、RESEND_FROM、RESEND_TO 环境变量运行的真实发信示例，不在源码中保存敏感信息；
- 提供 12 个 MoonBit 测试，覆盖请求构造、输入校验、JSON 字段、成功响应、API 错误、异常响应和 adapter 错误映射；
- 提供 GitHub Actions 持续集成，覆盖 MoonBit 检查、Wasm/Native 测试、Native 示例构建和格式校验；
- 提供中英文项目说明、架构图、功能覆盖矩阵、90 秒演示流程和分月开发路线。

## 移植或参考说明

- 是否为移植项目：否
- 参考平台：Resend Email API
- API 文档链接：[https://resend.com/docs/api-reference/emails](https://resend.com/docs/api-reference/emails)
- HTTP adapter 依赖：moonfetch
- moonfetch 项目链接：[https://github.com/moonbitstack/moonfetch](https://github.com/moonbitstack/moonfetch)
- moonfetch 许可证：Apache License 2.0
- 本项目许可证：Apache License 2.0

本项目不是对某个现有 Resend SDK 的逐行翻译或语言移植，而是依据 Resend 官方公开 API 契约，使用 MoonBit 的类型系统、包结构、异步能力和测试方式独立设计并实现。项目与官方 JavaScript、Python、Java 等 SDK 在功能目标上保持一致，但没有复制这些 SDK 的代码结构或实现细节。

与直接手写 HTTP 请求或照搬其他语言 SDK 相比，本项目做了以下 MoonBit 化设计：

- 将 Resend API 语义与 HTTP 传输实现分离，核心包可以独立完成确定性的请求构造、校验和响应解析；
- 使用 MoonBit 类型表达发送参数、附件、邮件状态、批量结果及分层错误，减少字符串拼装和运行时判断；
- 将真实网络实现放入独立 adapter 子包，既提供开箱即用的 moonfetch 集成，也为未来接入其他 MoonBit HTTP 运行时保留边界；
- 对输入错误、API 业务错误、异常响应和传输错误进行明确分类，方便调用方采取不同的重试、告警和用户提示策略；
- CI 和常规测试不依赖 Resend 账号与密钥，真实发信示例由操作者显式提供环境变量后运行，兼顾可复现性与密钥安全；
- 当前版本主动控制范围，优先完成事务邮件闭环；Webhook 验签计划在 12 月实现，Domains 与 Contacts 计划在 1 月实现，Inbound、Inboxes、Audiences 和 Templates 等能力根据真实使用需求继续扩展。

## 申报前需要参赛者补充的内容

- 将“参赛者”和“联系方式”替换为真实信息；
- 如报名表要求，补充个人简介、所在学校或单位；
- 完成一次使用本人 Resend 账号和已验证发件域名的真实发信验收；
- 补充演示视频、演示 GIF 或实际收件截图链接；
- 根据赛事表单字数限制摘取对应段落，不要提交 API Key、完整密钥截图或其他敏感信息。