initial commit

docs/zh/api/actions.md

@@ -0,0 +1,111 @@
+# 用户操作
+
+用户操作端点支持评论议题、合并 PR 和添加反应。所有操作端点都需要来自 OAuth 流程的有效 Bearer Token。
+
+## 鉴权
+
+所有操作端点都需要 `Authorization` 头：
+
+```
+Authorization: Bearer <github-access-token>
+```
+
+如果 Token 缺失或无效，端点返回 `401`。
+
+## 端点
+
+### 评论议题
+
+```
+POST /api/comment
+```
+
+在议题或拉取请求上创建评论。
+
+**请求体：**
+
+```json
+{
+  "owner": "org",
+  "repo": "repo",
+  "issueNumber": 42,
+  "body": "评论内容"
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+| --- | --- | --- | --- |
+| `owner` | string | 是 | 仓库所有者 |
+| `repo` | string | 是 | 仓库名称 |
+| `issueNumber` | number | 是 | 议题或 PR 编号 |
+| `body` | string | 是 | 评论内容（支持 Markdown） |
+
+**响应：** `200` 与 GitHub API 响应。
+
+### 合并拉取请求
+
+```
+POST /api/merge
+```
+
+合并拉取请求。
+
+**请求体：**
+
+```json
+{
+  "owner": "org",
+  "repo": "repo",
+  "pullNumber": 42,
+  "mergeMethod": "squash"
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+| --- | --- | --- | --- |
+| `owner` | string | 是 | 仓库所有者 |
+| `repo` | string | 是 | 仓库名称 |
+| `pullNumber` | number | 是 | 拉取请求编号 |
+| `mergeMethod` | string | 否 | `merge`、`squash` 或 `rebase`（默认：`merge`） |
+
+**响应：** `200` 与 GitHub 合并响应。
+
+### 添加反应
+
+```
+POST /api/react
+```
+
+为议题或评论添加表情反应。
+
+**请求体：**
+
+```json
+{
+  "owner": "org",
+  "repo": "repo",
+  "issueNumber": 42,
+  "content": "rocket"
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+| --- | --- | --- | --- |
+| `owner` | string | 是 | 仓库所有者 |
+| `repo` | string | 是 | 仓库名称 |
+| `issueNumber` | number | 是 | 议题、PR 或评论编号 |
+| `content` | string | 是 | 反应类型（见下方） |
+
+**反应类型：**
+
+`+1`、`-1`、`laugh`、`confused`、`heart`、`hooray`、`rocket`、`eyes`
+
+**响应：** `200` 与 GitHub 反应响应。
+
+## 错误响应
+
+| 状态码 | 响应体 | 原因 |
+| --- | --- | --- |
+| `401` | `{"error": "Unauthorized"}` | 缺少或无效的 Bearer Token |
+| `400` | `{"error": "..."}` | 无效的请求体 |
+| `500` | `{"error": "..."}` | GitHub API 错误 |

docs/zh/api/oauth.md

@@ -0,0 +1,85 @@
+# OAuth
+
+WebHooker 实现 GitHub OAuth2 以支持用户发起的操作（评论、合并、反应）。
+
+## 流程
+
+```text
+用户 → GET /auth/github → 重定向到 GitHub → 授权 →
+  → GET /auth/github/callback → 交换 code 获取 Token → 存储到 KV
+```
+
+## 端点
+
+### 启动 OAuth
+
+```
+GET /auth/github
+```
+
+将用户重定向到 GitHub 的授权页面。
+
+**查询参数：**
+
+| 参数 | 说明 |
+| --- | --- |
+| `userId` | 你的应用用户标识符 |
+
+**响应：** `302` 重定向到 GitHub OAuth 授权 URL。
+
+### OAuth 回调
+
+```
+GET /auth/github/callback
+```
+
+GitHub 授权后重定向到此地址。将 code 交换为访问令牌并存储到 KV。
+
+**查询参数（来自 GitHub）：**
+
+| 参数 | 说明 |
+| --- | --- |
+| `code` | 授权码 |
+| `state` | CSRF 保护的状态参数 |
+
+**响应：** 重定向到你的 `BASE_URL`，附带成功/失败指示。
+
+### 撤销 Token
+
+```
+DELETE /auth/token/:userId
+```
+
+删除用户存储的 OAuth Token。
+
+**响应：**
+
+```json
+{
+  "ok": true
+}
+```
+
+## Token 存储
+
+Token 以键模式 `token:{userId}` 存储在 KV 中：
+
+```json
+{
+  "accessToken": "gho_...",
+  "expiresAt": "2025-01-01T00:00:00.000Z"
+}
+```
+
+Token 会根据 `expiresAt` 时间戳自动过期。
+
+## 使用 Token
+
+OAuth 完成后，在操作 API 调用的 `Authorization` 头中包含访问令牌：
+
+```bash
+curl -X POST https://your-worker/api/comment \
+  -H "Authorization: Bearer gho_..." \
+  -H "Content-Type: application/json" \
+  -d '{"owner": "org", "repo": "repo", "issueNumber": 1, "body": "你好！"}'
+```

docs/zh/api/overview.md

@@ -0,0 +1,80 @@
+# API 概览
+
+WebHooker 通过 Hono 在 Cloudflare Workers 上提供 HTTP API。
+
+## 基础 URL
+
+```
+https://your-worker.workers.dev
+```
+
+## 端点
+
+| 方法 | 路径 | 鉴权 | 说明 |
+| --- | --- | --- | --- |
+| `GET` | `/health` | 无 | 健康检查 |
+| `POST` | `/webhook` | HMAC 签名 | GitHub webhook 接入 |
+| `GET` | `/auth/github` | 无 | 启动 GitHub OAuth 流程 |
+| `GET` | `/auth/github/callback` | 无 | OAuth 回调 |
+| `DELETE` | `/auth/token/:userId` | 无 | 撤销用户 Token |
+| `POST` | `/api/comment` | Bearer Token | 创建议题评论 |
+| `POST` | `/api/merge` | Bearer Token | 合并拉取请求 |
+| `POST` | `/api/react` | Bearer Token | 添加议题反应 |
+
+## 健康检查
+
+```
+GET /health
+```
+
+**响应：**
+
+```json
+{
+  "status": "ok"
+}
+```
+
+## Webhook 接入
+
+```
+POST /webhook
+```
+
+接受 GitHub webhook 载荷。需要有效的 `X-Hub-Signature-256` 头部。
+
+**请求头：**
+
+| 头部 | 必需 | 说明 |
+| --- | --- | --- |
+| `X-Hub-Signature-256` | 是 | HMAC-SHA256 签名 |
+| `X-GitHub-Event` | 是 | 事件类型名称 |
+| `X-GitHub-Delivery` | 是 | 唯一投递 ID |
+
+**请求体：** GitHub webhook JSON 载荷（最大 1MB）。
+
+**响应：**
+
+```json
+{
+  "ok": true
+}
+```
+
+**错误响应：**
+
+| 状态码 | 响应体 | 原因 |
+| --- | --- | --- |
+| `401` | `{"error": "Invalid signature"}` | 签名验证失败 |
+| `400` | `{"error": "Invalid event"}` | 缺少事件头或格式错误的请求体 |
+| `413` | `{"error": "Request too large"}` | 请求体超过 1MB 限制 |
+
+## 错误格式
+
+所有错误响应都遵循以下格式：
+
+```json
+{
+  "error": "错误的说明"
+}
+```