sweatstack 0.89.0__tar.gz → 0.91.0__tar.gz

sweatstack-0.91.0/.git-blame-ignore-revs

@@ -0,0 +1,3 @@
+# Formatting-only commits, skipped by git blame (git config blame.ignoreRevsFile .git-blame-ignore-revs)
+# Format with ruff
+61993be257e0873621e01baadbd25e881e6c3521

{sweatstack-0.89.0 → sweatstack-0.91.0}/.gitignore

@@ -40,6 +40,8 @@ dump/
 # Playground
 playground/
 
-# Claude skills (except our own)
-.claude/skills/*
-!.claude/skills/sweatstack-python/
+# Agent tooling (local only; the published skill lives in skills/)
+.claude/
+
+# Agent test workspaces and program output: real user data
+evals/agent/runs/

sweatstack-0.91.0/.gitleaks.toml

@@ -0,0 +1,9 @@
+# gitleaks configuration: the default rules, plus known false positives.
+# Run before going public and before each release: `gitleaks git .`
+
+[extend]
+useDefault = true
+
+[[allowlists]]
+description = "The Fernet key the tests use; it decodes to 'test-only-key-for-unit-tests-32b'"
+regexes = ['''dGVzdC1vbmx5LWtleS1mb3ItdW5pdC10ZXN0cy0zMmI=''']

sweatstack-0.91.0/AGENTS.md

@@ -0,0 +1,378 @@
+# 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).
+
+
+## Public repository
+
+This repository is public, and so is everything in its history. Treat every
+change as published the moment it is committed: code, comments, docstrings,
+tests and fixtures, `plans/`, `skills/`, examples, notebooks, the CHANGELOG,
+commit messages and PR descriptions. Removing something later does not
+unpublish it.
+
+Never commit:
+
+- **Secrets and credentials**: API keys, tokens, client secrets, session
+  keys, `.env` contents. Not even expired or test-account ones.
+- **Real identifiers**: user, app, activity or team IDs, emails, client
+  IDs, or truncated prefixes of them. Fixtures and examples use obvious
+  fakes: `app_123`, `user_123`, `YOUR_CLIENT_ID`.
+- **Customers and their behaviour**: names of apps, companies or people
+  using SweatStack, how many there are, what they call or filter on, or
+  anything learned from server logs, traffic or support conversations.
+  Write "SDK users" or "downstream apps".
+- **The private server codebase**: its file paths, function names, commit
+  hashes, branch names and plan numbers. Describe the server by its public
+  contract: the OpenAPI schema and docs.sweatstack.no. "The server now
+  returns X" is fine; "see server plan N" is not.
+- **Local environments**: home directories, machine paths, names of
+  private sibling repos, personal data in notebook outputs or test data.
+  Commit notebooks with outputs cleared.
+
+When unsure, leave it out and ask. `tests/test_public_hygiene.py` catches
+the patterns a regex can (real-looking IDs, JWTs, keys, home paths, server
+references, notebook outputs). Names and behaviour of customers need you
+to notice them; there is no list to check against, because the list itself
+would be the leak.
+
+
+## Guiding principle: mirror the REST API
+
+This client is a thin Python projection of the SweatStack REST API. Every endpoint group is a
+resource namespace on `Client`, and every name follows from the URL by eight rules. Apply them;
+don't invent names.
+
+| # | Rule | Examples |
+|---|---|---|
+| R1 | **The first URL segment after `/api/v1/` is the top-level namespace**, a typed `cached_property` on `Client`. | `/activities/...` → `client.activities` |
+| R2 | **Collection verbs follow Stripe:** `list`, `retrieve`, `create`, `delete`. | `GET /tests/{id}` → `tests.retrieve(id)` |
+| R3 | **Name writes by what they do, not by the HTTP verb.** Overwrites every field and clears what you leave out: `replace`. Changes only the fields you pass: `update`. Read the server code to tell which; the verb doesn't say. | `PUT /traces/{id}` → `traces.replace`; `PUT /users/{id}` → `users.update` |
+| R4 | **A single value that is set or cleared** (an upsert, or a blob with no ID) uses `set` and `delete`. | `POST /dailies/{measure}` → `dailies.set` |
+| R5 | **A nested collection is a nested namespace**, parent ID first. | `/portal/sessions` → `portal.sessions.create`; `.../{id}/app-metadata` → `activities.app_metadata.set(id, ...)` |
+| R6 | **A sub-path with a single `GET` is a method named after the noun.** | `GET /activities/{id}/data` → `activities.data(id)` |
+| R7 | **An action endpoint (`POST .../<verb>`) is a method named after the verb.** | `POST /activities/upload` → `activities.upload` |
+| R8 | **Parameter names are the wire names.** A repeatable query parameter takes one value or a list under the same name (normalise with `Resource._wire`). | `?sport=a&sport=b` → `sport=["a", "b"]` or `sport="a"` |
+
+Match the server's field names, enum values and write semantics. 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 (`tests.retrieve(test_id)`); everything else is
+  keyword-only.
+- Enum-typed params accept `Enum | str` so callers don't need to import the enum.
+- `limit` and `offset` on list methods are SDK-level: `limit` is how many items the caller gets,
+  and `Resource._paginate` pages through the endpoint to get them.
+- A `traces=` query parameter is `trace_resolution=` on `tests.retrieve`, where the wire name
+  would be ambiguous. The docstring states the mapping.
+- `name=` on `users.list` and `teams.users` filters client-side (case-insensitive substring of
+  the display name) until the server offers the filter; then it becomes the wire parameter
+  with the same name and semantics. Don't add other client-side filters.
+- `output=` is a client-side choice of container on the data endpoints. See "Output backends".
+- `activities.longitudinal` groups the three `/activities/longitudinal-*` endpoints.
+- Convenience composites that wrap several calls are a last resort. The 0.91 redesign removed
+  them (`get_latest_activity_data` became chaining); add one 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 (incl. OST Sport/Modifier) + Metric/Scope/DailyMeasure helpers.
+├── _frames.py           # output= backends: parquet/models -> pandas/polars/arrow/bytes.
+├── _renames.py          # Removed names -> replacement hints. Permanent; see "Breaking changes".
+├── _transport.py        # Retry policy and the per-request Session on the client's connection pool.
+├── exceptions.py        # Public error contract. No httpx types leak.
+├── client.py            # Client: config, auth, delegation, transport (_request), resource attributes,
+│                        #   and the module-level interface (one shared default client).
+├── resources/           # One module per URL segment: activities.py, traces.py, tests.py, ...
+│   ├── _base.py         #   Resource, _paginate, _wire, shared parameter types.
+│   └── _app_metadata.py #   One app-metadata class per endpoint (Activity/Trace/Test/Profile).
+├── utils.py             # Dataframe / JWT helpers.
+├── streamlit.py         # Streamlit integration (optional extra).
+├── fastapi/             # FastAPI integration (optional extra).
+└── cli.py               # Entry points (schema regeneration).
+
+skills/sweatstack-python/  # The published agent skill (npx skills add). Update with the public surface.
+plans/                     # Design plans, numbered. Public: see "Public repository".
+tests/typing/              # Static type tests, checked by ty, never run by pytest.
+```
+
+`.claude/` is git-ignored: it is local agent tooling only.
+
+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` and add it to `__all__` so `from sweatstack import *` exposes it.
+
+Skipping step 3 silently breaks the public surface. Same for new enums.
+
+Adding a new endpoint: find its namespace by R1, its name by R2–R7, write the method in that
+resource module (template below), and add it to `skills/sweatstack-python/api.md`. A new URL
+segment is a new resource module plus a `cached_property` on `Client`; the module level mirrors
+it automatically.
+
+
+## Hard rules
+
+- **`uv`, never `pip`.** Every command goes through `uv run` / `uv add`.
+- **`make check` before every commit.** Format, lint, types and tests; `make
+  publish` runs it too. Don't silence a finding without a comment saying why.
+- **Never hand-edit `openapi_schemas.py`.** Regenerate.
+- **`Raises:` references the typed exceptions** from `sweatstack.exceptions`.
+- **Every public resource method's docstring has an `Endpoint:` line and an `Examples:` block**
+  with a complete, runnable snippet. `tests/test_docstrings.py` enforces both.
+- **Public resources are typed `cached_property` attributes of `Client`**, so type checkers and
+  the snippet check resolve them statically, and a client built with `Client.__new__` still
+  has them. The module level mirrors them automatically.
+- **A breaking change ships with its upgrade path** (see "Breaking changes").
+- **A change to the public surface updates `skills/sweatstack-python/` in the same commit.**
+  `tests/test_skill.py` fails when `api.md` misses a method.
+- **Enum-typed params accept `Enum | str`** and route through
+  `_enums_to_strings`. Don't introduce strict-enum-only parameters.
+- **Open enums stay open.** When the server documents an enum as an open
+  set (metrics, scopes, daily measures, status codes, capabilities),
+  register it with `_open_enum(...)` in `schemas.py` so unknown values
+  parse as pseudo-members. Leave closed sets strict.
+- **Never retry a request the server can't safely repeat.** `_transport.RETRYABLE_METHODS`
+  is `GET`, `PUT` and `DELETE`; a `POST` is sent once (no idempotency keys). Don't add
+  per-method retry logic: everything goes through `_request`.
+- **Server-to-server calls pass `auth=False` to `_request`.** Endpoints that authenticate with
+  the app's own credentials in the body (Portal sessions, the token exchange) must never
+  receive a user's bearer.
+- **`Sport` is the OpenSportTaxonomy type** (`open_sport_taxonomy.Sport`), not a generated enum.
+  Construct with `Sport("cycling.road")` or `Sport.parse(value)`; serialise with `str(sport)`. Codegen
+  binds the `sport` field to OST's permissive `SportField` (cli.py `_bind_sport_to_ost`), so regen is
+  safe and `sport`-typed fields keep decoding to `Sport`.
+- **Tests are offline.** No network calls. Fake the transport at `Client._request` (see
+  `tests/test_resources.py`), or use `Client.__new__(Client)` to bypass init.
+- **Frame libraries are optional extras.** Never import pandas, numpy,
+  pyarrow or polars at module top level; import inside the function, via
+  `_frames.require(...)` where an `ImportError` should name the extra.
+  CI's bare-install job fails otherwise.
+- **No frame carries an index**, on any backend. Don't `set_index` in a
+  method; the caller does that.
+- **`replace` methods overwrite every field.** Document the silent-clear footgun in the
+  docstring (see below).
+- **CHANGELOG entries are user-facing**, not dev-facing.
+
+
+## Method shape
+
+Every resource method follows this shape. Match it.
+
+```python
+class Things(Resource):
+    def create(
+        self,
+        *,                                           # keyword-only (path IDs come first, positional)
+        timestamp: datetime,
+        sport: Sport | str | None = None,            # enum params: Enum | str
+        tags: list[str] | None = None,
+    ) -> ThingDetails:
+        """One-line summary.
+
+        Endpoint: ``POST /api/v1/things/``
+
+        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.
+
+        Examples:
+            ```python
+            from sweatstack import Client
+
+            client = Client()
+            thing = client.things.create(timestamp=datetime.now(timezone.utc))
+            ```
+        """
+        sport = self._client._enums_to_strings([sport])[0] if sport else None
+        response = self._client._request(
+            "post",
+            "/api/v1/things/",
+            json={"timestamp": timestamp.isoformat(), "sport": sport, "tags": tags},
+        )
+        return ThingDetails.model_validate(response.json())
+```
+
+Invariants baked into the template:
+
+- Path-param IDs positional, everything else keyword-only.
+- Datetimes serialize via `.isoformat()`; write timestamps go through `_require_aware`.
+- Every request goes through `self._client._request(...)`, which raises the typed exception
+  for an error status. Only streaming endpoints open `_http_client()` themselves.
+- Return is a validated Pydantic model, never the raw dict.
+- `replace` methods are typed `-> None`. The server's `{"message": "..."}` body carries no
+  useful info.
+- A class that defines `list` annotates with `builtins.list[...]`: inside the class body,
+  `list` is the method.
+
+**List endpoints** page with `self._paginate(path, params, Model, page_size=..., limit=...,
+offset=...)` and return `self._client._frame_from_models(models, Model, output, flatten=(...))`.
+Empty lists yield typed empty frames automatically. See `Activities.list`.
+
+**Parquet endpoints** return `self._client._read_frame(response.content, output)`. Never call
+`pd.read_parquet` in a method.
+
+Both kinds take `output` as a keyword-only parameter and carry `@overload` stubs keyed on the
+`Literal` values (clone the neighbours); `tests/typing/output_types.py` pins them.
+
+**Query parameters** are only sent when the caller supplied a non-default value. Repeatable
+ones go through `self._wire(value)` (R8). Always pass `.value` for enums into `httpx` params:
+`httpx` calls `str()`, which gives `"TraceResolution.linked"`, not `"linked"`.
+
+
+## Full-replace `replace` methods
+
+Some PUT endpoints overwrite every field, setting unsent fields to `null` (traces, tests); their
+methods are named `replace` (R3). 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 `replace` 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 call.
+
+Don't try to soften the contract with "preserve if omitted" sentinels;
+that diverges from how every other field behaves on these methods. A PUT that leaves unsent
+fields unchanged (users) is an `update` and sends only the fields given.
+
+
+## Breaking changes
+
+Until 1.0, breaking changes are allowed when they ship with an upgrade path. Every one needs:
+
+1. A `### Upgrading` section in the CHANGELOG entry, with an old-to-new table.
+2. A copy-paste migration prompt for coding agents in the same section, for any change bigger
+   than a rename or two.
+3. For a removed method or attribute, an entry in `_renames.REMOVED_IN`, so calling it raises an
+   `AttributeError` that names the replacement. Entries are permanent.
+   `tests/test_renames.py` checks each one against the client, the module and the CHANGELOG.
+
+Removed *parameters* need no entry: Python's `TypeError` names them, and the CHANGELOG explains
+the replacement.
+
+
+## Output backends
+
+`_frames.py` turns parquet bytes and lists of models into the container
+the caller asked for. Resolution: per-call `output` > `Client(output=)` >
+`sweatstack.set_output()` > the method's default: models for lists, and
+for parquet the installed frame library (`_frames.installed_frame_output`:
+Polars, then pandas, then Arrow; `ImportError` naming the extras if none).
+A configured default a method cannot produce is skipped, a per-call one
+is a `ValueError`. Never hard-code a frame library as a default.
+
+**Where `output` belongs.** On the *data* endpoints only: activities,
+traces, tests, dailies and the time series, the things a user groups,
+filters and plots. Everything about the account, the app, teams, status
+and the Portal (`oauth.userinfo`, `profile.status`, `portal.sessions.create`,
+`whoami`, `users.list`, `teams.list`, `profile.sports`, `profile.tags`, ...) takes no `output` and always returns models; those
+methods never call `_read_frame` or `_frame_from_models`, so a configured
+output cannot reach them. A new data endpoint gets `output`; a new
+control-plane endpoint does not.
+
+Dtype policy: pandas gets `convert_to_standard_dtypes` (float64, ns);
+Polars keeps wire dtypes except Float16 -> Float32; Arrow is the wire
+table minus pandas index metadata; bytes is the body.
+
+The Polars and Arrow paths for lists derive one type tree from each
+model's **JSON Schema** (`_frames.field_types`) and render it per library;
+values come from the instance.
+**Never add a per-model special case there.** If a model needs one, the
+JSON Schema grammar table in `_field_type` is missing a row: add the
+row and its test. `tests/test_frames.py` turns `FrameSchemaWarning` into
+a failure for every public model, so a regen that introduces an unknown
+construct fails the suite, not a user's notebook.
+
+
+## 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. Two workhorse patterns.
+
+**Faking the transport** at `Client._request`, the one choke point, to see exactly what goes
+on the wire:
+
+```python
+with patch.object(client, "_request", return_value=response) as request:
+    client.activities.list(sport="cycling")
+assert request.call_args.kwargs["params"]["sport"] == ["cycling"]
+```
+
+**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_resources.py`, `tests/test_trace_test_linking.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
+> - `traces.replace()` 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 `resources/`. Consistency with the
+  surroundings beats local cleverness.
+- Reuse the helpers: `_request`, `_paginate`, `_wire`, `_enums_to_strings`,
+  `_read_frame`, `_frame_from_models`, `_RecordAppMetadata`. Don't reinvent them.
+- Don't add abstractions for hypothetical future flexibility. Three
+  similar blocks is the pattern, not a smell.

{sweatstack-0.89.0 → sweatstack-0.91.0}/CHANGELOG.md

@@ -6,6 +6,250 @@ 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.91.0] - 2026-10-08
+
+One namespace per API resource: `client.activities.list()` instead of `client.get_activities()`.
+Every name now follows from the URL (`/api/v1/activities/...` is `client.activities`), so the
+REST API reference doubles as the SDK's map. This is a breaking release with a mechanical
+upgrade; see **Upgrading** below, or hand the migration prompt to your coding agent. Calling a
+removed name raises an `AttributeError` that names its replacement.
+
+### Changed
+
+- **BREAKING: methods moved to resource namespaces**: `activities`, `traces`, `tests`, `dailies`,
+  `profile`, `users`, `teams`, `portal` and `oauth`, on `Client` and at module level
+  (`sweatstack.activities.list()`). The full table is under **Upgrading**.
+- **BREAKING: `traces.replace()` and `tests.replace()`** are the old `update_trace()` and
+  `update_test()`. The new name says what they do: every field you leave out is cleared,
+  including a trace's `test_id`.
+- **BREAKING: `sport=` replaces `sports=`** on every filter, as on the server (which deprecated
+  `sports`). It takes one sport or a list: `sport="cycling"` or `sport=["cycling", "running"]`.
+  `tags=` and `metrics=` also take a single value now.
+- **BREAKING: `activities.latest()`** calls the API's `/activities/latest`: it takes only
+  `sport=`, and returns `None` when there is no activity (it raised `StopIteration`).
+- **BREAKING: keyword-only arguments** where they were positional: `metric=` on
+  `activities.mean_max()` and `activities.awd()`, `segmentation_on=` and `metrics=` on
+  `activities.data()`, `first_name=` and `last_name=` on `users.create()`, `only_root=` on
+  `profile.sports()`, `scopes=` on `teams.authorize()`, and every argument of
+  `oauth.authorization_url()` and `oauth.exchange_code()`.
+- **BREAKING: longitudinal `date=` / `window_days=`** (deprecated since 0.70) are gone; use
+  `start=` and `end=`, typed as `date` objects (`start=date(2026, 1, 1)`).
+  `sport=` is a required argument of all three longitudinal methods; the API rejected a
+  request without one.
+- **BREAKING: `activities.upload()`** returns the processing status of each file
+  (`list[SourceResponse]`) instead of a raw dict, and no longer takes `sport=`: the server never
+  read it. A CSV carries its sport in a `sport` column (an Open Sport Taxonomy code such as
+  `cycling.road`).
+- **BREAKING: `oauth.exchange_code()` no longer takes `redirect_uri=`**; the token endpoint never
+  read it.
+- **BREAKING: `users.retrieve(user_id)`** is the server's `GET /users/{id}`, which only finds
+  users you manage. Find anyone else with `users.list(name=...)`, which returns every user whose
+  name contains the text, ignoring case.
+- **BREAKING: `switch_user()` and `switch_back()` are removed.** They changed which user a shared
+  client acted as, invisibly to everything else holding it. `client.delegated_client(user)` does
+  the same job and returns a new client. It takes a user ID or a `UserSummary`, not a
+  name: `switch_user("Carla")` becomes a lookup with `users.list(name="Carla")` first.
+- `StreamlitAuth.select_activity()` takes `sport=` instead of `sports=`.
+- Clients from `delegated_client()` and `principal_client()` keep the app's `client_id` and
+  `client_secret`, so `portal.sessions.create()` works on them.
+
+- **Automatic retries**: `GET`, `PUT` and `DELETE` requests are retried up to twice after a
+  connection error, a timeout, or a 408, 429 or 5xx response, with exponential backoff and the
+  server's `Retry-After` (at most 30 s of waiting per call). `POST` is never retried, so a create
+  can't happen twice. `Client(max_retries=0)` turns retries off, e.g. inside a web request.
+
+### Added
+
+- `Client(timeout=60.0, max_retries=2)`: the timeout in seconds, and how often to retry.
+  Clients from `delegated_client()` and `principal_client()` keep both.
+- One connection pool per client, reused across requests (each request opened a new
+  connection). `client.close()` releases it; `with Client() as client:` closes on exit.
+- `users.retrieve()`, `users.update()` (changes only the fields you pass) and `users.delete()`
+  for managed users.
+- `users.list(include_managed=, include_shared=, name=)` and `teams.users(team_id, name=)`.
+- `SourceResponse` and `SourceError`, the upload status models.
+- `vo2=` on `traces.create()` and `traces.replace()`; the field was already on `TraceDetails`.
+
+### Fixed
+
+- `activities.watch_backfill_status(auto_reconnect=True)` reconnects after a dropped
+  connection; it raised instead.
+- `activities.backfill_status()` and `watch_backfill_status()` return the server's updates. Its
+  timestamps carry no UTC offset, which failed validation, and every update was skipped
+  silently. A line the client cannot parse is now logged as a warning.
+- `StreamlitAuth.select_user()` stores the selected user's own refresh token. It kept the
+  signed-in user's, so after the first token refresh the app silently showed the signed-in
+  user's data under the selected user's name.
+- `StreamlitAuth` keeps the app's `client_id` and `client_secret` after switching users.
+- Threads sharing a client refresh an expired token once; they all refreshed, which fails with
+  rotating refresh tokens.
+- `activities.watch_backfill_status()` no longer times out on a quiet stream: streams have no
+  read timeout.
+- Searching users by name ignores case; `get_user("Carla")` found nobody where `"carla"` worked.
+
+### Removed
+
+- **BREAKING:** the `sweatlab` and `sweatshell` commands, their example notebook, and the
+  `[jupyter]` extra. In any notebook: `uv add "sweatstack[pandas]" jupyterlab`, then
+  `sweatstack.authenticate()` in the first cell.
+- **BREAKING:** `client.jwt`; use `client.api_key`.
+
+<!-- --8<-- [start:upgrading-0-91] -->
+### Upgrading
+
+Removed names raise an `AttributeError` naming the replacement, so running your code points at
+each change. The module-level functions moved the same way: `sweatstack.get_activities()` is
+`sweatstack.activities.list()`.
+
+| 0.90 | 0.91 |
+|---|---|
+| `get_activities` | `client.activities.list()` |
+| `get_activity` | `client.activities.retrieve(activity_id)` |
+| `get_latest_activity` | `client.activities.latest()` |
+| `get_activity_data` | `client.activities.data(activity_id)` |
+| `get_activity_mean_max` | `client.activities.mean_max(activity_id, metric=...)` |
+| `get_activity_awd` | `client.activities.awd(activity_id)` |
+| `get_latest_activity_data` | `client.activities.data(client.activities.latest().id)` |
+| `get_latest_activity_mean_max` | `client.activities.mean_max(client.activities.latest().id, metric=...)` |
+| `get_longitudinal_data` | `client.activities.longitudinal.data(...)` |
+| `get_longitudinal_mean_max` | `client.activities.longitudinal.mean_max(...)` |
+| `get_longitudinal_awd` | `client.activities.longitudinal.awd(...)` |
+| `upload` | `client.activities.upload(files)` |
+| `get_backfill_status` | `client.activities.backfill_status()` |
+| `watch_backfill_status` | `client.activities.watch_backfill_status()` |
+| `set_activity_app_metadata` | `client.activities.app_metadata.set(activity_id, data=...)` |
+| `delete_activity_app_metadata` | `client.activities.app_metadata.delete(activity_id)` |
+| `get_traces` | `client.traces.list()` |
+| `create_trace` | `client.traces.create(...)` |
+| `update_trace` | `client.traces.replace(trace_id, ...)` |
+| `delete_trace` | `client.traces.delete(trace_id)` |
+| `set_trace_app_metadata` | `client.traces.app_metadata.set(trace_id, data=...)` |
+| `delete_trace_app_metadata` | `client.traces.app_metadata.delete(trace_id)` |
+| `get_tests` | `client.tests.list()` |
+| `get_test` | `client.tests.retrieve(test_id)` |
+| `create_test` | `client.tests.create(...)` |
+| `update_test` | `client.tests.replace(test_id, ...)` |
+| `delete_test` | `client.tests.delete(test_id)` |
+| `set_test_app_metadata` | `client.tests.app_metadata.set(test_id, data=...)` |
+| `delete_test_app_metadata` | `client.tests.app_metadata.delete(test_id)` |
+| `get_dailies` | `client.dailies.list(measure, start=..., end=...)` |
+| `set_daily` | `client.dailies.set(measure, date=..., value=...)` |
+| `delete_daily` | `client.dailies.delete(measure, date=...)` |
+| `get_profile_status` | `client.profile.status()` |
+| `get_sports` | `client.profile.sports()` |
+| `get_tags` | `client.profile.tags()` |
+| `set_user_app_metadata` | `client.profile.app_metadata.set(data=...)` |
+| `delete_user_app_metadata` | `client.profile.app_metadata.delete()` |
+| `get_users` | `client.users.list()` |
+| `get_user` | `client.users.list(name=...)`: every match, so check the length |
+| `create_user` | `client.users.create(first_name=...)` |
+| `get_teams` | `client.teams.list()` |
+| `get_team_users` | `client.teams.users(team_id)` |
+| `get_team_user` | `client.teams.users(team_id, name=...)`: every match |
+| `get_authorized_teams` | `client.teams.authorized()` |
+| `authorize_team` | `client.teams.authorize(team_id)` |
+| `create_portal_session` | `client.portal.sessions.create(destination)` |
+| `get_userinfo` | `client.oauth.userinfo()` |
+| `get_authorization_url` | `client.oauth.authorization_url(...)` |
+| `exchange_code_for_token` | `client.oauth.exchange_code(...)` |
+| `generate_pkce_params` | `client.oauth.generate_pkce_params()` |
+| `switch_user` | `client.delegated_client(user)`: a new client; this one is left unchanged |
+| `switch_back` | keep the original client, or `client.principal_client()` |
+| `client.jwt` | `client.api_key` |
+
+Changes that a rename alone doesn't cover. Most raise a `TypeError` naming the argument; the
+ones marked **silent** don't fail loudly, so check for them.
+
+| 0.90 | 0.91 |
+|---|---|
+| `sports=["cycling"]` (every filter, and `StreamlitAuth.select_activity`) | `sport="cycling"` or `sport=["cycling", "running"]` |
+| `get_activity_mean_max(id, "power")`, `get_activity_awd(id, "power")` | `activities.mean_max(id, metric="power")`, `activities.awd(id, metric="power")` |
+| `get_activity_data(id, "power", ["power"])` | `activities.data(id, segmentation_on="power", metrics=["power"])` |
+| `create_user("Carla", "Smith")` | `users.create(first_name="Carla", last_name="Smith")` |
+| `get_sports(True)`, `authorize_team(id, scopes)` | `profile.sports(only_root=True)`, `teams.authorize(id, scopes=scopes)` |
+| Positional arguments to `get_authorization_url()` / `exchange_code_for_token()` | Keywords: `oauth.authorization_url(client_id=..., ...)` |
+| `get_latest_activity(start=, end=, tag=)` | `activities.latest(sport=)`; for the rest, `activities.list(start=..., end=..., tags=..., limit=1)` |
+| `get_latest_activity()` raising `StopIteration` when there is none | **Silent:** `activities.latest()` returns `None`; check before using `.id` |
+| `get_longitudinal_*(date=..., window_days=...)` | `start=` and `end=` |
+| `get_longitudinal_*(...)` without `sport` | `sport=` is required (the API already rejected a request without one) |
+| `upload(files, sport=...)` | `activities.upload(files)`: no `sport=`; a CSV needs a `sport` column |
+| `upload(...)` returning a dict | **Silent:** `activities.upload(...)` returns `list[SourceResponse]`; read `.status` / `.error` |
+| `exchange_code_for_token(..., redirect_uri=...)` | `oauth.exchange_code(...)` without `redirect_uri=` |
+| `get_user("Carla")` returning one `UserSummary` | **Silent:** `users.list(name="Carla")` returns a list, every match; `search_mode=` is gone |
+| `switch_user("Carla")` (a name) | `client.delegated_client(users.list(name="Carla")[0])`: a name is not accepted |
+| `client.jwt` | `client.api_key` |
+| `sweatlab`, `sweatshell`, `pip install "sweatstack[jupyter]"` | `uv add "sweatstack[pandas]" jupyterlab`; `sweatstack.authenticate()` in the first cell |
+
+New defaults that change behaviour without changing code: `GET`, `PUT` and `DELETE` requests are
+retried (`Client(max_retries=0)` restores single attempts), and requests time out after 60 s
+(`Client(timeout=...)`).
+
+**Migration prompt.** Paste this into your coding agent:
+
+```text
+Upgrade this codebase to sweatstack 0.91, which moved every method to a resource namespace.
+The full upgrade guide, with both tables, is the "Upgrading" section of the 0.91.0 entry in
+https://github.com/SweatStack/sweatstack-python/blob/main/CHANGELOG.md
+(also at https://docs.sweatstack.no/learn/python/upgrading/). Read it first.
+
+Find every use of the sweatstack client (a Client instance, the sweatstack module, and
+StreamlitAuth or FastAPI user clients) and:
+
+1. Rename calls per the first table, e.g. get_activities() -> activities.list(),
+   get_activity_data(id) -> activities.data(id),
+   get_longitudinal_mean_max(...) -> activities.longitudinal.mean_max(...),
+   update_trace(id, ...) -> traces.replace(id, ...), get_users() -> users.list().
+2. Apply every row of the second table. In particular:
+   - sports= -> sport= (one value or a list).
+   - Pass by keyword: metric= (mean_max, awd), segmentation_on= and metrics= (data),
+     first_name= and last_name= (users.create), only_root= (profile.sports),
+     scopes= (teams.authorize), and all arguments of oauth.authorization_url() and
+     oauth.exchange_code().
+   - Longitudinal methods: sport= is required, and date=/window_days= become start=/end=
+     (datetime.date objects).
+   - activities.latest() takes only sport= and returns None when there is no activity:
+     handle None.
+   - activities.upload() takes no sport= (a CSV needs a sport column) and returns
+     list[SourceResponse], not a dict.
+   - oauth.exchange_code() takes no redirect_uri=.
+   - get_user(x) -> users.list(name=x), which returns a list of every match.
+   - switch_user(user) -> athlete = client.delegated_client(user_id_or_summary); use that
+     new client for the athlete's calls. It doesn't accept a name: look the user up first.
+     switch_back() -> keep using the original client.
+   - client.jwt -> client.api_key.
+3. Replace get_latest_activity_data(...) with activities.data(activities.latest().id, ...),
+   after checking that latest() returned an activity.
+4. If the project used sweatlab, sweatshell or the [jupyter] extra, depend on
+   "sweatstack[pandas]" (or [polars]) and jupyterlab instead.
+
+Then run the code and the tests. Fix any AttributeError (its message names the replacement)
+and TypeError (a renamed or keyword-only argument). Do not add compatibility shims.
+```
+<!-- --8<-- [end:upgrading-0-91] -->
+
+## [0.90.0] - 2026-09-28
+
+### Changed
+
+- **BREAKING: mean-max curves are one row per duration**.
+  `get_activity_mean_max`, `get_latest_activity_mean_max` and `get_longitudinal_mean_max` return
+  `duration`, the metric (W or m/s) and `start` (UTC timestamp of the best effort), plus
+  `activity_id`, `sport` and `after` on the longitudinal curve. By default 19 durations from 1 s to
+  6 h; the curve can rise again at longer durations and is returned as it is.
+
+### Added
+
+- `durations=` on all three mean-max methods: `None` for the 19 defaults, `"all"` for the full grid,
+  or a list of seconds. Keyword-only.
+
+### Removed
+
+- **BREAKING:** `segmentation` on `get_activity_mean_max` and `get_latest_activity_mean_max` (it never
+  reduced the payload; the server ignores it). It was positional: passing `True` in that slot now
+  raises `TypeError`.
+- **BREAKING:** `by` on `get_longitudinal_mean_max`, and its `DeprecationWarning`. Every curve is
+  duration-oriented.
+
 ## [0.89.0] - 2026-09-28
 
 Frames on your terms. Every method that returns a collection takes `output=`:
@@ -89,7 +333,7 @@ Four breaking changes come with it; the upgrade is mechanical, see **Upgrading**
 
 - **Breaking:** `create_trace`, `update_trace`, `create_test`, and `update_test` now require timezone-aware datetimes for `timestamp`, `start`, and `end`. A naive datetime raises `ValueError` before the request is sent. Attach a zone, e.g. `datetime(..., tzinfo=ZoneInfo("Europe/Amsterdam"))` or `datetime.now(timezone.utc)`; the offset is stored alongside the instant.
 - `start`, `end`, and `timestamp` on responses are absolute UTC instants (ISO 8601 with a `Z` suffix), no longer a fixed per-record local offset. For wall-clock display use the companion `start_local` / `end_local` / `timestamp_local` fields, which are always present. The Streamlit activity selector now labels activities by their local date.
-- Requires a SweatStack server with offset-based timezone handling (plan 033). Against an older server the aware-datetime writes still work, but responses keep the previous fixed-offset `start`/`end`/`timestamp`.
+- Requires a SweatStack server with offset-based timezone handling. Against an older server the aware-datetime writes still work, but responses keep the previous fixed-offset `start`/`end`/`timestamp`.
 
 ### Removed