Replace garth dependency with native DI OAuth authentication

Switch from garth-based OAuth/cookie login to the same mobile SSO flow
used by the official Garmin Connect Android app. Tokens are now stored
as garmin_tokens.json with auto-refresh via DI OAuth Bearer tokens.

- Add garminconnect/client.py with native SSO login, token exchange,
  and auto-refresh logic
- Add garminconnect/exceptions.py for standalone exception classes
- Update __init__.py to use new client instead of garth
- Simplify example.py and update demo.py error handling
- Update README with new auth docs and install instructions
- Update pyproject.toml dependencies (drop garth, add curl_cffi)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cyberjunky

.gitignore

@@ -1,7 +1,7 @@
 # Custom
 your_data/
 pdm.lock
-garth/
+.claude/
 
 # Virtual environments
 .venv/

README.md

@@ -8,6 +8,13 @@
 
 # Python: Garmin Connect
 
+> **Note:** Garmin has made significant changes to their authentication and API infrastructure.
+> The old `garth`-based OAuth/cookie login no longer works. This library now authenticates
+> using the same mobile SSO flow as the official Garmin Connect Android app, obtaining native
+> DI OAuth Bearer tokens. Saved tokens are stored in a new format (`garmin_tokens.json`) —
+> a fresh login is required after upgrading.
+> All existing API methods remain unchanged — no code changes needed on your end.
+
 The Garmin Connect API library comes with two examples:
 
 - **`example.py`** - Simple getting-started example showing authentication, token storage, and basic API calls
@@ -88,8 +95,7 @@ Compatible with all Garmin Connect accounts. See <https://connect.garmin.com/>
 Install from PyPI:
 
 ```bash
-python3 -m pip install --upgrade pip
-python3 -m pip install garminconnect
+pip install --upgrade garminconnect curl_cffi
 ```
 
 ## Run demo software (recommended)
@@ -180,41 +186,34 @@ Run these commands before submitting PRs to ensure code quality standards.
 
 ## 🔐 Authentication
 
