diff --git a/docs/integrations/dawarich.md b/docs/integrations/dawarich.md index 20540d2e7..3f16b3f08 100644 --- a/docs/integrations/dawarich.md +++ b/docs/integrations/dawarich.md @@ -1,82 +1,7 @@ # Dawarich integration -HealthLog can read daily movement context from a [Dawarich](https://dawarich.app) -instance: how far you moved, how much of it by car or by train, how many places -you visited, how long you were away from home, and whether a day was spent in -another country. It is part of the Environment module and runs only while that -module is on. - -HealthLog never stores a coordinate, a track, a place name or a visit. It reads -the day summaries and keeps one row of numbers per day. The place list is read -live when you pick your home and is not saved. - -## What is read - -Once a night (03:20 Europe/Berlin) HealthLog fetches the last seven days, ending -yesterday. Connecting fetches the last 30 days. Each request carries your API -key as `Authorization: Bearer `. - -| Dawarich endpoint | What HealthLog keeps | -| ----------------------- | -------------------------------------------------------------------------------------- | -| `GET /api/v1/timeline` | total distance, distance by car (`driving`), distance by train, places visited | -| `GET /api/v1/visits` | minutes spent at your home place, to work out time away from home | -| `GET /api/v1/residency` | the country of each day, sealed at rest, and whether it differs from your home country | -| `GET /api/v1/places` | nothing; the list is shown once so you can pick your home | -| `GET /api/v1/users/me` | nothing; used to check the key | - -Time away from home is the day's length minus the time a visit at your home -place covers. Without a home place, or on a day without a single visit, it is -left empty rather than shown as zero. Dawarich leaves out a mode that moved -less than half a kilometre; HealthLog then reads that mode as zero for the day. - -Residency needs API access on a hosted Dawarich plan; a self-hosted instance -has it. Without it there are no travel days, and everything else still works. -Dawarich keys residency by UTC date, so on a day that crosses a border late in -the evening the country can be the next morning's. - -## Connect - -1. In Dawarich, open your account settings and copy the API key. -2. In HealthLog, turn on the Environment module, then open - **Settings → Integrations → Dawarich**. -3. Enter the address of the instance and the key, and connect. -4. Pick your home place from the list, and set your home country if you like. - Without one, the country you spent most days in over the last year counts. - -Run Dawarich and HealthLog in the same time zone. Dawarich groups the -timeline by its own zone, HealthLog by yours; if they differ, a day can come -back without its distances. - -## A Dawarich instance on your own network - -A public instance works without any server setting. An instance on a private -network (a LAN address, a `.lan` name, a container on the same host) is refused -unless the operator lists its exact origin: - -```env -DAWARICH_PRIVATE_ORIGINS="http://dawarich.lan:3000" -``` - -The grammar is the one `NIGHTSCOUT_PRIVATE_ORIGINS` uses -([Nightscout](./nightscout.md)): one `scheme://host[:port]` per entry, comma -separated, no path, no wildcard and no range. Listing a host does not open its -subdomains or another port. The unspecified address, link-local and the -cloud-metadata range can never be listed. Restart HealthLog after changing it. -The variable is on the `environment:` whitelist in `docker-compose.yml`. - -## Where the values show up - -- The day view has an **On the move** section with the day's figures. -- Time away from home and the distance travelled join the correlation scan as - two more factors. -- Runs of at least two travel days that no trip covers yet are offered as - trips under **Settings → Location & weather → Location periods**. Using one fills - in the dates; you pick the place. -- The Coach and the MCP `get_day` tool see the figures and whether it was a - travel day, never the country. - -## Disconnect - -Disconnecting stops the nightly fetch and keeps the stored days. **Disconnect -and delete days** removes them as well. The days are part of the backup; the -address and key are not, so a restored account connects again. +The Dawarich guide lives on the docs site: +. It covers what is read +and what is never stored, connecting an instance, allowing one on your own +network (`DAWARICH_PRIVATE_ORIGINS`), where the values show up, and +disconnecting. diff --git a/docs/integrations/strava.md b/docs/integrations/strava.md index 5607894fb..3e9bb2804 100644 --- a/docs/integrations/strava.md +++ b/docs/integrations/strava.md @@ -1,74 +1,6 @@ # Strava integration -HealthLog reads your Strava activities and folds them into the same workout -history as every other source. Strava is a **workout source only** — its API is -activity-centric and exposes no sleep, recovery, body-composition or glucose -data, so connecting it adds runs, rides, swims and the rest to your workout -surface and nothing else. - -The OAuth app is brought **per user**: each self-hoster registers their own -Strava API application and pastes the client id/secret into Settings. Strava -caps every newly-created app at "single-player mode" (an athlete capacity of 1) -until you request a capacity increase — perfectly fine for a personal -self-host, and the reason a single shared app cannot serve many operators. - -## What you get — and what you don't - -**Covered** (one `Workout` row per activity): sport type, start and end time, -moving duration, distance, elevation gain, average and maximum heart rate (when -the activity recorded it), and calories. Power, cadence, the "trainer"/"commute" -flags and the activity name are kept on the row's metadata for provenance but -are **not** surfaced as training analytics — HealthLog treats Strava as another -workout source, not a training-load platform. - -**Not covered**: Strava exposes no daily metrics (steps, sleep, resting heart -rate, weight, …). Those come from your wearable's own integration or from Apple -Health / Google Health Connect. - -## Duplicate activities are collapsed automatically - -If you record a run on an Apple Watch **and** it also lands in Strava, the same -run arrives twice — once via Apple Health, once via Strava. HealthLog keeps one -canonical row per logical workout using your **source-priority ladder**: by -default the device-native capture (Apple Watch, WHOOP, Withings) wins over the -Strava copy, because a Strava activity is often a re-upload with lower-fidelity -or missing heart-rate data. A run you record **only** on Strava (phone GPS) -survives untouched. You can promote Strava above the wearables in -**Settings → Source priority** if you prefer the Strava copy. - -## 1. Register a Strava API application - -1. Sign in at . -2. Create an application. For **Authorization Callback Domain** enter the host - of your HealthLog instance (the domain only, no scheme or path). -3. Copy the **Client ID** and **Client Secret**. - -## 2. Paste the credentials into HealthLog - -1. Open **Settings → Integrations** and find the **Strava** card. -2. Paste the Client ID and Client Secret into the **API Credentials** fields and - save. (An operator can instead configure a shared app via the - `STRAVA_CLIENT_ID` / `STRAVA_CLIENT_SECRET` environment variables; per-user - credentials always take precedence.) -3. Click **Connect Strava** and approve the access request. HealthLog requests - the `activity:read_all` scope so it can read every activity, including those - you marked "only me". - -## 3. First sync - -The first history import runs in the background shortly after you connect; -afterwards an hourly poll pulls new activities. Strava rotates its refresh token -on every refresh, and HealthLog persists the rotated token each time, so the -connection stays healthy without you re-authorising. - -## Disconnecting - -Disconnecting revokes the grant at Strava and clears the stored tokens. -Activities already imported stay in your history; reconnecting resumes the sync. - -## Related - -- Wearable that syncs to Strava but not directly to HealthLog? See the device's - own page, or ingest via [Apple Health](./apple-health.md) / - [Google Health Connect](./google-health.md). -- **Garmin owners:** Garmin has no direct connector — see [garmin.md](./garmin.md). +The Strava guide lives on the docs site: +. It covers what Strava +adds (workouts only), how duplicate activities from a wearable are collapsed, +registering the Strava API application, the first sync and disconnecting.