sweatstack 0.77.0__tar.gz → 0.79.0__tar.gz

{sweatstack-0.77.0 → sweatstack-0.79.0}/.claude/settings.local.json

@@ -21,7 +21,9 @@
       "Bash(test:*)",
       "Bash(uv run:*)",
       "mcp__sentry__get_sentry_resource",
-      "Bash(awk *)"
+      "Bash(awk *)",
+      "Bash(git show *)",
+      "Read(//tmp/**)"
     ],
     "deny": []
   }

{sweatstack-0.77.0 → sweatstack-0.79.0}/.claude/skills/sweatstack-python/fastapi.md

@@ -11,6 +11,7 @@ Requires: `pip install sweatstack[fastapi]`
 - [User Delegation](#user-delegation)
 - [Webhooks](#webhooks)
 - [Token Stores](#token-stores)
+- [Access Token Cache](#access-token-cache)
 
 ---
 
@@ -55,6 +56,7 @@ configure(
     redirect_unauthenticated: bool = True,    # True = redirect to login, False = return 401
     webhook_secret: str = None,               # SWEATSTACK_WEBHOOK_SECRET
     token_store: TokenStore = None,           # for webhook user token persistence
+    access_token_cache: AccessTokenCache = None,  # default: in-process LRU. See "Access Token Cache"
 )
 ```
 
@@ -207,3 +209,79 @@ class RedisTokenStore(TokenStore):
 ```
 
 `StoredTokens` fields: `user_id`, `access_token`, `refresh_token`, `expires_at: datetime`.
+
+## Access Token Cache
+
+When a single page-load fans out into many concurrent requests, the cookie's access token may be on the edge of expiry for several of them at once. Without coordination, each request independently calls `/oauth/token` with the same refresh token, producing a burst of duplicate refreshes. The access-token cache collapses this to a single call: peers serialise on a per-session lock and share the result.
+
+The default `InMemoryAccessTokenCache` is correct for single-worker FastAPI deployments. It is **LRU-bounded** (10k entries) so memory is capped regardless of session churn, and uses **striped locking** (64 stripes) so eviction never coordinates with in-flight refreshes.
+
+### Tuning
+
+```python
+from sweatstack.fastapi import configure, InMemoryAccessTokenCache
+
+configure(
+    ...,
+    access_token_cache=InMemoryAccessTokenCache(
+        max_entries=50_000,   # high session-churn deployments
+        lock_stripes=128,     # very high concurrent refresh counts
+    ),
+)
+```
+
+### Multi-worker deployments
+
+For multiple FastAPI workers (uvicorn `--workers > 1`, Gunicorn, etc.) the in-memory cache de-duplicates **within** each worker, not across them. Cross-worker de-duplication requires a shared-state implementation. Implement the `AccessTokenCache` Protocol — `get`, `set`, `invalidate`, `migrate`, `lock` — and pass it to `configure()`.
+
+```python
+from sweatstack.fastapi import AccessTokenCache, CachedAccessToken
+# Sketch: Redis-backed implementation (hash the key, never store the raw refresh token).
+```
+
+The Protocol surface is documented in detail in `sweatstack/fastapi/access_token_cache.py`. The call pattern (`check → lock → recheck → refresh → set/migrate`) is in the `AccessTokenCache` docstring.
+
+### Timeouts and the `RefreshLockTimeout` exception
+
+The refresh path has two bounds, both intended as defence-in-depth rather than knobs users normally tune:
+
+| Constant | Default | What it bounds |
+|---|---|---|
+| `REFRESH_HTTP_TIMEOUT` | 10s read, 5s connect | The `/oauth/token` HTTP call |
+| `REFRESH_LOCK_TIMEOUT` | 15s | Waiting for a peer's refresh to finish |
+
+A waiter that cannot acquire the per-session lock within 15s raises `RefreshLockTimeout` rather than pinning a threadpool worker. In the cookie-based dependency path it surfaces as a 401; in the webhook path it is wrapped as `WebhookTokenRefreshError`. You don't normally catch it; if you want to wire it to metrics:
+
+```python
+from sweatstack.fastapi import RefreshLockTimeout
+
+@app.exception_handler(RefreshLockTimeout)
+async def on_refresh_timeout(request, exc):
+    metrics.increment("oauth.refresh.lock_timeout")
+    raise  # let the normal 401 / WebhookTokenRefreshError path run
+```
+
+### Refresh-token rotation
+
+The current SweatStack `/oauth/token` endpoint does not rotate refresh tokens, but the cache is rotation-aware: if the server ever starts returning a new refresh token, it is captured, the cookie / token store is rewritten with it, and the cache installs the result under both the old and new keys (so in-flight peers still arriving with the old refresh token continue to hit).
+
+### Debugging
+
+Enable debug logs to see every cache decision keyed by a short SHA-256 fingerprint of the refresh token (never the raw secret):
+
+```python
+import logging
+logging.getLogger("sweatstack.fastapi.dependencies").setLevel(logging.DEBUG)
+```
+
+Typical output for a 5-way concurrent fan-out on an expiring session:
+
+```
+DEBUG access-token refresh completed (session=4f2a91c0)
+DEBUG access-token cache hit after lock (peer refreshed; session=4f2a91c0)
+DEBUG access-token cache hit after lock (peer refreshed; session=4f2a91c0)
+DEBUG access-token cache hit (session=4f2a91c0)
+DEBUG access-token cache hit (session=4f2a91c0)
+```
+
+One refresh, four cache hits.

sweatstack-0.79.0/AGENTS.md

@@ -0,0 +1,225 @@
+# AGENTS.md
+
+Working agreement for agents (and humans) changing this codebase. Read end
+to end before your first change. Mechanics — install, test, regen, release —
+live in [DEVELOPMENT.md](DEVELOPMENT.md).
+
+
+## Guiding principle: mirror the REST API
+
+This client is a thin Python projection of the SweatStack REST API. When
+you add or change a surface, the default is to mirror the server:
+
+| Server                                  | Python                                  |
+| --------------------------------------- | --------------------------------------- |
+| `GET /api/v1/tests/{id}`                | `client.get_test(test_id)`              |
+| `POST /api/v1/traces/`                  | `client.create_trace(...)`              |
+| `PUT /api/v1/traces/{id}` (full-replace)| `client.update_trace(trace_id, ...)`    |
+| `DELETE /api/v1/dailies/{id}`           | `client.delete_daily(daily_id)`         |
+| query param `?sport=cycling&sport=running` | `sports=[Sport.cycling, Sport.running]` |
+| JSON body field `test_id`               | kwarg `test_id`                         |
+| OpenAPI enum value `"auto"`             | `TraceResolution.auto`                  |
+
+Match the server's field names, enum values, full-replace PUT semantics,
+and pagination shape. Don't redesign the API in Python.
+
+**Deliberate deviations** (these are the only ones — don't invent more):
+
+- Path-param IDs are positional Python args (`get_test(test_id)`), not part
+  of a URL string.
+- Enum-typed params accept `Enum | str` so callers don't need to import the
+  enum for one-off use.
+- A `traces=` query parameter renames to `trace_resolution=` on the Python
+  side when the wire name would be ambiguous as a kwarg. Document the
+  mapping in the docstring.
+- `as_dataframe=True` is a client-side convenience over list endpoints.
+- Convenience composites that wrap multiple calls
+  (`get_latest_activity_data`, `get_longitudinal_*`) live alongside the
+  literal mirrors. Add new ones sparingly; only when a real workflow is
+  awkward through the literal surface.
+
+
+## Project shape
+
+```
+src/sweatstack/
+├── openapi_schemas.py   # AUTO-GENERATED. Never hand-edit.
+├── schemas.py           # Re-exports + Enum._missing_ / display_name helpers.
+├── exceptions.py        # Public error contract. No httpx types leak.
+├── client.py            # Single Client class + module-level singletons.
+├── utils.py             # Dataframe / JWT helpers.
+├── streamlit.py         # Streamlit integration (optional extra).
+├── fastapi/             # FastAPI integration (optional extra).
+└── cli.py               # Entry points.
+```
+
+Adding a new Pydantic model from the server takes three steps:
+
+1. Regen `openapi_schemas.py` ([DEVELOPMENT.md](DEVELOPMENT.md#regenerating-openapi_schemaspy)).
+2. Re-export it from `schemas.py`.
+3. Import it into `client.py` so `from sweatstack import *` exposes it.
+
+Skipping step 3 silently breaks the public surface. Same for new enums.
+
+
+## Hard rules
+
+- **`uv`, never `pip`.** Every command goes through `uv run` / `uv add`.
+- **Never hand-edit `openapi_schemas.py`.** Regenerate.
+- **`Raises:` references the typed exceptions** from
+  `sweatstack.exceptions`. Don't write `HTTPStatusError` in new docstrings.
+- **Public methods belong in `_generate_singleton_methods(...)`** at the
+  bottom of `client.py`. Forgetting is silent.
+- **Enum-typed params accept `Enum | str`** and route through
+  `_enums_to_strings`. Don't introduce strict-enum-only parameters.
+- **Tests are offline.** No network calls. Use `Client.__new__(Client)` to
+  bypass init when you need an instance for a helper method.
+- **`update_*` methods are full-replace.** Document the silent-clear
+  footgun in the docstring (see below).
+- **CHANGELOG entries are user-facing**, not dev-facing.
+
+
+## Method shape
+
+Every method on `Client` follows this shape. Match it.
+
+```python
+def do_thing(
+    self,
+    resource_id: str,                            # path params: positional
+    *,                                           # rest: keyword-only
+    timestamp: datetime,
+    sport: Sport | str | None = None,            # enum params: Enum | str
+    tags: list[str] | None = None,
+) -> ThingDetails:
+    """One-line summary.
+
+    Optional paragraph for non-obvious behaviour (full-replace,
+    server-side defaults, side effects).
+
+    Args:
+        ...
+
+    Returns:
+        ThingDetails: ...
+
+    Raises:
+        SweatStackNotFoundError: If <specific condition>.
+        SweatStackAPIError: If the API request fails for any other reason.
+    """
+    sport = self._enums_to_strings([sport])[0] if sport else None
+    with self._http_client() as client:
+        response = client.post(
+            url=f"/api/v1/things/{resource_id}",
+            json={"timestamp": timestamp.isoformat(), "sport": sport, "tags": tags},
+        )
+        self._raise_for_status(response)
+        return ThingDetails.model_validate(response.json())
+```
+
+Invariants baked into the template:
+
+- Path-param IDs positional, everything else keyword-only.
+- Datetimes serialize via `.isoformat()`.
+- Body uses every field explicitly (full-replace contract).
+- Request goes through `self._http_client()` context manager.
+- Response goes through `self._raise_for_status()` before parsing.
+- Return is a validated Pydantic model — never the raw dict.
+- `update_*` methods are typed `-> None`. The server's
+  `{"message": "..."}` body carries no useful info.
+
+**List endpoints** add a `_get_<resource>_generator()` that yields
+validated objects with internal pagination, plus a `get_<resource>s(...,
+as_dataframe=False)` wrapper. Empty-list DataFrames go through
+`_create_empty_dataframe_from_model(Model, normalize_columns=[...])` so
+column names stay stable. See `get_activities` and `get_tests` for
+exemplars.
+
+**Query parameters** are only sent when the caller supplied a non-default
+value. For enum-typed query params with an explicit default, compare
+against the default and skip when equal. Always pass `.value` for enums
+into `httpx.params` — `httpx` calls `str()`, which gives
+`"TraceResolution.linked"`, not `"linked"`.
+
+
+## Full-replace `update_*` methods
+
+PUT endpoints overwrite every field, including by setting unsent fields
+to `null`. Two rules:
+
+1. **Send every field in the body, even when `None`.** Don't omit.
+2. **Document the silent-clear footgun in the docstring** whenever you
+   add a new optional field to an existing `update_*` method, *and*
+   call it out in the CHANGELOG `### Changed` section. Existing callers
+   who don't know about the new field will silently null it on their
+   next update.
+
+Don't try to soften the contract with "preserve if omitted" sentinels;
+that diverges from how every other field behaves on these methods.
+
+
+## Exceptions
+
+The hierarchy in `sweatstack/exceptions.py` is the **public** error
+contract — consumers should never need to import `httpx`.
+
+```
+SweatStackError
+├── SweatStackConnectionError       # DNS / timeout / no response
+├── SweatStackTokenRefreshError
+└── SweatStackAPIError              # got a response with status >= 400
+    ├── SweatStackAuthError         # 401, 403
+    ├── SweatStackNotFoundError     # 404
+    ├── SweatStackRateLimitError    # 429
+    ├── SweatStackBadRequestError   # other 4xx
+    └── SweatStackServerError       # 5xx
+```
+
+Docstrings: list specific subclasses for meaningful conditions (e.g. 404
+when a path ID may not exist), then a catch-all `SweatStackAPIError`.
+
+
+## Tests
+
+Live in `tests/`. Offline only. The workhorse pattern is schema
+round-tripping:
+
+```python
+restored = TraceDetails.model_validate(original.model_dump())
+assert restored.test_id == "test_123"
+```
+
+Catches missing fields, type drift, and enum-casing changes from regen.
+Exemplars: `tests/test_trace_test_linking.py`, `tests/test_tests.py`,
+`tests/test_dtype_conversion.py`.
+
+
+## CHANGELOG
+
+User-facing only. Lead with what changed for the user; skip regen
+output, file renames, refactors. Loud-callout any behaviour change in
+`### Changed`, especially full-replace footguns. SemVer.
+
+Good:
+
+> ### Changed
+> - `update_trace()` replaces all fields, including `test_id`. Callers
+>   that omit `test_id` will clear any existing link.
+
+Bad (belongs in the commit message, not the changelog):
+
+> ### Changed
+> - Local datetime fields are now `AwareDatetime`. The
+>   `BodyExpressAddEmail...` schema is renamed to
+>   `BodyConnectAddEmail...`.
+
+
+## When in doubt
+
+- Match the nearest existing method in `client.py`. Consistency with the
+  surroundings beats local cleverness.
+- Reuse the helpers: `_enums_to_strings`, `_get_*_generator`,
+  `_normalize_dataframe_column`, `_create_empty_dataframe_from_model`,
+  `_set_app_metadata`. Don't reinvent them.
+- Don't add abstractions for hypothetical future flexibility. Three
+  similar blocks is the pattern, not a smell.

{sweatstack-0.77.0 → sweatstack-0.79.0}/CHANGELOG.md

@@ -6,6 +6,35 @@ 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.79.0] - 2026-05-28
+
+### Fixed
+- `sweatstack.fastapi`: a single page load that fans out into many concurrent requests no longer produces a burst of duplicate `/oauth/token` refreshes when the session's access token is on the edge of expiring. Concurrent requests for the same session now serialise on a per-session lock and share the resulting refresh, so an N-way race collapses to a single token endpoint call.
+
+### Added
+- `sweatstack.fastapi.AccessTokenCache` (Protocol) and `InMemoryAccessTokenCache` (default), exposed via `configure(access_token_cache=...)`. The default is correct for single-worker deployments. Multi-worker deployments that want cross-worker de-duplication can plug in a shared-state implementation (e.g. Redis-backed). The default implementation is bounded by an LRU cap (10k entries) and uses striped locking, so memory growth is bounded regardless of session churn.
+- `sweatstack.fastapi`: refresh-token rotation is now handled transparently. If a future `/oauth/token` response returns a new refresh token, the cache installs the result under both the old and new keys (so in-flight peers still hit), and the cookie / token store is rewritten with the new value. Current SweatStack servers do not rotate, so this is a forward-compatibility measure.
+- `sweatstack.fastapi.RefreshLockTimeout`: a waiter that cannot acquire the per-session refresh lock within 15 seconds now raises this rather than blocking a FastAPI threadpool worker indefinitely. The `/oauth/token` call itself also has an explicit 10-second timeout.
+- `sweatstack.fastapi`: debug logs (`sweatstack.fastapi.dependencies` logger) on every cache hit / seed / refresh / failure, keyed by a short SHA-256 fingerprint of the refresh token. Enable with `logging.getLogger("sweatstack.fastapi.dependencies").setLevel(logging.DEBUG)`.
+
+
+## [0.78.0] - 2026-05-19
+
+### Added
+- `update_trace()` and `delete_trace()` are now exposed as module-level functions (e.g. `sweatstack.update_trace(...)`), matching the rest of the CRUD surface. They were previously only reachable via a `Client` instance.
+- The package now declares an `__all__`, so `from sweatstack import *` and tooling that inspects the public surface (Sphinx, IDEs, type-checkers) see a well-defined list.
+
+### Changed
+- Minimum Python version is now declared as `>=3.10` (the code already required 3.10+ syntax; the previous `>=3.9` declaration was incorrect).
+- Exception types in docstrings now reference the typed hierarchy introduced in 0.76.0 (`SweatStackAPIError`, `SweatStackNotFoundError`, `SweatStackAuthError`, `SweatStackBadRequestError`) instead of the now-incorrect `HTTPStatusError`.
+
+
+## [0.77.1] - 2026-05-19
+
+### Fixed
+- Reverted unrelated OpenAPI schema drift.
+
+
 ## [0.77.0] - 2026-05-19
 
 ### Added

sweatstack-0.79.0/DEVELOPMENT.md

@@ -0,0 +1,105 @@
+# Development
+
+Mechanics for working on the SweatStack Python client locally. For the
+conventions you must follow when changing code, see [AGENTS.md](AGENTS.md).
+
+
+## Tooling
+
+This project uses [`uv`](https://docs.astral.sh/uv/) for everything.
+**Never use `pip` directly.**
+
+```bash
+uv sync                     # install/update dependencies
+uv run pytest               # run tests
+uv run python -c "..."      # ad-hoc scripts
+uv run generate-response-models   # regenerate OpenAPI schemas (see below)
+```
+
+Python ≥ 3.9 is supported; develop against the version pinned in
+`.python-version`.
+
+
+## Running locally
+
+For interactive exploration (Jupyter):
+
+```bash
+uvx --with-editable "path/to/sweatstack-python[jupyterlab]" jupyter lab
+```
+
+Run from a scratch directory so JupyterLab does not litter the repo with
+`Untitled` notebooks.
+
+
+## Running tests
+
+```bash
+uv run pytest                          # full suite
+uv run pytest tests/test_<name>.py     # one file
+uv run pytest --ignore=tests/test_webhooks.py   # skip optional-dep tests
+```
+
+`tests/test_webhooks.py` requires `fastapi`, which is an optional extra. If
+you have not installed it, ignore that file or `uv sync --extra fastapi`.
+
+All tests are offline — no test should make a network call. See
+[AGENTS.md → Testing](AGENTS.md#testing) for how to write new ones.
+
+
+## Regenerating `openapi_schemas.py`
+
+`src/sweatstack/openapi_schemas.py` is **fully machine-generated** from the
+backend's OpenAPI document by `datamodel-code-generator`. Never hand-edit it.
+
+### Procedure
+
+1. Start the SweatStack backend so it serves `http://localhost:8080/openapi.json`.
+2. Run:
+
+   ```bash
+   uv run generate-response-models
+   ```
+
+3. Review the diff carefully. The file is regenerated as a whole, so the
+   diff will often include **unrelated upstream changes** since the last
+   regeneration (field renames, type tightening, new endpoints).
+
+4. If the diff contains changes outside the feature you are working on,
+   **split them into a separate commit** (`chore: regenerate openapi
+   schemas`) that lands before the feature commit. Keep the feature
+   commit minimal so reviewers can read it.
+
+### Staging only part of the regenerated file
+
+When the regen drift is too large to include in a feature commit but you
+do not want to lose it, stage only the relevant hunks:
+
+```bash
+cp src/sweatstack/openapi_schemas.py /tmp/openapi.full.py
+git checkout HEAD -- src/sweatstack/openapi_schemas.py
+# hand-apply only the lines relevant to your feature
+git add src/sweatstack/openapi_schemas.py
+cp /tmp/openapi.full.py src/sweatstack/openapi_schemas.py   # restore working tree
+```
+
+The working tree now has the full regen (unstaged), and the index has the
+minimal feature delta. Commit, then handle the remainder separately.
+
+
+## Releasing
+
+1. Bump `version` in `pyproject.toml` (SemVer).
+2. Add a CHANGELOG entry — see [AGENTS.md → CHANGELOG](AGENTS.md#changelog).
+3. `make build` and `make publish` (twine to PyPI). The `Makefile` has
+   the canonical commands.
+
+
+## Docs
+
+```bash
+make docs
+```
+
+Renders Sphinx to `docs/_build/markdown/`. Most public classes are
+documented automatically via `autoclass` directives in `docs/everything.rst`.

{sweatstack-0.77.0 → sweatstack-0.79.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.77.0
+Version: 0.79.0
 Summary: The official Python client for SweatStack
 Project-URL: Homepage, https://sweatstack.no
 Project-URL: Documentation, https://docs.sweatstack.no/getting-started/
@@ -15,13 +15,12 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: email-validator>=2.2.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: pandas>=2.2.3