initial commit

docs/api/actions.md

@@ -0,0 +1,111 @@
+# Actions
+
+User action endpoints allow commenting on issues, merging PRs, and adding reactions. All action endpoints require a valid Bearer token from the OAuth flow.
+
+## Authentication
+
+All action endpoints require the `Authorization` header:
+
+```
+Authorization: Bearer <github-access-token>
+```
+
+If the token is missing or invalid, the endpoint returns `401`.
+
+## Endpoints
+
+### Comment on Issue
+
+```
+POST /api/comment
+```
+
+Creates a comment on an issue or pull request.
+
+**Request Body:**
+
+```json
+{
+  "owner": "org",
+  "repo": "repo",
+  "issueNumber": 42,
+  "body": "Comment text here"
+}
+```
+
+| Field         | Type   | Required | Description                       |
+| ------------- | ------ | -------- | --------------------------------- |
+| `owner`       | string | Yes      | Repository owner                  |
+| `repo`        | string | Yes      | Repository name                   |
+| `issueNumber` | number | Yes      | Issue or PR number                |
+| `body`        | string | Yes      | Comment body (Markdown supported) |
+
+**Response:** `200` with GitHub API response.
+
+### Merge Pull Request
+
+```
+POST /api/merge
+```
+
+Merges a pull request.
+
+**Request Body:**
+
+```json
+{
+  "owner": "org",
+  "repo": "repo",
+  "pullNumber": 42,
+  "mergeMethod": "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`) |
+
+**Response:** `200` with GitHub merge response.
+
+### Add Reaction
+
+```
+POST /api/react
+```
+
+Adds an emoji reaction to an issue or comment.
+
+**Request Body:**
+
+```json
+{
+  "owner": "org",
+  "repo": "repo",
+  "issueNumber": 42,
+  "content": "rocket"
+}
+```
+
+| Field         | Type   | Required | Description                  |
+| ------------- | ------ | -------- | ---------------------------- |
+| `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 Types:**
+
+`+1`, `-1`, `laugh`, `confused`, `heart`, `hooray`, `rocket`, `eyes`
+
+**Response:** `200` with GitHub reaction response.
+
+## Error Responses
+
+| Status | Body                        | Cause                           |
+| ------ | --------------------------- | ------------------------------- |
+| `401`  | `{"error": "Unauthorized"}` | Missing or invalid Bearer token |
+| `400`  | `{"error": "..."}`          | Invalid request body            |
+| `500`  | `{"error": "..."}`          | GitHub API error                |

docs/api/oauth.md

@@ -0,0 +1,85 @@
+# OAuth
+
+WebHooker implements GitHub OAuth2 to enable user-initiated actions (comment, merge, react).
+
+## Flow
+
+```text
+User → GET /auth/github → Redirect to GitHub → Authorize →
+  → GET /auth/github/callback → Exchange code for token → Store in KV
+```
+
+## Endpoints
+
+### Start OAuth
+
+```
+GET /auth/github
+```
+
+Redirects the user to GitHub's authorization page.
+
+**Query Parameters:**
+
+| Parameter | Description                        |
+| --------- | ---------------------------------- |
+| `userId`  | Your application's user identifier |
+
+**Response:** `302` redirect to GitHub OAuth authorize URL.
+
+### OAuth Callback
+
+```
+GET /auth/github/callback
+```
+
+GitHub redirects here after authorization. Exchanges the code for an access token and stores it in KV.
+
+**Query Parameters (from GitHub):**
+
+| Parameter | Description                         |
+| --------- | ----------------------------------- |
+| `code`    | Authorization code                  |
+| `state`   | State parameter for CSRF protection |
+
+**Response:** Redirects to your `BASE_URL` with a success/error indicator.
+
+### Revoke Token
+
+```
+DELETE /auth/token/:userId
+```
+
+Removes the stored OAuth token for a user.
+
+**Response:**
+
+```json
+{
+  "ok": true
+}
+```
+
+## Token Storage
+
+Tokens are stored in KV with key pattern `token:{userId}`:
+
+```json
+{
+  "accessToken": "gho_...",
+  "expiresAt": "2025-01-01T00:00:00.000Z"
+}
+```
+
+Tokens are automatically expired based on the `expiresAt` timestamp.
+
+## Using Tokens
+
+After OAuth, include the access token in the `Authorization` header for action API calls:
+
+```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": "Hello!"}'
+```

docs/api/overview.md

@@ -0,0 +1,80 @@
+# API Overview
+
+WebHooker exposes an HTTP API via Hono on Cloudflare Workers.
+
+## Base URL
+
+```
+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/react`            | Bearer token   | Add reaction to issue    |
+
+## Health Check
+
+```
+GET /health
+```
+
+**Response:**
+
+```json
+{
+  "status": "ok"
+}
+```
+
+## Webhook Ingestion
+
+```
+POST /webhook
+```
+
+Accepts GitHub webhook payloads. Requires valid `X-Hub-Signature-256` header.
+
+**Headers:**
+
+| Header                | Required | Description           |
+| --------------------- | -------- | --------------------- |
+| `X-Hub-Signature-256` | Yes      | HMAC-SHA256 signature |
+| `X-GitHub-Event`      | Yes      | Event type name       |
+| `X-GitHub-Delivery`   | Yes      | Unique delivery ID    |
+
+**Request Body:** GitHub webhook JSON payload (max 1MB).
+
+**Response:**
+
+```json
+{
+  "ok": true
+}
+```
+
+**Error Responses:**
+
+| Status | Body                             | Cause                                  |
+| ------ | -------------------------------- | -------------------------------------- |
+| `401`  | `{"error": "Invalid signature"}` | Signature verification failed          |
+| `400`  | `{"error": "Invalid event"}`     | Missing event header or malformed body |
+| `413`  | `{"error": "Request too large"}` | Body exceeds 1MB limit                 |
+
+## Error Format
+
+All error responses follow the format:
+
+```json
+{
+  "error": "Description of the error"
+}
+```