aurorabot/api/README.md

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 in-memory 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:

bun run dev

Optional panel dev server:

bun run panel:dev

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