# Aurora API Reference

REST API server for Aurora bot management. Base URL: `http://localhost:3000`

## Health

### `GET /api/health`
Returns server health status.

**Response:** `{ "status": "ok", "timestamp": 1234567890 }`

---

## Items

### `GET /api/items`
List all items with optional filtering.

| Query Param | Type | Description |
|-------------|------|-------------|
| `search` | string | Filter by name/description |
| `type` | string | Filter by item type |
| `rarity` | string | Filter by rarity (C, R, SR, SSR) |
| `limit` | number | Max results (default: 100) |
| `offset` | number | Pagination offset |

**Response:** `{ "items": [...], "total": number }`

### `GET /api/items/:id`
Get single item by ID.

### `POST /api/items`
Create new item. Supports JSON or multipart/form-data with image.

**Body (JSON):**
```json
{
  "name": "Health Potion",
  "description": "Restores HP",
  "type": "CONSUMABLE",
  "rarity": "C",
  "price": "100",
  "usageData": { "consume": true, "effects": [] }
}
```

### `PUT /api/items/:id`
Update existing item.

### `DELETE /api/items/:id`
Delete item and associated asset.

### `POST /api/items/:id/icon`
Upload/replace item image. Accepts multipart/form-data with `image` field.

---

## Quests

### `GET /api/quests`
List all quests.

### `POST /api/quests`
Create new quest.

**Body:**
```json
{
  "name": "Daily Login",
  "description": "Login once",
  "triggerEvent": "login",
  "target": 1,
  "xpReward": 50,
  "balanceReward": 100
}
```

### `PUT /api/quests/:id`
Update quest.

### `DELETE /api/quests/:id`
Delete quest.

---

## Settings

### `GET /api/settings`
Get current bot configuration.

### `POST /api/settings`
Update configuration (partial merge supported).

### `GET /api/settings/meta`
Get Discord metadata (roles, channels, commands).

---

## Admin Actions

### `POST /api/actions/reload-commands`
Reload bot slash commands.

### `POST /api/actions/clear-cache`
Clear internal caches.

### `POST /api/actions/maintenance-mode`
Toggle maintenance mode.

**Body:** `{ "enabled": true, "reason": "Updating..." }`

---

## Stats

### `GET /api/stats`
Get full dashboard statistics.

### `GET /api/stats/activity`
Get activity aggregation (cached 5 min).

---

## Assets

### `GET /assets/items/:filename`
Serve item images. Cached 24 hours.

---

## WebSocket

### `ws://localhost:3000/ws`
Real-time dashboard updates.

**Messages:**
- `STATS_UPDATE` - Periodic stats broadcast (every 5s when clients connected)
- `NEW_EVENT` - Real-time system events
- `PING/PONG` - Heartbeat

**Limits:** Max 10 concurrent connections, 16KB max payload, 60s idle timeout.