stats B11: EP-Online energy labels (monthly total file → homes per label for NL, Gouda, Gouda PC4s; aggregates only), stats.ep_label_agg, monthly timer with key from ~/.config/stats/ep-online.env, charts on /stats/energy and /stats/gouda

deploy/stats-collector/README.md

@@ -1,7 +1,7 @@
 # stats collector
 
 Host-side collector for the public [/stats](https://stanrunge.dev/stats) section. It pulls open
-statistics (no API keys) into the `stats` schema with `scripts/stats-fetch.ts`:
+statistics into the `stats` schema with `scripts/stats-fetch.ts`:
 
 | source | timer | schedule (Europe/Amsterdam) | what |
 |---|---|---|---|
@@ -16,6 +16,7 @@ statistics (no API keys) into the `stats` schema with `scripts/stats-fetch.ts`:
 | `rijksfinancien` | `stats-rijksfinancien.timer` | 3rd of the month 05:05 | Rijksfinanciën budget tables, last year to next year (`--backfill` from 2015) |
 | `ustreasury` | `stats-ustreasury.timer` | daily 23:25 | US Treasury MTS receipts/outlays + Debt to the Penny (last 400 days; `--backfill` all) |
 | `usaspending` | `stats-usaspending.timer` | Sundays 06:10 | USAspending budgetary resources per agency and fiscal year |
+| `eponline` | `stats-eponline.timer` | 3rd of the month 05:20 | EP-Online monthly total file (RVO energy labels): homes per label for NL, Gouda and Gouda PC4s; aggregates only. Needs `EP_ONLINE_API_KEY` in `~/.config/stats/ep-online.env` (mode 600), which the runner exports for this source only |
 
 Each timer starts `stats-collector@<source>.service`, which runs
 `~/.local/bin/stats-collector-run.sh <source>`: it updates a detached checkout of `origin/main`

deploy/stats-collector/stats-collector-run.sh

@@ -31,4 +31,16 @@ DB_URL=$(sudo -n docker inspect personal-website-app-1 --format '{{range .Config
 	| sed -n 's/^DB_URL=//p' | sed 's/@db:5432/@127.0.0.1:5440/')
 [ -n "$DB_URL" ] || { echo "no DB_URL from app container" >&2; exit 1; }
 export DB_URL
+# Per-source API keys live in ~/.config/stats/<name>.env (mode 600); exported, never echoed.
+case "$source_name" in
+	eponline) env_file="$HOME/.config/stats/ep-online.env" ;;
+	*) env_file="" ;;
+esac
+if [ -n "$env_file" ]; then
+	[ -r "$env_file" ] || { echo "missing $env_file" >&2; exit 1; }
+	set -a
+	# shellcheck disable=SC1090
+	. "$env_file"
+	set +a
+fi
 exec nice -n 10 bun scripts/stats-fetch.ts "$@"

deploy/stats-collector/stats-eponline.timer

@@ -0,0 +1,11 @@
+[Unit]
+Description=/stats collector: EP-Online energy labels, monthly total file (published on the 1st)
+
+[Timer]
+OnCalendar=*-*-03 05:20:00 Europe/Amsterdam
+RandomizedDelaySec=20min
+Persistent=true
+Unit=stats-collector@eponline.service
+
+[Install]
+WantedBy=timers.target