ReCloudStudio/WebHooker
1
0
Fork 0
mirror of https://github.com/ReCloudStudio/WebHooker.git synced 2026-09-22 16:11:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: document admin groups, OAuth redirect, and API renames

Browse source
This commit is contained in:
RhenCloud 2026-08-03 00:33:18 +08:00
parent 8c8cfbf211
commit 8c9720b1b3
No known key found for this signature in database
GPG key ID: A574A617378C4E0B
10 changed files with 324 additions and 142 deletions
Download patch file Download diff file Expand all files Collapse all files

28
docs/api/actions.md
View file

@ -57,16 +57,16 @@ Merges a pull request.
"owner": "org",
"repo": "repo",
"pullNumber": 42,
"mergeMethod": "squash"
"method": "squash"
}
```
| Field | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------- |
| `owner` | string | Yes | Repository owner |
| `repo` | string | Yes | Repository name |
| `pullNumber` | number | Yes | Pull request number |
| `mergeMethod` | string | No | `merge`, `squash`, or `rebase` (default: `merge`) |
| Field | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------------------------- |
| `owner` | string | Yes | Repository owner |
| `repo` | string | Yes | Repository name |
| `pullNumber` | number | Yes | Pull request number |
| `method` | string | No | `merge`, `squash`, or `rebase` (default: `squash`) |
**Response:** `200` with GitHub merge response.
@ -88,11 +88,11 @@ Closes a pull request without merging.
}
```
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ----------------------- |
| `owner` | string | Yes | Repository owner |
| `repo` | string | Yes | Repository name |
| `pullNumber` | number | Yes | Pull request number |
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ------------------- |
| `owner` | string | Yes | Repository owner |
| `repo` | string | Yes | Repository name |
| `pullNumber` | number | Yes | Pull request number |
**Response:** `200` with GitHub update response.
@ -111,7 +111,7 @@ Adds an emoji reaction to an issue or comment.
"owner": "org",
"repo": "repo",
"issueNumber": 42,
"content": "rocket"
"reaction": "rocket"
}
```
@ -120,7 +120,7 @@ Adds an emoji reaction to an issue or comment.
| `owner` | string | Yes | Repository owner |
| `repo` | string | Yes | Repository name |
| `issueNumber` | number | Yes | Issue, PR, or comment number |
| `content` | string | Yes | Reaction type (see below) |
| `reaction` | string | Yes | Reaction type (see below) |
**Reaction Types:**

18
docs/api/oauth.md
View file

@ -21,9 +21,9 @@ Redirects the user to GitHub's authorization page.
**Query Parameters:**
| Parameter | Description |
| --------- | ---------------------------------- |
| `userId` | Your application's user identifier |
| Parameter | Description |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `redirect` | Optional relative path to return to after sign-in (e.g. `/admin`). Must start with `/` but not `//`; any unsafe value falls back to `/`. |
**Response:** `302` redirect to GitHub OAuth authorize URL.
@ -42,7 +42,11 @@ GitHub redirects here after authorization. Exchanges the code for an access toke
| `code` | Authorization code |
| `state` | State parameter for CSRF protection |
**Response:** Redirects to your `BASE_URL` with a success/error indicator.
**Response:**
- **Browser flow** (`Accept: text/html`): sets an admin session cookie, then redirects to the `redirect` target. Users without admin access are redirected to `/admin?error=forbidden`.
- **JSON flow**: returns `{ "userId": "...", "login": "...", "redirectTo": "..." }`.
- **Discord link flow** (started with a pending `discordUserId`): links the Discord user to this GitHub account, returning `{ "ok": true, "discordUserId": "...", "login": "..." }` — or a success page in the browser.
### Revoke Token
@ -66,12 +70,14 @@ Tokens are stored in KV with key pattern `token:{userId}`:
```json
{
"userId": "12345",
"accessToken": "gho_...",
"expiresAt": "2025-01-01T00:00:00.000Z"
"expiresAt": 1735689600000,
"refreshToken": "..."
}
```
Tokens are automatically expired based on the `expiresAt` timestamp.
`expiresAt` is a Unix timestamp in milliseconds. KV entries expire at 90% of the token's lifetime (minimum 60 seconds). A reverse index `token-reverse:{sha256 of token}` maps the access token back to its user id so Bearer-authenticated endpoints can resolve the caller. Discord users linked to a GitHub account are stored under `discord-link:{discordUserId}`.
## Using Tokens

