Garmin

Sync a Garmin Connect account into swamp: one authenticated transport, plus domain models that read its cached responses — devices with a capability map that gates the rest, the activity history with FIT/TCX/GPX downloads, daily wellness, weight/body composition, and training + performance metrics.

Garmin Connect has no public API. It needs a signed OAuth1 handshake to mint a rotating OAuth2 bearer token, it rate-limits aggressively, and every data domain would otherwise repeat that fragile login. This extension does it once: @svendowideit/garmin-connect owns login, token refresh, authenticated cached GETs and binary downloads, while domain models declare the connectapi paths they need and parse the cached bodies. The seam is a workflow: transport fetch → domain sync. Because Garmin features depend on the devices an account owns, the devices model derives a capability map so later workflows can gate on it instead of failing on data a device cannot produce; and the wellness and performance models drop metrics (HRV, SpO2, VO2max, FTP) whose devices are absent.

WHAT IT DOES

It turns a fragile, undocumented fitness API into composable swamp data. One model owns the whole auth chain (SSO → OAuth1 → OAuth2), a refresh token lasts weeks so unattended runs keep working with no password, responses are cached on disk so a rate-limited or offline run degrades to last-known data, and every domain fetch is one paced batch. You get a normalised activity history with per-activity splits and weather plus original activity files as first-class swamp files; a per-day wellness roll-up (steps, sleep and sleep score, stress, heart rate, body battery); weight with body composition; and training + performance metrics (training status and readiness, VO2max per sport, race predictions, endurance and hill score, FTP, personal records), all gated by a device capability map.

INSTALL

swamp extension pull @svendowideit/garmin

DEPENDENCIES

None. It uses only Deno's built-in fetch and WebCrypto (the OAuth1 HMAC-SHA1 signer is implemented here), plus the bundled deno binary swamp already ships. Nothing is installed on the host.

RUN

# See what is configured and the exact commands to fix any gap (read-only).
swamp model @svendowideit/garmin-connect method run setup garmin-connect

# Preferred: seed the session from a base64 garth token store, so no
# password is ever handled and scheduled runs need no interactivity.
swamp vault put garmin-secrets GARMIN_TOKEN_STORE
swamp model @svendowideit/garmin-connect method run import-tokens garmin-connect

# Or log in with credentials; add --input interactiveMfa=<code> if Garmin
# asks for a one-time code.
swamp vault put garmin-secrets GARMIN_EMAIL
swamp vault put garmin-secrets GARMIN_PASSWORD
swamp model @svendowideit/garmin-connect method run login garmin-connect

# Refresh the session then sync each domain; these run in sequence on
# their own schedule once 'swamp serve' is up.
swamp workflow run @svendowideit/garmin-session
swamp workflow run @svendowideit/garmin-devices-sync
swamp workflow run @svendowideit/garmin-activities-sync
swamp workflow run @svendowideit/garmin-health-sync
swamp workflow run @svendowideit/garmin-body-sync
swamp workflow run @svendowideit/garmin-performance-sync

# Backfill a wider window (any domain sync accepts a date range).
swamp workflow run @svendowideit/garmin-performance-sync --input startDate=2026-01-01 --input endDate=2026-01-31

# Download original activity files (FIT by default) for the synced list.
swamp workflow run @svendowideit/garmin-download --input format=tcx --input limit=50

# Read the data: wellness, weight, or performance and records.
swamp data get garmin-health health-range --json \
  | jq '.content.summaries[] | {date, steps, sleepScore, avgStress}'
swamp data get garmin-performance records --json \
  | jq '.content | {ftp, best, personalRecords}'
swamp data get garmin-performance metrics-<date> --json \
  | jq '.content | {trainingStatus, trainingReadiness, vo2maxRunning}'

CONFIGURE

All optional, set on the model instance (recommended — scheduled runs have no --input) or overridden per call with --input:

domain               Region domain (default garmin.com; garmin.cn for China)
vaultName            Vault for credentials + session (default garmin-secrets). The session and pending-MFA token resources are pinned to garmin-secrets, so sensitive tokens are always written there regardless of other vaults.
cacheDir             Shared response cache (default ~/.swamp/garmin-cache)
requestDelayMs       Minimum delay between origin requests (default 500)
maxRetries           Retries after 429/5xx (default 2)
maxFetchesPerCall    Origin-fetch cap per fetch-many/download-many (default 100)
capabilityOverrides  Force capabilities true/false when detection misses
detailKinds          Per-activity detail to fetch (default detail, splits, weather)
metrics              Wellness and performance metrics to fetch (see README)
respectCapabilities  Drop device-gated metrics (default true)
timezone             IANA zone for activity bucketing and the wellness
                     and body default window; empty = host local. Set it
                     so a morning run fetches the day you are living in.
days                 Local wellness/body days through today (default 3; cap 14)
unit                 Body display unit: kg or lb (default kg; grams always kept)

See every setting and its current value: swamp model @svendowideit/garmin-connect method run setup garmin-connect swamp model @svendowideit/garmin-devices method run setup garmin-devices swamp model @svendowideit/garmin-activities method run setup garmin-activities swamp model @svendowideit/garmin-health method run setup garmin-health swamp model @svendowideit/garmin-body method run setup garmin-body swamp model @svendowideit/garmin-performance method run setup garmin-performance

SETUP

Every model ships a read-only setup method: run it to see the config that was detected or reused and exactly what is missing before a sync runs (it prints no secret). Global arguments are persisted on the model and read back on every run, credentials and session live in the vault, and each model verifies the real state — a valid session, cached responses, a resolvable window — stopping with a clear message on a blocking failure. Capabilities enable progressively: a model fetches only the domains its config and the account's device capability map support.

UPGRADE

Nothing is installed on the host, so there is no in-place rebuild to run. Upgrade by updating the extension; each model carries its own upgrades entry and migrates its stored configuration on the next run, reusing the existing vault session and cache.

swamp extension update @svendowideit/garmin

WHAT IT INSTALLS

Nothing on the host — no services, daemons, or webhooks. Six cron triggers are registered while 'swamp serve' runs, staggered through the morning: garmin-session at 0 5 * * *, garmin-devices-sync at 10 5 * * *, garmin-activities-sync at 20 5 * * *, garmin-health-sync at 30 5 * * *, garmin-body-sync at 40 5 * * *, and garmin-performance-sync at 50 5 * * *. Downloads run on demand. All state lives in swamp resources; the session tokens live in the vault (marked sensitive), pinned to the garmin-secrets vault (vaultName on the session and pendingMfa resource specs) so creating another vault can never redirect them — see the README's 'Vault pinning'.