hubmc_essentionals/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
}
```

**Ответ:**
```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"
}
```

### 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/`

Создает новую точку варпа.

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

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

**Ответ:**
```json
{
  "id": "uuid",
  "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"
}
```

### PATCH `/warps/`

Обновляет существующую точку варпа.

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

**Ответ:**
```json
{
  "id": "uuid",
  "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"
}
```

### DELETE `/warps/`

Удаляет точку варпа.

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

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

### POST `/warps/get`

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

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

**Ответ:**
```json
{
  "id": "uuid",
  "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",
      "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 ключ
- `404 Not Found` - ресурс не найден
- `500 Internal Server Error` - внутренняя ошибка сервера

Тело ответа при ошибке содержит детальное описание проблемы.