feat: 添加邮件服务器客户端库的基础功能

- 新增完整的Go客户端库实现，支持邮件服务器API的各种操作 - 实现账户管理、签名管理、邮件发送、审计、配额、通道等功能模块 - 提供ServiceAuth和AppAuth两种认证模式的客户端 - 添加详细的README文档，包含安装指南和使用示例 - 配置.gitignore文件以忽略构建产物和开发工具配置 - 支持分页查询、错误处理和客户端选项配置
2026-04-18 10:36:45 +08:00
commit 5b4774e9c1
16 changed files with 1251 additions and 0 deletions
@@ -0,0 +1,200 @@
+# email-serverr-cli
+
+Go client library for the Email Server API.
+
+## Install
+
+```bash
+go get gitea.s1f.ren/shiran/email-serverr-cli
+```
+
+## Quick Start
+
+### Management Client (ServiceAuth)
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    emailcli "gitea.s1f.ren/shiran/email-serverr-cli"
+)
+
+func main() {
+    client := emailcli.NewServiceClient(
+        "https://your-server.com",
+        "your-service-token",
+    )
+
+    // List accounts
+    accounts, err := client.ListAccounts(context.Background(), emailcli.AccountListQuery{
+        PaginationQuery: emailcli.PaginationQuery{Page: 1, PageSize: 20},
+    })
+    if err != nil {
+        panic(err)
+    }
+    for _, a := range accounts.List {
+        fmt.Printf("Account: %s (ID: %d)\n", a.Name, a.ID)
+    }
+}
+```
+
+### Mail Sending Client (AppAuth)
+
+```go
+client := emailcli.NewAppClient(
+    "https://your-server.com",
+    "your-app-key",
+    "your-app-secret",
+)
+
+resp, err := client.SendMail(context.Background(), emailcli.SendMailReq{
+    To:      []string{"recipient@example.com"},
+    Subject: "Hello",
+    Body:    "<h1>Hello World</h1>",
+    Channel: "default",
+})
+if err != nil {
+    panic(err)
+}
+fmt.Printf("Mail sent: log_id=%d status=%s\n", resp.MailLogID, resp.Status)
+```
+
+## Authentication
+
+| Mode | Constructor | Header | Use Case |
+|------|-------------|--------|----------|
+| ServiceAuth | `NewServiceClient` | `Authorization: Bearer <token>` | Management APIs |
+| AppAuth | `NewAppClient` | `X-App-Key` + `X-App-Secret` | Mail sending |
+
+## API Reference
+
+### Mail (AppAuth)
+
+| Method | Description |
+|--------|-------------|
+| `SendMail` | Send an email |
+
+### Accounts (ServiceAuth)
+
+| Method | Description |
+|--------|-------------|
+| `CreateAccount` | Create mail account |
+| `ListAccounts` | List accounts with filters |
+| `GetAccount` | Get account details |
+| `UpdateAccount` | Update account |
+| `DeleteAccount` | Delete account |
+| `ResetAccountSecret` | Reset app secret |
+
+### Signatures (ServiceAuth)
+
+| Method | Description |
+|--------|-------------|
+| `CreateSignature` | Create signature |
+| `ListSignatures` | List signatures with filters |
+| `GetSignature` | Get signature details |
+| `UpdateSignature` | Update signature |
+| `DeleteSignature` | Delete signature |
+| `AuditSignature` | Approve or reject signature |
+
+### Mail Logs (ServiceAuth)
+
+| Method | Description |
+|--------|-------------|
+| `ListMailLogs` | List mail logs with filters |
+| `GetMailLog` | Get mail log detail with body |
+| `GetMailStats` | Get status statistics |
+
+### Quotas (ServiceAuth)
+
+| Method | Description |
+|--------|-------------|
+| `CreateQuota` | Create quota |
+| `ListQuotas` | List quotas with filters |
+| `GetQuotaSummary` | Get quota summary for account |
+| `UpdateQuota` | Update quota |
+| `DeleteQuota` | Delete quota |
+
+### Channels (ServiceAuth)
+
+| Method | Description |
+|--------|-------------|
+| `CreateChannel` | Create channel |
+| `ListChannels` | List channels with filters |
+| `UpdateChannel` | Update channel |
+| `DeleteChannel` | Delete channel |
+
+### Sender Accounts (ServiceAuth)
+
+| Method | Description |
+|--------|-------------|
+| `CreateSender` | Create sender under channel |
+| `ListSendersByChannel` | List senders for channel |
+| `UpdateSender` | Update sender |
+| `DeleteSender` | Delete sender |
+
+### Audits (ServiceAuth)
+
+| Method | Description |
+|--------|-------------|
+| `ListAuditPending` | List pending audit items |
+| `GetAuditPendingDetail` | Get pending item detail |
+| `ApproveAudit` | Approve single item |
+| `RejectAudit` | Reject single item |
+| `BatchApproveAudit` | Batch approve |
+| `BatchRejectAudit` | Batch reject |
+| `ListAuditLogs` | List audit history |
+| `GetAuditStats` | Get audit statistics |
+
+### Audit Rules (ServiceAuth)
+
+| Method | Description |
+|--------|-------------|
+| `CreateAuditRule` | Create rule |
+| `ListAuditRules` | List all rules |
+| `GetAuditRule` | Get rule details |
+| `UpdateAuditRule` | Update rule |
+| `DeleteAuditRule` | Delete rule |
+| `UpdateAuditRuleStatus` | Toggle rule status |
+| `TestAuditRule` | Test rules against sample |
+
+### Queue (ServiceAuth)
+
+| Method | Description |
+|--------|-------------|
+| `GetQueueStatus` | Get queue lengths |
+| `ListQueuePending` | List pending queue items |
+| `CancelQueueItem` | Cancel queued mail |
+| `RetryQueueItem` | Retry failed mail |
+
+### Health Checks (ServiceAuth)
+
+| Method | Description |
+|--------|-------------|
+| `ListCheckLogs` | List check logs |
+| `GetCheckSummary` | Get sender health summary |
+| `TriggerCheck` | Trigger health check |
+
+## Error Handling
+
+```go
+resp, err := client.SendMail(ctx, req)
+if err != nil {
+    var apiErr *emailcli.APIError
+    if errors.As(err, &apiErr) {
+        fmt.Printf("API error: code=%d message=%s\n", apiErr.Code, apiErr.Message)
+    }
+}
+```
+
+## Options
+
+```go
+client := emailcli.NewServiceClient(
+    "https://your-server.com",
+    "token",
+    emailcli.WithTimeout(60 * time.Second),
+    emailcli.WithHTTPClient(customClient),
+)
+```