sweatstack 0.76.2__tar.gz → 0.77.1__tar.gz

{sweatstack-0.76.2 → sweatstack-0.77.1}/.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.1/AGENTS.md

@@ -0,0 +1,247 @@
+# 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...`.
+
+
+## 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
+  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.76.2 → sweatstack-0.77.1}/CHANGELOG.md

@@ -6,6 +6,22 @@ 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.77.1] - 2026-05-19
+
+### Fixed
+- Reverted unrelated OpenAPI schema drift.
+
+
+## [0.77.0] - 2026-05-19
+
+### Added
+- Link a trace to a test via the new `test_id` argument on `create_trace()` and `update_trace()`. A linked trace appears in the test's traces regardless of its timestamp.
+- `get_test()` accepts `trace_resolution=TraceResolution.linked` to return only traces explicitly linked to the test. Defaults to `TraceResolution.auto` (unchanged behaviour).
+
+### Changed
+- `update_trace()` replaces all fields, including `test_id`. Callers that omit `test_id` will clear any existing link — pass it back in to keep the trace linked.
+
+
 ## [0.76.2] - 2026-04-27
 
 ### Fixed

{sweatstack-0.76.2 → sweatstack-0.77.1}/CONTRIBUTING.md

@@ -6,4 +6,4 @@ This repository is open-sourced primarily to make it easier for developers and A
 
 If you've found a bug or have a question about using the library, feel free to [open an issue](https://github.com/SweatStack/sweatstack-python/issues).
 
