garmin-connect-personal-api-python 1.0.0__py3-none-any.whl

garmin_personal_api/__main__.py

@@ -0,0 +1,20 @@
+"""Run the package CLI with ``python -m garmin_personal_api``."""
+
+# Copyright 2026 Garmin Ltd. or its subsidiaries.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

garmin_personal_api/_credentials.py

@@ -0,0 +1,41 @@
+"""Shared credential validation and file-permission checks."""
+
+# Copyright 2026 Garmin Ltd. or its subsidiaries.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+from .errors import GarminPersonalApiError
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _require_nonempty_key(value: str, source: str) -> str:
+    key = value.strip()
+    if not key:
+        raise GarminPersonalApiError(f"The value from {source} is empty.")
+    return key
+
+
+def _warn_if_readable_by_others(path: Path, description: str) -> None:
+    if os.name == "posix" and path.stat().st_mode & 0o077:
+        _LOGGER.warning(
+            "%s %s is readable by group or other users; restrict it with chmod 600",
+            description,
+            path,
+        )

garmin_personal_api/_version.py

@@ -0,0 +1,17 @@
+"""Package version used by both runtime metadata and the build backend."""
+
+# Copyright 2026 Garmin Ltd. or its subsidiaries.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+__version__ = "1.0.0"

garmin_personal_api/api_keys.py

@@ -0,0 +1,64 @@
+"""Personal API key discovery."""
+
+# Copyright 2026 Garmin Ltd. or its subsidiaries.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from pathlib import Path
+
+from ._credentials import _require_nonempty_key, _warn_if_readable_by_others
+from .constants import DEFAULT_API_KEY_ENV_VAR, DEFAULT_API_KEY_FILE
+from .errors import GarminPersonalApiError
+
+
+def resolve_api_key(
+    api_key: str | None = None,
+    *,
+    env: Mapping[str, str] | None = None,
+    env_var: str = DEFAULT_API_KEY_ENV_VAR,
+    key_file: str | Path | None = None,
+) -> str:
+    """Resolve an explicit key, explicit file, environment, then default file.
+
+    Pass the result to ``PersonalApiAuthenticator.obtain_token()`` to opt into
+    discovery. An explicitly supplied ``key_file`` overrides the environment,
+    even when it names the default file. Invalid explicit sources do not fall
+    back to other sources.
+    """
+    if api_key is not None:
+        return _require_nonempty_key(api_key, "the explicit API key")
+
+    if key_file is None:
+        environment = os.environ if env is None else env
+        environment_value = environment.get(env_var)
+        if environment_value is not None:
+            return _require_nonempty_key(environment_value, f"environment variable {env_var}")
+
+    path = Path(DEFAULT_API_KEY_FILE if key_file is None else key_file).expanduser()
+    try:
+        file_value = path.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        if key_file is not None:
+            raise GarminPersonalApiError(
+                f"Personal API key file {path} does not exist."
+            ) from exc
+        raise GarminPersonalApiError(
+            "No personal API key was provided. Pass --api-key/api_key, set "
+            f"{env_var}, or create {path}."
+        ) from exc
+    _warn_if_readable_by_others(path, "Personal API key file")
+    return _require_nonempty_key(file_value, f"personal API key file {path}")

garmin_personal_api/auth.py

