Add minimal Companion-to-Nextcloud-Health bridge (weight only, MVP)

2026-09-17 02:02:34 +02:00
parent d376d5ee95
commit 37f3399953
6 changed files with 609 additions and 0 deletions
@@ -0,0 +1,40 @@
+# Bridge: Life Dashboard Companion → Nextcloud Health v3
+
+Minimal MVP. Forwards only the `weight` records from the Companion webhook
+payload to Health v3's `POST /entries` endpoint, one entry per record, since
+weight is currently the only OpenScale-relevant metric Health v3 has built in.
+
+Requires Python 3.10+ (uses `str | None` type hints).
+
+## Setup
+
+```bash
+# One-time: obtain a Nextcloud app password via Login Flow v2.
+# Opens a browser tab, confirm the login there, then this writes credentials.json.
+uv run nc_login_flow.py https://your-nextcloud.example.com
+
+# Set the same HMAC secret configured under "Webhook Headers" in the Companion app.
+export NC_WEBHOOK_SECRET="..."
+uv run server.py
+```
+
+Point the Companion app's webhook URL at `http://<this-host>:8080/webhook/health-connect`.
+
+## Scope
+
+- Verifies `X-Signature: sha256=<hmac>` on every request; rejects with 401 on
+  mismatch (Companion does not retry on 401).
+- Only reads the `weight` array; everything else in the payload is ignored.
+- Uses the Health Connect record `uuid` as Health's `operationId` for
+  idempotent retries where it parses as a UUID.
+- Returns 502 on partial forwarding failure so the Companion app retries the
+  whole payload later (transient failures are retried by the app).
+
+## Not yet covered
+
+- Body fat / muscle mass / body water (not yet built into Health v3; muscle
+  mass and body water aren't even on Health v3's roadmap — see the main
+  README's architecture diagram).
+- Blood pressure, steps, activity (add once this MVP is proven out).
+- Containerized deployment (currently a local script only, per the current
+  iteration's scope).