# typhon

`typhon` is an AC Infinity telemetry exporter that polls the AC Infinity cloud API and exposes Prometheus metrics for Grafana dashboards and alerting.

Stage 1 scope:
- ingest controller climate telemetry (temperature, humidity, VPD)
- ingest fan/port telemetry (online state, power state, speed, mode)
- expose `/metrics` + `/healthz`

Stage 2 scope:
- add authenticated control APIs and UI for `climate.bstein.dev`

## API behavior (based on homebridge-acinfinity)

This implementation follows the same API conventions used by `keithah/homebridge-acinfinity`:
- host: `http://www.acinfinityserver.com`
- login endpoint: `/api/user/appUserLogin`
- list endpoint: `/api/user/devInfoListAll`
- mode endpoint: `/api/dev/getdevModeSettingList`
- auth header: `token: <appId>`
- request headers include `phoneType=1`, `appVersion=1.9.7`, and `User-Agent` matching the official app style
- password field key is intentionally `appPasswordl`
- API only honors the first 25 chars of password

## Configuration

Environment variables:
- `TYPHON_MODE` (optional, default `cloud`, values: `cloud|ble`)
- `ACI_EMAIL` (required)
- `ACI_PASSWORD` (required, use <= 25 chars for reliability)
- `ACI_HOST` (optional, default `http://www.acinfinityserver.com`)
- `POLL_INTERVAL_SECONDS` (optional, default `30`)
- `REQUEST_TIMEOUT_MS` (optional, default `10000`)
- `LISTEN_PORT` (optional, default `9108`)
- `LOG_LEVEL` (optional, default `info`)
- `ENABLE_CONTROL_API` (optional, default `false`)
- `CONTROL_LISTEN_PORT` (optional, default `9110`)
- `TY_BLE_DEFAULT_MAC` (optional, default empty)
- `TY_BLE_ALLOWED_MACS` (optional, comma-delimited)
- `TY_BLE_DEVICE_TYPE` (optional, default `11` for Controller 69 Pro)
- `TY_BLE_SCAN_TIMEOUT_MS` (optional, default `20000`)
- `TY_BLE_PORT_BASE` (optional, `1` by default; set `0` if your controller expects zero-based port bytes)

Notes:
- `TYPHON_MODE=cloud` keeps the existing v1 cloud exporter behavior.
- `TYPHON_MODE=ble` enables the v2 control API scaffolding and does not require `ACI_EMAIL`/`ACI_PASSWORD`.
- BLE mode uses BlueZ DBus (`node-ble`) and AC Infinity protocol packets for telemetry + per-port speed writes.
- BLE mode includes a Wi-Fi recovery API endpoint (`POST /api/v2/wifi/recover`) for v2 orchestration.
- Current `node-ble` client returns `501` for Wi-Fi recovery until provisioning packet frames are finalized.

Kubernetes runtime is expected to source `ACI_EMAIL`/`ACI_PASSWORD` from Vault.

## Local development

```bash
npm ci
npm run lint
npm test
npm run build
```

Run locally:

```bash
ACI_EMAIL='you@example.com' \
ACI_PASSWORD='your-password' \
npm run dev
```

Metrics endpoint:
- `http://localhost:9108/metrics`
- `http://localhost:9108/healthz`

Control API (when `ENABLE_CONTROL_API=true`):
- `GET /api/v2/status`
- `GET /api/v2/ports`
- `POST /api/v2/pair` `{ "mac_address": "AA:BB:CC:DD:EE:FF" }`
- `POST /api/v2/ports/:port/speed` `{ "speed_level": 0..10 }`
- `POST /api/v2/wifi/recover` `{ "ssid": "...", "password": "...", "hidden": false }`