# Serwery Gier (Game API)

Kompletny przewodnik po endpointach do zarządzania instancjami serwerów gier (Minecraft, GTA V / FiveM, Rust, Palworld, CS2, ARK itp.).

---

## 1. Lista serwerów (`/v1/servers`)

Zwraca listę wszystkich aktywnych serwerów gier oraz maszyn VPS przypisanych do Twojego konta.

* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers`
* **Wymagany scope:** `account:read`

### Jednostki zwracanych pól:
| Pole | Jednostka | Opis |
| :--- | :--- | :--- |
| `cpu` | **% (Procent)** | Limit procesora (`100` = 1 rdzeń vCPU, `200` = 2 rdzenie) |
| `ram_mb` | **MB (Megabajty)** | Przypisany limit pamięci operacyjnej RAM |
| `disk_gb` | **GB (Gigabajty)** | Przypisana przestrzeń dyskowa |
| `unique_id` | **String** | Publiczny unikalny identyfikator serwera (używany we wszystkich endpointach) |
| `monthly_price`| **wPLN** | Miesięczny koszt odnowienia usługi |

### Przykład zapytania cURL

```bash
curl -X GET "https://api.blackhost.pl/v1/servers" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"
```

### Przykład odpowiedzi (200 OK)

```json
{
  "success": true,
  "gameServers": [
    {
      "id": 1191,
      "unique_id": "d0969f0b",
      "name": "Minecraft Survival 1.21",
      "system": "MC",
      "node": "PL-P",
      "status": "running",
      "is_suspended": false,
      "cpu": 200,
      "ram_mb": 4096,
      "disk_gb": 20,
      "monthly_price": 0,
      "ip": "s1.blackhost.pl:25565",
      "created_at": null,
      "expires_at": null
    }
  ],
  "pveServers": []
}
```

---

## 2. Szczegóły i stan serwera (`/v1/servers/game/:id/details`)

Pobiera szczegółowe parametry wybranego serwera gry, w tym alokacje portów, limity i konfigurację techniczną.

* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/game/{id}/details`
* **Wymagany scope:** `game:read`
* **Parametr `{id}`:** Krótki identyfikator serwera (`unique_id`, np. `d0969f0b`).

### Jednostki w obiekcie `limits`:
| Pole | Jednostka | Opis |
| :--- | :--- | :--- |
| `limits.memory` | **MB (Megabajty)** | Limit pamięci RAM (np. `4096` MB) |
| `limits.swap` | **MB (Megabajty)** | Limit pamięci SWAP (`0` = wyłączony) |
| `limits.disk` | **MB (Megabajty)** | Przestrzeń dyskowa w megabajtach (np. `20480` MB = 20 GB) |
| `limits.cpu` | **% (Procent)** | Limit CPU (`200` = 200% alokacji) |
| `limits.io` | **Waga (10-1000)** | Priorytet operacji wejścia/wyjścia I/O dysku |

### Przykład zapytania cURL

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/details" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"
```

### Przykład odpowiedzi (200 OK)

```json
{
  "success": true,
  "server": {
    "id": 1191,
    "unique_id": "d0969f0b",
    "name": "Minecraft Survival 1.21",
    "node": "PL-P",
    "status": "running",
    "limits": {
      "memory": 4096,
      "swap": 0,
      "disk": 20480,
      "io": 500,
      "cpu": 200
    },
    "allocations": [
      {
        "ip": "89.144.32.28",
        "ip_alias": "s1.blackhost.pl",
        "port": 25565,
        "is_default": true
      }
    ]
  }
}
```

---

## 3. Statystyki zużycia na żywo (`/v1/servers/game/:id/stats`)

Pobiera aktualne zużycie zasobów w czasie rzeczywistym (CPU, RAM, dysk, transfer sieciowy, uptime) oraz stan procesu.

* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/game/{id}/stats`
* **Wymagany scope:** `game:read`

