Files
HealthLog/src/lib/garmin/sport-map.ts
T
Marc-André Bombeck e2ba86b12f feat(garmin): sync Garmin Connect through the Personal API
Garmin Connect now offers a Personal API: a person creates a key for
their own account and any client can buy short-lived tokens with it.
HealthLog takes that key in a new Garmin card, checks it with Garmin
before storing it sealed on the user row, and polls every hour.

- Transport: key exchange with a per-process token cache keyed on the
  key, one re-exchange on a refused token and then reauth_required, the
  429 Retry-After carried to the caller, the China host tried when the
  global one does not know the key, answers read with a byte cap, all
  egress through safeFetch to the two fixed hosts.
- Sync: daily summaries, sleep summaries, HRV, weigh-ins and the
  activity search, chunked to each resource's documented range, read one
  after another and stopped at the first rate limit; today's menstrual
  cycle summary adds logged period days the person has not logged.
- Backfill: a resumable walk through the shared admission lane that
  learns where the history starts from the daily summaries and the
  activities, waits out Garmin's rate limit and stamps its marker.
- Types: GARMIN source; BODY_BATTERY and STRESS_LEVEL for Garmin's own
  day scores, kept apart from the computed STRESS_SCORE; TRAINING_READINESS
  and ACUTE_TRAINING_LOAD for figures a bridge pushes through the ingest
  token. All four chart on the recovery page and sit on the ladders,
  units, ranges, labels and report groups like the device-native scores.
- Key expiry: learned from a token capped short of a day, else estimated
  from the validity picked at connect; the card warns a week ahead and
  asks for a new key once Garmin refuses the old one.
- Ledger, health, freshness, watchdog, backup classes, wipe plan,
  encrypted-column registry, rotation script, OpenAPI and all ten
  locales carry the new integration. The old "no Garmin connector" note
  is gone.
2026-11-04 10:14:10 +01:00

126 lines
3.9 KiB
TypeScript

/**
* Garmin activity `activityType.typeKey` → HealthLog canonical
* `WorkoutSportType`.
*
* Garmin's keys are lowercase snake_case (`running`, `trail_running`,
* `road_biking`, `lap_swimming`, `strength_training`, ...), and some carry a
* version suffix (`kayaking_v2`). The bucket choices follow the Oura, Polar
* and Strava tables (paddle sports → rowing, racket sports → tennis,
* functional training → crossTraining, mobility and breath work →
* mindAndBody, snow sports → other), so one real session lands in one bucket
* whichever source reported it. An unknown key lands on `"other"`; the row
* still persists and the raw key travels in `Workout.metadata.garminActivity`.
*/
import type { WorkoutSportType } from "@/lib/validations/workout";
const GARMIN_SPORT_TABLE: ReadonlyArray<readonly [string, WorkoutSportType]> = [
// running
["running", "running"],
["trail_running", "running"],
["treadmill_running", "running"],
["track_running", "running"],
["indoor_running", "running"],
["street_running", "running"],
["virtual_run", "running"],
["ultra_run", "running"],
// cycling
["cycling", "cycling"],
["road_biking", "cycling"],
["mountain_biking", "cycling"],
["gravel_cycling", "cycling"],
["indoor_cycling", "cycling"],
["virtual_ride", "cycling"],
["cyclocross", "cycling"],
["e_bike_fitness", "cycling"],
["e_bike_mountain", "cycling"],
["bmx", "cycling"],
["track_cycling", "cycling"],
// walking / hiking
["walking", "walking"],
["casual_walking", "walking"],
["speed_walking", "walking"],
["indoor_walking", "walking"],
["hiking", "hiking"],
["mountaineering", "hiking"],
// water
["swimming", "swimming"],
["lap_swimming", "swimming"],
["open_water_swimming", "swimming"],
["rowing", "rowing"],
["indoor_rowing", "rowing"],
["kayaking", "rowing"],
["paddling", "rowing"],
["stand_up_paddleboarding", "rowing"],
// machines
["elliptical", "elliptical"],
["stair_climbing", "stairClimber"],
["floor_climbing", "stairClimber"],
// strength / intervals / functional
["strength_training", "strength"],
["hiit", "hiit"],
["indoor_cardio", "mixedCardio"],
["cardio", "mixedCardio"],
["fitness_equipment", "crossTraining"],
["bouldering", "crossTraining"],
["rock_climbing", "crossTraining"],
["indoor_climbing", "crossTraining"],
// mind and body
["yoga", "yoga"],
["pilates", "mindAndBody"],
["breathwork", "mindAndBody"],
["meditation", "mindAndBody"],
["mobility", "mindAndBody"],
// dance
["dance", "dance"],
// ball and racket sports
["golf", "golf"],
["tennis", "tennis"],
["table_tennis", "tennis"],
["squash", "tennis"],
["padel", "tennis"],
["pickleball", "tennis"],
["racquetball", "tennis"],
["badminton", "badminton"],
["basketball", "basketball"],
["soccer", "soccer"],
// persisted outside a bucket
["resort_skiing", "other"],
["backcountry_skiing", "other"],
["cross_country_classic_skiing", "other"],
["cross_country_skate_skiing", "other"],
["resort_snowboarding", "other"],
["inline_skating", "other"],
["surfing", "other"],
["boxing", "other"],
["multi_sport", "other"],
["triathlon", "other"],
["other", "other"],
];
/** Fold case, drop a `_v2`-style suffix and separators. */
function normaliseGarminTypeKey(raw: string): string {
return raw
.trim()
.toLowerCase()
.replace(/_v\d+$/, "")
.replace(/[^a-z0-9]+/g, "");
}
const GARMIN_SPORT_MAP: ReadonlyMap<string, WorkoutSportType> = new Map(
GARMIN_SPORT_TABLE.map(([key, canonical]) => [
normaliseGarminTypeKey(key),
canonical,
]),
);
/**
* Resolve a Garmin `typeKey` to a canonical `WorkoutSportType`; `"other"` for
* an absent, blank or unknown key. Never returns the raw key.
*/
export function mapGarminSportType(
typeKey: string | null | undefined,
): WorkoutSportType {
if (typeof typeKey !== "string" || typeKey.trim() === "") return "other";
return GARMIN_SPORT_MAP.get(normaliseGarminTypeKey(typeKey)) ?? "other";
}