fitbit-connector

# Fitbit Connector Skill (Tool Provider) Use this skill when OpenClaw needs Fitbit or unified health data. This is the **canonical front door** for health / Fitbit retrieval in OpenClaw. If a user asks for latest Fitbit numbers, recovery signals, readiness trends, sleep/HRV/resting-HR patterns, or recent health metrics for training interpretation, start here. This skill is **data-plane only**: - it authenticates, - fetches Fitbit data, - syncs/cache stores normalized metrics, - returns compact JSON. OpenClaw handles interpretation, decisions, and coaching language. ## Canonical usage rule For ordinary question-answering, prefer this skill first. Do **not** start by searching the workspace for Fitbit paths if this skill is available. Do **not** prefer older opinionated helper scripts over this interface. For training questions, combine this skill with `memory/training-continuity.md`: - this skill = latest health/recovery data - `memory/training-continuity.md` = training state, progression rules, recent workout context ## Setup 1. Create Fitbit developer app (type `Personal`). 2. Redirect URI: `http://127.0.0.1:8787/callback`. 3. Create `.env` from `references/env.example`. 4. Run auth bootstrap: - `python3 scripts/fitbit_auth.py auth-url` - approve in browser, copy `code` + returned `state` - `python3 scripts/fitbit_auth.py exchange --code <CODE> --state <STATE>` ## Primary front-door interface (recommended) For most OpenClaw usage, call the narrow front door first: - `node ../skills/health-training-frontdoor/scripts/request.js '{"action":"latest_recovery"}'` This keeps retrieval typed and low-ambiguity. ## Backend tool interface (compact JSON) Direct backend contract/schema: - `python3 scripts/fitbit_tools.py schema` - Auth status: - `python3 scripts/fitbit_tools.py auth-status` - Endpoint catalog (broad API surface): - `python3 scripts/fitbit_tools.py catalog` - Capability discovery across last N days (rate-limit aware): - `python3 scripts/fitbit_tools.py discover-capabilities --days 14 --sleep-ms 500 --stop-on-429` - Direct Fitbit endpoint fetch (generic exposure): - `python3 scripts/fitbit_tools.py fetch-endpoint --path sleep/date/YYYY-MM-DD.json --normalize` - Fetch API day payload: - `python3 scripts/fitbit_tools.py fetch-day --date YYYY-MM-DD` - add `--raw` for full Fitbit payload - Fetch cached date range (field-filtered): - `python3 scripts/fitbit_tools.py fetch-range --start YYYY-MM-DD --end YYYY-MM-DD --metrics hrv_rmssd,resting_hr,sleep_minutes,data_quality` - add `--ensure-fresh` to auto-sync that range before reading - Fetch latest N cached days: - `python3 scripts/fitbit_tools.py fetch-latest --days 5 --metrics hrv_rmssd,resting_hr,sleep_minutes,data_quality` - add `--ensure-fresh` to auto-sync the last N days before reading - Sync one day from Fitbit API to cache: - `python3 scripts/fitbit_tools.py store-sync-day --date YYYY-MM-DD` - Sync date range from Fitbit API to cache: - `python3 scripts/fitbit_tools.py store-sync-range --start YYYY-MM-DD --end YYYY-MM-DD` - Query sync quality flags: - `python3 scripts/fitbit_tools.py quality-flags --days 7` - Unified DB status (Apple + Fitbit): - `python3 scripts/fitbit_tools.py unified-status` - Unified latest daily rows with source preference: - `python3 scripts/fitbit_tools.py unified-fetch-latest --days 14 --source best` ## Canonical QA patterns ### Latest Fitbit / recovery snapshot For questions like: - "What do my latest Fitbit numbers suggest?" - "How does recovery look today?" - "Give me my newest HRV / sleep / resting HR" Prefer: - `python3 scripts/fitbit_tools.py fetch-latest --days 3 --metrics hrv_rmssd,resting_hr,sleep_minutes,data_quality --ensure-fresh` ### Unified health snapshot For questions that may blend Fitbit + Apple Health: - `python3 scripts/fitbit_tools.py unified-fetch-latest --days 14 --source best` ### Trend / confidence checks When freshness or quality confidence matters: - `python3 scripts/fitbit_tools.py quality-flags --days 7` ### Training interpretation For questions like: - "Should I train today?" - "How did yesterday compare to recovery?" - "Has recovery improved since earlier this week?" Use both: 1. this skill for current/recent health signals 2. `memory/training-continuity.md` for training rules, progression, and recent exercise context ## Notes - Output contract: compact JSON (machine-optimized, minimal token usage). - Prefer narrow `--metrics` lists to keep token usage low. - SQLite cache is local reliability layer; Fitbit API remains source-of-truth. - No medical diagnosis. This skill only provides data. ## Anti-patterns If this skill is available, avoid these failure modes: - searching the workspace first just to locate Fitbit functionality - asking the user where the connector lives - preferring `fitbit_query.py` over `fitbit_tools.py` for normal QA - treating memory references as the primary source of live Fitbit data - using orchestrator files as the first discovery surface for ordinary health questions ## Legacy scripts Older opinionated scripts remain only for backward compatibility and should be treated as **non-canonical** for ordinary OpenClaw reasoning: - `fitbit_query.py` - `fitbit_coach_view.py` If a normal user question can be answered through `fitbit_tools.py`, do that instead.