### Jednostki w obiekcie `stats`:
| Pole | Jednostka | Opis |
| :--- | :--- | :--- |
| `stats.cpu` | **% (Procent)** | Aktualne zużycie CPU (np. `42.5` oznacza 42.5% rdzenia) |
| `stats.mem` | **Bajty (Bytes)** | Aktualnie zajęta pamięć RAM (np. `2147483648` B = 2 GB) |
| `stats.disk` | **Bajty (Bytes)** | Aktualnie zajęta przestrzeń dyskowa (np. `8589934592` B = 8 GB) |
| `stats.uptime` | **Sekundy (s)** | Czas nieprzerwanego działania serwera od startu |
| `stats.netin` | **Bajty (Bytes)** | Łączna liczba odebranych bajtów przez interfejs sieciowy |
| `stats.netout` | **Bajty (Bytes)** | Łączna liczba wysłanych bajtów |
| `stats.players.online` | **Liczba** | Aktualna liczba graczy na serwerze |
| `stats.players.max` | **Liczba** | Maksymalna liczba slotów graczy |

### Przykład zapytania cURL

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/stats" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"
```

### Przykład odpowiedzi (200 OK)

```json
{
  "success": true,
  "status": "running",
  "stats": {
    "status": "running",
    "cpu": 42.5,
    "mem": 2147483648,
    "disk": 8589934592,
    "uptime": 364000,
    "netin": 10240000,
    "netout": 40960000,
    "players": {
      "online": 14,
      "max": 50
    }
  }
}
```

---

## 4. Zarządzanie zasilaniem (`/v1/servers/game/:id/power`)

Wysyła sygnał zasilania do serwera gry.

* **Metoda:** `POST`
* **Ścieżka:** `/v1/servers/game/{id}/power`
* **Wymagany scope:** `game:power`
* **Nagłówek:** `Content-Type: application/json`

### Dostępne sygnały (`signal`):
* `start` - uruchomienie serwera
* `stop` - bezpieczne zatrzymanie (graceful shutdown)
* `restart` - ponowne uruchomienie
* `kill` - natychmiastowe ubicie procesu (force kill)

### Przykład zapytania cURL

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/power" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signal": "restart"}'
```

### Przykład odpowiedzi (200 OK)

```json
{
  "success": true,
  "message": "Signal restart sent successfully."
}
```

---

## 5. Wysyłanie poleceń do konsoli (`/v1/servers/game/:id/command`)

Wykonuje polecenie tekstowe bezpośrednio w konsoli działającego serwera gry.

* **Metoda:** `POST`
* **Ścieżka:** `/v1/servers/game/{id}/command`
* **Wymagany scope:** `game:command`

### Przykład zapytania cURL

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/command" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "say Serwer zostanie zrestartowany za 5 minut!"}'
```

### Przykład odpowiedzi (200 OK)

```json
{
  "success": true
}
```

---

## 6. Połączenie z konsolą na żywo (`/v1/servers/game/:id/websocket`)

Zwraca jednorazowy token uwierzytelniający JWT oraz adres URL WebSocket umożliwiający dwukierunkowy odbiór logów i wysyłanie poleceń konsoli w czasie rzeczywistym.

* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/game/{id}/websocket`
* **Wymagany scope:** `game:read`

### Przykład zapytania cURL

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/websocket" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"
```

### Przykład odpowiedzi (200 OK)

```json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "socket": "wss://node1.blackhost.pl:8080/api/client/servers/d0969f0b/ws"
  }
}
```

---

## 7. Menedżer plików (File Manager API)

### 7.1 Lista plików w katalogu
* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/game/{id}/files/list?directory={dir}`
* **Wymagany scope:** `game:files:read`
* **Jednostka `size`:** **Bajty (Bytes)**

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/list?directory=/config" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"
```

```json
{
  "success": true,
  "files": [
    {
      "name": "paper-global.yml",
      "mode": "-rw-r--r--",
      "size": 4096,
      "isFile": true,
      "isSymlink": false,
      "mimetype": "text/yaml",
      "createdAt": "2026-08-10T12:00:00.000Z",
      "modifiedAt": "2026-08-20T14:30:00.000Z"
    }
  ]
}
```

---

### 7.2 Odczyt zawartości pliku
* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/game/{id}/files/contents?file={filepath}`
* **Wymagany scope:** `game:files:read`

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/contents?file=/server.properties" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
```

---

### 7.3 Zapis zawartości do pliku
* **Metoda:** `POST`
* **Ścieżka:** `/v1/servers/game/{id}/files/contents?file={filepath}`
* **Wymagany scope:** `game:files:write`
* **Nagłówek:** `Content-Type: text/plain`

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/contents?file=/server.properties" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-raw "server-port=25565\nmotd=Nowy opis serwera!\ndifficulty=hard"
```