-For general questions about SweatStack, please refer to the [developer documentation](https://developer.sweatstack.no/getting-started/).
+For general questions about SweatStack, please refer to the [developer documentation](https://docs.sweatstack.no/getting-started/).

sweatstack-0.77.1/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.76.2 → sweatstack-0.77.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.76.2
+Version: 0.77.1
 Summary: The official Python client for SweatStack
 Project-URL: Homepage, https://sweatstack.no
-Project-URL: Documentation, https://developer.sweatstack.no/getting-started/
+Project-URL: Documentation, https://docs.sweatstack.no/getting-started/
 Project-URL: Repository, https://github.com/SweatStack/sweatstack-python
 Project-URL: Issues, https://github.com/SweatStack/sweatstack-python/issues
 Project-URL: Changelog, https://github.com/SweatStack/sweatstack-python/blob/main/CHANGELOG.md
@@ -43,4 +43,4 @@ Description-Content-Type: text/markdown
 
 This is the official Python client library for SweatStack.
 
-Documentation can be found [here](https://developer.sweatstack.no/getting-started/).
+Documentation can be found [here](https://docs.sweatstack.no/getting-started/).

{sweatstack-0.76.2 → sweatstack-0.77.1}/README.md

@@ -2,4 +2,4 @@
 
 This is the official Python client library for SweatStack.
 
-Documentation can be found [here](https://developer.sweatstack.no/getting-started/).
+Documentation can be found [here](https://docs.sweatstack.no/getting-started/).

sweatstack-0.77.1/plans/003_trace_test_linking.md

@@ -0,0 +1,300 @@
+# Plan: Trace ↔ Test linking + `TraceResolution`
+
+## Summary
+
+Mirror upstream `sweatstack@93cd588` ("Adds trace to test optional foreign key
+relationship") in the Python client:
+
+- Traces gain an optional `test_id` FK that *explicitly* links them to a test
+  (independent of timestamp).
+- `GET /api/v1/tests/{test_id}` gains a `traces` query parameter
+  (`TraceResolution` enum: `auto` | `linked`) that controls how the returned
+  `traces` list is resolved.
+- `POST /api/v1/traces/` and `PUT /api/v1/traces/{trace_id}` may now return
+  `404` when a referenced `test_id` does not exist.
+
+Server-side behaviour:
+
+- `auto` (default): traces whose timestamp falls in the test's window, **plus**
+  traces explicitly linked to this test, **minus** traces explicitly linked to a
+  *different* test.
+- `linked`: only traces explicitly linked via `test_id`; the time window is
+  ignored.
+
+The `activities` list is unaffected — always time-overlap matched.
+
+## Code Quality Requirements
+
+Same bar as plan 001a:
+
+- Follow existing patterns exactly (keyword-only params, enum handling,
+  `_enums_to_strings`, error surface via `_raise_for_status`, docstring style).
+- Comprehensive type hints. No `Any`. No string-typed enums on the surface.
+- Concise Google-style docstrings (Args / Returns / Raises).
+- No dead code, no TODOs, no half-finished branches.
+
+## Step 1: Regenerate `openapi_schemas.py`
+
+The **user will run the SweatStack server locally** at
+`http://localhost:8080`. Wait for confirmation that the server is up
+before running the regen, and do not attempt to start the server.
+
+Then:
+
+```bash
+uv run generate-response-models
+```
+
+Expected diff in `src/sweatstack/openapi_schemas.py`:
+
+- `TraceDetails`: new `test_id: str | None = Field(None, title='Test Id')`.
+- `TraceCreateOrUpdate`: new `test_id: str | None = Field(None, title='Test Id')`.
+- New top-level enum:
+
+  ```python
+  class TraceResolution(Enum):
+      auto = 'auto'
+      linked = 'linked'
+  ```
+
+**Caveat — regen pulls more than this feature.** Two intervening upstream
+commits since `openapi_schemas.py` was last regenerated also touch the
+schema/API surface: `feebe56` ("Adds security.txt …") and `3f29c1f`
+("Better handling of tags=null"). The regenerated diff will not be
+confined to this plan's scope.
+
+Action: review the full diff. If unrelated changes appear, **split them
+into a separate commit** ahead of the trace-linking commit so the
+trace-linking commit stays reviewable. Do not merge regen-noise as part
+of this feature.
+
+Also verify on the running server before committing: open
+`http://localhost:8080/openapi.json`, search for `TraceResolution`,
+confirm wire values are `"auto"` and `"linked"` (lowercase). This guards
+against an upstream `BaseEnum` casing change.
+
+## Step 2: Re-export `TraceResolution`
+
+Two-step exposure (mirrors `Sport`):
+
+1. `src/sweatstack/schemas.py` — add `TraceResolution` to the import from
+   `openapi_schemas`.
+2. `src/sweatstack/client.py` — add `TraceResolution` to the import block
+   pulling enums/schemas from `.schemas` (≈ line 45, where `Sport`,
+   `TraceDetails`, etc. are imported).
+
+`__init__.py` is `from .client import *`, so step 2 is what actually makes
+`from sweatstack import TraceResolution` work. Verify with a smoke test
+in the REPL after the change. (This is the step that's easy to skip and
+breaks the public surface.)
+
+## Step 3: Update `src/sweatstack/client.py`
+
+Import `TraceResolution` from `schemas` in the existing imports block
+(≈ line 45, alongside `TraceDetails`).
+
+### 3a. `create_trace` — add `test_id` keyword arg
+
+Location: ≈ line 1708.
+
+- Add `test_id: str | None = None` as the **last** keyword-only param
+  (preserves existing call-site compatibility — every existing caller uses
+  keyword args, but appending keeps the visual ordering stable).
+- Add `"test_id": test_id` to the JSON body. Do not omit when `None`; the
+  server accepts `null` and other optional fields are already passed as
+  `None` (consistent with `lactate`, `rpe`, etc.).
+- Docstring:
+  - Add `test_id: Optional ID of a test to explicitly link this trace to.
+    If the test does not exist, the API raises 404.` to Args.
+  - Add a `Raises:` note that an `HTTPStatusError(404)` is raised when
+    `test_id` references a non-existent test (existing `_raise_for_status`
+    already surfaces this; just document it).
+
+### 3b. `update_trace` — add `test_id` keyword arg
+
+Location: ≈ line 1762.
+
+Identical treatment to `create_trace`. Same docstring additions.
+
+**Behavioural-change callout (required in both docstring and CHANGELOG):**
+`update_trace` is full-replace. Once `test_id` is in the signature with a
+default of `None`, **existing callers that don't pass `test_id` will silently
+unlink any previously linked test** the next time they call
+`update_trace`. This is consistent with how every other optional field on
+`update_trace` already behaves (e.g. `lactate=None` nulls lactate), but
+it's a real, observable change for upgraders.
+
+Docstring wording suggestion:
+
+> Note: This is a full-replace operation. If a trace was previously linked
+> to a test via `test_id`, you must pass that `test_id` again to preserve
+> the link — otherwise it is cleared.
+
+Do not try to work around this with "preserve if omitted" sentinels — that
+would diverge from how every other field on this method behaves and rot
+the contract.
+
+### 3c. `get_test` — add `trace_resolution` keyword arg
+
+Location: ≈ line 1934.
+
+Current signature:
+
+```python
+def get_test(self, test_id: str) -> TestDetails:
+```
+
+New signature:
+
+```python
+def get_test(
+    self,
+    test_id: str,
+    *,
+    trace_resolution: TraceResolution = TraceResolution.auto,
+) -> TestDetails:
+```
+
+Naming decision: **`trace_resolution`, not `traces`.** The wire name is
+`traces=` (server query param), but on the Python method
+`client.get_test("t1", traces=TraceResolution.linked)` reads as "give me
+the test and traces=X" — ambiguous. `trace_resolution=` is
+self-documenting. Note the wire mapping in the docstring so future
+maintainers know they don't match.
+
+Typing decision: **strict `TraceResolution`, not `TraceResolution | str`.**
+This diverges from the `Sport | str` pattern used elsewhere in the
+client. The deviation is deliberate: the enum has exactly two values, it
+is a brand-new surface (no historical string callers to support), and
+the brief asks for "extremely clean". Document the deviation in a code
+review note when the PR goes up; don't surprise the reviewer.
+
+Implementation:
+
+```python
+with self._http_client() as client:
+    params = {}
+    if trace_resolution is not TraceResolution.auto:
+        params["traces"] = trace_resolution.value
+    response = client.get(
+        url=f"/api/v1/tests/{test_id}",
+        params=params,
+    )
+    self._raise_for_status(response)
+    return TestDetails.model_validate(response.json())
+```
+
+Notes:
+
+- Use `.value` (lowercase `"auto"` / `"linked"`) explicitly. `httpx` does
+  not unwrap `Enum.value` on its own — it `str()`s the value, which gives
+  `"TraceResolution.linked"`. Verified pattern: `_get_tests_generator` and
+  every other enum query usage in this file calls `.value`.
+- **Omit the param when at default** — matches the convention used by
+  `_get_activities_generator`, `_get_tests_generator`, etc., which only
+  add optional query params when the caller supplied a non-default.
+  Sending `?traces=auto` would deviate from this pattern.
+- Keep `test_id` positional (existing call sites pass it positionally);
+  only `trace_resolution` is keyword-only. Strictly additive.
+- Docstring: explain `auto` vs `linked` in user terms. Copy the
+  server-side wording verbatim from `app/routers/api.py` — it is the
+  canonical description and survives doc drift.
+
+### 3d. No other method changes
+
+- `get_traces()` is unchanged. Upstream does not yet expose a `test_id`
+  filter on the list endpoint; do not add a client-side filter
+  (out of scope, would lie about API support).
+- `_get_traces_generator()` is unchanged. The new `test_id` field rides
+  along automatically in `TraceDetails`.
+
+## Step 4: Tests
+
+Add `tests/test_trace_test_linking.py`. Follow the no-network pattern
+established by the other tests in this repo.
+
+Coverage:
+
+- **Schema round-trip**: build a `TraceDetails` with `test_id="t_123"`,
+  `.model_dump()` → `.model_validate()` round-trip preserves it.
+- **TraceCreateOrUpdate accepts `test_id`**: `TraceCreateOrUpdate(timestamp=...,
+  test_id="t_123")` validates; `.model_dump()` includes the field.
+- **`TraceResolution` enum values**: assert `TraceResolution.auto.value ==
+  "auto"` and `TraceResolution.linked.value == "linked"` (guards against the
+  generator regenerating the enum with different casing on the wire).
+- **Re-export**: `from sweatstack import TraceResolution` resolves, *and*
+  `import sweatstack; sweatstack.TraceResolution` resolves (catches the
+  client-level import step easy to skip).
+
+If the repo already has an httpx-mock based test harness (it currently does
+not, judging by the existing files), add a single integration-style test for
+`get_test(test_id, traces=TraceResolution.linked)` that asserts the request
+URL carries `?traces=linked`. If not, skip — the enum-value test above
+provides the same guarantee without inventing a test infrastructure for this
+plan alone.
+
+## Step 5: Examples / docs
+
+- Quick scan of `examples/` — if there is an existing "tests" example, append
+  a short snippet showing:
+
+  ```python
+  test = client.create_test(sport=Sport.cycling, start=...)
+  client.create_trace(timestamp=..., lactate=4.0, test_id=test.id)
+  detail = client.get_test(test.id, traces=TraceResolution.linked)
+  ```
+
+  If none exists, do **not** add a new example file for this alone.
+
+- `docs/everything.rst` — `TraceDetails` and `TraceCreateOrUpdate` autoclass
+  entries pick up the new field automatically. Add a `.. autoclass::
+  sweatstack.openapi_schemas.TraceResolution` entry in the same enums block
+  where `Sport` lives (if `Sport` is documented there — check before adding).
+
+- `.claude/skills/sweatstack-python/client.md` — update the `create_trace`,
+  `update_trace`, and `get_test` signatures, and add `TraceResolution` to
+  the list of exported enums.
+
+## Step 6: Changelog + version bump
+
+- `CHANGELOG.md`: new entry under the next minor version. Must include
+  both the additive feature and the behavioural-change callout.
+  Wording suggestion:
+
+  > **Added** — Traces can be explicitly linked to a test via the new
+  > `test_id` parameter on `create_trace` and `update_trace`. `get_test`
+  > accepts a `trace_resolution` parameter (`TraceResolution.auto` or
+  > `TraceResolution.linked`) controlling how the returned traces list is
+  > resolved.
+  >
+  > **Behaviour change** — `update_trace` is full-replace. Callers that
+  > previously linked a trace to a test (e.g. via the SweatStack UI or
+  > another client) and then call `update_trace` without passing
+  > `test_id` will now unlink that trace. Pass the existing `test_id`
+  > back in to preserve the link.
+
+- `pyproject.toml`: bump `0.76.2 → 0.77.0` (minor — additive feature, no
+  breaking change). Confirm the version cadence with the maintainer if
+  unsure; this is the only judgement call in the plan.
+
+## API Reference
+
+| Method | Path | New parameter | Notes |
+|--------|------|---------------|-------|
+| POST | `/api/v1/traces/` | body `test_id?: str` | 404 if test missing |
+| PUT  | `/api/v1/traces/{id}` | body `test_id?: str` | full-replace; `null` unlinks; 404 if test missing |
+| GET  | `/api/v1/tests/{id}` | query `traces=auto\|linked` | default `auto` |
+
+### Resolution semantics (server-side, reference only)
+
+- `auto`: `(traces in window AND not claimed by another test) ∪ (traces with test_id == this test)`
+- `linked`: `traces with test_id == this test` (window ignored)
+
+## Out of Scope
+
+- Listing/filtering traces by `test_id` on `GET /traces/` (upstream does not
+  expose this).
+- Bulk attach/detach helpers (`attach_traces_to_test(...)`). Not requested by
+  upstream; would be premature abstraction.
+- A `linked_only: bool` convenience on `get_test`. Rejected in favour of the
+  enum to keep a single, faithful surface.

{sweatstack-0.76.2 → sweatstack-0.77.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sweatstack"
-version = "0.76.2"
+version = "0.77.1"
 description = "The official Python client for SweatStack"
 readme = "README.md"
 license = "MIT"
@@ -32,7 +32,7 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://sweatstack.no"
-Documentation = "https://developer.sweatstack.no/getting-started/"
+Documentation = "https://docs.sweatstack.no/getting-started/"
 Repository = "https://github.com/SweatStack/sweatstack-python"
 Issues = "https://github.com/SweatStack/sweatstack-python/issues"
 Changelog = "https://github.com/SweatStack/sweatstack-python/blob/main/CHANGELOG.md"
@@ -64,6 +64,7 @@ build-backend = "hatchling.build"
 dev = [
     "datamodel-code-generator[ruff]>=0.54.1",
     "myst-parser>=4.0.1",
+    "pytest>=9.0.3",
     "sphinx>=8.2.3",
     "sphinx-markdown-builder>=0.6.8",
     "streamlit>=1.42.0",

{sweatstack-0.76.2 → sweatstack-0.77.1}/src/sweatstack/client.py

@@ -43,7 +43,7 @@ from .schemas import (
     BackfillStatus, DailyMeasure, DailyResponse,
     Marker, Metric, Scope, Sport,
     TeamResponse, TestDetails, TestResults, TestSummary, TokenResponse, TraceDetails,
-    UserInfoResponse, UserResponse, UserSummary
+    TraceResolution, UserInfoResponse, UserResponse, UserSummary
 )
 from .utils import convert_to_standard_dtypes, decode_jwt_body, make_dataframe_streamlit_compatible
 
@@ -1717,6 +1717,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         heart_rate: int | None = None,
         tags: list[str] | None = None,
         sport: Sport | str | None = None,
+        test_id: str | None = None,
     ) -> TraceDetails:
         """Creates a new trace with the specified parameters.
 
@@ -1733,12 +1734,18 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             heart_rate: Optional heart rate measurement in beats per minute.
             tags: Optional list of tags to associate with this trace.
             sport: Optional sport to associate with this trace.
+            test_id: Optional ID of a test to explicitly link this trace to.
+                The link is independent of timestamp — a linked trace appears
+                in the test's traces list regardless of whether its timestamp
+                falls inside the test window.
 
         Returns:
             TraceDetails: The created trace object with all details.
 
         Raises:
-            HTTPStatusError: If the API request fails.
+            SweatStackNotFoundError: If ``test_id`` references a test that
+                does not exist.
+            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:
@@ -1754,6 +1761,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
                     "heart_rate": heart_rate,
                     "tags": tags,
                     "sport": sport,
+                    "test_id": test_id,
                 },
             )
             self._raise_for_status(response)
@@ -1772,6 +1780,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         heart_rate: int | None = None,
         tags: list[str] | None = None,
         sport: Sport | str | None = None,
+        test_id: str | None = None,
     ) -> None:
         """Updates a trace by replacing all fields.
 
@@ -1779,6 +1788,10 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         server-side. To modify a single field, first fetch the trace with
         ``get_traces()``, then pass all fields back.
 
+        In particular: if the trace was previously linked to a test via
+        ``test_id`` and you do not pass ``test_id`` here, the link is cleared.
+        Pass the existing ``test_id`` back in to preserve it.
+
         Args:
             trace_id: The unique identifier of the trace to update.
             timestamp: The date and time when the trace was recorded.
@@ -1790,9 +1803,13 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             heart_rate: Optional heart rate measurement in beats per minute.
             tags: Optional list of tags to associate with this trace.
             sport: Optional sport to associate with this trace.
+            test_id: Optional ID of a test to explicitly link this trace to.
+                Pass ``None`` (or omit) to leave the trace unlinked.
 
         Raises:
-            HTTPStatusError: If the API request fails.
+            SweatStackNotFoundError: If ``trace_id`` does not exist, or if
+                ``test_id`` references a test that does not exist.
+            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:
@@ -1808,6 +1825,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
                     "heart_rate": heart_rate,
                     "tags": tags,
                     "sport": sport,
+                    "test_id": test_id,
                 },
             )
             self._raise_for_status(response)
@@ -1931,11 +1949,29 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         else:
             return tests
 
-    def get_test(self, test_id: str) -> TestDetails:
+    def get_test(
+        self,
+        test_id: str,
+        *,
+        trace_resolution: TraceResolution | str = TraceResolution.auto,
+    ) -> TestDetails:
         """Gets details for a specific test by ID.
 
         Args:
             test_id: The unique identifier of the test to retrieve.
+            trace_resolution: How traces are matched to this test. Affects only
+                the ``traces`` list on the response; ``activities`` is always
+                time-overlap matched. Accepts a ``TraceResolution`` enum or
+                its string value (``"auto"`` or ``"linked"``).
+
+                - ``"auto"`` (default): traces whose timestamp falls in the
+                  test's time range, plus any traces explicitly linked to
+                  this test, minus any traces explicitly linked to a
+                  different test.
+                - ``"linked"``: only traces explicitly linked to this test
+                  via ``test_id``, regardless of timestamp.
+
+                Maps to the ``traces`` query parameter on the wire.
 
         Returns:
             TestDetails: The test details including resolved traces and overlapping activities.
@@ -1943,8 +1979,10 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         Raises:
             HTTPStatusError: If the API request fails.
         """
+        resolution = self._enums_to_strings([trace_resolution])[0]
+        params = {} if resolution == TraceResolution.auto.value else {"traces": resolution}
         with self._http_client() as client:
-            response = client.get(url=f"/api/v1/tests/{test_id}")
+            response = client.get(url=f"/api/v1/tests/{test_id}", params=params)
             self._raise_for_status(response)
             return TestDetails.model_validate(response.json())
 

{sweatstack-0.76.2 → sweatstack-0.77.1}/src/sweatstack/openapi_schemas.py

@@ -1150,6 +1150,7 @@ class TokenResponse(BaseModel):
 
 class TraceCreateOrUpdate(BaseModel):
     timestamp: AwareDatetime = Field(..., title='Timestamp')
+    test_id: str | None = Field(None, title='Test Id')
     lactate: float | None = Field(None, title='Lactate')
     rpe: int | None = Field(None, title='Rpe')
     notes: str | None = Field(None, title='Notes')
@@ -1161,6 +1162,11 @@ class TraceCreateOrUpdate(BaseModel):
     sport: Sport | None = None
 
 
+class TraceResolution(Enum):
+    auto = 'auto'
+    linked = 'linked'
+
+
 class UserFlow(Enum):
     session = 'session'
     signup = 'signup'
@@ -1603,6 +1609,7 @@ class TestDetails(BaseModel):
 class TraceDetails(BaseModel):
     tags: list[str] | None = Field(None, title='Tags')
     id: str = Field(..., title='Id')
+    test_id: str | None = Field(None, title='Test Id')
     timestamp: AwareDatetime = Field(..., title='Timestamp')
     lactate: float | None = Field(None, title='Lactate')
     rpe: int | None = Field(None, title='Rpe')

{sweatstack-0.76.2 → sweatstack-0.77.1}/src/sweatstack/schemas.py

@@ -18,7 +18,7 @@ from .openapi_schemas import (
     BackfillStatus, DailyMeasure, DailyResponse,
     Marker, Metric, Scope, Sport,
     TeamResponse, TestDetails, TestResults, TestSummary, TokenResponse, TraceDetails,
-    UserInfoResponse, UserResponse, UserSummary
+    TraceResolution, UserInfoResponse, UserResponse, UserSummary
 )
 
 

sweatstack-0.77.1/tests/test_trace_test_linking.py

@@ -0,0 +1,90 @@
+"""Tests for the trace <-> test linking surface.
+
+Covers:
+
+- ``test_id`` round-trips through ``TraceDetails`` and ``TraceCreateOrUpdate``.
+- ``TraceResolution`` enum wire values are exactly ``"auto"`` / ``"linked"``
+  (these are what the server's query parameter accepts).
+- ``TraceResolution`` is exposed on the public package surface.
+"""
+
+from datetime import datetime, timezone
+
+import sweatstack
+from sweatstack import TraceDetails, TraceResolution
+from sweatstack.openapi_schemas import TraceCreateOrUpdate
+
+
+def _trace_details(**overrides) -> TraceDetails:
+    base = dict(
+        id="trace_001",
+        timestamp=datetime(2026, 3, 15, 9, 30, tzinfo=timezone.utc),
+        timestamp_local=datetime(2026, 3, 15, 10, 30),
+    )
+    base.update(overrides)
+    return TraceDetails(**base)
+
+
+class TestTestIdField:
+    def test_trace_details_round_trip_with_test_id(self):
+        original = _trace_details(test_id="test_123", lactate=4.2)
+        restored = TraceDetails.model_validate(original.model_dump())
+
+        assert restored.test_id == "test_123"
+        assert restored.lactate == 4.2
+
+    def test_trace_details_test_id_defaults_to_none(self):
+        trace = _trace_details()
+        assert trace.test_id is None
+
+    def test_trace_create_or_update_accepts_test_id(self):
+        payload = TraceCreateOrUpdate(
+            timestamp=datetime(2026, 3, 15, 9, 30, tzinfo=timezone.utc),
+            lactate=4.2,
+            test_id="test_123",
+        )
+
+        dumped = payload.model_dump()
+        assert dumped["test_id"] == "test_123"
+
+    def test_trace_create_or_update_test_id_defaults_to_none(self):
+        payload = TraceCreateOrUpdate(
+            timestamp=datetime(2026, 3, 15, 9, 30, tzinfo=timezone.utc),
+        )
+
+        assert payload.test_id is None
+        assert payload.model_dump()["test_id"] is None
+
+
+class TestGetTestTraceResolution:
+    """``get_test`` should accept both the enum and the bare string for
+    ``trace_resolution`` (mirroring how ``sport``, ``measure`` etc. work
+    elsewhere in the client)."""
+
+    def _build_client(self):
+        from sweatstack.client import Client
+
+        return Client.__new__(Client)
+
+    def test_enum_input(self):
+        client = self._build_client()
+        assert client._enums_to_strings([TraceResolution.linked]) == ["linked"]
+
+    def test_string_input(self):
+        client = self._build_client()
+        assert client._enums_to_strings(["linked"]) == ["linked"]
+
+
+class TestTraceResolutionEnum:
+    def test_wire_values(self):
+        """The wire values must match the server's query parameter exactly."""
+        assert TraceResolution.auto.value == "auto"
+        assert TraceResolution.linked.value == "linked"
+
+    def test_membership(self):
+        """Guards against accidental additions/removals on regen."""
+        assert {m.value for m in TraceResolution} == {"auto", "linked"}
+
+    def test_publicly_exported(self):
+        """Importable from the top-level package, like other enums (e.g. Sport)."""
+        assert sweatstack.TraceResolution is TraceResolution

{sweatstack-0.76.2 → sweatstack-0.77.1}/uv.lock

@@ -893,6 +893,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/8a/eb/427ed2b20a38a4ee29f24dbe4ae2dafab198674fe9a85e3d6adf9e5f5f41/inflect-7.5.0-py3-none-any.whl", hash = "sha256:2aea70e5e70c35d8350b8097396ec155ffd68def678c7ff97f51aa69c1d92344", size = 35197, upload-time = "2024-12-28T17:11:15.931Z" },
 ]
 
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
+]
+
 [[package]]
 name = "ipykernel"
 version = "6.29.5"
@@ -1680,6 +1689,15 @@ dependencies = [
 [package.metadata]
 requires-dist = [{ name = "sweatstack", extras = ["streamlit"], editable = "." }]
 
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
 [[package]]
 name = "prometheus-client"
 version = "0.21.1"
@@ -1901,6 +1919,22 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/1c/a7/c8a2d361bf89c0d9577c934ebb7421b25dc84bf3a8e3ac0a40aed9acc547/pyparsing-3.2.1-py3-none-any.whl", hash = "sha256:506ff4f4386c4cec0590ec19e6302d3aedb992fdc02c761e90416f158dacf8e1", size = 107716, upload-time = "2024-12-31T20:59:42.738Z" },
 ]
 
+[[package]]
+name = "pytest"
+version = "9.0.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/549bd94f1a0a402dc8cf64563a117c0f3765662e2e668477624baeec44d5/pytest-9.0.3.tar.gz", hash = "sha256:b86ada508af81d19edeb213c681b1d48246c1a91d304c6c81a427674c17eb91c", size = 1572165, upload-time = "2026-04-07T17:16:18.027Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" },
+]
+
 [[package]]
 name = "python-dateutil"
 version = "2.9.0.post0"
@@ -2537,7 +2571,7 @@ wheels = [
 
 [[package]]
 name = "sweatstack"
-version = "0.76.0"
+version = "0.77.1"
 source = { editable = "." }
 dependencies = [
     { name = "email-validator" },
@@ -2566,6 +2600,7 @@ streamlit = [
 dev = [
     { name = "datamodel-code-generator", extra = ["ruff"] },
     { name = "myst-parser" },
+    { name = "pytest" },
     { name = "sphinx" },
     { name = "sphinx-markdown-builder" },
     { name = "streamlit" },
@@ -2592,6 +2627,7 @@ provides-extras = ["streamlit", "jupyter", "fastapi"]
 dev = [
     { name = "datamodel-code-generator", extras = ["ruff"], specifier = ">=0.54.1" },
     { name = "myst-parser", specifier = ">=4.0.1" },
+    { name = "pytest", specifier = ">=9.0.3" },
     { name = "sphinx", specifier = ">=8.2.3" },
     { name = "sphinx-markdown-builder", specifier = ">=0.6.8" },
     { name = "streamlit", specifier = ">=1.42.0" },

sweatstack-0.76.2/DEVELOPMENT.md

@@ -1,13 +0,0 @@
-# Development
-
-
-
-## Running locally
-
-Point your terminal to some other directory (to not clutter this one with `Untitled` files) and then run:
-
-```bash
-uvx --with-editable "path/to/sweatstack-python[jupyterlab]" jupyter lab
-```
-
-This will start a JupyterLab instance.