38
docs/api/overview.md
View file

@ -10,28 +10,34 @@ https://your-worker.workers.dev
## Endpoints
| Method | Path | Auth | Description |
| -------- | ----------------------- | -------------- | ------------------------ |
| `GET` | `/health` | None | Health check |
| `POST` | `/webhook` | HMAC signature | GitHub webhook ingestion |
| `GET` | `/auth/github` | None | Start GitHub OAuth flow |
| `GET` | `/auth/github/callback` | None | OAuth callback |
| `DELETE` | `/auth/token/:userId` | None | Revoke user token |
| `POST` | `/api/comment` | Bearer token | Create issue comment |
| `POST` | `/api/merge` | Bearer token | Merge pull request |
| `POST` | `/api/close` | Bearer token | Close pull request |
| `POST` | `/api/react` | Bearer token | Add reaction to issue |
| `GET` | `/admin` | Admin session | Config console UI |
| `GET` | `/admin/api/routes` | Admin session | List routes |
| `PUT` | `/admin/api/routes` | Admin session | Replace routes |
| Method | Path | Auth | Description |
| -------- | ------------------------------ | -------------- | ------------------------ |
| `GET` | `/health` | None | Health check |
| `POST` | `/webhook` | HMAC signature | GitHub webhook ingestion |
| `GET` | `/auth/github` | None | Start GitHub OAuth flow |
| `GET` | `/auth/github/callback` | None | OAuth callback |
| `DELETE` | `/auth/token/:userId` | None | Revoke user token |
| `POST` | `/api/comment` | Bearer token | Create issue comment |
| `POST` | `/api/merge` | Bearer token | Merge pull request |
| `POST` | `/api/close` | Bearer token | Close pull request |
| `POST` | `/api/react` | Bearer token | Add reaction to issue |
| `GET` | `/admin` | Admin session | Config console UI |
| `GET` | `/admin/api/routes` | Admin session | List routes |
| `PUT` | `/admin/api/routes` | Admin session | Replace routes |
| `GET` | `/admin/api/groups` | Admin session | List groups (scoped) |
| `PUT` | `/admin/api/groups` | Admin session | Replace groups (super) |
| `GET` | `/admin/api/groups/:id/routes` | Admin session | List a group's routes |
| `PUT` | `/admin/api/groups/:id/routes` | Admin session | Replace a group's routes |
| `GET` | `/admin/api/me` | Admin session | Current session info |
| `GET` | `/admin/api/logs` | Admin session | Send logs (scoped) |
## Admin Console
See [Configuration → Web UI](../guide/configuration.md#web-ui) for setup. Admin endpoints require a session cookie obtained via `GET /admin/login` (GitHub OAuth); the signed-in user must be listed in `ADMIN_USER_IDS`.
See [Configuration → Web UI](../guide/configuration.md#web-ui) for setup. Admin endpoints require a session cookie obtained via `GET /admin/login` (GitHub OAuth); the signed-in user must be listed in `ADMIN_USER_IDS` or manage a group.
- `GET /admin` — Serves the config console HTML
- `GET /admin/api/routes` — Returns `{ "routes": Route[] }`
- `PUT /admin/api/routes` — Body `{ "routes": Route[] }`; validates each route (id pattern, unique id, name, enabled, ≥1 valid filter, string `target.channelId`) and persists to KV `config:routes`. Returns `200 { ok, count }` or `400 { error }` / `401 { error }`.
- `PUT /admin/api/routes` — Body `{ "routes": Route[] }`; validates each route (id pattern, unique id, name, enabled, `groupId`, filters — empty only allowed for `fallback` routes — and string `target.channelId`) and persists to KV `config:routes`. Returns `200 { ok, count }` or `400 { error }` / `401 { error }`.
## Health Check