---

### 7.4 Pobieranie pliku (Download URL)
* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/game/{id}/files/download?file={filepath}`
* **Wymagany scope:** `game:files:read`

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/download?file=/logs/latest.log" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
```

```json
{
  "success": true,
  "url": "https://node1.blackhost.pl:8080/download/backup/file?token=..."
}
```

---

### 7.5 Wyszukiwanie plików po nazwie
* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/game/{id}/files/search?query={search_term}`
* **Wymagany scope:** `game:files:read`

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/search?query=paper" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
```

```json
{
  "success": true,
  "results": [
    {
      "name": "paper.jar",
      "path": "/paper.jar",
      "isFile": true,
      "size": 48234496
    }
  ]
}
```

---

### 7.6 Tworzenie folderu
* **Metoda:** `POST`
* **Ścieżka:** `/v1/servers/game/{id}/files/create-folder`
* **Wymagany scope:** `game:files:write`

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/create-folder" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"root": "/", "name": "plugins"}'
```

---

### 7.7 Usuwanie plików i folderów
* **Metoda:** `POST`
* **Ścieżka:** `/v1/servers/game/{id}/files/delete`
* **Wymagany scope:** `game:files:write`

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/delete" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"root": "/", "files": ["logs/old.log", "cache"]}'
```

---

### 7.8 Zmiana nazwy lub przenoszenie
* **Metoda:** `POST`
* **Ścieżka:** `/v1/servers/game/{id}/files/rename`
* **Wymagany scope:** `game:files:write`

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/rename" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"root": "/", "files": [{"from": "config.yml", "to": "config.yml.bak"}]}'
```

---

### 7.9 Pakowanie (ZIP) i Rozpakowywanie
* **Kompresja:** `POST /v1/servers/game/{id}/files/compress`
  ```bash
  curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/compress" \
    -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"root": "/", "files": ["world", "world_nether"]}'
  ```

* **Rozpakowywanie:** `POST /v1/servers/game/{id}/files/decompress`
  ```bash
  curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/files/decompress" \
    -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"root": "/", "file": "backup.zip"}'
  ```

---

## 8. Zarządzanie Graczami (Players API)

### 8.1 Lista graczy
* **Metoda:** `GET`
* **Ścieżka:** `/v1/servers/game/{id}/players`
* **Wymagany scope:** `game:read`

```bash
curl -X GET "https://api.blackhost.pl/v1/servers/game/d0969f0b/players" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"
```

```json
{
  "success": true,
  "players": [
    {
      "name": "Steve",
      "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
      "isOp": true,
      "isOnline": true
    }
  ],
  "banned": []
}
```

---

### 8.2 Akcje na graczach (Kick, Ban, Op, Whitelist)
* **Metoda:** `POST`
* **Ścieżka:** `/v1/servers/game/{id}/players/action`
* **Wymagany scope:** `game:command`

```bash
curl -X POST "https://api.blackhost.pl/v1/servers/game/d0969f0b/players/action" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "kick",
    "player": "Steve",
    "reason": "Złamanie regulaminu"
  }'
```

```json
{
  "success": true
}
```

#### Dostępne wartości `action`:
* `kick` - wyrzucenie gracza z serwera (`reason` opcjonalny)
* `ban` - zablokowanie gracza na serwerze
* `pardon` - odbanowanie gracza
* `op` - nadanie uprawnień operatora serwera
* `deop` - odebranie uprawnień operatora
* `gamemode` - zmiana trybu gry (`gamemode`: `survival`, `creative`, `adventure`, `spectator`)
* `whitelist_add` - dodanie gracza do białej listy
* `whitelist_remove` - usunięcie gracza z białej listy