sweatstack 0.77.1__tar.gz → 0.80.0__tar.gz

{sweatstack-0.77.1 → sweatstack-0.80.0}/.claude/settings.local.json

@@ -23,7 +23,11 @@
       "mcp__sentry__get_sentry_resource",
       "Bash(awk *)",
       "Bash(git show *)",
-      "Read(//tmp/**)"
+      "Read(//tmp/**)",
+      "WebFetch(domain:pypi.org)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(uv add *)"
     ],
     "deny": []
   }

{sweatstack-0.77.1 → sweatstack-0.80.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.77.1 → sweatstack-0.80.0}/AGENTS.md

@@ -214,28 +214,6 @@ Bad (belongs in the commit message, not the changelog):
 >   `BodyConnectAddEmail...`.
 
 
-## Known rough edges
-
-These are conventions we live with but would reconsider in a rewrite.
-Don't paper over them in new code; flag them in review.
-
-- **Singleton functions are injected via `globals()`** at module import.
-  The "is this method a singleton?" rule is unwritten, which is exactly
-  why `update_trace` and `delete_trace` are missing from the list while
-  `update_test` and `delete_test` are present. When you touch an
-  unregistered public method, register it.
-- **`__init__.py` uses `from .client import *`.** Explicit re-exports
-  would be safer; we haven't done the work.
-- **Docstring exception drift.** Most existing docstrings still say
-  `HTTPStatusError`. Fix as you touch them, but a one-shot sweep is also
-  welcome.
-- **`pyproject.toml` claims `requires-python = ">=3.9"`** while the code
-  uses `X | Y` union syntax (3.10+). The real floor is 3.10. Bump the
-  pin when convenient.
-- **No CI type-checker or linter.** For a typed library, this is a gap.
-  Don't let new code make it worse.
-
-
 ## When in doubt
 
 - Match the nearest existing method in `client.py`. Consistency with the

{sweatstack-0.77.1 → sweatstack-0.80.0}/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 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.80.0] - 2026-06-12
+
+### Changed
+- Makes the Sport enum forward compatible with OpenSportTaxonomy sports.
+
+
+## [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
 

