forked from syntaxbullet/aurorabot
feat: implement user inventory management and class update endpoints
This commit is contained in:
syntaxbullet
321
docs/api.md
321
docs/api.md
@@ -2,6 +2,35 @@
|
||||
|
||||
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:**
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
@@ -29,6 +58,21 @@ List all items with optional filtering.
|
||||
### `GET /api/items/:id`
|
||||
Get single item by ID.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
@@ -40,10 +84,16 @@ Create new item. Supports JSON or multipart/form-data with image.
|
||||
"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.
|
||||
|
||||
@@ -55,11 +105,273 @@ 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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"inventory": [
|
||||
{
|
||||
"userId": "123456789012345678",
|
||||
"itemId": 1,
|
||||
"quantity": "5",
|
||||
"item": { "id": 1, "name": "Health Potion", ... }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/users/:id/inventory`
|
||||
Add item to user inventory.
|
||||
|
||||
**Body:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"id": "2",
|
||||
"name": "Mage",
|
||||
"balance": "0",
|
||||
"roleId": "987654321"
|
||||
}
|
||||
```
|
||||
|
||||
### `PUT /api/classes/:id`
|
||||
Update class.
|
||||
|
||||
**Body:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
---
|
||||
|
||||
## Quests
|
||||
|
||||
### `GET /api/quests`
|
||||
List all quests.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
@@ -94,6 +406,15 @@ Update configuration (partial merge supported).
|
||||
### `GET /api/settings/meta`
|
||||
Get Discord metadata (roles, channels, commands).
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"roles": [{ "id": "123", "name": "Admin", "color": "#FF0000" }],
|
||||
"channels": [{ "id": "456", "name": "general", "type": 0 }],
|
||||
"commands": [{ "name": "daily", "category": "economy" }]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Admin Actions
|
||||
|
||||
Reference in New Issue
Block a user