sweatstack 0.68.0__tar.gz → 0.70.0__tar.gz

{sweatstack-0.68.0 → sweatstack-0.70.0}/.claude/settings.local.json

@@ -13,7 +13,8 @@
       "WebFetch(domain:developer.sweatstack.no)",
       "Bash(uv run ruff:*)",
       "Bash(chmod:*)",
-      "mcp__acp__Bash"
+      "mcp__acp__Bash",
+      "Bash(wc:*)"
     ],
     "deny": []
   }

sweatstack-0.70.0/.claude/skills/sweatstack-python/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sweatstack-python
+description: >
+  Builds Python applications using the SweatStack client library (pip install 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
+  sports data — even if the user just says "Python" and "SweatStack" without naming the
+  library explicitly.
+---
+
+# SweatStack Python Client
+
+Python client library for the SweatStack sports data platform.
+
+**Install:** `pip install sweatstack`
+
+**Extras:** `pip install sweatstack[streamlit]` · `pip install sweatstack[fastapi]`
+
+## Quick Start
+
+```python
+import sweatstack
+
+sweatstack.authenticate()  # Opens browser, stores tokens locally
+activities = sweatstack.get_activities(limit=5)
+for a in activities:
+    print(f"{a.start_local:%Y-%m-%d} {a.sport.display_name()} {a.duration}")
+```
+
+Or with an explicit client:
+
+```python
+from sweatstack import Client
+
+client = Client()
+client.authenticate()
+df = client.get_activities(as_dataframe=True)
+```
+
+## Reference
+
+**Client API** — methods for activities, traces, longitudinal data, users, uploads. Read [client.md](client.md)
+
+**Streamlit** — StreamlitAuth, selector components, behind-proxy mode. Read [streamlit.md](streamlit.md)
+
+**FastAPI** — configure/instrument, dependency injection, webhooks, token stores. Read [fastapi.md](fastapi.md)
+
+**Data Models** — Sport, Metric, Scope enums and response model fields. Read [data-models.md](data-models.md)

sweatstack-0.70.0/.claude/skills/sweatstack-python/client.md

@@ -0,0 +1,259 @@
+# Client API
+
+## Contents
+
+- [Authentication](#authentication)
+- [Activities](#activities)
+- [Time-Series Data](#time-series-data)
+- [Mean-Max and AWD](#mean-max-and-awd)
+- [Longitudinal Data](#longitudinal-data)
+- [Traces](#traces)
+- [Profile](#profile)
+- [Users and Teams](#users-and-teams)
+- [User Delegation](#user-delegation)
+- [File Uploads](#file-uploads)
+- [Singleton vs Instance](#singleton-vs-instance)
+- [Gotchas](#gotchas)
+
+---
+
+## Authentication
+
+Three modes — pick one:
+
+**Interactive (scripts, notebooks):**
+```python
+import sweatstack
+sweatstack.authenticate()  # Opens browser, persists tokens to disk
+```
+Tokens stored at `~/.local/share/SweatStack/SweatStack/tokens.json`. Subsequent runs reuse stored tokens automatically. Pass `force=True` to re-authenticate.
+
+**Environment variables (CI, containers):**
+```
+SWEATSTACK_API_KEY=<access_token>
+SWEATSTACK_REFRESH_TOKEN=<refresh_token>
+```
+No `authenticate()` call needed — the client picks up env vars automatically.
+
+**Direct token (advanced):**
+```python
+client = Client(api_key="...", refresh_token="...")
+```
+
+Token refresh is automatic in all modes. The library handles expiry checks and refreshes transparently.
+
+## Activities
+
+```python
+# List activities (returns list[ActivitySummary])
+activities = client.get_activities(
+    start=date(2025, 1, 1),      # optional
+    end=date(2025, 12, 31),      # optional
+    sports=[Sport.cycling_road],  # optional, list of Sport enum or strings
+    tags=["race"],                # optional
+    limit=100,                    # default 100
+    offset=0,                     # for pagination
+)
+
+# As DataFrame instead
+df = client.get_activities(as_dataframe=True)
+
+# Single activity by ID (returns ActivityDetails)
+activity = client.get_activity("activity_id")
+
+# Most recent activity (returns ActivityDetails)
+latest = client.get_latest_activity()
+latest = client.get_latest_activity(sport=Sport.running)
+```
+
+## Time-Series Data
+
+Returns pandas DataFrame with 1-second sampled data.
+
+```python
+# All available metrics
+df = client.get_activity_data("activity_id")
+
+# Specific metrics only
+df = client.get_activity_data("activity_id", metrics=[Metric.power, Metric.heart_rate])
+
+# Latest activity shortcut
+df = client.get_latest_activity_data(sport=Sport.cycling)
+```
+
+Columns match requested metrics. The `duration` column is included by default.
+
+## Mean-Max and AWD
+
+```python
+# Mean-max curve (max average power/speed at each duration)
+df = client.get_activity_mean_max("activity_id", metric="power")
+
+# Accumulated Work Duration (time spent at each intensity level)
+df = client.get_activity_awd("activity_id", metric="power")
+
+# Latest activity shortcuts
+df = client.get_latest_activity_mean_max(metric="power", sport=Sport.cycling)
+```
+
+## Longitudinal Data
+
+Aggregated time-series across multiple activities. One request instead of looping.
+
+```python
+df = client.get_longitudinal_data(
+    sport=Sport.cycling,                # single sport
+    start=date(2025, 1, 1),             # required
+    end=date(2025, 12, 31),             # optional (defaults to today)
+    metrics=[Metric.power, Metric.heart_rate],  # optional
+)
+
+# Or filter by multiple sports
+df = client.get_longitudinal_data(
+    sports=[Sport.cycling_road, Sport.cycling_gravel],
+    start=date(2025, 1, 1),
+)
+
+# Longitudinal mean-max (best efforts across time range)
+df = client.get_longitudinal_mean_max(sport=Sport.cycling, start=date(2025, 1, 1))
+
+# Longitudinal AWD
+df = client.get_longitudinal_awd(sport=Sport.cycling, start=date(2025, 1, 1))
+```
+
+The DataFrame has a timezone-aware datetime index and includes an `activity_id` column — group by it for per-activity aggregation.
+
+**Local caching** for reproducible analysis (avoids re-fetching on reruns):
+```python
+import os
+os.environ["SWEATSTACK_LOCAL_CACHE"] = "true"
+# Use fixed end dates (not "today") to get stable cache hits
+df = client.get_longitudinal_data(sport=Sport.cycling, start=date(2025, 1, 1), end=date(2025, 3, 31))
+```
+
+## Traces
+
+Custom data points with measurements (e.g., lactate tests, RPE entries).
+
+```python
+# List traces
+traces = client.get_traces(start=date(2025, 1, 1), as_dataframe=True)
+
+# Create a trace
+trace = client.create_trace(
+    timestamp=datetime(2025, 6, 1, 10, 0),
+    lactate=2.5,
+    rpe=7,
+    heart_rate=155,
+    sport=Sport.cycling,
+    tags=["test"],
+    notes="Lactate threshold test",
+)
+```
+
+## Profile
+
+```python
+sports = client.get_sports()              # list[Sport] — sports with data
+root_sports = client.get_sports(only_root=True)  # top-level only
+tags = client.get_tags()                  # list[str]
+user = client.get_userinfo()              # UserInfoResponse (sub, name, email)
+who = client.whoami()                     # UserSummary (from JWT, no API call)
+```
+
+## Users and Teams
+
+```python
+# List accessible users
+users = client.get_users()
+
+# Find a specific user (by ID or name)
+user = client.get_user("john")                    # auto-detects ID vs name
+user = client.get_user("abc123", search_mode="id")
+
+# Create a managed user (no login credentials)
+user = client.create_user(first_name="John", last_name="Doe")
+
+# Team management
+team_users = client.get_team_users(team_id="team_abc")
+athlete = client.get_team_user(team_id="team_abc", user="john")  # by name or ID
+client.authorize_team(team_id="team_abc", scopes=[Scope.data_read])
+```
+
+## User Delegation
+
+Operate on behalf of another user (requires appropriate permissions).
+
+**Prefer `delegated_client()`** — creates a separate client, keeping the scope explicit:
+
+```python
+other = client.delegated_client("john")
+other_activities = other.get_activities()
+# original client is unchanged
+
+# Via team membership
+athlete = client.get_team_user(team_id="team_abc", user="john")
+other = client.delegated_client(athlete, team_id="team_abc")
+```
+
+`switch_user()` modifies the client in-place — useful in interactive/notebook contexts but avoid in scripts:
+
+```python
+client.switch_user("john")                # mutates client
+client.switch_user("john", team_id="team_abc")
+client.switch_back()                      # revert to principal
+```
+
+## File Uploads
+
+```python
+# Upload FIT files (sport detected automatically)
+client.upload("activity.fit")
+client.upload(["file1.fit", "file2.fit"])
+
+# Upload CSV (sport required)
+client.upload("data.csv", sport=Sport.cycling_road)
+```
+
+CSV files must contain a `timestamp` column with ISO 8601 datetimes.
+
+## Singleton vs Instance
+
+**Singleton** (module-level functions) — uses a shared default `Client()`:
+```python
+import sweatstack
+sweatstack.authenticate()
+sweatstack.get_activities()
+```
+
+**Instance** — create your own client when you need multiple clients, custom URLs, or explicit control:
+```python
+from sweatstack import Client
+client = Client(api_key="...", url="https://custom.sweatstack.no")
+```
+
+Use singleton for scripts and notebooks. Use instances for servers, multi-user apps, or tests.
+
+## One-Off Scripts with `uv run`
+
+For standalone analysis scripts, use PEP 723 inline metadata so `uv run script.py` handles dependencies automatically:
+
+```python
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["sweatstack", "matplotlib"]
+# ///
+import sweatstack
+sweatstack.authenticate()
+df = sweatstack.get_latest_activity_data()
+```
+
+## Gotchas
+
+- **Sport enum uses underscores:** `Sport.cycling_road`, not `Sport("road")` or `Sport.cycling.road`. String values use dots: `"cycling.road"`.
+- **`start` is required for longitudinal endpoints.** Unlike `get_activities()` where all filters are optional.
+- **`sport` (singular) vs `sports` (list):** `get_latest_activity(sport=...)` takes one. `get_activities(sports=[...])` and `get_longitudinal_data(sports=[...])` take a list.
+- **DataFrames have standard dtypes.** The library converts API-optimized types (Int16, float16) to float64/datetime64[ns] automatically.
+- **`as_dataframe=True`** is available on `get_activities()` and `get_traces()`. Time-series methods (`get_activity_data`, `get_longitudinal_data`, etc.) always return DataFrames.
+- **`summary` fields are optional.** Always null-check: `activity.summary.power.mean if activity.summary and activity.summary.power else None`.
+- **`metrics` on ActivitySummary** lists available data streams, not the data itself. Use to check availability before calling `get_activity_data()`.

sweatstack-0.70.0/.claude/skills/sweatstack-python/data-models.md

@@ -0,0 +1,68 @@
+# Data Models
+
+All models are importable from `sweatstack.schemas`.
+
+## Sport Enum
+
+Hierarchical values — root sports have sub-sports:
+
+| Root | Sub-sports |
+|------|-----------|
+| `cycling` | `road`, `tt`, `cyclocross`, `gravel`, `mountainbike`, `track`, `trainer` |
+| `running` | `road`, `track`, `trail`, `treadmill` |
+| `swimming` | `pool`, `pool.25m`, `pool.50m`, `open_water`, `flume` |
+| `cross_country_skiing` | `classic`, `skating` |
+| `rowing` | _(none)_ |
+| `walking` | `hiking` |
+| `generic` | _(none)_ |
+
+**Usage:** `Sport.cycling_road` (underscore, not dot). String values use dots: `"cycling.road"`.
+
+**Utility methods:**
+- `sport.display_name()` → `"cycling (road)"`
+- `sport.root_sport()` → `Sport.cycling`
+- `sport.is_root_sport()` → `True`/`False`
+- `sport.is_sub_sport_of(Sport.cycling)` → `True`/`False`
+
+**Unknown sports:** The enum handles unknown values from newer API versions gracefully — no crashes on new sports.
+
+## Metric Enum
+
+Available data stream names: `duration`, `power`, `speed`, `heart_rate`, `cadence`, `altitude`, `elevation`, `temperature`, `core_temperature`, `smo2`, `distance`, `latitude`, `longitude`, `lactate`, `rpe`, `respiration_rate`, `notes`
+
+`metric.display_name()` → human-readable form.
+
+## Scope Enum
+
+| Enum member | Value |
+|---|---|
+| `Scope.data_read` | `data:read` |
+| `Scope.data_write` | `data:write` |
+| `Scope.profile` | `profile` |
+| `Scope.openid` | `openid` |
+| `Scope.admin` | `admin` |
+
+## Response Models
+
+**ActivitySummary** — returned by `get_activities()`:
+`id`, `sport: Sport`, `start: datetime`, `end: datetime`, `start_local: datetime`, `end_local: datetime`, `duration: timedelta`, `distance: float?`, `name: str?`, `description: str?`, `metrics: list[Metric]`, `summary: ActivitySummarySummary?`, `tags: list[str]?`
+
+The `summary` object contains per-metric aggregates: `summary.power.mean`, `summary.power.max`, `summary.heart_rate.mean`, `summary.distance.sum`, `summary.altitude.gain`, etc. All fields optional.
+
+The `metrics` list indicates which data streams are available (e.g., `[Metric.power, Metric.heart_rate]`). Use to check availability without fetching data.
+
+**ActivityDetails** — returned by `get_activity()`, `get_latest_activity()`:
+Extends ActivitySummary with `traces: list[TraceDetails]?`, `devices: list[str]?`, `laps: list[Lap]?`
+
+**TraceDetails** — returned by `get_traces()`, `create_trace()`:
+`id`, `timestamp: datetime`, `timestamp_local: datetime`, `lactate: float?`, `rpe: int?`, `notes: str?`, `power: int?`, `speed: float?`, `heart_rate: int?`, `tags: list[str]?`, `sport: Sport?`, `activity: ActivitySummary?`
+
+**UserSummary:** `id`, `first_name: str?`, `last_name: str?`, `display_name: str`, `admin: bool`
+
+**UserInfoResponse:** `sub: str`, `name: str`, `given_name: str?`, `family_name: str?`, `email: str?`, `registered_at: datetime`
+
+**UserResponse:** `id`, `first_name: str?`, `last_name: str?`, `display_name: str`, `admin: bool`, `is_managed: bool`, `registered_at: datetime`
+
+**TokenResponse:** `access_token: str`, `token_type: str`, `expires_in: int`, `refresh_token: str`, `scope: str?`, `id_token: str?`
+
+**BackfillStatus:** `backfill_loaded_until: datetime?`, `backfill_errors: list?`

sweatstack-0.70.0/.claude/skills/sweatstack-python/fastapi.md

@@ -0,0 +1,209 @@
+# FastAPI Integration
+
+Requires: `pip install sweatstack[fastapi]`
+
+## Contents
+
+- [Setup](#setup)
+- [Configuration](#configuration)
+- [User Dependencies](#user-dependencies)
+- [URL Helpers](#url-helpers)
+- [User Delegation](#user-delegation)
+- [Webhooks](#webhooks)
+- [Token Stores](#token-stores)
+
+---
+
+## Setup
+
+Two steps: `configure()` then `instrument()`.
+
+```python
+from fastapi import FastAPI
+from sweatstack.fastapi import configure, instrument, AuthenticatedUser
+
+app = FastAPI()
+
+configure(
+    client_id="YOUR_CLIENT_ID",      # or SWEATSTACK_CLIENT_ID env var
+    client_secret="YOUR_SECRET",      # or SWEATSTACK_CLIENT_SECRET env var
+    app_url="http://localhost:8000",   # or APP_URL env var
+    session_secret="your-fernet-key", # or SWEATSTACK_SESSION_SECRET env var
+)
+
+instrument(app)  # Registers auth routes
+
+@app.get("/activities")
+def list_activities(user: AuthenticatedUser):
+    return user.client.get_activities(limit=10)
+```
+
+`instrument()` registers routes at `{auth_route_prefix}/login`, `/callback`, `/logout`, `/select-user/{user_id}`, `/select-self`. Default prefix: `/auth/sweatstack`.
+
+## Configuration
+
+```python
+configure(
+    client_id: str = None,                    # SWEATSTACK_CLIENT_ID
+    client_secret: str = None,                # SWEATSTACK_CLIENT_SECRET
+    app_url: str = None,                      # APP_URL
+    session_secret: str = None,               # SWEATSTACK_SESSION_SECRET (Fernet key)
+    scopes: list[str] = ["profile", "data:read"],
+    cookie_secure: bool = None,               # auto-detected from app_url scheme
+    cookie_max_age: int = 86400,              # session lifetime in seconds
+    auth_route_prefix: str = "/auth/sweatstack",
+    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
+)
+```
+
+**Redirect URI** is computed automatically: `{app_url}{auth_route_prefix}/callback`
+
+## User Dependencies
+
+Inject into endpoint handlers via type annotations:
+
+```python
+from sweatstack.fastapi import AuthenticatedUser, SelectedUser, OptionalUser, OptionalSelectedUser
+
+@app.get("/me")
+def get_me(user: AuthenticatedUser):
+    # Always the principal (logged-in) user. Returns 401 if not authenticated.
+    return user.client.get_userinfo()
+
+@app.get("/dashboard")
+def dashboard(user: SelectedUser):
+    # Delegated user if one is selected, otherwise principal.
+    # Returns 401 if not authenticated.
+    return user.client.get_activities()
+
+@app.get("/public")
+def public(user: OptionalUser):
+    # Principal user or None. Never raises 401.
+    if user:
+        return user.client.get_activities()
+    return {"message": "Log in to see activities"}
+
+@app.get("/feed")
+def feed(user: OptionalSelectedUser):
+    # Selected user or None. Never raises 401.
+    ...
+```
+
+**`SweatStackUser`** — the object all dependencies return:
+- `user.client` — authenticated `Client` instance
+- `user.user_id` — user ID extracted from JWT
+
+## URL Helpers
+
+Generate URLs for auth actions in templates and redirects:
+
+```python
+from sweatstack.fastapi import urls
+
+urls.login()                              # /auth/sweatstack/login
+urls.login(next="/dashboard")             # /auth/sweatstack/login?next=/dashboard
+urls.logout()                             # /auth/sweatstack/logout
+urls.select_user("user_id")              # /auth/sweatstack/select-user/user_id
+urls.select_user("user_id", next="/app") # ...?next=/app
+urls.select_user("user_id", team_id="t") # ...?team_id=t (delegate via team)
+urls.select_self()                        # /auth/sweatstack/select-self
+```
+
+## User Delegation
+
+Switch the session to operate as another user:
+
+```python
+@app.get("/users")
+def list_users(user: AuthenticatedUser):
+    # List users accessible to the principal
+    users = user.client.get_users()
+    # Generate switch links
+    return [
+        {"name": u.display_name, "switch_url": urls.select_user(u.id, next="/dashboard")}
+        for u in users
+    ]
+```
+
+The built-in `/select-user/{user_id}` and `/select-self` routes handle token delegation. After switching, `SelectedUser` returns the delegated user's client.
+
+## Webhooks
+
+Receive and verify webhook events from SweatStack.
+
+```python
+from sweatstack.fastapi import configure, WebhookPayload, AuthenticatedUser
+
+configure(
+    webhook_secret="your-webhook-secret",  # or SWEATSTACK_WEBHOOK_SECRET
+    token_store=SQLiteTokenStore(),         # required for webhook user lookups
+)
+
+@app.post("/webhooks/sweatstack")
+def handle_webhook(payload: WebhookPayload, user: AuthenticatedUser):
+    # payload.user_id, payload.event_type, payload.resource_id, payload.timestamp
+    # user.client is authenticated as the webhook's user (loaded from token store)
+    activity = user.client.get_activity(payload.resource_id)
+    process(activity)
+```
+
+**`WebhookPayload`** dependency verifies the `X-Sweatstack-Signature` header automatically. Returns 400 if invalid.
+
+**Signature verification** uses HMAC-SHA256 with a 5-minute timestamp tolerance.
+
+**Manual verification** (without the dependency):
+
+```python
+from sweatstack.fastapi import verify_signature
+
+verify_signature(
+    payload=request_body_bytes,
+    signature_header=request.headers["X-Sweatstack-Signature"],
+    secret="your-webhook-secret",
+)
+```
+
+### Webhook Exceptions
+
+| Exception | When |
+|---|---|
+| `WebhookVerificationError` | Invalid signature or expired timestamp |
+| `WebhookTokenStoreError` | TokenStore not configured |
+| `WebhookUserNotFoundError` | No stored tokens for the webhook's user |
+| `WebhookTokenRefreshError` | Stored tokens expired and refresh failed |
+
+## Token Stores
+
+Required for webhooks — persists user tokens so webhooks can authenticate as the user.
+
+Tokens are saved automatically when users log in through the OAuth flow.
+
+**Built-in stores (development only):**
+
+```python
+from sweatstack.fastapi import SQLiteTokenStore, EncryptedSQLiteTokenStore
+
+# Plain SQLite
+store = SQLiteTokenStore(db_path="tokens.db")
+
+# Encrypted SQLite (Fernet AES-128-CBC)
+store = EncryptedSQLiteTokenStore(
+    encryption_key="your-key",
+    db_path="tokens_encrypted.db",
+)
+```
+
+**Production:** Implement the `TokenStore` protocol:
+
+```python
+from sweatstack.fastapi import TokenStore, StoredTokens
+
+class RedisTokenStore(TokenStore):
+    def save(self, tokens: StoredTokens) -> None: ...
+    def load(self, user_id: str) -> StoredTokens | None: ...
+    def delete(self, user_id: str) -> None: ...
+```
+
+`StoredTokens` fields: `user_id`, `access_token`, `refresh_token`, `expires_at: datetime`.