-The library uses the same OAuth authentication as the official Garmin Connect app via [Garth](https://github.com/matin/garth).
+Authentication uses the same mobile SSO flow as the official Garmin Connect Android app.
+No browser is needed.
 
-**Key Features:**
-- Login credentials valid for one year (no repeated logins)
-- Secure OAuth token storage
-- Same authentication flow as official app
+**How it works:**
 
-**Advanced Configuration:**
-```python
-# Optional: Custom OAuth consumer (before login)
-import os
-import garth
-garth.sso.OAUTH_CONSUMER = {
-    'key': os.getenv('GARTH_OAUTH_KEY', '<YOUR_KEY>'),
-    'secret': os.getenv('GARTH_OAUTH_SECRET', '<YOUR_SECRET>'),
-}
-# Note: Set these env vars securely; placeholders are non-sensitive.
-```
+1. **First login**: Authenticates via `sso.garmin.com/mobile/api/login` using the Android
+   app's client ID. If MFA is required, a callback (`prompt_mfa`) prompts for the one-time code.
+2. **Token exchange**: The service ticket is exchanged for DI OAuth Bearer tokens
+   (`access_token` + `refresh_token`) via `diauth.garmin.com`. Tokens are stored at
+   `~/.garminconnect/garmin_tokens.json`.
+3. **Auto-refresh**: Before each API request the library checks whether the DI token is about
+   to expire and refreshes it automatically — no user interaction required.
 
-**Token Storage:**
-Tokens are automatically saved to `~/.garminconnect` directory for persistent authentication.
-For security, ensure restrictive permissions:
+**Session lifetime:**
+- DI tokens auto-refresh indefinitely as long as the refresh token remains valid.
+- A full re-login with credentials (and possibly MFA) is only needed if the refresh token
+  itself expires or is revoked.
 
+**Token storage:**
 ```bash
-chmod 700 ~/.garminconnect
-chmod 600 ~/.garminconnect/* 2>/dev/null || true
+~/.garminconnect/garmin_tokens.json   # saved automatically, mode 0600
 ```
 
 ## 🧪 Testing
 
-Run the test suite to verify functionality:
-
 **Prerequisites:**
 
-Create tokens in ~/.garminconnect by running the example program.
+Run `example.py` once to create saved tokens in `~/.garminconnect`.
 
 ```bash
 # Install development dependencies
@@ -232,13 +231,13 @@ Optional: keep test tokens isolated
 
 ```bash
 export GARMINTOKENS="$(mktemp -d)"
-python3 ./example.py # create fresh tokens for tests
+python3 ./example.py   # create a fresh token file for tests
 pdm run test
 ```
 
-**Note:** Tests automatically use `~/.garminconnect` as the default token file location. You can override this by setting the `GARMINTOKENS` environment variable. Run `example.py` first to generate authentication tokens for testing.
-
-**For Developers:** Tests use VCR cassettes to record/replay HTTP interactions. If tests fail with authentication errors, ensure valid tokens exist in `~/.garminconnect`
+**Note:** Tests use VCR cassettes to record/replay API responses. If tests fail with
+authentication errors, ensure valid tokens exist in `~/.garminconnect` (run
+`example.py` first).
 
 ## 📦 Publishing
 
@@ -326,23 +325,25 @@ Explore the API interactively with our [reference notebook](https://github.com/c
 ### Python Code Examples
 
 ```python
-from garminconnect import Garmin
 import os
+from datetime import date
+from garminconnect import Garmin
 
-# Initialize and login
+# First run: logs in and saves tokens to ~/.garminconnect
+# Subsequent runs: loads saved tokens and auto-refreshes
 client = Garmin(
-    os.getenv("GARMIN_EMAIL", "<YOUR_EMAIL>"),
-    os.getenv("GARMIN_PASSWORD", "<YOUR_PASSWORD>")
+    os.getenv("EMAIL"),
+    os.getenv("PASSWORD"),
+    prompt_mfa=lambda: input("MFA code: "),
 )
-client.login()
+client.login("~/.garminconnect")
 
 # Get today's stats
-from datetime import date
-_today = date.today().strftime('%Y-%m-%d')
-stats = client.get_stats(_today)
+today = date.today().isoformat()
+stats = client.get_stats(today)
 
 # Get heart rate data
-hr_data = client.get_heart_rates(_today)
+hr_data = client.get_heart_rates(today)
 print(f"Resting HR: {hr_data.get('restingHeartRate', 'n/a')}")
 ```
 

demo.py

@@ -8,11 +8,11 @@
 For a simple getting-started example, see example.py
 
 Dependencies:
-pip3 install garth requests readchar
+pip3 install requests readchar
 
 Environment Variables (optional):
-export EMAIL=<your garmin email address>
-export PASSWORD=<your garmin password>
+export GARMIN_EMAIL=<your garmin email address>
+export GARMIN_PASSWORD=<your garmin password>
 export GARMINTOKENS=<path to token storage>
 """
 
@@ -29,7 +29,6 @@
 
 import readchar
 import requests
-from garth.exc import GarthException, GarthHTTPError
 
 from garminconnect import (
     Garmin,
@@ -73,12 +72,9 @@ class Config:
 
     def __init__(self):
         # Load environment variables
-        self.email = os.getenv("EMAIL")
-        self.password = os.getenv("PASSWORD")
+        self.email = os.getenv("GARMIN_EMAIL") or os.getenv("EMAIL")
+        self.password = os.getenv("GARMIN_PASSWORD") or os.getenv("PASSWORD")
         self.tokenstore = os.getenv("GARMINTOKENS") or "~/.garminconnect"
-        self.tokenstore_base64 = (
-            os.getenv("GARMINTOKENS_BASE64") or "~/.garminconnect_base64"
-        )
 
         # Date settings
         self.today = datetime.date.today()
@@ -1094,7 +1090,7 @@ def safe_api_call(api_method, *args, method_name: str | None = None, **kwargs):
         result = api_method(*args, **kwargs)
         return True, result, None
 
-    except GarthHTTPError as e:
+    except GarminConnectConnectionError as e:
         # Handle specific HTTP errors more gracefully
         error_str = str(e)
 
@@ -1145,7 +1141,7 @@ def safe_api_call(api_method, *args, method_name: str | None = None, **kwargs):
         print(f"⚠️ {method_name} failed: {error_msg}")
         return False, None, error_msg
 
-    except GarminConnectConnectionError as e:
+    except GarminConnectConnectionError as e:  # noqa: B025
         error_str = str(e)
         # Extract a clean message by detecting common HTTP status codes
         if "410" in error_str:
@@ -3425,16 +3421,16 @@ def get_virtual_challenges_data(api: Garmin) -> None:
     # that don't have virtual challenges enabled, so handle it quietly
     try:
         challenges = api.get_inprogress_virtual_challenges(
-            config.start, config.default_limit
+            config.start_badge, config.default_limit
         )
         if challenges:
             print("✅ Virtual challenges data retrieved successfully")
             call_and_display(
                 api.get_inprogress_virtual_challenges,
-                config.start,
+                config.start_badge,
                 config.default_limit,
                 method_name="get_inprogress_virtual_challenges",
-                api_call_desc=f"api.get_inprogress_virtual_challenges({config.start}, {config.default_limit})",
+                api_call_desc=f"api.get_inprogress_virtual_challenges({config.start_badge}, {config.default_limit})",
             )
             return
         print("ℹ️ No in-progress virtual challenges found")
@@ -4152,7 +4148,6 @@ def init_api(email: str | None = None, password: str | None = None) -> Garmin |
 
     except (
         FileNotFoundError,
-        GarthHTTPError,
         GarminConnectAuthenticationError,
         GarminConnectConnectionError,
     ):
@@ -4182,31 +4177,24 @@ def init_api(email: str | None = None, password: str | None = None) -> Garmin |
                     garmin.resume_login(result2, mfa_code)
                     print("✅ MFA authentication successful!")
 
-                except GarthHTTPError as garth_error:
-                    # Handle specific HTTP errors from MFA
-                    error_str = str(garth_error)
+                except GarminConnectTooManyRequestsError:
+                    print("❌ Too many MFA attempts")
+                    print("💡 Please wait 30 minutes before trying again")
+                    sys.exit(1)
+                except GarminConnectAuthenticationError as mfa_error:
+                    # Handle specific errors from MFA
+                    error_str = str(mfa_error)
                     print(f"🔍 Debug: MFA error details: {error_str}")
-
-                    if "429" in error_str and "Too Many Requests" in error_str:
-                        print("❌ Too many MFA attempts")
-                        print("💡 Please wait 30 minutes before trying again")
-                        sys.exit(1)
-                    elif "401" in error_str or "403" in error_str:
+                    if "401" in error_str or "403" in error_str:
                         print("❌ Invalid MFA code")
                         print("💡 Please verify your MFA code and try again")
                         continue
-                    else:
-                        # Other HTTP errors - don't retry
-                        print(f"❌ MFA authentication failed: {garth_error}")
-                        sys.exit(1)
-
-                except GarthException as garth_error:
-                    print(f"❌ MFA authentication failed: {garth_error}")
-                    print("💡 Please verify your MFA code and try again")
-                    continue
+                    # Other HTTP errors - don't retry
+                    print(f"❌ MFA authentication failed: {mfa_error}")
+                    sys.exit(1)
 
             # Save tokens for future use
-            garmin.garth.dump(config.tokenstore)
+            garmin.client.dump(config.tokenstore)
             print(f"Login successful! Tokens saved to: {config.tokenstore}")
 
             return garmin
@@ -4225,8 +4213,6 @@ def init_api(email: str | None = None, password: str | None = None) -> Garmin |
 
         except (
             FileNotFoundError,
-            GarthHTTPError,
-            GarthException,
             GarminConnectConnectionError,
             requests.exceptions.HTTPError,
         ) as err: