# npm_api.py — sterowanie Nginx Proxy Manager przez REST API

CLI do zarzadzania dwoma instancjami NPM (PIHA, VPS) bez klikania w web UI.
Uzywa tego samego REST API co panel admina (`/api/tokens`, `/api/nginx/*`).

## Dlaczego stdlib (`urllib`), nie `requests`

Skrypt uzywa wylacznie biblioteki standardowej Pythona (3.11+) — zero zaleznosci
do zainstalowania. To narzedzie CLI uruchamiane doraznie z roznych miejsc (SATURN,
laptop operatora), nie serwis z wlasnym obrazem Docker — `pip install` przed kazdym
uzyciem byloby tarciem bez korzysci. Zapotrzebowanie na API jest proste (JWT bearer,
JSON), wiec `urllib.request` w zupelnosci wystarcza.

## Konfiguracja

```bash
cp scripts/npm/env.example scripts/npm/.env
# wypelnij NPM_PIHA_USER/PASS i NPM_VPS_USER/PASS realnymi danymi
```

`.env` jest gitignored (wzorzec `*.env` w `.gitignore`) — nigdy nie trafia do repo.

Adresy domyslne (nadpisywalne w `.env` przez `NPM_PIHA_URL`/`NPM_VPS_URL`):

| Instancja | URL | Uwaga |
|---|---|---|
| `piha` | `http://192.168.31.5:81` | LAN |
| `vps`  | `http://100.95.58.48:81` | **Tailscale mesh**, NIE publiczny IP `135.181.153.108:81` |

## Uzycie

```bash
python3 scripts/npm/npm_api.py --npm piha|vps <komenda> [opcje]
```

### Komendy

- `token` — loguje sie i pokazuje status + czas wygasniecia tokenu (test poswiadczen).
- `list-hosts` — tabela proxy hostow (id, domeny, forward, cert, ssl_forced, enabled).
- `list-certs` — tabela certyfikatow (id, provider, nice_name, domeny, expires_on).
- `set-cert HOST_ID CERT_ID [--apply]` — podpina certyfikat pod host. **Dry-run domyslnie**,
  realna zmiana tylko z `--apply`. NPM przeladowuje nginx sam po PUT.
- `create-host --domain ... --forward-host ... --forward-port ... [opcje] [--apply]` —
  tworzy nowy proxy host. **Dry-run domyslnie**, realna zmiana tylko z `--apply`.

`create-host` opcje: `--domain` (powtarzalne), `--forward-host`, `--forward-port`,
`--forward-scheme http|https` (domyslnie `http`), `--cert-id` (domyslnie `0` = brak),
`--ssl-forced`/`--no-ssl-forced` (domyslnie: `true` jesli podano `--cert-id`),
`--http2-support`/`--no-http2-support`, `--block-exploits`/`--no-block-exploits`
(domyslnie `true`), `--websocket`/`--no-websocket` (domyslnie `false`),
`--access-list-id`, `--advanced-config`.

## Przyklady

### Faza 2 okit.pl — przepiecie certow proxy hostow na wildcard

Zamiast bulk-SQL + recznego `sed` na `.conf` (patrz
`docs/sessions/2026-07-07-okit-wildcard.md`), API robi reload samo:

```bash
# 1. znajdz ID wildcard certu
python3 scripts/npm/npm_api.py --npm piha list-certs

# 2. znajdz ID hosta ktory ma dostac nowy cert
python3 scripts/npm/npm_api.py --npm piha list-hosts

# 3. podejrzyj zmiane (dry-run)
python3 scripts/npm/npm_api.py --npm piha set-cert 11 5

# 4. wykonaj
python3 scripts/npm/npm_api.py --npm piha set-cert 11 5 --apply
```

### Deploy Gokapi — vhost share.okit.pl na npm@VPS

```bash
# dry-run
python3 scripts/npm/npm_api.py --npm vps create-host \
  --domain share.okit.pl \
  --forward-host 127.0.0.1 --forward-port 8080 \
  --cert-id 5 --ssl-forced --http2-support --block-exploits

# apply
python3 scripts/npm/npm_api.py --npm vps create-host \
  --domain share.okit.pl \
  --forward-host 127.0.0.1 --forward-port 8080 \
  --cert-id 5 --ssl-forced --http2-support --block-exploits \
  --apply
```

## Obsluga bledow

Bledy autentykacji, brakujace hosty/certy i bledy API zwracane sa z czytelnym
komunikatem na stderr (kod wyjscia 1) — np.:

```
Error: PUT /nginx/proxy-hosts/11 -> HTTP 404: Proxy host not found
```

## Referencje API

Oficjalny swagger jest niekompletny; zweryfikowano bezposrednio ze zrodla
(`GET /api/schema` na dzialacej instancji NPM 2.14, OpenAPI 3.1) oraz
`github.com/DenAV/nginx-proxy-manager-ansible`.