sweatstack 0.75.0__tar.gz → 0.76.0__tar.gz

{sweatstack-0.75.0 → sweatstack-0.76.0}/.claude/skills/sweatstack-python/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: sweatstack-python
 description: >
-  Builds Python applications using the SweatStack client library (pip install sweatstack).
+  Builds Python applications using the SweatStack client library (uv add sweatstack).
   Covers authentication, activity and trace data retrieval, pandas DataFrames, Streamlit
   dashboards, FastAPI backends, user delegation, teams, and file uploads. Use when writing
   Python scripts, notebooks, Streamlit apps, or FastAPI services that access SweatStack
@@ -13,9 +13,9 @@ description: >
 
 Python client library for the SweatStack sports data platform.
 
-**Install:** `pip install sweatstack`
+**Install:** `uv add sweatstack`
 
-**Extras:** `pip install sweatstack[streamlit]` · `pip install sweatstack[fastapi]`
+**Extras:** `uv add sweatstack[streamlit]` · `uv add sweatstack[fastapi]`
 
 ## Quick Start
 

{sweatstack-0.75.0 → sweatstack-0.76.0}/.claude/skills/sweatstack-python/client.md

@@ -381,6 +381,42 @@ sweatstack.authenticate()
 df = sweatstack.get_latest_activity_data()
 ```
 
+## Error Handling
+
+All errors raised by the library are subclasses of `SweatStackError`. Consumers never need to import `httpx`.
+
+```python
+from sweatstack import (
+    SweatStackError,            # base — catch-all
+    SweatStackConnectionError,  # DNS, timeout, connection refused
+    SweatStackTokenRefreshError,# token refresh failed (expired/missing)
+    SweatStackAPIError,         # HTTP error response (has status_code, url, method, body, request_id)
+    SweatStackAuthError,        # 401, 403
+    SweatStackNotFoundError,    # 404
+    SweatStackRateLimitError,   # 429 (has retry_after)
+    SweatStackBadRequestError,  # other 4xx
+    SweatStackServerError,      # 5xx
+)
+```
+
+Typical usage:
+
+```python
+try:
+    activity = client.get_activity("nonexistent_id")
+except SweatStackNotFoundError:
+    print("Activity doesn't exist")
+except SweatStackServerError as e:
+    print(f"Server error (transient): {e.status_code}")
+except SweatStackAPIError as e:
+    print(f"API error: {e.status_code} {e.body}")
+```
+
+Hierarchy:
+- `SweatStackConnectionError`, `SweatStackTokenRefreshError`, and `SweatStackAPIError` are all direct children of `SweatStackError`.
+- All HTTP-response errors (`SweatStackAuthError`, `SweatStackNotFoundError`, etc.) are subclasses of `SweatStackAPIError` and carry `status_code`, `url`, `method`, `request_id`, and `body` attributes.
+- `SweatStackRateLimitError` additionally has `retry_after: int | None`.
+
 ## Gotchas
 
 - **Sport enum uses underscores:** `Sport.cycling_road`, not `Sport("road")` or `Sport.cycling.road`. String values use dots: `"cycling.road"`.

{sweatstack-0.75.0 → sweatstack-0.76.0}/CHANGELOG.md

@@ -6,6 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.76.0] - 2026-04-27
+
+### Added
+- Typed exception hierarchy (`sweatstack.exceptions`). All API errors now raise specific exception types: `SweatStackAuthError` (401/403), `SweatStackNotFoundError` (404), `SweatStackRateLimitError` (429), `SweatStackBadRequestError` (other 4xx), `SweatStackServerError` (5xx). Transport failures raise `SweatStackConnectionError`.
+- Structured error metadata on all API exceptions: `status_code`, `url`, `method`, `request_id`, `body`.
+
+### Changed
+- **BREAKING:** All client methods now raise `SweatStackAPIError` subclasses instead of `httpx.HTTPStatusError`. Code that catches `httpx.HTTPStatusError` must switch to catching `SweatStackAPIError` (or a specific subclass).
+- **BREAKING:** `TokenRefreshError` renamed to `SweatStackTokenRefreshError` and moved to `sweatstack.exceptions`. Import path changed from `from sweatstack import TokenRefreshError` to `from sweatstack import SweatStackTokenRefreshError`.
+- **BREAKING:** 422 responses now raise `SweatStackBadRequestError` instead of `ValueError`.
+- Transport errors (DNS, timeouts, connection refused) now raise `SweatStackConnectionError` instead of leaking raw httpx exceptions.
+
+### Removed
+- `httpx` is no longer part of the public error surface. Consumers do not need to import `httpx` to handle errors.
+
+
 ## [0.75.0] - 2026-04-23
 
 ### Added

{sweatstack-0.75.0 → sweatstack-0.76.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.75.0
+Version: 0.76.0
 Summary: The official Python client for SweatStack
 Project-URL: Homepage, https://sweatstack.no
 Project-URL: Documentation, https://developer.sweatstack.no/getting-started/

sweatstack-0.76.0/plans/002_TYPED_EXCEPTIONS.md

@@ -0,0 +1,269 @@
+# Typed exception hierarchy for the SweatStack client
+
+## Context
+
+The `sweatstack` Python client currently surfaces `httpx.HTTPStatusError`
+directly to consumers via `Client._raise_for_status` /
+`Client._print_response_and_raise` (`src/sweatstack/client.py:968-997`).
+
+This has two problems:
+
+1. **Consumers can't branch on error kind without inspecting status codes.**
+   Telling apart "upstream is down" (5xx, transient) from "you sent bad input"
+   (4xx, your bug) requires `exc.response.status_code`. That's the leaky
+   abstraction a client library exists to absorb.
+2. **`httpx` is an implementation detail.** Any consumer that wants to handle
+   errors must `import httpx` to catch `HTTPStatusError`. If the transport
+   ever changes, every consumer breaks.
+
+## Exception hierarchy
+
+```
+SweatStackError                       # base -- catch-all for anything sweatstack-related
+├── SweatStackConnectionError         # transport-level: DNS, timeout, no response
+├── SweatStackTokenRefreshError       # client-side auth failure (before any request)
+└── SweatStackAPIError                # HTTP response with error status
+    ├── SweatStackAuthError           # 401, 403
+    ├── SweatStackNotFoundError       # 404
+    ├── SweatStackRateLimitError      # 429 -- exposes retry_after
+    ├── SweatStackBadRequestError     # other 4xx
+    └── SweatStackServerError         # 5xx
+```
+
+`SweatStackTokenRefreshError` is a direct child of `SweatStackError`, not of
+`SweatStackAPIError`. Token refresh is a client-side operation that happens
+before a request is made -- it has no status code, no URL, no method. Forcing
+it under `SweatStackAPIError` would violate Liskov: every `SweatStackAPIError`
+guarantees `status_code: int`, and a token refresh failure can't provide one.
+
+### Attributes on `SweatStackAPIError`
+
+```python
+class SweatStackAPIError(SweatStackError):
+    status_code: int
+    url: str
+    method: str
+    request_id: str | None   # from X-Request-ID header, if present
+    body: dict | str | None  # parsed JSON if possible, else raw text, else None
+```
+
+`SweatStackRateLimitError` adds `retry_after: int | None` (seconds, from
+`Retry-After` header).
+
+`SweatStackConnectionError` and `SweatStackTokenRefreshError` take only a
+`message: str`.
+
+### Why these classes
+
+| Class | Reason |
+|---|---|
+| `SweatStackServerError` | The most important new class. `except SweatStackServerError` handles "upstream is unhappy" without catching consumer bugs. |
+| `SweatStackBadRequestError` | Separate from server errors: don't retry, surface to developers. Different remediation = different class. |
+| `SweatStackNotFoundError` | 404 is often domain-meaningful ("trace was deleted"), not a bug. Consumers want to handle it as a business case. |
+| `SweatStackRateLimitError` | Reserves the class even if the API isn't rate-limited today. Zero cost, prevents future refactoring. |
+| `SweatStackConnectionError` | Covers `httpx.ConnectError`, `httpx.ReadTimeout`, etc. Currently these leak through as raw httpx types. |
+| `SweatStackAuthError` | Groups 401/403 HTTP responses. |
+| `SweatStackTokenRefreshError` | Client-side auth failure. Sibling of `SweatStackAPIError`, not child -- no HTTP response data to carry. |
+
+## Implementation
+
+### 1. New module: `src/sweatstack/exceptions.py`
+
+Define the full hierarchy. Pure module -- no imports from `client.py`, no
+`httpx`. This is the public error contract.
+
+```python
+class SweatStackError(Exception):
+    """Base exception for all SweatStack errors."""
+
+class SweatStackConnectionError(SweatStackError):
+    """Transport-level failure: DNS, connect timeout, read timeout, no response."""
+
+class SweatStackTokenRefreshError(SweatStackError):
+    """Token refresh failed (expired, missing, or refresh request failed)."""
+
+class SweatStackAPIError(SweatStackError):
+    """HTTP response with an error status code."""
+    def __init__(self, *, status_code, url, method, request_id=None, body=None):
+        self.status_code = status_code
+        self.url = url
+        self.method = method
+        self.request_id = request_id
+        self.body = body
+        super().__init__(self._format_message())
+
+    def _format_message(self):
+        msg = f"{self.status_code}: {self.method} {self.url}"
+        if self.request_id:
+            msg += f" (request_id={self.request_id})"
+        if self.body:
+            msg += f" — {self.body}"
+        return msg
+
+    def __repr__(self):
+        return (
+            f"{type(self).__name__}(status_code={self.status_code!r}, "
+            f"method={self.method!r}, url={self.url!r})"
+        )
+
+class SweatStackAuthError(SweatStackAPIError):
+    """401 or 403: authentication or authorization failure."""
+
+class SweatStackNotFoundError(SweatStackAPIError):
+    """404: resource not found."""
+
+class SweatStackRateLimitError(SweatStackAPIError):
+    """429: rate limited."""
+    def __init__(self, *, retry_after=None, **kwargs):
+        self.retry_after = retry_after
+        super().__init__(**kwargs)
+
+class SweatStackBadRequestError(SweatStackAPIError):
+    """4xx (not 401, 403, 404, 429): client sent invalid input."""
+
+class SweatStackServerError(SweatStackAPIError):
+    """5xx: server-side failure, transient, safe to retry for idempotent ops."""
+```
+
+### 2. Translation in `client.py`
+
+Replace `_raise_for_status` and `_print_response_and_raise` with a single
+translation point:
+
+```python
+def _raise_for_status(self, response: httpx.Response) -> None:
+    if response.is_success:
+        return
+
+    status = response.status_code
+    body = self._parse_error_body(response)
+    request_id = response.headers.get("x-request-id")
+    common = dict(
+        status_code=status,
+        url=str(response.request.url),
+        method=response.request.method,
+        request_id=request_id,
+        body=body,
+    )
+
+    if status in (401, 403):
+        raise SweatStackAuthError(**common)
+    if status == 404:
+        raise SweatStackNotFoundError(**common)
+    if status == 429:
+        retry_after = int(response.headers.get("retry-after", "0")) or None
+        raise SweatStackRateLimitError(retry_after=retry_after, **common)
+    if 400 <= status < 500:
+        raise SweatStackBadRequestError(**common)
+    if 500 <= status < 600:
+        raise SweatStackServerError(**common)
+    # Fallback (e.g. 3xx that wasn't followed) -- shouldn't happen
+    raise SweatStackAPIError(**common)
+
+@staticmethod
+def _parse_error_body(response: httpx.Response) -> dict | str | None:
+    try:
+        return response.json()
+    except Exception:
+        text = response.text
+        return text if text else None
+```
+
+Wrap transport-level errors at the HTTP call site:
+
+```python
+try:
+    response = self._http_client.request(...)
+except httpx.HTTPError as exc:
+    raise SweatStackConnectionError(str(exc)) from exc
+self._raise_for_status(response)
+```
+
+### 3. Remove `_print_response_and_raise` and `_add_note`
+
+These exist only to annotate `httpx.HTTPStatusError` with response text.
+The new exceptions carry `body` natively, so these methods are dead code.
+
+### 4. Clean up the 422 special case
+
+The current code raises `ValueError(response.json())` for 422. This should
+raise `SweatStackBadRequestError` like any other 4xx. The parsed validation
+error body lands in `body` where consumers can inspect it.
+
+### 5. Clean up the 401/Streamlit special case
+
+`_raise_for_status` currently detects Streamlit and adds a hint note on 401.
+After this change, it raises `SweatStackAuthError`. The Streamlit hint (if
+still wanted) moves to the Streamlit integration layer, not the core error
+path.
+
+### 6. Move `TokenRefreshError` to `exceptions.py`
+
+- Rename to `SweatStackTokenRefreshError`.
+- Parent is `SweatStackError` (not `SweatStackAPIError`).
+- Remove old definition from `client.py`.
+- Import in `client.py` from `exceptions.py`.
+
+### 7. Update `__init__.py` exports
+
+```python
+from .client import *
+from .exceptions import (
+    SweatStackError,
+    SweatStackConnectionError,
+    SweatStackTokenRefreshError,
+    SweatStackAPIError,
+    SweatStackAuthError,
+    SweatStackNotFoundError,
+    SweatStackRateLimitError,
+    SweatStackBadRequestError,
+    SweatStackServerError,
+)
+```
+
+### 8. Tests
+
+Unit tests covering each status branch (401, 403, 404, 429, 400, 422, 500,
+502, 503, network error). Each test asserts:
+- Correct exception type raised
+- `status_code`, `url`, `method`, `body` populated correctly
+- `request_id` populated when header present
+- `retry_after` populated for 429
+- Inheritance: e.g. `SweatStackServerError` is caught by
+  `except SweatStackAPIError` and `except SweatStackError`
+- `__repr__` produces structured output suitable for logging
+
+## Backwards incompatibilities
+
+Since no external consumers exist yet, these are listed for completeness and
+to inform the changelog for the first stable release.
+
+| What changed | Before | After |
+|---|---|---|
+| HTTP error exceptions | `httpx.HTTPStatusError` | `SweatStackAPIError` subclasses |
+| 422 responses | `ValueError(response.json())` | `SweatStackBadRequestError` |
+| Transport errors (DNS, timeout) | Raw `httpx.ConnectError`, `httpx.ReadTimeout`, etc. | `SweatStackConnectionError` |
+| `TokenRefreshError` class name | `TokenRefreshError` | `SweatStackTokenRefreshError` |
+| `TokenRefreshError` base class | `Exception` | `SweatStackError` |
+| `TokenRefreshError` import path | `from sweatstack import TokenRefreshError` or `from sweatstack.client import TokenRefreshError` | `from sweatstack import SweatStackTokenRefreshError` or `from sweatstack.exceptions import SweatStackTokenRefreshError` |
+| 401 + Streamlit hint | Appended as exception note on `httpx.HTTPStatusError` | `SweatStackAuthError` raised; Streamlit hint moves to Streamlit integration layer |
+| `_print_response_and_raise` | Public-ish method on `Client` | Removed |
+| `_add_note` | Helper on `Client` | Removed |
+
+## Out of scope
+
+- **Built-in retry on 5xx / 429.** Clean follow-up once typed exceptions exist.
+- **Idempotency keys on POST.** Requires API-side support.
+- **Native async client.** Separate effort.
+
+## Acceptance criteria
+
+- All public client methods that previously raised `httpx.HTTPStatusError`
+  raise a `SweatStackAPIError` subclass appropriate to the status code.
+- All transport-level failures raise `SweatStackConnectionError`.
+- `httpx` types never appear in the public API surface.
+- `SweatStackTokenRefreshError` is importable from `sweatstack.exceptions`
+  and `sweatstack`.
+- Unit tests cover each status branch and verify exception type, attributes,
+  and inheritance.
+- All `SweatStackAPIError` instances have a useful `__repr__` for debugging.

{sweatstack-0.75.0 → sweatstack-0.76.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sweatstack"
-version = "0.75.0"
+version = "0.76.0"
 description = "The official Python client for SweatStack"
 readme = "README.md"
 license = "MIT"

sweatstack-0.76.0/src/sweatstack/__init__.py

@@ -0,0 +1,12 @@
+from .client import *  # noqa: F403
+from .exceptions import (
+    SweatStackError,
+    SweatStackConnectionError,
+    SweatStackTokenRefreshError,
+    SweatStackAPIError,
+    SweatStackAuthError,
+    SweatStackNotFoundError,
+    SweatStackRateLimitError,
+    SweatStackBadRequestError,
+    SweatStackServerError,
+)

{sweatstack-0.75.0 → sweatstack-0.76.0}/src/sweatstack/client.py

@@ -28,6 +28,16 @@ import pandas as pd
 from platformdirs import user_cache_dir, user_data_dir
 
 from .constants import DEFAULT_URL
+from .exceptions import (
+    SweatStackAPIError,
+    SweatStackAuthError,
+    SweatStackBadRequestError,
+    SweatStackConnectionError,
+    SweatStackNotFoundError,
+    SweatStackRateLimitError,
+    SweatStackServerError,
+    SweatStackTokenRefreshError,
+)
 from .schemas import (
     ActivityDetails, ActivitySummary, ApplicationMemberRole, AuthorizedTeamResponse,
     BackfillStatus, DailyMeasure, DailyResponse,
@@ -56,16 +66,6 @@ def enable_cache(path: str | None = None) -> None:
     _cache_config = {"path": path}
 
 
-class TokenRefreshError(Exception):
-    """Raised when automatic token refresh fails.
-
-    This can happen when:
-    - The refresh token is missing
-    - The refresh token has expired
-    - The token refresh request fails
-    """
-
-    pass
 
 
 AUTH_SUCCESSFUL_RESPONSE = """<!DOCTYPE html>
@@ -340,15 +340,15 @@ class _OAuth2Mixin:
         if redirect_uri:
             token_data["redirect_uri"] = redirect_uri
 
-        response = httpx.post(
-            f"{self.url}/api/v1/oauth/token",
-            data=token_data,
-        )
-
         try:
-            self._raise_for_status(response)
-        except httpx.HTTPStatusError as e:
-            raise Exception(f"Token exchange failed: {e}") from e
+            response = httpx.post(
+                f"{self.url}/api/v1/oauth/token",
+                data=token_data,
+            )
+        except httpx.HTTPError as exc:
+            raise SweatStackConnectionError(str(exc)) from exc
+
+        self._raise_for_status(response)
 
         token_response = TokenResponse.model_validate(response.json())
 
@@ -773,7 +773,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             New access token string.
 
         Raises:
-            TokenRefreshError: If the refresh request fails.
+            SweatStackTokenRefreshError: If the refresh request fails.
         """
         with self._http_client(skip_token_check=True) as client:
             response = client.post(
@@ -789,8 +789,8 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
 
             try:
                 self._raise_for_status(response)
-            except httpx.HTTPStatusError as e:
-                raise TokenRefreshError(f"Token refresh request failed: {e}") from e
+            except SweatStackAPIError as e:
+                raise SweatStackTokenRefreshError(f"Token refresh request failed: {e}") from e
 
             return response.json()["access_token"]
 
@@ -805,16 +805,16 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             Valid access token (original if not expired, refreshed otherwise).
 
         Raises:
-            TokenRefreshError: If the token is expired and refresh fails.
+            SweatStackTokenRefreshError: If the token is expired and refresh fails.
         """
         try:
             payload = decode_jwt_body(access_token)
         except Exception as e:
-            raise TokenRefreshError(f"Invalid access token: {e}") from e
+            raise SweatStackTokenRefreshError(f"Invalid access token: {e}") from e
 
         expires_at = payload.get("exp")
         if expires_at is None:
-            raise TokenRefreshError("Access token missing 'exp' claim")
+            raise SweatStackTokenRefreshError("Access token missing 'exp' claim")
 
         is_expired = expires_at - TOKEN_EXPIRY_MARGIN_SECONDS < time.time()
         if not is_expired:
@@ -822,7 +822,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
 
         # Token needs refresh
         if refresh_token is None:
-            raise TokenRefreshError(
+            raise SweatStackTokenRefreshError(
                 "Access token expired but no refresh token available. "
                 "Call client.authenticate(force=True) to re-authenticate."
             )
@@ -850,7 +850,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             SecretStr containing the access token, or None if not authenticated.
 
         Raises:
-            TokenRefreshError: If the token is expired and refresh fails.
+            SweatStackTokenRefreshError: If the token is expired and refresh fails.
         """
         access_token, refresh_token = self._load_token_pair()
 
@@ -934,6 +934,9 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         """
         Creates an httpx client with the base URL and authentication headers pre-configured.
 
+        Transport-level errors (DNS, timeouts, connection refused) are caught and
+        re-raised as SweatStackConnectionError so consumers never see raw httpx types.
+
         Args:
             skip_token_check: If True, uses the raw _api_key without triggering token expiry check.
                               This prevents recursive token refresh attempts.
@@ -951,50 +954,47 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         if token:
             headers["Authorization"] = f"Bearer {token.get_secret_value()}"
 
-        with httpx.Client(base_url=self.url, headers=headers, timeout=60) as client:
-            yield client
+        try:
+            with httpx.Client(base_url=self.url, headers=headers, timeout=60) as client:
+                yield client
+        except httpx.HTTPError as exc:
+            raise SweatStackConnectionError(str(exc)) from exc
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.is_success:
+            return
+
+        status = response.status_code
+        body = self._parse_error_body(response)
+        request_id = response.headers.get("x-request-id")
+        common = dict(
+            status_code=status,
+            url=str(response.request.url),
+            method=response.request.method,
+            request_id=request_id,
+            body=body,
+        )
 
-    @staticmethod
-    def _add_note(exception: Exception, note: str):
-        """Add a note to an exception, compatible with Python <3.11."""
-        if hasattr(exception, "add_note"):
-            exception.add_note(note)
-        else:
-            if not exception.args:
-                exception.args = (note,)
-            else:
-                exception.args = (f"{exception.args[0]}\n{note}",) + exception.args[1:]
+        if status in (401, 403):
+            raise SweatStackAuthError(**common)
+        if status == 404:
+            raise SweatStackNotFoundError(**common)
+        if status == 429:
+            retry_after = int(response.headers.get("retry-after", "0")) or None
+            raise SweatStackRateLimitError(retry_after=retry_after, **common)
+        if 400 <= status < 500:
+            raise SweatStackBadRequestError(**common)
+        if 500 <= status < 600:
+            raise SweatStackServerError(**common)
+        raise SweatStackAPIError(**common)
 
-    def _print_response_and_raise(self, response: httpx.Response):
+    @staticmethod
+    def _parse_error_body(response: httpx.Response) -> dict | str | None:
         try:
-            response.raise_for_status()
-        except httpx.HTTPStatusError as exception:
-            additional_info = response.text
-            self._add_note(exception, additional_info)
-            raise exception
-
-    def _raise_for_status(self, response: httpx.Response):
-        if response.status_code == 422:
-            raise ValueError(response.json())
-        elif response.status_code == 401:
-            try:
-                import streamlit
-            except ImportError:
-                self._print_response_and_raise(response)
-            else:
-                try:
-                    response.raise_for_status()
-                except Exception as exception:
-                    if not self.streamlit_compatible:
-                        streamlit_error_message = (
-                            "\nStreamlit environment detected. Use StreamlitAuth.client instance.\n"
-                            "Docs: https://developer.sweatstack.no/learn/integrations/streamlit/"
-                        )
-                        self._add_note(exception, streamlit_error_message)
-                    raise
-
-        else:
-            self._print_response_and_raise(response)
+            return response.json()
+        except Exception:
+            text = response.text
+            return text if text else None
 
     def _enums_to_strings(self, values: list[Enum | str]) -> list[str]:
         return [value.value if isinstance(value, Enum) else value for value in values]

sweatstack-0.76.0/src/sweatstack/exceptions.py

@@ -0,0 +1,67 @@
+"""Typed exception hierarchy for the SweatStack client.
+
+This module defines all exceptions raised by the SweatStack library.
+No httpx types are exposed — this is the public error contract.
+"""
+
+
+class SweatStackError(Exception):
+    """Base exception for all SweatStack errors."""
+
+
+class SweatStackConnectionError(SweatStackError):
+    """Transport-level failure: DNS, connect timeout, read timeout, no response."""
+
+
+class SweatStackTokenRefreshError(SweatStackError):
+    """Token refresh failed (expired, missing, or refresh request failed)."""
+
+
+class SweatStackAPIError(SweatStackError):
+    """HTTP response with an error status code."""
+
+    def __init__(self, *, status_code: int, url: str, method: str, request_id: str | None = None, body: dict | str | None = None):
+        self.status_code = status_code
+        self.url = url
+        self.method = method
+        self.request_id = request_id
+        self.body = body
+        super().__init__(self._format_message())
+
+    def _format_message(self) -> str:
+        msg = f"{self.status_code}: {self.method} {self.url}"
+        if self.request_id:
+            msg += f" (request_id={self.request_id})"
+        if self.body:
+            msg += f" — {self.body}"
+        return msg
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(status_code={self.status_code!r}, "
+            f"method={self.method!r}, url={self.url!r})"
+        )
+
+
+class SweatStackAuthError(SweatStackAPIError):
+    """401 or 403: authentication or authorization failure."""
+
+
+class SweatStackNotFoundError(SweatStackAPIError):
+    """404: resource not found."""
+
+
+class SweatStackRateLimitError(SweatStackAPIError):
+    """429: rate limited."""
+
+    def __init__(self, *, retry_after: int | None = None, **kwargs):
+        self.retry_after = retry_after
+        super().__init__(**kwargs)
+
+
+class SweatStackBadRequestError(SweatStackAPIError):
+    """4xx (not 401, 403, 404, 429): client sent invalid input."""
+
+
+class SweatStackServerError(SweatStackAPIError):
+    """5xx: server-side failure, transient, safe to retry for idempotent ops."""

{sweatstack-0.75.0 → sweatstack-0.76.0}/src/sweatstack/fastapi/routes.py

@@ -13,6 +13,7 @@ from fastapi import APIRouter, FastAPI, HTTPException, Request, Response
 from fastapi.responses import RedirectResponse
 
 from ..constants import DEFAULT_URL
+from ..exceptions import SweatStackAPIError, SweatStackConnectionError
 from ..utils import decode_jwt_body
 from .config import get_config
 from .dependencies import _extract_expiry
@@ -101,18 +102,27 @@ def _fetch_delegated_token(
     if team_id is not None:
         body["team_id"] = team_id
 
-    response = httpx.post(
-        f"{DEFAULT_URL}/api/v1/oauth/delegated-token",
-        headers={"Authorization": f"Bearer {principal_tokens.access_token}"},
-        json=body,
-    )
+    try:
+        response = httpx.post(
+            f"{DEFAULT_URL}/api/v1/oauth/delegated-token",
+            headers={"Authorization": f"Bearer {principal_tokens.access_token}"},
+            json=body,
+        )
+    except httpx.HTTPError as exc:
+        raise SweatStackConnectionError(str(exc)) from exc
 
     if response.status_code == 403:
         raise HTTPException(status_code=403, detail="You don't have access to this user")
     if response.status_code == 404:
         raise HTTPException(status_code=404, detail="User not found")
 
-    response.raise_for_status()
+    if not response.is_success:
+        raise SweatStackAPIError(
+            status_code=response.status_code,
+            url=str(response.request.url),
+            method=response.request.method,
+            body=response.text or None,
+        )
     tokens = response.json()
 
     return TokenSet(
@@ -213,15 +223,16 @@ def create_router() -> APIRouter:
                     "redirect_uri": config.redirect_uri,
                 },
             )
-            token_response.raise_for_status()
-            tokens = token_response.json()
-        except httpx.HTTPStatusError as e:
-            logger.error("Token exchange failed: %s - %s", e.response.status_code, e.response.text)
-            return error_redirect("token_exchange_failed")
-        except Exception as e:
+        except httpx.HTTPError as e:
             logger.error("Token exchange error: %s", e)
             return error_redirect("token_exchange_failed")
 
+        if not token_response.is_success:
+            logger.error("Token exchange failed: %s - %s", token_response.status_code, token_response.text)
+            return error_redirect("token_exchange_failed")
+
+        tokens = token_response.json()
+
         access_token = tokens.get("access_token")
         refresh_token = tokens.get("refresh_token")
 
@@ -299,7 +310,7 @@ def create_router() -> APIRouter:
         # Fetch delegated token for the target user
         try:
             delegated_tokens = _fetch_delegated_token(session.principal, user_id, team_id=team_id)
-        except httpx.HTTPStatusError as e:
+        except SweatStackAPIError as e:
             logger.warning("Failed to fetch delegated token for user %s: %s", user_id, e)
             raise HTTPException(status_code=403, detail="You don't have access to this user")
 

{sweatstack-0.75.0 → sweatstack-0.76.0}/src/sweatstack/openapi_schemas.py

@@ -1,10 +1,10 @@
 # generated by datamodel-codegen:
 #   filename:  openapi.json
-#   timestamp: 2026-04-22T12:23:13+00:00
+#   timestamp: 2026-04-27T08:07:03+00:00
 
 from __future__ import annotations
 
-from datetime import date as _Date, datetime, timedelta
+from datetime import date, datetime, timedelta
 from enum import Enum
 from typing import Any, Dict, List, Literal, Optional, Union
 
@@ -783,7 +783,7 @@ class CoreTemperatureSummary(BaseModel):
 
 
 class DailyCreate(BaseModel):
-    date: _Date = Field(..., title='Date')
+    date: date = Field(..., title='Date')
     value: float = Field(..., title='Value')
 
 
@@ -798,7 +798,7 @@ class DailyMeasure(Enum):
 
 
 class DailyResponse(BaseModel):
-    date: _Date = Field(..., title='Date')
+    date: date = Field(..., title='Date')
     value: Optional[float] = Field(..., title='Value')
     source: str = Field(..., title='Source')
 
@@ -1297,7 +1297,7 @@ class BodyCreateCheckoutSessionApiV1PaymentStripeCheckoutPost(BaseModel):
 
 class BodyCreateDailyDataDailiesPost(BaseModel):
     measure: DailyMeasure
-    date: _Date = Field(..., title='Date')
+    date: date = Field(..., title='Date')
     value: float = Field(..., title='Value')
 
 

{sweatstack-0.75.0 → sweatstack-0.76.0}/src/sweatstack/streamlit.py

@@ -40,6 +40,7 @@ import httpx
 
 from .client import Client
 from .constants import DEFAULT_URL
+from .exceptions import SweatStackAuthError
 from .schemas import Metric, Scope, Sport
 
 
@@ -311,10 +312,13 @@ class StreamlitAuth:
             data=token_data,
             auth=auth,
         )
-        try:
-            response.raise_for_status()
-        except httpx.HTTPStatusError as e:
-            raise Exception(f"SweatStack Python login failed. Please try again.") from e
+        if not response.is_success:
+            raise SweatStackAuthError(
+                status_code=response.status_code,
+                url=str(response.request.url),
+                method=response.request.method,
+                body="SweatStack Python login failed. Please try again.",
+            )
         token_response = response.json()
 
         self._set_api_key(

sweatstack-0.76.0/tests/test_exceptions.py

@@ -0,0 +1,312 @@
+"""Tests for the SweatStack exception hierarchy.
+
+Covers:
+- Exception instantiation and attributes
+- Inheritance relationships
+- __str__ and __repr__ formatting
+- _raise_for_status status code mapping
+- Transport error wrapping
+"""
+
+import httpx
+import pytest
+from unittest.mock import patch
+
+from sweatstack import Client
+from sweatstack.exceptions import (
+    SweatStackAPIError,
+    SweatStackAuthError,
+    SweatStackBadRequestError,
+    SweatStackConnectionError,
+    SweatStackError,
+    SweatStackNotFoundError,
+    SweatStackRateLimitError,
+    SweatStackServerError,
+    SweatStackTokenRefreshError,
+)
+
+
+# ---------------------------------------------------------------------------
+# Hierarchy and inheritance
+# ---------------------------------------------------------------------------
+
+
+class TestHierarchy:
+    def test_api_error_is_sweatstack_error(self):
+        exc = SweatStackAPIError(status_code=500, url="http://x", method="GET")
+        assert isinstance(exc, SweatStackError)
+        assert isinstance(exc, Exception)
+
+    def test_server_error_is_api_error(self):
+        exc = SweatStackServerError(status_code=500, url="http://x", method="GET")
+        assert isinstance(exc, SweatStackAPIError)
+        assert isinstance(exc, SweatStackError)
+
+    def test_auth_error_is_api_error(self):
+        exc = SweatStackAuthError(status_code=401, url="http://x", method="GET")
+        assert isinstance(exc, SweatStackAPIError)
+
+    def test_not_found_error_is_api_error(self):
+        exc = SweatStackNotFoundError(status_code=404, url="http://x", method="GET")
+        assert isinstance(exc, SweatStackAPIError)
+
+    def test_rate_limit_error_is_api_error(self):
+        exc = SweatStackRateLimitError(status_code=429, url="http://x", method="GET")
+        assert isinstance(exc, SweatStackAPIError)
+
+    def test_bad_request_error_is_api_error(self):
+        exc = SweatStackBadRequestError(status_code=422, url="http://x", method="POST")
+        assert isinstance(exc, SweatStackAPIError)
+
+    def test_connection_error_is_sweatstack_error_not_api_error(self):
+        exc = SweatStackConnectionError("DNS failed")
+        assert isinstance(exc, SweatStackError)
+        assert not isinstance(exc, SweatStackAPIError)
+
+    def test_token_refresh_error_is_sweatstack_error_not_api_error(self):
+        exc = SweatStackTokenRefreshError("token expired")
+        assert isinstance(exc, SweatStackError)
+        assert not isinstance(exc, SweatStackAPIError)
+
+
+# ---------------------------------------------------------------------------
+# Attributes
+# ---------------------------------------------------------------------------
+
+
+class TestAttributes:
+    def test_api_error_attributes(self):
+        exc = SweatStackAPIError(
+            status_code=500,
+            url="https://api.sweatstack.no/api/v1/activities",
+            method="GET",
+            request_id="req-123",
+            body={"error": "internal"},
+        )
+        assert exc.status_code == 500
+        assert exc.url == "https://api.sweatstack.no/api/v1/activities"
+        assert exc.method == "GET"
+        assert exc.request_id == "req-123"
+        assert exc.body == {"error": "internal"}
+
+    def test_api_error_optional_attributes_default_to_none(self):
+        exc = SweatStackAPIError(status_code=400, url="http://x", method="POST")
+        assert exc.request_id is None
+        assert exc.body is None
+
+    def test_rate_limit_error_retry_after(self):
+        exc = SweatStackRateLimitError(
+            retry_after=30, status_code=429, url="http://x", method="GET"
+        )
+        assert exc.retry_after == 30
+        assert exc.status_code == 429
+
+    def test_rate_limit_error_retry_after_defaults_to_none(self):
+        exc = SweatStackRateLimitError(status_code=429, url="http://x", method="GET")
+        assert exc.retry_after is None
+
+
+# ---------------------------------------------------------------------------
+# Formatting
+# ---------------------------------------------------------------------------
+
+
+class TestFormatting:
+    def test_str_basic(self):
+        exc = SweatStackServerError(status_code=502, url="http://api/v1/x", method="GET")
+        assert str(exc) == "502: GET http://api/v1/x"
+
+    def test_str_with_request_id(self):
+        exc = SweatStackServerError(
+            status_code=503, url="http://api/v1/x", method="POST", request_id="abc-123"
+        )
+        assert "(request_id=abc-123)" in str(exc)
+
+    def test_str_with_body(self):
+        exc = SweatStackBadRequestError(
+            status_code=400, url="http://x", method="POST", body="bad input"
+        )
+        assert "bad input" in str(exc)
+
+    def test_repr(self):
+        exc = SweatStackServerError(status_code=502, url="http://api/v1/x", method="GET")
+        r = repr(exc)
+        assert r == "SweatStackServerError(status_code=502, method='GET', url='http://api/v1/x')"
+
+    def test_connection_error_str(self):
+        exc = SweatStackConnectionError("Connection refused")
+        assert str(exc) == "Connection refused"
+
+    def test_token_refresh_error_str(self):
+        exc = SweatStackTokenRefreshError("token expired")
+        assert str(exc) == "token expired"
+
+
+# ---------------------------------------------------------------------------
+# _raise_for_status mapping
+# ---------------------------------------------------------------------------
+
+
+def _make_response(status_code, headers=None, json_body=None, text_body=""):
+    """Create a mock httpx.Response for testing _raise_for_status."""
+    request = httpx.Request("GET", "https://api.sweatstack.no/api/v1/test")
+    response = httpx.Response(
+        status_code=status_code,
+        request=request,
+        headers=headers or {},
+        json=json_body,
+        text=text_body if json_body is None else None,
+    )
+    return response
+
+
+class TestRaiseForStatus:
+    @pytest.fixture
+    def client(self):
+        return Client.__new__(Client)
+
+    def test_success_does_not_raise(self, client):
+        response = _make_response(200)
+        client._raise_for_status(response)  # should not raise
+
+    def test_401_raises_auth_error(self, client):
+        response = _make_response(401)
+        with pytest.raises(SweatStackAuthError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.status_code == 401
+
+    def test_403_raises_auth_error(self, client):
+        response = _make_response(403)
+        with pytest.raises(SweatStackAuthError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.status_code == 403
+
+    def test_404_raises_not_found_error(self, client):
+        response = _make_response(404)
+        with pytest.raises(SweatStackNotFoundError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.status_code == 404
+
+    def test_429_raises_rate_limit_error(self, client):
+        response = _make_response(429, headers={"retry-after": "60"})
+        with pytest.raises(SweatStackRateLimitError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.status_code == 429
+        assert exc_info.value.retry_after == 60
+
+    def test_429_without_retry_after_header(self, client):
+        response = _make_response(429)
+        with pytest.raises(SweatStackRateLimitError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.retry_after is None
+
+    def test_400_raises_bad_request_error(self, client):
+        response = _make_response(400)
+        with pytest.raises(SweatStackBadRequestError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.status_code == 400
+
+    def test_422_raises_bad_request_error(self, client):
+        response = _make_response(422, json_body={"detail": [{"msg": "field required"}]})
+        with pytest.raises(SweatStackBadRequestError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.status_code == 422
+        assert exc_info.value.body == {"detail": [{"msg": "field required"}]}
+
+    def test_500_raises_server_error(self, client):
+        response = _make_response(500)
+        with pytest.raises(SweatStackServerError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.status_code == 500
+
+    def test_502_raises_server_error(self, client):
+        response = _make_response(502)
+        with pytest.raises(SweatStackServerError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.status_code == 502
+
+    def test_503_raises_server_error(self, client):
+        response = _make_response(503)
+        with pytest.raises(SweatStackServerError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.status_code == 503
+
+    def test_request_id_populated_from_header(self, client):
+        response = _make_response(500, headers={"x-request-id": "req-abc"})
+        with pytest.raises(SweatStackServerError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.request_id == "req-abc"
+
+    def test_json_body_parsed(self, client):
+        response = _make_response(400, json_body={"error": "invalid_field"})
+        with pytest.raises(SweatStackBadRequestError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.body == {"error": "invalid_field"}
+
+    def test_text_body_fallback(self, client):
+        response = _make_response(500, text_body="Internal Server Error")
+        with pytest.raises(SweatStackServerError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.body == "Internal Server Error"
+
+    def test_url_and_method_populated(self, client):
+        response = _make_response(404)
+        with pytest.raises(SweatStackNotFoundError) as exc_info:
+            client._raise_for_status(response)
+        assert exc_info.value.url == "https://api.sweatstack.no/api/v1/test"
+        assert exc_info.value.method == "GET"
+
+    def test_catchable_as_api_error(self, client):
+        response = _make_response(503)
+        with pytest.raises(SweatStackAPIError):
+            client._raise_for_status(response)
+
+    def test_catchable_as_sweatstack_error(self, client):
+        response = _make_response(401)
+        with pytest.raises(SweatStackError):
+            client._raise_for_status(response)
+
+
+# ---------------------------------------------------------------------------
+# Transport error wrapping
+# ---------------------------------------------------------------------------
+
+
+class TestTransportErrors:
+    def test_http_client_wraps_connect_error(self):
+        client = Client.__new__(Client)
+        client.url = "http://localhost:1"
+        client._api_key = None
+        client._client_secret = None
+        client.streamlit_compatible = False
+
+        with pytest.raises(SweatStackConnectionError) as exc_info:
+            with client._http_client(skip_token_check=True) as http:
+                raise httpx.ConnectError("Connection refused")
+
+        assert "Connection refused" in str(exc_info.value)
+
+    def test_http_client_wraps_timeout_error(self):
+        client = Client.__new__(Client)
+        client.url = "http://localhost:1"
+        client._api_key = None
+        client._client_secret = None
+        client.streamlit_compatible = False
+
+        with pytest.raises(SweatStackConnectionError):
+            with client._http_client(skip_token_check=True) as http:
+                raise httpx.ReadTimeout("Read timed out")
+
+    def test_connection_error_preserves_cause(self):
+        client = Client.__new__(Client)
+        client.url = "http://localhost:1"
+        client._api_key = None
+        client._client_secret = None
+        client.streamlit_compatible = False
+
+        original = httpx.ConnectError("DNS resolution failed")
+        with pytest.raises(SweatStackConnectionError) as exc_info:
+            with client._http_client(skip_token_check=True) as http:
+                raise original
+
+        assert exc_info.value.__cause__ is original

{sweatstack-0.75.0 → sweatstack-0.76.0}/uv.lock

@@ -2456,7 +2456,7 @@ wheels = [
 
 [[package]]
 name = "sweatstack"
-version = "0.73.0"
+version = "0.75.0"
 source = { editable = "." }
 dependencies = [
     { name = "email-validator" },

sweatstack-0.75.0/src/sweatstack/__init__.py

@@ -1 +0,0 @@
-from .client import *