@@ -0,0 +1,188 @@
+"""Bearer-token authentication and caching."""
+
+# Copyright 2026 Garmin Ltd. or its subsidiaries.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import os
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from time import time
+
+import requests
+
+from ._credentials import _require_nonempty_key, _warn_if_readable_by_others
+from .constants import (
+    BASE_URL_ENV_VAR,
+    DEFAULT_BASE_URL,
+    DEFAULT_BEARER_TOKEN_CACHE_FILE,
+    DEFAULT_TIMEOUT_SECONDS,
+    TOKEN_PATH,
+)
+from .errors import GarminPersonalApiError, HttpError
+
+_BEARER_TOKEN_REFRESH_WINDOW_SECONDS = 60 * 60
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class BearerToken:
+    """A bearer token and its expiration time in seconds since the epoch."""
+
+    access_token: str = field(repr=False)
+    expires_at: float
+
+
+class PersonalApiAuthenticator:
+    """Cache bearer tokens and exchange a Garmin personal API key when needed.
+
+    Key discovery is separate from HTTP authentication. Pass :meth:`obtain_token`
+    a key from :func:`garmin_personal_api.api_keys.resolve_api_key` or from
+    another secret source.
+    """
+
+    def __init__(
+        self,
+        *,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        session: requests.Session | None = None,
+        bearer_token_cache_file: str | Path = DEFAULT_BEARER_TOKEN_CACHE_FILE,
+        clock: Callable[[], float] = time,
+    ) -> None:
+        if timeout <= 0:
+            raise GarminPersonalApiError("timeout must be greater than zero")
+        self.base_url = os.environ.get(BASE_URL_ENV_VAR, DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+        self.bearer_token_cache_file = Path(bearer_token_cache_file).expanduser()
+        self._clock = clock
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    def __enter__(self) -> PersonalApiAuthenticator:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(base_url={self.base_url!r}, timeout={self.timeout!r})"
+
+    def obtain_token(
+        self,
+        api_key: str,
+        *,
+        force_refresh: bool = False,
+    ) -> BearerToken:
+        """Return a cached bearer token or exchange the key for a new bearer token."""
+        if not isinstance(api_key, str):
+            raise GarminPersonalApiError(
+                "An API key string is required; use resolve_api_key() to discover one."
+            )
+        key = _require_nonempty_key(api_key, "the explicit API key")
+        # Cached tokens are only reused for the same API key and environment.
+        fingerprint = hashlib.sha256(f"{self.base_url}\0{key}".encode()).hexdigest()
+        if not force_refresh:
+            cached_token = self._read_cached_token(fingerprint)
+            if cached_token is not None:
+                if cached_token.expires_at - self._clock() > _BEARER_TOKEN_REFRESH_WINDOW_SECONDS:
+                    _LOGGER.info("Using cached bearer token")
+                    return cached_token
+                _LOGGER.info(
+                    "Cached bearer token is expired or expires within the 1-hour refresh "
+                    "window; requesting a new token"
+                )
+
+        url = f"{self.base_url}{TOKEN_PATH}"
+        _LOGGER.info("POST %s", TOKEN_PATH)
+        response = self._session.post(
+            url,
+            headers={"Accept": "*/*", "Authorization": f"ApiKey {key}"},
+            timeout=self.timeout,
+        )
+        if not response.ok:
+            raise HttpError(
+                status_code=response.status_code,
+                method="POST",
+                url=url,
+                response_text=response.text,
+            )
+
+        access_token = response.text.strip()
+        token = BearerToken(access_token=access_token, expires_at=_jwt_expiration(access_token))
+        self._write_cached_token(fingerprint, token)
+        _LOGGER.info("Received and cached a new bearer token")
+        return token
+
+    def _read_cached_token(self, fingerprint: str) -> BearerToken | None:
+        path = self.bearer_token_cache_file
+        try:
+            serialized = path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            _LOGGER.info(
+                "No cached bearer token found; requesting a new token"
+            )
+            return None
+        _warn_if_readable_by_others(path, "Bearer-token cache file")
+        try:
+            cache = json.loads(serialized)
+            if cache["fingerprint"] != fingerprint:
+                _LOGGER.info(
+                    "Cached bearer token fingerprint does not match the current API key or "
+                    "base URL; requesting a new token"
+                )
+                return None
+            return BearerToken(
+                access_token=cache["access_token"],
+                expires_at=float(cache["expires_at"]),
+            )
+        except (KeyError, TypeError, ValueError):
+            _LOGGER.warning("Ignoring invalid bearer-token cache file %s", path)
+            return None
+
+    def _write_cached_token(self, fingerprint: str, token: BearerToken) -> None:
+        path = self.bearer_token_cache_file
+        path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as cache_file:
+            json.dump(
+                {
+                    "fingerprint": fingerprint,
+                    "access_token": token.access_token,
+                    "expires_at": token.expires_at,
+                },
+                cache_file,
+            )
+
+
+def _jwt_expiration(access_token: str) -> float:
+    """Return the ``exp`` claim of a JWT without verifying its signature."""
+    try:
+        encoded_payload = access_token.split(".")[1]
+        payload = json.loads(
+            base64.urlsafe_b64decode(encoded_payload + "=" * (-len(encoded_payload) % 4))
+        )
+        return float(payload["exp"])
+    except (IndexError, KeyError, TypeError, ValueError) as exc:
+        raise GarminPersonalApiError(
+            "The token endpoint did not return a JWT with an exp claim."
+        ) from exc

garmin_personal_api/cli.py

@@ -0,0 +1,330 @@
+"""Command-line reference application for Garmin Personal API reads."""
+
+# Copyright 2026 Garmin Ltd. or its subsidiaries.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import logging
+import sys
+from collections.abc import Sequence
+from contextlib import nullcontext
+from datetime import date, datetime
+from functools import partial
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from . import __version__
+from .api_keys import resolve_api_key
+from .auth import PersonalApiAuthenticator
+from .client import GarminPersonalApiClient
+from .commands import COMMANDS, COMMANDS_BY_NAME, TOKEN_REFRESH_COMMAND, CommandSpec
+from .constants import (
+    DEFAULT_API_KEY_FILE,
+    DEFAULT_BEARER_TOKEN_CACHE_FILE,
+    DEFAULT_TIMEOUT_SECONDS,
+)
+from .downloads import save_download
+from .errors import GarminPersonalApiError
+from .interactive import (
+    _route_logs_to_status,
+    print_heading,
+    print_request_status,
+    run_interactive,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI argument parser from the endpoint registry."""
+    parser = argparse.ArgumentParser(
+        prog="gc-personal",
+        description="Retrieve Garmin data with a personal API key.",
+    )
+    parser.add_argument("--version", action="version", version=f"gc-personal {__version__}")
+    parser.add_argument(
+        "--api-key",
+        help=(
+            "Personal API key. Prefer the environment variable or key file to avoid "
+            "shell-history and process-list exposure."
+        ),
+    )
+    parser.add_argument(
+        "--api-key-file",
+        type=Path,
+        help=(
+            "Plain-text API key file; overrides GARMIN_PERSONAL_API_KEY unless --api-key "
+            f"is given. Without either option, use the environment variable, then "
+            f"{DEFAULT_API_KEY_FILE}."
+        ),
+    )
+    parser.add_argument(
+        "--bearer-token-cache-file",
+        type=Path,
+        default=DEFAULT_BEARER_TOKEN_CACHE_FILE,
+        help=f"Bearer-token cache file (default: {DEFAULT_BEARER_TOKEN_CACHE_FILE}).",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        help=f"Request timeout in seconds (default: {DEFAULT_TIMEOUT_SECONDS:g}).",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress request logging for non-interactive commands.",
+    )
+    parser.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable interactive terminal colors.",
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+    for spec in COMMANDS:
+        help_text = spec.description or (
+            f"{spec.label}." if spec.output_kind == "download" else f"Get {spec.label.lower()}."
+        )
+        subparser = subparsers.add_parser(spec.command, help=help_text, description=help_text)
+        _add_command_arguments(subparser, spec)
+    refresh_help = "Obtain and cache a new bearer token, replacing any cached token."
+    subparsers.add_parser(TOKEN_REFRESH_COMMAND, help=refresh_help, description=refresh_help)
+    return parser
+
+
+def _add_command_arguments(
+    parser: argparse.ArgumentParser,
+    spec: CommandSpec,
+) -> None:
+    today = date.today().isoformat()
+    if spec.input_kind == "date":
+        parser.add_argument(
+            "--date",
+            metavar="DATE",
+            default=today,
+            help="Calendar date in YYYY-MM-DD format (default: today).",
+        )
+    elif spec.input_kind == "date_with_today":
+        parser.add_argument(
+            "--date",
+            metavar="DATE",
+            default=today,
+            help="Calendar date in YYYY-MM-DD format (default: today).",
+        )
+        parser.add_argument(
+            "--today-date",
+            metavar="DATE",
+            default=today,
+            help="Reference today date in YYYY-MM-DD format (default: today).",
+        )
+    elif spec.input_kind == "date_range":
+        parser.add_argument(
+            "--start-date",
+            metavar="START_DATE",
+            default=today,
+            help="Start date in YYYY-MM-DD format (default: today).",
+        )
+        parser.add_argument(
+            "--end-date",
+            metavar="END_DATE",
+            default=today,
+            help="End date in YYYY-MM-DD format (default: today).",
+        )
+        if spec.command == "body-battery":
+            parser.add_argument(
+                "--chunks",
+                type=int,
+                default=1,
+                help="Number of min/max body battery pairs per day.",
+            )
+    elif spec.input_kind == "activities":
+        parser.add_argument(
+            "--start",
+            type=int,
+            default=0,
+            help="Zero-based result offset (default: 0).",
+        )
+        parser.add_argument(
+            "--limit",
+            type=int,
+            default=20,
+            metavar="COUNT",
+            help="Maximum number of activities to return (default: 20).",
+        )
+        parser.add_argument(
+            "--start-date",
+            metavar="DATE",
+            help="Optional start date in YYYY-MM-DD format.",
+        )
+        parser.add_argument(
+            "--end-date",
+            metavar="DATE",
+            help="Optional end date in YYYY-MM-DD format.",
+        )
+        parser.add_argument(
+            "--activity-type",
+            metavar="TYPE",
+            help="Optional activity type filter, such as running or hiking.",
+        )
+    elif spec.input_kind == "activity":
+        parser.add_argument(
+            "activity_id",
+            metavar="ACTIVITY_ID",
+            help=(
+                "Activity ID to download."
+                if spec.output_kind == "download"
+                else "Activity ID to look up."
+            ),
+        )
+    if spec.output_kind == "download":
+        parser.add_argument(
+            "-o",
+            "--output",
+            metavar="PATH",
+            help="Save ZIP to PATH (default: activity-ID.zip); '-' writes binary stdout.",
+        )
+        parser.add_argument("--force", action="store_true", help="Replace an existing output file.")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Authenticate once, then execute a command or open the interactive menu."""
+    args = build_parser().parse_args(argv)
+    interactive = args.command is None
+    refresh_only = args.command == TOKEN_REFRESH_COMMAND
+    if interactive and not _ensure_interactive_dependency():
+        return 1
+    _configure_logging(quiet=args.quiet or interactive)
+    color = False if args.no_color else None
+
+    try:
+        download = (
+            not interactive
+            and not refresh_only
+            and COMMANDS_BY_NAME[args.command].output_kind == "download"
+        )
+        if download and args.output == "-" and sys.stdout.isatty():
+            raise GarminPersonalApiError("Refusing to write ZIP bytes to a terminal; use -o PATH")
+        log_output = (
+            _route_logs_to_status(output=sys.stdout, color=color) if interactive else nullcontext()
+        )
+        with log_output:
+            api_key = resolve_api_key(args.api_key, key_file=args.api_key_file)
+            with PersonalApiAuthenticator(
+                timeout=args.timeout,
+                bearer_token_cache_file=args.bearer_token_cache_file,
+            ) as authenticator:
+                if interactive:
+                    print_heading("Garmin Personal API", output=sys.stdout, width=56, color=color)
+                    print_request_status(
+                        "Checking bearer-token cache",
+                        output=sys.stdout,
+                        color=color,
+                    )
+                token = authenticator.obtain_token(api_key, force_refresh=refresh_only)
+                if refresh_only:
+                    expires_at = datetime.fromtimestamp(token.expires_at).astimezone()
+                    print(
+                        "Cached a new bearer token that expires at "
+                        f"{expires_at.isoformat(timespec='seconds')}",
+                        file=sys.stderr,
+                    )
+                    return 0
+                with GarminPersonalApiClient(token.access_token, timeout=args.timeout) as client:
+                    if interactive:
+
+                        def refresh_token() -> None:
+                            refreshed = authenticator.obtain_token(api_key, force_refresh=True)
+                            client.update_bearer_token(refreshed.access_token)
+
+                        return run_interactive(
+                            client,
+                            color=color,
+                            show_header=False,
+                            refresh_token=refresh_token,
+                        )
+                    result = _execute_command(client, args)
+                    if download:
+                        if not isinstance(result, bytes):
+                            raise GarminPersonalApiError("Expected binary download content")
+                        if args.output == "-":
+                            sys.stdout.buffer.write(result)
+                            sys.stdout.buffer.flush()
+                        else:
+                            destination = save_download(
+                                result,
+                                Path(args.output or f"activity-{args.activity_id}.zip"),
+                                overwrite=args.force,
+                            )
+                            print(f"Saved {destination} ({len(result)} bytes)", file=sys.stderr)
+                        return 0
+    except (GarminPersonalApiError, requests.RequestException, OSError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    _print_json(result)
+    return 0
+
+
+def _execute_command(client: GarminPersonalApiClient, args: argparse.Namespace) -> Any:
+    spec = COMMANDS_BY_NAME[args.command]
+    method = partial(spec.method, client)
+    if spec.input_kind == "date":
+        return method(args.date)
+    if spec.input_kind == "date_with_today":
+        return method(args.date, args.today_date)
+    if spec.input_kind == "date_range":
+        if spec.command == "body-battery":
+            return method(args.start_date, args.end_date, chunks=args.chunks)
+        return method(args.start_date, args.end_date)
+    if spec.input_kind == "activities":
+        return method(
+            start=args.start,
+            limit=args.limit,
+            start_date=args.start_date,
+            end_date=args.end_date,
+            activity_type=args.activity_type,
+        )
+    if spec.input_kind == "activity":
+        return method(args.activity_id)
+    return method()
+
+
+def _ensure_interactive_dependency() -> bool:
+    try:
+        importlib.import_module("rich")
+    except ImportError:
+        print(
+            "Interactive mode requires the optional 'rich' dependency. "
+            "Install it with: pip install 'garmin-connect-personal-api-python[interactive]'",
+            file=sys.stderr,
+        )
+        return False
+    return True
+
+
+def _print_json(value: Any) -> None:
+    print(json.dumps(value, indent=2, ensure_ascii=False, sort_keys=True))
+
+
+def _configure_logging(*, quiet: bool) -> None:
+    """Configure this package's logger without replacing application handlers."""
+    level = logging.WARNING if quiet else logging.INFO
+    logging.getLogger(__package__).setLevel(level)
+    if not logging.root.handlers:
+        logging.basicConfig(level=level, format="%(levelname)s %(message)s")