syntaxbullet/aurorabot
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
878e3306eb01901f27db2271930fe20a4b5b08a1
aurorabot/docs/api.md

9.3 KiB
Raw Blame History

Aurora API Reference

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

Common Response Formats

Success Responses:

  • Single resource: { ...resource } or { success: true, resource: {...} }
  • List operations: { items: [...], total: number }
  • Mutations: { success: true, resource: {...} }

Error Responses:

{
  "error": "Brief error message",
  "details": "Optional detailed error information"
}

HTTP Status Codes:

Code Description
200 Success
201 Created
204 No Content (successful DELETE)
400 Bad Request (validation error)
404 Not Found
409 Conflict (e.g., duplicate name)
429 Too Many Requests
500 Internal Server Error

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.

Response:

{
  "id": 1,
  "name": "Health Potion",
  "description": "Restores HP",
  "type": "CONSUMABLE",
  "rarity": "C",
  "price": "100",
  "iconUrl": "/assets/items/1.png",
  "imageUrl": "/assets/items/1.png",
  "usageData": { "consume": true, "effects": [] }
}

POST /api/items

Create new item. Supports JSON or multipart/form-data with image.

Body (JSON):

{
  "name": "Health Potion",
  "description": "Restores HP",
  "type": "CONSUMABLE",
  "rarity": "C",
  "price": "100",
  "iconUrl": "/assets/items/placeholder.png",
  "imageUrl": "/assets/items/placeholder.png",
  "usageData": { "consume": true, "effects": [] }
}

Body (Multipart):

  • data: JSON string with item fields
  • image: Image file (PNG, JPEG, WebP, GIF, max 15MB)

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.

Users

GET /api/users

List all users with optional filtering and sorting.

Query Param Type Description
search string Filter by username (partial match)
sortBy string Sort field: balance, level, xp, username (default: balance)
sortOrder string Sort order: asc, desc (default: desc)
limit number Max results (default: 50)
offset number Pagination offset

Response: { "users": [...], "total": number }

GET /api/users/:id

Get single user by Discord ID.

Response:

{
  "id": "123456789012345678",
  "username": "Player1",
  "balance": "1000",
  "xp": "500",
  "level": 5,
  "dailyStreak": 3,
  "isActive": true,
  "classId": "1",
  "class": { "id": "1", "name": "Warrior", "balance": "5000" },
  "settings": {},
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T12:00:00Z"
}

PUT /api/users/:id

Update user fields.

Body:

{
  "username": "NewName",
  "balance": "2000",
  "xp": "750",
  "level": 10,
  "dailyStreak": 5,
  "classId": "1",
  "isActive": true,
  "settings": {}
}

GET /api/users/:id/inventory

Get user's inventory with item details.

Response:

{
  "inventory": [
    {
      "userId": "123456789012345678",
      "itemId": 1,
      "quantity": "5",
      "item": { "id": 1, "name": "Health Potion", ... }
    }
  ]
}

POST /api/users/:id/inventory

Add item to user inventory.

Body:

{
  "itemId": 1,
  "quantity": "5"
}

DELETE /api/users/:id/inventory/:itemId

Remove item from user inventory. Use query param amount to specify quantity (default: 1).

Query Param Type Description
amount number Amount to remove (default: 1) 

---

## Classes

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

**Response:**
```json
{
  "classes": [
    { "id": "1", "name": "Warrior", "balance": "5000", "roleId": "123456789" }
  ]
}

POST /api/classes

Create new class.

Body:

{
  "id": "2",
  "name": "Mage",
  "balance": "0",
  "roleId": "987654321"
}

PUT /api/classes/:id

Update class.

Body:

{
  "name": "Updated Name",
  "balance": "10000",
  "roleId": "111222333"
}

DELETE /api/classes/:id

Delete class.

Moderation

GET /api/moderation

List moderation cases with optional filtering.

Query Param Type Description
userId string Filter by target user ID
moderatorId string Filter by moderator ID
type string Filter by case type: warn, timeout, kick, ban, note, prune
active boolean Filter by active status
limit number Max results (default: 50)
offset number Pagination offset

Response:

{
  "cases": [
    {
      "id": "1",
      "caseId": "CASE-0001",
      "type": "warn",
      "userId": "123456789",
      "username": "User1",
      "moderatorId": "987654321",
      "moderatorName": "Mod1",
      "reason": "Spam",
      "metadata": {},
      "active": true,
      "createdAt": "2024-01-15T12:00:00Z",
      "resolvedAt": null,
      "resolvedBy": null,
      "resolvedReason": null
    }
  ]
}

GET /api/moderation/:caseId

Get single case by case ID (e.g., CASE-0001).

POST /api/moderation

Create new moderation case.

Body:

{
  "type": "warn",
  "userId": "123456789",
  "username": "User1",
  "moderatorId": "987654321",
  "moderatorName": "Mod1",
  "reason": "Rule violation",
  "metadata": { "duration": "24h" }
}

PUT /api/moderation/:caseId/clear

Clear/resolve a moderation case.

Body:

{
  "clearedBy": "987654321",
  "clearedByName": "Mod1",
  "reason": "Appeal accepted"
}

Transactions

GET /api/transactions

List economy transactions.

Query Param Type Description
userId string Filter by user ID
type string Filter by transaction type
limit number Max results (default: 50)
offset number Pagination offset

Response:

{
  "transactions": [
    {
      "id": "1",
      "userId": "123456789",
      "relatedUserId": null,
      "amount": "100",
      "type": "DAILY_REWARD",
      "description": "Daily reward (Streak: 3)",
      "createdAt": "2024-01-15T12:00:00Z"
    }
  ]
}

Transaction Types:

  • DAILY_REWARD - Daily claim reward
  • TRANSFER_IN - Received from another user
  • TRANSFER_OUT - Sent to another user
  • LOOTDROP_CLAIM - Claimed lootdrop
  • SHOP_BUY - Item purchase
  • QUEST_REWARD - Quest completion reward

Lootdrops

GET /api/lootdrops

List lootdrops (default limit 50, sorted by newest).

Query Param Type Description
limit number Max results (default: 50)

Response: { "lootdrops": [...] }

POST /api/lootdrops

Spawn a lootdrop in a channel.

Body:

{
  "channelId": "1234567890",
  "amount": 100,
  "currency": "Gold"
}

DELETE /api/lootdrops/:messageId

Cancel and delete a lootdrop.

Quests

GET /api/quests

List all quests.

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Daily Login",
      "description": "Login once",
      "triggerEvent": "login",
      "requirements": { "target": 1 },
      "rewards": { "xp": 50, "balance": 100 }
    }
  ]
}

POST /api/quests

Create new quest.

Body:

{
  "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).

Response:

{
  "roles": [{ "id": "123", "name": "Admin", "color": "#FF0000" }],
  "channels": [{ "id": "456", "name": "general", "type": 0 }],
  "commands": [{ "name": "daily", "category": "economy" }]
}

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.

Reference in New Issue View Git Blame Copy Permalink