# Quickstart: Implementing Persisted Garmin Authentication

**Date**: 2025-12-22

This guide provides a high-level overview for developers implementing the `Persist Garmin Authentication for Stateless Sync` feature.

## 1. Database Model

-   **Action**: Implement the `GarminAuthenticationState` model as defined in `data-model.md`.
-   **File**: Create a new model in `src/models/garmin_auth_state.py`.
-   **Details**: Ensure the model includes `user_id`, `session_data`, `mfa_pending`, and `last_validated` fields. Use SQLAlchemy and create a corresponding Alembic migration script.

## 2. API Endpoints

-   **Action**: Implement the three new endpoints defined in `contracts/garmin_auth_session.json`.
-   **Files**: Add a new router in `src/api/v1/auth.py`.
-   **Logic**:
    -   `POST /api/v1/garmin/session/login`:
        -   Initialize `garth`.
        -   Call `garth.login(username, password)`.
        -   If `garth.MFARequired` is raised, create/update the `GarminAuthenticationState` record with `mfa_pending=True` and return `{"status": "MFA_REQUIRED"}`.
        -   If successful, `dumps()` the session, save it to `session_data`, set `mfa_pending=False`, and return `{"status": "SUCCESS"}`.
    -   `POST /api/v1/garmin/session/mfa`:
        -   Load the pending `garth` client state.
        -   Call `garth.enter_mfa(mfa_code)`.
        -   On success, `dumps()` the completed session and persist it to the database.
    -   `GET /api/v1/garmin/session/status`:
        -   Query the `GarminAuthenticationState` for the current user.
        -   Perform a lightweight validation call with the loaded session (e.g., `garth.connectapi.get_user_settings()`).
        -   Return the status (`VALID`, `MISSING`, `EXPIRED`, `MFA_PENDING`).

## 3. Update Background Sync Services

-   **Action**: Modify the existing background sync services (`GarminActivityService`, `GarminHealthService`) to use the persisted session.
-   **Files**: Update the relevant service files in `src/services/`.
-   **Pattern: Load-Use-Update**:
    1.  **Load**: At the start of the job, fetch the `session_data` from the database.
    2.  **Initialize**: Call `garth.client.loads(session_data)` to initialize the client.
    3.  **Use**: Perform the sync operations. `garth` will handle automatic token refreshes.
    4.  **Update**: Before the job finishes, check if the session was modified (refreshed). If so, `dumps()` the new session and update the `session_data` field in the database. This is critical for maintaining a fresh session for the next job.

## 4. Error Handling

-   Implement logic to catch `garth` exceptions for invalid sessions.
-   If a session is invalid and cannot be refreshed, update the sync job status to `AUTH_EXPIRED` and clear the `session_data` from the database.

## 5. Testing

-   Write unit tests for the new API endpoints and the Load-Use-Update pattern.
-   Write integration tests that cover the full login (including MFA) and background sync flow.
-   Mock the `garth` library to simulate different scenarios: successful login, MFA required, invalid session, and token refresh.