hubmc-datagw/API_ENDPOINTS.md

# HubGW API Endpoints Documentation

Полное описание всех API endpoints в HubGW с телами запросов и ответов.

Базовый URL: `/api/v1`

Все endpoints требуют аутентификации через заголовок `X-API-Key`.

---

## Health

**Префикс:** `/health`

### GET `/health/`

Проверка работоспособности сервиса.

**Ответ:**
```json
{
  "status": "ok"
}
```

---

## Homes

**Префикс:** `/homes`

### PUT `/homes/`

Создает или обновляет дом игрока с проверкой лимита.

**Тело запроса:**
```json
{
  "player_uuid": "string",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": false,
  "max_homes": 5
}
```

**Параметры:**
- `max_homes` (optional) - Максимальное количество домов для игрока. Если указан, проверяется лимит при создании нового дома.

**Ответ:**
```json
{
  "id": "uuid",
  "player_uuid": "string",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": false,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

**Ошибки:**
- `409 Conflict` - Лимит домов превышен (если указан `max_homes`)
  ```json
  {
    "message": "Home limit exceeded. Maximum 5 homes allowed.",
    "code": "limit_exceeded",
    "details": {
      "player_uuid": "string",
      "current_count": 5,
      "max_homes": 5
    }
  }
  ```

### POST `/homes/get`

Получает конкретный дом игрока по имени.

**Тело запроса:**
```json
{
  "player_uuid": "string",
  "name": "string"
}
```

**Ответ:**
```json
{
  "id": "uuid",
  "player_uuid": "string",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": false,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### GET `/homes/{player_uuid}`

Получает список всех домов игрока.

**Параметры:**
- `player_uuid` (path) - UUID игрока

**Ответ:**
```json
{
  "homes": [
    {
      "id": "uuid",
      "player_uuid": "string",
      "name": "string",
      "world": "string",
      "x": 0.0,
      "y": 0.0,
      "z": 0.0,
      "yaw": 0.0,
      "pitch": 0.0,
      "is_public": false,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1
}
```

---

## Kits

**Префикс:** `/kits`

### POST `/kits/claim`

Выдает набор (kit) игроку.

**Тело запроса:**
```json
{
  "player_uuid": "uuid",
  "kit_name": "string"
}
```

**Ответ:**
```json
{
  "success": true,
  "message": "string",
  "cooldown_remaining": 3600
}
```

---

## Cooldowns

**Префикс:** `/cooldowns`

### POST `/cooldowns/check`

Проверяет статус кулдауна для игрока.

**Тело запроса:**
```json
{
  "player_uuid": "string",
  "cooldown_type": "string"
}
```

**Ответ:**
```json
{
  "is_active": true,
  "expires_at": "2024-01-01T00:00:00Z",
  "remaining_seconds": 3600
}
```

### POST `/cooldowns/`

Создает новый кулдаун для игрока.

**Тело запроса:**
```json
{
  "player_uuid": "string",
  "cooldown_type": "string",
  "expires_at": "2024-01-01T00:00:00Z",
  "cooldown_seconds": 3600,
  "data": {}
}
```

**Статус:** `201 Created`

**Ответ:**
```json
{
  "message": "Cooldown created successfully"
}
```

---

## Warps

**Префикс:** `/warps`

Варпы имеют глобально уникальные имена и владельцев. Только владелец может редактировать или удалять свой варп.

### POST `/warps/`

Создает новую точку варпа с проверкой лимита per-player.

**Тело запроса:**
```json
{
  "player_uuid": "string",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": true,
  "description": "string",
  "max_warps": 10
}
```

**Параметры:**
- `player_uuid` (required) - UUID владельца варпа
- `name` (required) - Глобально уникальное имя варпа
- `max_warps` (optional) - Максимальное количество варпов для игрока

**Статус:** `201 Created`

**Ответ:**
```json
{
  "id": "uuid",
  "player_uuid": "string",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": true,
  "description": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

**Ошибки:**
- `409 Conflict` - Варп с таким именем уже существует
  ```json
  {
    "message": "Warp 'spawn' already exists",
    "code": "already_exists",
    "details": {
      "owner_uuid": "другой-uuid"
    }
  }
  ```
- `409 Conflict` - Лимит варпов превышен (если указан `max_warps`)
  ```json
  {
    "message": "Warp limit exceeded. Maximum 10 warps allowed.",
    "code": "limit_exceeded",
    "details": {
      "player_uuid": "string",
      "current_count": 10,
      "max_warps": 10
    }
  }
  ```

### PATCH `/warps/`

Обновляет существующую точку варпа. Только владелец может редактировать варп.

**Тело запроса:**
```json
{
  "player_uuid": "string",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": false,
  "description": "string"
}
```

**Параметры:**
- `player_uuid` (required) - UUID игрока (для проверки ownership)
- `name` (required) - Имя варпа для обновления
- Все остальные поля опциональны

**Ответ:**
```json
{
  "id": "uuid",
  "player_uuid": "string",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": false,
  "description": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

**Ошибки:**
- `403 Forbidden` - Нет прав для редактирования варпа
  ```json
  {
    "message": "You don't have permission to update warp 'spawn'",
    "code": "permission_denied",
    "details": {
      "warp_owner": "uuid-владельца",
      "requested_by": "ваш-uuid"
    }
  }
  ```
- `404 Not Found` - Варп не найден

### DELETE `/warps/`

Удаляет точку варпа. Только владелец может удалить варп.

**Тело запроса:**
```json
{
  "player_uuid": "string",
  "name": "string"
}
```

**Параметры:**
- `player_uuid` (required) - UUID игрока (для проверки ownership)
- `name` (required) - Имя варпа для удаления

**Статус:** `204 No Content`

**Ошибки:**
- `403 Forbidden` - Нет прав для удаления варпа
- `404 Not Found` - Варп не найден

### POST `/warps/get`

Получает конкретную точку варпа по имени. Доступно всем игрокам.

**Тело запроса:**
```json
{
  "name": "string"
}
```

**Ответ:**
```json
{
  "id": "uuid",
  "player_uuid": "string",
  "name": "string",
  "world": "string",
  "x": 0.0,
  "y": 0.0,
  "z": 0.0,
  "yaw": 0.0,
  "pitch": 0.0,
  "is_public": true,
  "description": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### POST `/warps/list`

Получает список точек варпа с возможностью фильтрации.

**Тело запроса:**
```json
{
  "name": "string",
  "world": "string",
  "is_public": true,
  "page": 1,
  "size": 20
}
```

**Ответ:**
```json
{
  "warps": [
    {
      "id": "uuid",
      "player_uuid": "string",
      "name": "string",
      "world": "string",
      "x": 0.0,
      "y": 0.0,
      "z": 0.0,
      "yaw": 0.0,
      "pitch": 0.0,
      "is_public": true,
      "description": "string",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}
```

---

## Whitelist

**Префикс:** `/whitelist`

### POST `/whitelist/add`

Добавляет игрока в белый список.

**Тело запроса:**
```json
{
  "player_name": "string",
  "added_by": "string",
  "added_at": "2024-01-01T00:00:00Z",
  "expires_at": "2024-01-01T00:00:00Z",
  "is_active": true,
  "reason": "string"
}
```

**Статус:** `201 Created`

**Ответ:**
```json
{
  "id": "uuid",
  "player_name": "string",
  "added_by": "string",
  "added_at": "2024-01-01T00:00:00Z",
  "expires_at": "2024-01-01T00:00:00Z",
  "is_active": true,
  "reason": "string"
}
```

### POST `/whitelist/remove`

Удаляет игрока из белого списка.

**Тело запроса:**
```json
{
  "player_name": "string"
}
```

**Статус:** `204 No Content`

### POST `/whitelist/check`

Проверяет, находится ли игрок в белом списке.

**Тело запроса:**
```json
{
  "player_name": "string"
}
```

**Ответ:**
```json
{
  "is_whitelisted": true
}
```

### GET `/whitelist/`

Получает список всех игроков в белом списке.

**Ответ:**
```json
{
  "entries": [
    {
      "id": "uuid",
      "player_name": "string",
      "added_by": "string",
      "added_at": "2024-01-01T00:00:00Z",
      "expires_at": "2024-01-01T00:00:00Z",
      "is_active": true,
      "reason": "string"
    }
  ],
  "total": 1
}
```

### GET `/whitelist/count`

Получает общее количество игроков в белом списке.

**Ответ:**
```json
{
  "total": 42
}
```

---

## Punishments

**Префикс:** `/punishments`

### POST `/punishments/`

Создает новое наказание (бан/мут).

**Тело запроса:**
```json
{
  "player_uuid": "string",
  "player_name": "string",
  "player_ip": "192.168.1.1",
  "punishment_type": "string",
  "reason": "string",
  "staff_uuid": "string",
  "staff_name": "string",
  "expires_at": "2024-01-01T00:00:00Z",
  "evidence_url": "string",
  "notes": "string"
}
```

**Статус:** `201 Created`

**Ответ:**
```json
{
  "id": "uuid",
  "player_uuid": "string",
  "player_name": "string",
  "player_ip": "192.168.1.1",
  "punishment_type": "string",
  "reason": "string",
  "staff_uuid": "string",
  "staff_name": "string",
  "expires_at": "2024-01-01T00:00:00Z",
  "is_active": true,
  "revoked_at": null,
  "revoked_by": null,
  "revoked_reason": null,
  "evidence_url": "string",
  "notes": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### POST `/punishments/revoke`

Отменяет наказание.

**Тело запроса:**
```json
{
  "punishment_id": "uuid",
  "revoked_by": "string",
  "revoked_reason": "string"
}
```

**Ответ:**
```json
{
  "id": "uuid",
  "player_uuid": "string",
  "player_name": "string",
  "player_ip": "192.168.1.1",
  "punishment_type": "string",
  "reason": "string",
  "staff_uuid": "string",
  "staff_name": "string",
  "expires_at": "2024-01-01T00:00:00Z",
  "is_active": false,
  "revoked_at": "2024-01-01T00:00:00Z",
  "revoked_by": "string",
  "revoked_reason": "string",
  "evidence_url": "string",
  "notes": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### POST `/punishments/query`

Выполняет поиск наказаний по фильтрам.

**Тело запроса:**
```json
{
  "player_uuid": "string",
  "punishment_type": "string",
  "is_active": true,
  "page": 1,
  "size": 20
}
```

**Ответ:**
```json
{
  "punishments": [
    {
      "id": "uuid",
      "player_uuid": "string",
      "player_name": "string",
      "player_ip": "192.168.1.1",
      "punishment_type": "string",
      "reason": "string",
      "staff_uuid": "string",
      "staff_name": "string",
      "expires_at": "2024-01-01T00:00:00Z",
      "is_active": true,
      "revoked_at": null,
      "revoked_by": null,
      "revoked_reason": null,
      "evidence_url": "string",
      "notes": "string",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}
```

### GET `/punishments/ban/{player_uuid}`

Получает статус активного бана игрока.

**Параметры:**
- `player_uuid` (path) - UUID игрока

**Ответ:**
```json
{
  "is_banned": true,
  "punishment": {
    "id": "uuid",
    "player_uuid": "string",
    "player_name": "string",
    "player_ip": "192.168.1.1",
    "punishment_type": "ban",
    "reason": "string",
    "staff_uuid": "string",
    "staff_name": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "is_active": true,
    "revoked_at": null,
    "revoked_by": null,
    "revoked_reason": null,
    "evidence_url": "string",
    "notes": "string",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### GET `/punishments/mute/{player_uuid}`

Получает статус активного мута игрока.

**Параметры:**
- `player_uuid` (path) - UUID игрока

**Ответ:**
```json
{
  "is_muted": true,
  "punishment": {
    "id": "uuid",
    "player_uuid": "string",
    "player_name": "string",
    "player_ip": "192.168.1.1",
    "punishment_type": "mute",
    "reason": "string",
    "staff_uuid": "string",
    "staff_name": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "is_active": true,
    "revoked_at": null,
    "revoked_by": null,
    "revoked_reason": null,
    "evidence_url": "string",
    "notes": "string",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

---

## Audit

**Префикс:** `/audit`

### POST `/audit/commands`

Логирует выполнение команды для аудита.

**Тело запроса:**
```json
{
  "player_uuid": "uuid",
  "player_name": "string",
  "command": "string",
  "arguments": ["arg1", "arg2"],
  "server": "string",
  "timestamp": "2024-01-01T00:00:00Z"
}
```

**Статус:** `202 Accepted`

**Ответ:**
```json
{
  "accepted": 1
}
```

---

## LuckPerms

**Префикс:** `/luckperms`

### GET `/luckperms/players/{uuid}`

Получает информацию об игроке по UUID.

**Параметры:**
- `uuid` (path) - UUID игрока

**Ответ:**
```json
{
  "uuid": "string",
  "username": "string",
  "primary_group": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### GET `/luckperms/players/username/{username}`

Получает информацию об игроке по имени.

**Параметры:**
- `username` (path) - Имя игрока

**Ответ:**
```json
{
  "uuid": "string",
  "username": "string",
  "primary_group": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### GET `/luckperms/groups/{name}`

Получает информацию о группе по имени.

**Параметры:**
- `name` (path) - Название группы

**Ответ:**
```json
{
  "name": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### GET `/luckperms/players/{uuid}/permissions`

Получает список разрешений игрока.

**Параметры:**
- `uuid` (path) - UUID игрока

**Ответ:**
```json
[
  {
    "id": 1,
    "uuid": "string",
    "permission": "string",
    "value": true,
    "server": "string",
    "world": "string",
    "expiry": 1234567890,
    "contexts": "string",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
]
```

### GET `/luckperms/players/{uuid}/with-permissions`

Получает информацию об игроке вместе со всеми разрешениями.

**Параметры:**
- `uuid` (path) - UUID игрока

**Ответ:**
```json
{
  "uuid": "string",
  "username": "string",
  "primary_group": "string",
  "permissions": [
    {
      "id": 1,
      "uuid": "string",
      "permission": "string",
      "value": true,
      "server": "string",
      "world": "string",
      "expiry": 1234567890,
      "contexts": "string",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### POST `/luckperms/players`

Создает нового игрока в LuckPerms.

**Тело запроса:**
```json
{
  "username": "string",
  "primary_group": "default"
}
```

**Статус:** `201 Created`

**Ответ:**
```json
{
  "uuid": "string",
  "username": "string",
  "primary_group": "default",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

---

## Teleport History

**Префикс:** `/teleport-history`

### POST `/teleport-history/`

Создает запись о телепортации в истории.

**Тело запроса:**
```json
{
  "player_uuid": "string",
  "from_world": "string",
  "from_x": 0.0,
  "from_y": 0.0,
  "from_z": 0.0,
  "to_world": "string",
  "to_x": 0.0,
  "to_y": 0.0,
  "to_z": 0.0,
  "tp_type": "string",
  "target_name": "string"
}
```

**Статус:** `201 Created`

**Ответ:**
```json
{
  "id": "uuid",
  "player_uuid": "string",
  "from_world": "string",
  "from_x": 0.0,
  "from_y": 0.0,
  "from_z": 0.0,
  "to_world": "string",
  "to_x": 0.0,
  "to_y": 0.0,
  "to_z": 0.0,
  "tp_type": "string",
  "target_name": "string",
  "created_at": "2024-01-01T00:00:00Z"
}
```

### GET `/teleport-history/players/{player_uuid}`

Получает историю телепортаций игрока.

**Параметры:**
- `player_uuid` (path) - UUID игрока
- `limit` (query) - Максимальное количество записей (по умолчанию: 100, мин: 1, макс: 1000)

**Ответ:**
```json
[
  {
    "id": "uuid",
    "player_uuid": "string",
    "from_world": "string",
    "from_x": 0.0,
    "from_y": 0.0,
    "from_z": 0.0,
    "to_world": "string",
    "to_x": 0.0,
    "to_y": 0.0,
    "to_z": 0.0,
    "tp_type": "string",
    "target_name": "string",
    "created_at": "2024-01-01T00:00:00Z"
  }
]
```

---

## Users

**Префикс:** `/users`

### GET `/users/users/{name}/game-id`

Получает игровой ID пользователя по имени.

**Параметры:**
- `name` (path) - Имя пользователя

**Ответ:**
```json
{
  "game_id": "string"
}
```

---

## Аутентификация

Все endpoints (кроме `/health/`) требуют наличия заголовка:

```
X-API-Key: <your-api-key>
```

API ключ настраивается через переменную окружения `SECURITY__API_KEY`.

## Обработка ошибок

Все endpoints возвращают стандартные HTTP коды ошибок:
- `400 Bad Request` - некорректные данные в запросе
- `401 Unauthorized` - отсутствует или неверный API ключ
- `403 Forbidden` - недостаточно прав для выполнения операции (например, попытка удалить чужой варп)
- `404 Not Found` - ресурс не найден
- `409 Conflict` - конфликт ресурсов (ресурс уже существует, лимит превышен)
- `500 Internal Server Error` - внутренняя ошибка сервера

Тело ответа при ошибке имеет следующий формат:
```json
{
  "message": "Human-readable error message",
  "code": "error_code",
  "details": {
    "additional": "context"
  }
}
```

**Коды ошибок:**
- `not_found` - ресурс не найден (404)
- `already_exists` - ресурс уже существует (409)
- `limit_exceeded` - превышен лимит ресурсов (409)
- `permission_denied` - нет прав на операцию (403)
- `invalid_state` - некорректное состояние данных (400)
- `cooldown_active` - кулдаун активен (400)