# Hämta riktiga Garmin-aktiviteter

Appen använder för närvarande **exempelpass** i `app/sample_data.py`. För att visa **dina** löprundor behöver du **Garmin Connect Developer Program** och anropa Garmins API:er med giltiga OAuth-token. Att skrapa Garmin Connect privat strider mot deras villkor; använd det officiella programmet.

## 1. Få tillgång till programmet

1. Läs översikten: [Activity API | Garmin Connect Developer Program](https://developer.garmin.com/gc-developer-program/activity-api/).
2. Tillgång ges **godkända företagsutvecklare** (inte en privat hobby-nyckel). Använd **Request now** / kontakt på sidan om du behöver produktionstillgång.
3. Skapa ett **Garmin developer-konto** och registrera din app i **developer portal** när du är med i programmet. Du får **client ID** och **client secret** för integrationen.

## 2. OAuth 2.0 med PKCE

Garmin använder **OAuth 2.0 med PKCE** (Proof Key for Code Exchange). Efter att användaren loggat in och godkänt får din app en **auktoriseringskod**, byter den mot **access-** och **refresh-token**, och anropar sedan API:er med:

```http
Authorization: Bearer <access_token>
```

Officiellt referensmaterial (PDF från Garmins developer portal):

- [OAuth2 PKCE specification (Garmin)](https://developerportal.garmin.com/sites/default/files/OAuth2PKCE_1.pdf)

Typiskt flöde (exakta parameternamn och scopes finns i dokumentet och i din portalprojekt):

1. **Auktorisering (webbläsaromdirigering)**  
   Användaren öppnar en URL på Garmins auktoriseringsserver (t.ex. `https://connect.garmin.com/oauth2Confirm` med `response_type=code`, din `client_id`, `redirect_uri`, PKCE `code_challenge`, `code_challenge_method=S256` och `state`).

2. **Tokenbyte (backend)**  
   Din server skickar `POST` till token-endpoint (t.ex. `https://diauth.garmin.com/di-oauth2-service/oauth/token`) med `grant_type=authorization_code`, `code`, `client_id`, `client_secret`, `redirect_uri` och PKCE `code_verifier`.

3. **Förnya**  
   Innan access-token går ut: använd `grant_type=refresh_token` med refresh-token (se PDF för fält och svarsformat).

4. **Testa flödet**  
   Garmin har verktyg på utvecklarsidan, t.ex. OAuth authorize user:  
   [https://apis.garmin.com/tools/oauthAuthorizeUser](https://apis.garmin.com/tools/oauthAuthorizeUser)  
   (kräver inloggning med **client ID** och **client secret** från appregistreringen.)

## 3. Behörigheter och aktivitetsdata

- Efter samtycke: kontrollera vilka **scopes / behörigheter** användaren gett (t.ex. activity export). Wellness-endpoints i Garmins dokumentation (t.ex. user id, permissions) hjälper dig bekräfta vad du får hämta.
- **Activity API** ger aktivitetsdetaljer och filer som **FIT**, **GPX** och **TCX** när data synkats till Garmin Connect från användarens enhet.
- Exakta REST-sökvägar, frågeparametrar och push/ping-alternativ finns i **API-referensen** i developer portal efter godkännande – allt finns inte på den publika marknadssidan.

## 4. Koppla data till lotc

1. **Lagra token säkert** (miljövariabler eller valv för hemligheter). Committa aldrig `client_secret`, refresh-token eller access-token till git.
2. **Lista eller ta emot aktiviteter** via Activity API enligt dokumentationen för din integration (pull eller push).
3. **Ladda ner** aktivitetsfilen du behöver (t.ex. FIT eller GPX).
4. **Tolka** filen i Python (t.ex. `fitparse` för FIT eller `gpxpy` för GPX) och bygg samma struktur som `get_sample_workouts()`:
   - `route`: lista av `[latitud, longitud]` för kartpolylinjen.
   - `distance_km`, `duration_min`, `avg_pace_min_per_km` m.m. från sammanfattningsfält eller beräknat från spåret.
5. **Byt ut** anropet till `get_sample_workouts()` i `app/main.py` mot din funktion som laddar från Garmin (valfritt med lokal cache/databas).

## 5. FAQ och support

- [Program FAQ](https://developer.garmin.com/gc-developer-program/) (länkad från Activity API-sidan).
- För API-frågor efter godkännande: Garmins utvecklarstöd enligt portalen.

## 6. Checklista

| Steg | Åtgärd |
|------|--------|
| 1 | Ansök om / få **Garmin Connect Developer Program**-tillgång för din produkt. |
| 2 | Registrera app → **client_id** + **client_secret**, konfigurera **redirect URI** exakt. |
| 3 | Implementera **OAuth 2.0 + PKCE** och **token refresh**. |
| 4 | Anropa **Activity API** med `Authorization: Bearer` enligt portalens dokumentation. |
| 5 | Ladda ner **FIT/GPX/TCX**, tolka till lat/lng och mätvärden, mata in `Workout`-liknande dicts i appen. |