docs: comprehensive API documentation from source code

Replace existing docs with fresh documentation built entirely from source code analysis. OpenAPI 3.1 spec as source of truth, plus human-readable Markdown with curl examples, response samples, and workflow guides. - OpenAPI 3.1 spec covering all 42 endpoints (validated against source) - 7 endpoint reference docs (auth, games, sessions, picker, stats, votes, webhooks) - WebSocket protocol documentation (auth, subscriptions, 4 event types) - 4 guide documents (getting started, session lifecycle, voting, webhooks) - API README with overview, auth docs, and quick reference table - Old docs archived to docs/archive/ Made-with: Cursor
2026-03-15 16:44:53 -04:00
parent 505c335d20
commit 8ba32e128c
25 changed files with 6546 additions and 0 deletions
--- a/docs/api/endpoints/webhooks.md
+++ b/docs/api/endpoints/webhooks.md
@@ -0,0 +1,382 @@
+# Webhooks Endpoints
+
+HTTP callback endpoints for external integrations. Register webhook URLs to receive notifications about events like game additions. All endpoints require authentication.
+
+## Endpoint Summary
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/api/webhooks` | Bearer | List all webhooks |
+| GET | `/api/webhooks/{id}` | Bearer | Get single webhook |
+| POST | `/api/webhooks` | Bearer | Create webhook |
+| PATCH | `/api/webhooks/{id}` | Bearer | Update webhook |
+| DELETE | `/api/webhooks/{id}` | Bearer | Delete webhook |
+| POST | `/api/webhooks/test/{id}` | Bearer | Send test event |
+| GET | `/api/webhooks/{id}/logs` | Bearer | Get webhook delivery logs |
+
+---
+
+## GET /api/webhooks
+
+List all registered webhooks. `secret` is not included in responses. `events` is returned as a parsed array. `enabled` is returned as a boolean.
+
+### Authentication
+
+Bearer token required.
+
+### Response
+
+**200 OK**
+
+```json
+[
+  {
+    "id": 1,
+    "name": "Discord Bot",
+    "url": "https://example.com/webhook",
+    "events": ["game.added"],
+    "enabled": true,
+    "created_at": "2024-01-15T12:00:00.000Z"
+  }
+]
+```
+
+Note: `secret` is never returned.
+
+### Error Responses
+
+| Status | Body | When |
+|--------|------|------|
+| 401 | `{ "error": "Access token required" }` | No Bearer token |
+| 403 | `{ "error": "Invalid or expired token" }` | Bad or expired token |
+| 500 | `{ "error": "..." }` | Server error |
+
+### Example
+
+```bash
+curl "http://localhost:5000/api/webhooks" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## GET /api/webhooks/{id}
+
+Get a single webhook by ID.
+
+### Authentication
+
+Bearer token required.
+
+### Path Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| id | integer | Webhook ID |
+
+### Response
+
+**200 OK**
+
+```json
+{
+  "id": 1,
+  "name": "Discord Bot",
+  "url": "https://example.com/webhook",
+  "events": ["game.added"],
+  "enabled": true,
+  "created_at": "2024-01-15T12:00:00.000Z"
+}
+```
+
+### Error Responses
+
+| Status | Body | When |
+|--------|------|------|
+| 404 | `{ "error": "Webhook not found" }` | Invalid ID |
+
+### Example
+
+```bash
+curl "http://localhost:5000/api/webhooks/1" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## POST /api/webhooks
+
+Create a new webhook.
+
+### Authentication
+
+Bearer token required.
+
+### Request Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | Display name for the webhook |
+| url | string | Yes | Callback URL (must be valid) |
+| secret | string | Yes | Secret for signing payloads |
+| events | array | Yes | Event types to subscribe to (e.g., `["game.added"]`) |
+
+```json
+{
+  "name": "Discord Bot",
+  "url": "https://example.com/webhook",
+  "secret": "mysecret123",
+  "events": ["game.added"]
+}
+```
+
+### Response
+
+**201 Created**
+
+```json
+{
+  "id": 5,
+  "name": "Discord Bot",
+  "url": "https://example.com/webhook",
+  "events": ["game.added"],
+  "enabled": true,
+  "created_at": "2024-01-15T12:00:00.000Z",
+  "message": "Webhook created successfully"
+}
+```
+
+### Error Responses
+
+| Status | Body | When |
+|--------|------|------|
+| 400 | `{ "error": "Missing required fields: name, url, secret, events" }` | Missing fields |
+| 400 | `{ "error": "events must be an array" }` | `events` is not an array |
+| 400 | `{ "error": "Invalid URL format" }` | URL validation failed |
+
+### Example
+
+```bash
+curl -X POST "http://localhost:5000/api/webhooks" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Discord Bot",
+    "url": "https://example.com/webhook",
+    "secret": "mysecret123",
+    "events": ["game.added"]
+  }'
+```
+
+---
+
+## PATCH /api/webhooks/{id}
+
+Update an existing webhook. At least one field must be provided.
+
+### Authentication
+
+Bearer token required.
+
+### Path Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| id | integer | Webhook ID |
+
+### Request Body
+
+All fields optional. Include only the fields to update.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | No | Display name |
+| url | string | No | Callback URL (must be valid) |
+| secret | string | No | New secret |
+| events | array | No | Event types (must be array) |
+| enabled | boolean | No | Enable or disable the webhook |
+
+```json
+{
+  "name": "Discord Bot Updated",
+  "url": "https://example.com/webhook-v2",
+  "enabled": true
+}
+```
+
+### Response
+
+**200 OK**
+
+```json
+{
+  "id": 5,
+  "name": "Discord Bot Updated",
+  "url": "https://example.com/webhook-v2",
+  "events": ["game.added"],
+  "enabled": true,
+  "created_at": "2024-01-15T12:00:00.000Z",
+  "message": "Webhook updated successfully"
+}
+```
+
+### Error Responses
+
+| Status | Body | When |
+|--------|------|------|
+| 400 | `{ "error": "No fields to update" }` | No fields in body |
+| 400 | `{ "error": "Invalid URL format" }` | Invalid URL |
+| 400 | `{ "error": "events must be an array" }` | `events` not an array |
+| 404 | `{ "error": "Webhook not found" }` | Invalid ID |
+
+### Example
+
+```bash
+curl -X PATCH "http://localhost:5000/api/webhooks/5" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Discord Bot Updated", "enabled": true}'
+```
+
+---
+
+## DELETE /api/webhooks/{id}
+
+Delete a webhook. Cascades to `webhook_logs` (logs are deleted).
+
+### Authentication
+
+Bearer token required.
+
+### Path Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| id | integer | Webhook ID |
+
+### Response
+
+**200 OK**
+
+```json
+{
+  "message": "Webhook deleted successfully",
+  "webhookId": 5
+}
+```
+
+### Error Responses
+
+| Status | Body | When |
+|--------|------|------|
+| 404 | `{ "error": "Webhook not found" }` | Invalid ID |
+
+### Example
+
+```bash
+curl -X DELETE "http://localhost:5000/api/webhooks/5" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## POST /api/webhooks/test/{id}
+
+Send a test `game.added` event with dummy data to the webhook URL. Delivery runs asynchronously; check `webhook_logs` for status.
+
+### Authentication
+
+Bearer token required.
+
+### Path Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| id | integer | Webhook ID |
+
+### Response
+
+**200 OK**
+
+```json
+{
+  "message": "Test webhook sent",
+  "note": "Check webhook_logs table for delivery status"
+}
+```
+
+### Error Responses
+
+| Status | Body | When |
+|--------|------|------|
+| 404 | `{ "error": "Webhook not found" }` | Invalid ID |
+
+### Example
+
+```bash
+curl -X POST "http://localhost:5000/api/webhooks/test/5" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## GET /api/webhooks/{id}/logs
+
+Get delivery logs for a webhook. Payload is parsed from JSON string to object.
+
+### Authentication
+
+Bearer token required.
+
+### Path Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| id | integer | Webhook ID |
+
+### Query Parameters
+
+| Name | In | Type | Required | Description |
+|------|-----|------|----------|-------------|
+| limit | query | integer | No | Max number of logs (default: 50) |
+
+### Response
+
+**200 OK**
+
+```json
+[
+  {
+    "id": 1,
+    "webhook_id": 5,
+    "event_type": "game.added",
+    "payload": {
+      "session": { "id": 3, "is_active": true, "games_played": 2 },
+      "game": {
+        "id": 42,
+        "title": "Quiplash 3",
+        "pack_name": "Jackbox Party Pack 7",
+        "min_players": 3,
+        "max_players": 8,
+        "manually_added": false
+      }
+    },
+    "response_status": 200,
+    "error_message": null,
+    "created_at": "2024-01-15T12:00:00.000Z"
+  }
+]
+```
+
+### Error Responses
+
+| Status | Body | When |
+|--------|------|------|
+| 500 | `{ "error": "..." }` | Server error |
+
+### Example
+
+```bash
+curl "http://localhost:5000/api/webhooks/5/logs?limit=20" \
+  -H "Authorization: Bearer $TOKEN"
+```