Add REFERENCE.md

2026-07-08 13:37:36 -05:00
1 parent e59b28b377
commit f82d0340be
@@ -0,0 +1,337 @@
+# TACHYON API Reference
+
+Base URL (local dev): `http://localhost:3000`
+Base URL (once deployed behind the tunnel, e.g.): `https://api.radium.wtf`
+
+All request/response bodies are JSON. `POST`/`PUT` requests must send
+`Content-Type: application/json`.
+
+---
+
+## Health
+
+### `GET /api/health`
+
+Liveness check — confirms the API process is up and responding.
+
+**Response `200`**
+```json
+{ "ok": true }
+```
+
+**Example**
+```bash
+curl http://localhost:3000/api/health
+```
+
+---
+
+## News
+
+Backed by the `news_posts` table. Powers the **News** panel.
+
+### `GET /api/news`
+
+List news posts, newest first.
+
+**Query params**
+
+| Param   | Type   | Default | Notes                          |
+|---------|--------|---------|---------------------------------|
+| `limit` | number | `20`    | Capped at `100`                 |
+
+**Response `200`**
+```json
+[
+  {
+    "id": 3,
+    "title": "Placeholder announcement title",
+    "content": "Short placeholder line describing an update or change.",
+    "created_at": "2026-07-06T12:00:00.000Z"
+  }
+]
+```
+
+**Example**
+```bash
+curl "http://localhost:3000/api/news?limit=5"
+```
+
+---
+
+### `POST /api/news`
+
+Create a news post.
+
+**Body**
+
+| Field     | Type   | Required |
+|-----------|--------|----------|
+| `title`   | string | yes      |
+| `content` | string | yes      |
+
+**Response `201`** — the created row (with generated `id` and `created_at`)
+```json
+{
+  "id": 4,
+  "title": "New post title",
+  "content": "New post body text.",
+  "created_at": "2026-07-08T18:30:00.000Z"
+}
+```
+
+**Response `400`** — missing fields
+```json
+{ "error": "title and content are required" }
+```
+
+**Example**
+```bash
+curl -X POST http://localhost:3000/api/news \
+  -H "Content-Type: application/json" \
+  -d '{"title": "New post title", "content": "New post body text."}'
+```
+
+---
+
+### `DELETE /api/news/:id`
+
+Delete a news post by id.
+
+**Response `204`** — no body, success.
+**Response `404`**
+```json
+{ "error": "not found" }
+```
+
+**Example**
+```bash
+curl -X DELETE http://localhost:3000/api/news/4
+```
+
+---
+
+## Media
+
+Backed by the `media_items` table. Powers the **Media** grid.
+
+### `GET /api/media`
+
+List media items, newest first.
+
+**Query params**
+
+| Param   | Type   | Default | Notes                          |
+|---------|--------|---------|---------------------------------|
+| `limit` | number | `24`    | Capped at `100`                 |
+
+**Response `200`**
+```json
+[
+  {
+    "id": 1,
+    "title": "placeholder clip one",
+    "media_type": "image",
+    "url": "https://example.com/media/1.png",
+    "created_at": "2026-07-08T17:59:31.129Z"
+  }
+]
+```
+
+**Example**
+```bash
+curl "http://localhost:3000/api/media?limit=12"
+```
+
+---
+
+### `POST /api/media`
+
+Add a media item.
+
+**Body**
+
+| Field        | Type   | Required | Notes                          |
+|--------------|--------|----------|----------------------------------|
+| `title`      | string | yes      |                                  |
+| `media_type` | string | yes      | must be `"image"` or `"video"`  |
+| `url`        | string | yes      |                                  |
+
+**Response `201`** — the created row
+```json
+{
+  "id": 5,
+  "title": "new clip",
+  "media_type": "video",
+  "url": "https://example.com/media/5.mp4",
+  "created_at": "2026-07-08T18:35:00.000Z"
+}
+```
+
+**Response `400`**
+```json
+{ "error": "title, url, and media_type (image|video) are required" }
+```
+
+**Example**
+```bash
+curl -X POST http://localhost:3000/api/media \
+  -H "Content-Type: application/json" \
+  -d '{"title": "new clip", "media_type": "video", "url": "https://example.com/media/5.mp4"}'
+```
+
+---
+
+### `DELETE /api/media/:id`
+
+Delete a media item by id.
+
+**Response `204`** — no body, success.
+**Response `404`**
+```json
+{ "error": "not found" }
+```
+
+**Example**
+```bash
+curl -X DELETE http://localhost:3000/api/media/5
+```
+
+---
+
+## Stats
+
+Backed by `users`, `sessions`, `activity_log`, and `site_stats`. Powers the
+**Overview** panel (Current Users / Recent Activity / General Statistics
+columns).
+
+### `GET /api/stats/overview`
+
+The main endpoint for this panel — returns all three columns in a single
+call so the frontend doesn't need three round trips.
+
+**Response `200`**
+```json
+{
+  "currentUsers": [
+    { "id": 1, "username": "placeholder_user_01", "started_at": "2026-07-08T18:00:00.000Z" }
+  ],
+  "recentActivity": [
+    { "id": 1, "description": "placeholder event one", "created_at": "2026-07-08T17:00:00.000Z" }
+  ],
+  "general": {
+    "users": {
+      "total": 3,
+      "mostRecent": { "username": "placeholder_user_03", "id": 3 }
+    },
+    "reports": { "named": "00", "associated": "00", "logged": "00" },
+    "build": { "pipeline": "Completed", "buildNumber": "00000000", "version": "0.0.0" }
+  }
+}
+```
+
+- `currentUsers` — users with an open session (`sessions.ended_at IS NULL`), most recently started first.
+- `recentActivity` — latest rows from `activity_log`.
+- `general.users.total` — total row count in `users` (not just online users).
+- `general.reports` / `general.build` — pulled from the `site_stats` key/value table; update these directly in the DB or add an admin endpoint if you want them editable via API.
+
+**Example**
+```bash
+curl http://localhost:3000/api/stats/overview
+```
+
+---
+
+### `GET /api/stats/users`
+
+Just the current-users list, if you want it without the rest of the
+overview payload (e.g. a lighter-weight poll for a live "online now" count).
+
+**Response `200`**
+```json
+[
+  { "id": 1, "username": "placeholder_user_01", "started_at": "2026-07-08T18:00:00.000Z" }
+]
+```
+
+**Example**
+```bash
+curl http://localhost:3000/api/stats/users
+```
+
+---
+
+### `POST /api/stats/session/start`
+
+Marks a user as online by opening a session. Creates the user row if the
+username doesn't exist yet.
+
+**Body**
+
+| Field      | Type   | Required |
+|------------|--------|----------|
+| `username` | string | yes      |
+
+**Response `201`**
+```json
+{ "sessionId": 7, "userId": 3 }
+```
+
+**Response `400`**
+```json
+{ "error": "username is required" }
+```
+
+**Example**
+```bash
+curl -X POST http://localhost:3000/api/stats/session/start \
+  -H "Content-Type: application/json" \
+  -d '{"username": "placeholder_user_04"}'
+```
+
+> Save the returned `sessionId` — you'll need it to end the session later.
+
+---
+
+### `POST /api/stats/session/end`
+
+Marks a session as ended (user no longer counted as "current").
+
+**Body**
+
+| Field       | Type   | Required |
+|-------------|--------|----------|
+| `sessionId` | number | yes      |
+
+**Response `204`** — no body, success.
+**Response `400`**
+```json
+{ "error": "sessionId is required" }
+```
+**Response `404`** — id doesn't exist or was already ended
+```json
+{ "error": "no active session with that id" }
+```
+
+**Example**
+```bash
+curl -X POST http://localhost:3000/api/stats/session/end \
+  -H "Content-Type: application/json" \
+  -d '{"sessionId": 7}'
+```
+
+---
+
+## Error format
+
+All error responses follow the same shape:
+
+```json
+{ "error": "human-readable message" }
+```
+
+There's no auth layer on any of this yet — every endpoint above is open.
+Add something (API key header, session cookie, whatever fits your setup)
+before exposing the write endpoints (`POST`/`DELETE`) publicly, since right
+now anyone who can reach the API can create/delete news and media or spoof
+"current users."