isapi-cli

CLI tipada (typer + Pydantic 2 + httpx Digest) para câmeras Hikvision via ISAPI.

Status: execução real via httpx + Digest auth, testada com respx (mock server) — cobertura 98%, sem câmera. Publicação no PyPI é a próxima etapa.

🚀 Demo em 30s

uv sync --all-extras
export ISAPI_PASSWORD=...          # ou deixe a CLI pedir por prompt oculto
uv run isapi snapshot --host 10.0.0.9 --channel 1 --output snap.jpg
# → snapshot salvo: snap.jpg (48213 bytes)

Comandos: snapshot · events · ptz --preset N · zoom --zoom N — todos --host

• --username/--password (via env ISAPI_* ou prompt) + --insecure (TLS self-signed).

🏗️ Design

flowchart LR
    U[usuário] --> CLI[typer app<br/>tipado, testado]
    CLI --> EP[endpoints ISAPI<br/>paths puros]
    CLI --> C[cliente httpx Digest]
    C -- ISAPI --> CAM[(Câmera Hikvision)]

Loading

A construção de paths (endpoints.py) é pura — separada do transporte, testável 100% sem câmera. O cliente httpx com Digest auth entra por cima, sem tocar nessa lógica.

🧪 Testes & CI

Camada	Ferramenta	Status
Estilo & tipos	ruff + mypy --strict	✅ em CI
Unit + CLI + cobertura	pytest + typer.testing (≥ 80%)	✅ 98%
Execução real	httpx Digest + respx mock	✅
Publicação	pipx install isapi-cli (PyPI, trusted publishing)	🔧 workflow pronto

🗺️ Roadmap

• CLI tipada + endpoints ISAPI puros, testados (ruff/mypy/cov 98%)
• Cliente httpx com Digest auth + respx mock server nos testes
• CLI ligada à execução real (senha via env ISAPI_PASSWORD/prompt oculto)
• Erros humanizados (401/conexão/timeout, sem stack trace) + --timeout
• retry / paths v1/v2 — adiado: retry mascara falha numa CLI; v1/v2 exige câmera real
• Workflow de publicação PyPI/TestPyPI (trusted publishing, OIDC sem token)
• Registrar trusted publisher no PyPI + primeiro release + asciinema no README

📦 Publicação (trusted publishing)

publish.yml usa OIDC — nenhum token de API no repo. Configuração manual única (nome isapi-cli verificado livre em PyPI e TestPyPI):

1. TestPyPI → https://test.pypi.org/manage/account/publishing/ → Add a pending publisher: owner abreu0x, repo isapi-cli, workflow publish.yml, environment testpypi.
2. PyPI → https://pypi.org/manage/account/publishing/ → idem, environment pypi.
3. Ensaio: Actions → publish → Run workflow (publica no TestPyPI).
4. Release real: criar um GitHub Release v0.1.0 → dispara publish no PyPI.

🛠️ Stack

Python 3.12 · typer · Pydantic 2 · httpx (Digest) · pytest · ruff · mypy

📄 Licença

MIT — ver LICENSE.