# Aurora API

Aurora's API is a Bun server that runs inside the same process as the Discord bot. It serves REST routes, the authenticated WebSocket endpoint, static assets, and built panel files.

## Runtime model

- Entry point: `api/src/server.ts`
- Route dispatcher: `api/src/routes/index.ts`
- Auth: Discord OAuth with signed session cookies
- WebSocket: `/ws`
- Static assets: `/assets/*`
- Built panel fallback: `panel/dist`

## Access model

Public:

- `GET /api/health`
- `/auth/discord`
- `/auth/callback`
- `POST /auth/logout`
- `GET /auth/me`

Player-accessible API routes:

- `GET /api/stats`
- `GET /api/health`
- `GET /api/me`
- `GET /api/me/inventory`

Admin-only API routes:

- everything else under `/api/*`

Admin vs player is derived from `ADMIN_USER_IDS`. A user must already exist in the `users` table to complete panel login.

## Route summary

### Auth

- `GET /auth/discord`
- `GET /auth/callback`
- `POST /auth/logout`
- `GET /auth/me`

### Dashboard and system

- `GET /api/health`
- `GET /api/stats`
- `GET /api/stats/activity`
- `POST /api/actions/reload-commands`
- `POST /api/actions/clear-cache`
- `POST /api/actions/maintenance-mode`

### Settings

- `GET /api/settings`
- `POST /api/settings`
- `GET /api/settings/meta`
- `GET /api/guilds/:guildId/settings`
- `PUT|PATCH /api/guilds/:guildId/settings`
- `DELETE /api/guilds/:guildId/settings`

### Users, classes, and inventory

- `GET /api/me`
- `GET /api/me/inventory`
- `GET /api/users`
- `GET /api/users/:id`
- `PUT /api/users/:id`
- `GET /api/users/:id/inventory`
- `POST /api/users/:id/inventory`
- `DELETE /api/users/:id/inventory/:itemId`
- `GET /api/classes`
- `POST /api/classes`
- `PUT /api/classes/:id`
- `DELETE /api/classes/:id`

### Game content

- `GET /api/items`
- `POST /api/items`
- `GET /api/items/:id`
- `PUT /api/items/:id`
- `DELETE /api/items/:id`
- `POST /api/items/:id/icon`
- `GET /api/quests`
- `POST /api/quests`
- `PUT /api/quests/:id`
- `DELETE /api/quests/:id`
- `GET /api/lootdrops`
- `POST /api/lootdrops`
- `DELETE /api/lootdrops/:messageId`

### Moderation and economy history

- `GET /api/moderation`
- `POST /api/moderation`
- `GET /api/transactions`

## WebSocket

`/ws` requires a valid `aurora_session` cookie.

Current behavior:

- dashboard clients subscribe to `dashboard`
- game clients also use lobby and room-scoped traffic through `GameServer`
- `PING` from the client returns `PONG`
- dashboard stats are broadcast every 5 seconds while at least one client is connected
- hard limits in `api/src/server.ts`:
  - 200 concurrent connections
  - 16 KB max payload
  - 60 second idle timeout

## Development

Start the backend:

```bash
bun run dev
```

Optional panel dev server:

```bash
bun run panel:dev
```

Panel dev runs on `http://localhost:5173` and proxies API/auth/assets/WebSocket requests to `http://localhost:3000`.