sweatstack 0.75.0__tar.gz → 0.76.1__tar.gz

{sweatstack-0.75.0 → sweatstack-0.76.1}/.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.1}/.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.1}/CHANGELOG.md

@@ -6,6 +6,28 @@ 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.1] - 2026-04-27
+
+### Fixed
+- Local datetime fields (`start_local`, `end_local`, `timestamp_local`) in OpenAPI schemas corrected from `AwareDatetime` to `NaiveDatetime`.
+
+
+## [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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.75.0
+Version: 0.76.1
 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.1/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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sweatstack"
-version = "0.75.0"
+version = "0.76.1"
 description = "The official Python client for SweatStack"
 readme = "README.md"
 license = "MIT"
@@ -62,7 +62,7 @@ build-backend = "hatchling.build"
 
 [dependency-groups]
 dev = [
-    "datamodel-code-generator>=0.26.5",
+    "datamodel-code-generator[ruff]>=0.54.1",
     "myst-parser>=4.0.1",
     "sphinx>=8.2.3",
     "sphinx-markdown-builder>=0.6.8",

sweatstack-0.76.1/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.1}/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.1/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."""