{sweatstack-0.77.1 → sweatstack-0.80.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.77.1
+Version: 0.80.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

sweatstack-0.80.0/plans/004_codebase_hygiene.md

@@ -0,0 +1,204 @@
+# Plan: Codebase hygiene follow-ups
+
+A backlog of items that came up while landing trace-to-test linking and
+writing AGENTS.md. Two buckets, with an explicit inclusion criterion so the
+list stays principled instead of accumulating taste.
+
+
+## Inclusion criterion
+
+The **rough edges** section below contains items that meet at least one of:
+
+1. **Inconsistent within the codebase** — same pattern, handled two ways.
+2. **Contradicts explicit documentation** — code says one thing, docstrings
+   or metadata say another.
+3. **Literal falsehood** — config or metadata that is untrue.
+4. **Blocks a class of improvements** — a structural absence with broad
+   downstream consequence.
+
+Items that meet none of those are stylistic preferences or open design
+questions. They go in the **Design questions** section, marked as such, so
+they don't quietly migrate into "things we must fix."
+
+
+## Rough edges
+
+### 1. Singleton method registration is hand-curated and inconsistent
+
+**Observation.** `client.py` bottom: `_generate_singleton_methods([...])`
+takes a hand-maintained list of method names to expose as module-level
+functions. The list is incomplete: `update_test` and `delete_test` are
+registered, `update_trace` and `delete_trace` are not. There is no written
+rule for which methods should be in the list.
+
+**Why fix.** A consumer calling `sweatstack.update_trace(...)` gets
+`AttributeError` even though `Client.update_trace` exists. The surface
+silently drifts from the class.
+
+**Approach.** Either:
+
+- **(a) Auto-register**: at module load, iterate `Client` methods, skip
+  underscore-prefixed names, generate singletons for the rest. Single
+  source of truth, no list to forget.
+- **(b) Keep the list, codify the rule**: AGENTS.md says "all public
+  methods on `Client` go here", and add a test that asserts the list
+  matches the class.
+
+(a) is the cleaner fix; (b) is the smaller patch. (a) preferred.
+
+**Effort.** Small (a) / tiny (b).
+
+
+### 2. Docstring exception drift since 0.76.0
+
+**Observation.** The 0.76.0 typed-exception migration replaced
+`httpx.HTTPStatusError` with `SweatStackAPIError` subclasses at the call
+site, but most existing docstrings still say `Raises: HTTPStatusError`.
+The library now documents an exception it does not raise.
+
+**Why fix.** The docs lie. A consumer reading `help(client.get_activity)`
+is told to catch `HTTPStatusError`; their `try/except` will never trigger.
+
+**Approach.** One-shot sweep of `client.py`. For each `Raises:` block:
+
+- If the endpoint has a path-param resource ID or references another
+  resource by ID, list `SweatStackNotFoundError` for the 404 case.
+- If it is an app-token-only endpoint (e.g. `*_app_metadata`), list
+  `SweatStackAuthError` for the 403 case.
+- Always finish with `SweatStackAPIError` as the catch-all.
+
+Roughly 30 methods; mechanical but needs per-endpoint judgement.
+
+**Effort.** Medium.
+
+
+### 3. `requires-python = ">=3.9"` is a literal falsehood
+
+**Observation.** `pyproject.toml` declares `requires-python = ">=3.9"` and
+classifies for 3.9 onwards. The code uses `X | Y` union syntax (PEP 604,
+Python 3.10+) freely throughout `client.py`, `schemas.py`, generated
+schemas, and tests. On 3.9 the package will install and crash at first
+import with a `TypeError`.
+
+**Why fix.** The package metadata is wrong. pip/uv will happily install
+into a 3.9 environment based on the declared floor.
+
+**Approach.**
+
+- Bump `requires-python = ">=3.10"`.
+- Drop the `Programming Language :: Python :: 3.9` classifier.
+- Ship as a minor bump (`0.78.0`) — tightening a Python floor is a
+  breaking change for the affected versions, but in this case the
+  package was already non-functional on 3.9, so no real user is
+  affected.
+
+**Effort.** Tiny. Worth bundling with another release rather than as a
+standalone.
+
+
+### 4. No CI type-checker or linter
+
+**Observation.** The library ships type hints as part of its value
+proposition. There is no `pyright`, `mypy`, or `ruff` config in
+`pyproject.toml` and no GitHub Actions workflow that runs them.
+
+**Why fix.** The issues we hit during trace-to-test linking — silent
+type widening on regen, `Enum | str` vs strict-enum inconsistency, the
+`.value` trap on `httpx.params` — are exactly what a type-checker would
+surface. A linter would catch the `from .client import *` and unused
+imports that creep in.
+
+**Approach.**
+
+- Add `ruff` config to `pyproject.toml`. Start conservative: formatter +
+  the `E`, `F`, `I`, `B`, `UP` rule sets. Format the codebase in a single
+  commit to keep the diff readable.
+- Add `pyright` config in non-strict mode (so existing code passes), then
+  flip individual `reportMissingTypeArgument`-style checks on over time.
+- One GH Actions workflow: install via `uv sync --dev`, run `ruff
+  check`, `ruff format --check`, `pyright`, `pytest`. Block PRs on
+  failure.
+
+**Effort.** Medium for the first pass. The follow-up of tightening
+pyright strictness is open-ended; gate it on individual PRs rather than
+a flag day.
+
+
+## Design questions
+
+These do **not** meet the inclusion criterion above. They are deliberate
+choices that someone could reasonably make differently. Listed here so we
+can record a decision and stop re-litigating each time.
+
+### A. Should `update_*` methods return more than `None`?
+
+**Today.** PUT methods return `None`; the server's `{"message": "..."}`
+body is read but discarded.
+
+**For.** Future-proof if the server starts returning the updated resource
+or an `updated_at`. Symmetric with `create_*` (which returns a model).
+
+**Against.** PUT-returns-no-body is standard REST. The create/update
+asymmetry tracks a real semantic difference: create produces a new ID;
+update mutates an existing one. The current message body is
+operator-level noise, not data.
+
+**Standing decision.** Keep as `None`. Revisit if the server contract
+changes.
+
+### B. `from .client import *` in `__init__.py`
+
+**Today.** Wildcard import.
+
+**For.** Explicit re-exports are easier to review; surface-area drift
+shows up in diffs; tools (Sphinx, pyright) handle them better.
+
+**Against.** Requires syncing a list every time something is added to
+`client.py`. Small library, low cost.
+
+**Standing decision.** Keep wildcard. Reconsider if (a) the public
+surface exceeds what fits comfortably in a manual list, or (b) we adopt
+a type-checker that struggles with `__all__`-less wildcards.
+
+### C. `Client.__new__(Client)` in tests
+
+**Today.** Tests that need a `Client` instance for a helper method
+construct via `__new__` to skip `__init__`, then set instance attributes
+directly.
+
+**For.** A no-I/O `__init__` would let tests construct clients normally
+(`Client(api_key="test")`).
+
+**Against.** `Client.__init__` already does no I/O — it just stores
+fields and wraps secrets. The `__new__` pattern in tests signals "this
+test never authenticates" clearly. Two characters longer than `Client()`.
+
+**Standing decision.** Keep. The smell is cosmetic.
+
+### D. `_enums_to_strings([x])[0]` for single values
+
+**Today.** Helper takes a list. Single-value callers write
+`self._enums_to_strings([sport])[0] if sport else None`.
+
+**For.** A companion `_enum_to_string(x)` would read cleaner at the
+single-value call sites.
+
+**Against.** Trivially small footprint; helper proliferation has its
+own cost; the wrap-and-index idiom is already understood across the
+file.
+
+**Standing decision.** Keep. Add `_enum_to_string` only if a new
+call site appears where the wrap-and-index actively confuses.
+
+### E. `_default_client = Client()` at module import
+
+**Today.** A `Client` instance is constructed when `sweatstack.client`
+is imported, so the module-level singleton functions can bind to it.
+
+**For.** Lazy construction would defer any cost to first use.
+
+**Against.** `Client.__init__` is I/O-free; the cost is microseconds.
+Lazy binding would complicate the `_generate_singleton_methods`
+machinery for no measurable benefit.
+
+**Standing decision.** Keep.