sweatstack 0.88.0__tar.gz → 0.89.0__tar.gz

{sweatstack-0.88.0 → sweatstack-0.89.0}/.claude/skills/sweatstack-python/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: sweatstack-python
 description: >
-  Builds Python applications using the SweatStack client library (uv add sweatstack).
-  Covers authentication, activity and trace data retrieval, pandas DataFrames, Streamlit
+  Builds Python applications using the SweatStack client library (uv add "sweatstack[pandas]").
+  Covers authentication, activity and trace data retrieval, pandas/Polars/Arrow output, 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
@@ -13,9 +13,10 @@ description: >
 
 Python client library for the SweatStack sports data platform.
 
-**Install:** `uv add sweatstack`
+**Install:** `uv add "sweatstack[pandas]"` for analysis (or `"sweatstack[polars]"`); plain `uv add sweatstack` for
+services that only need the models (no frame library is installed by default).
 
-**Extras:** `uv add sweatstack[streamlit]` · `uv add sweatstack[fastapi]`
+**Extras:** `sweatstack[pandas]` · `sweatstack[polars]` · `sweatstack[arrow]` (pyarrow only; DuckDB users) · `sweatstack[streamlit]` (includes pandas) · `sweatstack[fastapi]`
 
 ## Quick Start
 
@@ -35,9 +36,14 @@ from sweatstack import Client
 
 client = Client()
 client.authenticate()
-df = client.get_activities(as_dataframe=True)
+df = client.get_activities(output="pandas")     # or output="polars"; default is a list of models
 ```
 
+Every collection method takes `output=` (`"pandas"`, `"polars"`, `"arrow"`, `"bytes"`; `"models"` for
+lists). Time series default to the installed frame library (Polars, then pandas, then Arrow), so code that assumes
+one library should set it once: `sweatstack.set_output("pandas")` or `Client(output="polars")`. No frame has an
+index: `timestamp`, the mean-max metric value and `date` are columns.
+
 ## Reference
 
 **Client API** — methods for activities, traces, longitudinal data, users, uploads. Read [client.md](client.md)

{sweatstack-0.88.0 → sweatstack-0.89.0}/.claude/skills/sweatstack-python/client.md

@@ -3,6 +3,7 @@
 ## Contents
 
 - [Authentication](#authentication)
+- [Output: pandas, Polars, Arrow, bytes](#output-pandas-polars-arrow-bytes)
 - [Activities](#activities)
 - [Time-Series Data](#time-series-data)
 - [Mean-Max and AWD](#mean-max-and-awd)
@@ -12,6 +13,7 @@
 - [Dailies](#dailies-daily-health-metrics)
 - [App Metadata](#app-metadata)
 - [Profile](#profile)
+- [Account status and the Portal](#account-status-and-the-portal)
 - [Users and Teams](#users-and-teams)
 - [User Delegation](#user-delegation)
 - [File Uploads](#file-uploads)
@@ -45,6 +47,35 @@ client = Client(api_key="...", refresh_token="...")
 
 Token refresh is automatic in all modes. The library handles expiry checks and refreshes transparently.
 
+## Output: pandas, Polars, Arrow, bytes
+
+Every method that returns a collection takes `output=`:
+
+| Endpoints | Values | Default |
+|---|---|---|
+| Time series, mean-max, AWD, longitudinal | `"pandas"`, `"polars"`, `"arrow"`, `"bytes"` | the installed library: Polars, then pandas, then Arrow |
+| `get_activities`, `get_traces`, `get_tests`, `get_dailies` | `"models"`, `"pandas"`, `"polars"`, `"arrow"` | `"models"` |
+
+```python
+df = client.get_activity_data("activity_id")                    # installed library: Polars, then pandas, then Arrow
+pf = client.get_activity_data("activity_id", output="polars")   # polars.DataFrame, wire dtypes
+tb = client.get_activity_data("activity_id", output="arrow")    # pyarrow.Table
+raw = client.get_activity_data("activity_id", output="bytes")   # parquet bytes: write to disk, query with DuckDB
+
+sweatstack.set_output("polars")        # module-wide default, or Client(output="polars")
+client.get_activities()                # now a polars frame; output="models" per call to get the list back
+```
+
+Resolution: per-call > `Client(output=)` > `set_output()` > method default. Requires `sweatstack[pandas]`,
+`sweatstack[polars]` or `sweatstack[arrow]`; a missing library raises `ImportError` naming the extra.
+
+**DuckDB:** `duckdb.sql("select ... from tb")` works directly on an `output="arrow"` table or an `output="polars"`
+frame (both need pyarrow: `sweatstack[arrow]`), or on a file written from `output="bytes"`
+(`duckdb.sql("select ... from 'season.parquet'")`, no extra needed). No frame has an index on any
+backend: `timestamp`, the mean-max metric value and `date` are ordinary first columns (`df.set_index("timestamp")`
+if you need one). Polars and Arrow list frames give nested fields as structs (`df.unnest("summary")`); pandas flattens them
+to dotted columns (`summary.power.mean`).
+
 ## Activities
 
 ```python
@@ -58,8 +89,9 @@ activities = client.get_activities(
     offset=0,                     # for pagination
 )
 
-# As DataFrame instead
-df = client.get_activities(as_dataframe=True)
+# As a frame instead (nested summary/laps/traces flattened in pandas, structs in Polars)
+df = client.get_activities(output="pandas")
+pf = client.get_activities(output="polars")
 
 # Single activity by ID (returns ActivityDetails)
 activity = client.get_activity("activity_id")
@@ -71,7 +103,7 @@ latest = client.get_latest_activity(sport=Sport.running)
 
 ## Time-Series Data
 
-Returns pandas DataFrame with 1-second sampled data.
+Returns a frame with 1-second sampled data (`output="pandas"`, `"polars"`, `"arrow"` or `"bytes"`; default is the installed library, Polars if both). `timestamp` is a column, not an index.
 
 ```python
 # All available metrics
@@ -132,7 +164,7 @@ df = client.get_longitudinal_awd(
 )
 ```
 
-The DataFrame has a timezone-aware datetime index and includes an `activity_id` column — group by it for per-activity aggregation.
+The frame has a timezone-aware `timestamp` column (UTC), a naive `timestamp_local` column, and `activity_id` / `sport` columns — group by `activity_id` for per-activity aggregation. Mean-max and AWD frames have the metric value and `duration` as columns.
 
 **Local caching** for reproducible analysis (avoids re-fetching on reruns). Caches `get_longitudinal_data()` and `get_longitudinal_mean_max()`:
 ```python
@@ -151,7 +183,7 @@ 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)
+traces = client.get_traces(start=date(2025, 1, 1), output="pandas")
 
 # Create a trace
 trace = client.create_trace(
@@ -195,8 +227,8 @@ tests = client.get_tests(
     limit=50,                          # default 50
 )
 
-# As DataFrame (results column gets normalized into flat columns like results.vo2max)
-df = client.get_tests(as_dataframe=True)
+# As a frame (pandas flattens results into columns like results.vo2max; Polars keeps a results struct)
+df = client.get_tests(output="pandas")
 
 # Single test by ID (returns TestDetails with resolved traces + overlapping activities)
 test = client.get_test("test_id")
@@ -242,8 +274,8 @@ dailies = client.get_dailies(
     interpolate=True,            # default; server fills gaps
 )
 
-# As DataFrame (date as index)
-df = client.get_dailies(DailyMeasure.body_mass, start=date(2026, 1, 1), end=date(2026, 3, 31), as_dataframe=True)
+# As a frame (date is a column)
+df = client.get_dailies(DailyMeasure.body_mass, start=date(2026, 1, 1), end=date(2026, 3, 31), output="pandas")
 
 # Set a daily value (upsert — creates or updates)
 daily = client.set_daily(DailyMeasure.body_mass, date=date(2026, 4, 1), value=75.2)
@@ -284,10 +316,48 @@ Metadata appears as `app_metadata` on entity responses when accessed via app tok
 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)
+user = client.get_userinfo()              # UserInfoResponse (sub, name, email, issue); needs `profile` scope
+who = client.whoami()                     # UserSummary for the token's user; two API calls, no `profile` scope needed
+```
+
+## Account status and the Portal
+
+Beta on the server side. `issue` is `None` or the one thing to tell the user; show `message`, and a button to
+`action_url` only when it is present (it is `None` on delegated tokens and on issues nobody can act on).
+Branch on `status`, never parse `message`, never branch on `code`.
+
+```python
+user = client.get_userinfo()                      # needs `profile`
+if user.issue:
+    banner(user.issue.message, user.issue.action_url)
+
+status = client.get_profile_status()              # `data:read` or `profile`; AccountStatusResponse
+status.issue                                      # same object as above
+status.capabilities[Capability.activity_history]  # CapabilityStatus: ready | syncing | action_required | unavailable
 ```
 
+| `status` | Show |
+|---|---|
+| `syncing` | a waiting state; resolves within 24 h |
+| `action_required` | a button to `action_url` when present |
+| `unavailable` | explain once, do not poll |
+| `issue is None` | nothing |
+
+Codes and capability keys are open sets (unknown ones parse as pseudo-members; ignore them). These methods
+return models and ignore `output=`.
+
+**Portal sessions** are for apps that want to choose the destination or the return link; otherwise
+`action_url` already is a Portal link. Server-to-server: uses the client's `client_id` and (if registered)
+`client_secret`, never a user token. `user.client` in FastAPI and `auth.client` in Streamlit already carry them.
+
+```python
+app = Client(client_id="01JMYRA...", client_secret="...")      # secret only if the app has one
+session = app.create_portal_session("manage-integrations", return_url="https://example.com/app/")
+redirect(session.url)                                           # opaque URL; never build one by hand
+```
+
+Omit `return_url` on purpose for native apps and installed PWAs: the Portal then tells the user to close the page.
+
 ## Users and Teams
 
 ```python
@@ -422,8 +492,9 @@ Hierarchy:
 - **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=...)` and `create_trace(sport=...)` take a single sport. All other methods that filter by sport use `sports=[...]` (list). The singular `sport` parameter on longitudinal methods is deprecated.
-- **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()`, `get_traces()`, `get_tests()`, and `get_dailies()`. Time-series methods (`get_activity_data`, `get_longitudinal_data`, etc.) always return DataFrames.
+- **pandas frames have standard dtypes.** The library converts API-optimized types (Int16, float16) to float64/datetime64[ns] for pandas. Polars and Arrow keep the compact wire dtypes.
+- **No frame has an index.** `timestamp`, the mean-max metric value and `date` are columns. `df.set_index("timestamp")` if you need one.
+- **`output=`** is on every collection method; `as_dataframe` no longer exists. Time-series methods always return a frame (the installed library by default, Polars if both), list methods return models by default. Set `sweatstack.set_output(...)` once when the code assumes one library.
 - **`update_test()` and `update_trace()` are full replaces.** Omitted optional fields are set to null. Always re-pass all fields you want to keep.
 - **`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.88.0 → sweatstack-0.89.0}/.claude/skills/sweatstack-python/data-models.md

@@ -42,6 +42,15 @@ Available data stream names: `duration`, `power`, `speed`, `heart_rate`, `cadenc
 | `Scope.openid` | `openid` |
 | `Scope.admin` | `admin` |
 
+## Account Status Models
+
+- `StatusIssueResponse`: `code` (`StatusIssueCode`, open set), `status` (`CapabilityStatus`, closed:
+  `ready`, `syncing`, `action_required`, `unavailable`), `message` (display only), `action_url` (`str | None`).
+- `AccountStatusResponse`: `issue: StatusIssueResponse | None`, `capabilities: dict[Capability, CapabilityStatus]`
+  (`Capability` is an open set: `activities`, `activity_history`, `dailies`, `workouts`, ...).
+- `UserInfoResponse.issue: StatusIssueResponse | None`.
+- `PortalDestination` (`manage-integrations`, `manage-teams`) and `PortalSessionResponse` (`url`).
+
 ## Response Models
 
 **ActivitySummary** — returned by `get_activities()`:

{sweatstack-0.88.0 → sweatstack-0.89.0}/.claude/skills/sweatstack-python/fastapi.md

@@ -285,3 +285,15 @@ DEBUG access-token cache hit (session=4f2a91c0)
 ```
 
 One refresh, four cache hits.
+
+## Portal Sessions
+
+`user.client` carries the app's `client_id` / `client_secret` from `configure()`, so it can mint a Portal link
+without further setup. See [client.md](client.md#account-status-and-the-portal).
+
+```python
+@app.get("/fix-my-data")
+def fix_my_data(user: AuthenticatedUser):
+    session = user.client.create_portal_session("manage-integrations", return_url="https://example.com/app/")
+    return RedirectResponse(session.url)
+```

{sweatstack-0.88.0 → sweatstack-0.89.0}/.claude/skills/sweatstack-python/streamlit.md

@@ -33,7 +33,7 @@ if not auth.is_authenticated():
 
 # Use auth.client for all API calls
 activities = auth.client.get_activities(limit=10)
-st.dataframe(auth.client.get_activities(as_dataframe=True))
+st.dataframe(auth.client.get_activities(output="pandas"))  # st.dataframe also accepts output="polars"
 ```
 
 **`authenticate(login_label=None, show_logout=True)`** — renders login button if unauthenticated, logout button if authenticated. Handles OAuth callback automatically via `st.query_params`.
@@ -114,3 +114,16 @@ activities = auth.client.get_activities()
 - **Session state keys:** `sweatstack_api_key`, `sweatstack_refresh_token`. Don't overwrite these.
 - **`select_user()` switches the client.** After calling it, `auth.client` operates as the selected user. Call `auth.switch_to_principal_user()` to revert.
 - **Scopes default to `data:read,profile`** in Streamlit — not the broader set used by `Client.authenticate()`. Add `offline_access` if you need refresh tokens in direct OAuth mode.
+
+## Account Status and the Portal
+
+```python
+user = auth.client.get_userinfo()
+if user.issue:
+    st.warning(user.issue.message)
+    if user.issue.action_url:
+        st.link_button("Fix it", user.issue.action_url)
+```
+
+`auth.client` carries the app credentials, so `auth.client.create_portal_session("manage-integrations",
+return_url=...)` works too. See [client.md](client.md#account-status-and-the-portal).

sweatstack-0.89.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: pytest (py${{ matrix.python }}${{ matrix.pandas && format(', pandas {0}', matrix.pandas) || '' }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          # The lock file tracks the newest pandas; this leg keeps the declared
+          # lower bound (pyproject `pandas>=2.2.3`) honest.
+          - python: "3.12"
+            pandas: "2.2"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --all-extras
+      - if: matrix.pandas == '2.2'
+        run: uv pip install "pandas>=2.2.3,<3"
+      - run: uv run pytest
+
+  bare-install:
+    # The base package must import without pandas, pyarrow or polars. This job
+    # is what keeps the frame libraries optional: a top-level `import pandas`
+    # added by habit fails here, not in a user's FastAPI service.
+    name: bare install imports without frame libraries
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv venv
+      - run: uv pip install .
+      - run: |
+          uv run --no-project python - <<'EOF'
+          import sys
+          import sweatstack
+          forbidden = {"pandas", "numpy", "pyarrow", "polars"} & set(sys.modules)
+          assert not forbidden, f"base import pulled in frame libraries: {sorted(forbidden)}"
+          print("ok: sweatstack imports without", "pandas/numpy/pyarrow/polars")
+          EOF
+      - run: uv pip install ".[fastapi]"
+      - run: |
+          uv run --no-project python - <<'EOF'
+          import sys
+          import sweatstack.fastapi
+          forbidden = {"pandas", "numpy", "pyarrow", "polars"} & set(sys.modules)
+          assert not forbidden, f"fastapi import pulled in frame libraries: {sorted(forbidden)}"
+          print("ok: sweatstack.fastapi imports without frame libraries")
+          EOF

{sweatstack-0.88.0 → sweatstack-0.89.0}/AGENTS.md

@@ -32,7 +32,9 @@ and pagination shape. Don't redesign the API in Python.
 - 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.
+- `output=` is a client-side choice of container over every collection
+  endpoint: `"pandas" | "polars" | "arrow" | "bytes"` for parquet endpoints,
+  `"models" | "pandas" | "polars" | "arrow"` for list endpoints. See "Output backends".
 - 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
@@ -45,6 +47,7 @@ and pagination shape. Don't redesign the API in Python.
 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.
 ├── exceptions.py        # Public error contract. No httpx types leak.
 ├── client.py            # Single Client class + module-level singletons.
 ├── utils.py             # Dataframe / JWT helpers.
@@ -72,12 +75,25 @@ Skipping step 3 silently breaks the public surface. Same for new enums.
   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.
+- **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.
+- **Server-to-server calls use `_http_client(auth=False)`.** Endpoints
+  that authenticate with the app's own credentials in the body (Portal
+  sessions) 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. Use `Client.__new__(Client)` to
   bypass init when you need an instance for a helper method.
+- **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.
 - **`update_*` methods are full-replace.** Document the silent-clear
   footgun in the docstring (see below).
 - **CHANGELOG entries are user-facing**, not dev-facing.
@@ -134,10 +150,16 @@ Invariants baked into the template:
 
 **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.
+output=None)` wrapper that returns
+`self._frame_from_models(models, Model, output, flatten=(...))`. Empty
+lists yield typed empty frames automatically. See `get_activities` and
+`get_tests` for exemplars.
+
+**Parquet endpoints** return `self._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).
 
 **Query parameters** are only sent when the caller supplied a non-default
 value. For enum-typed query params with an explicit default, compare
@@ -162,6 +184,40 @@ Don't try to soften the contract with "preserve if omitted" sentinels;
 that diverges from how every other field behaves on these methods.
 
 
+## 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 (`get_userinfo`, `get_profile_status`,
+`create_portal_session`, `whoami`, `get_users`, `get_teams`, `get_sports`,
+`get_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
@@ -223,7 +279,7 @@ Bad (belongs in the commit message, not the changelog):
 - 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.
+  `_read_frame`, `_frame_from_models`, `_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.88.0 → sweatstack-0.89.0}/CHANGELOG.md

@@ -6,6 +6,83 @@ 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.89.0] - 2026-09-28
+
+Frames on your terms. Every method that returns a collection takes `output=`:
+`"pandas"`, `"polars"`, `"arrow"` or `"bytes"` for time-series endpoints, and `"models"`
+(default), `"pandas"`, `"polars"` or `"arrow"` for list endpoints. Set it per call, per client
+(`Client(output="polars")`) or once for everything (`sweatstack.set_output("polars")`). When you
+don't say, time series come back in the frame library you installed: Polars, then pandas,
+then Arrow.
+Four breaking changes come with it; the upgrade is mechanical, see **Upgrading** below.
+
+### Added
+
+- `get_profile_status()` (beta): why this user has little or no data, and what the
+  account can supply. Returns `issue` (`None`, or one `{code, status, message, action_url}`)
+  and `capabilities` (`activities`, `activity_history`, `dailies`, `workouts`, each `ready`,
+  `syncing`, `action_required` or `unavailable`). Accepts `data:read` or `profile`.
+- `get_userinfo()` now carries the same `issue` (beta). The whole integration is
+  `if user.issue: banner(user.issue.message, user.issue.action_url)`; `action_url` is `None` on
+  delegated tokens and on issues the user cannot act on.
+- `create_portal_session(destination, return_url=None)` (beta): mints a SweatStack Portal link
+  branded for the client's app, using the app's own `client_id` / `client_secret` from the
+  constructor and no user token. Works from `sweatstack.fastapi` dependencies and
+  `StreamlitAuth` as is.
+- New models and enums: `AccountStatusResponse`, `StatusIssueResponse`, `Capability`,
+  `CapabilityStatus`, `StatusIssueCode`, `PortalDestination`, `PortalSessionResponse`.
+  `StatusIssueCode` and `Capability` are open sets: values a newer server adds parse as
+  pseudo-members instead of failing validation.
+- `output=` on `get_activity_data`, `get_activity_mean_max`, `get_activity_awd`,
+  `get_latest_activity_data`, `get_latest_activity_mean_max`, `get_longitudinal_data`,
+  `get_longitudinal_mean_max`, `get_longitudinal_awd`, `get_activities`, `get_traces`,
+  `get_tests` and `get_dailies`.
+- `Client(output=...)` and `sweatstack.set_output(...)` to choose once. A per-call value
+  always wins. Delegated clients inherit the setting.
+- Polars frames keep the compact wire dtypes (Int16, Float32, Categorical, Duration) and
+  give nested fields as typed structs (`df.unnest("summary")`), as do Arrow tables. On
+  time-series endpoints Arrow tables are the response as-is. `"bytes"` is the raw parquet, ready for `duckdb.sql("... from 'file.parquet'")`.
+- `sweatstack[polars]` and `sweatstack[arrow]` extras. `[arrow]` is pyarrow alone: what
+  `output="arrow"` needs, and what DuckDB needs to query any in-memory frame. See the
+  README's "Using DuckDB" for the three routes.
+
+### Fixed
+
+- `whoami()` raised `AttributeError` on every call since the helper it relied on was removed.
+  It resolves the token's user through `get_user()` again, for principal and delegated clients
+  alike, and still needs no `profile` scope.
+
+### Changed
+
+- **Breaking:** pandas is no longer installed by default. Install `sweatstack[pandas]`
+  (pandas + pyarrow), `sweatstack[polars]` or `sweatstack[arrow]`. The `streamlit` and
+  `jupyter` extras include pandas. FastAPI services and webhook consumers can stay on the base package. Asking for an
+  output whose library is missing raises an `ImportError` naming the extra to install.
+- **Breaking:** the default frame library is the one you installed, in the order Polars,
+  pandas, Arrow. An environment with pandas and Polars now gets Polars frames from the time-series
+  methods unless you set `output` (per call, `Client(output="pandas")`, or
+  `sweatstack.set_output("pandas")` once).
+- **Breaking:** `as_dataframe=True` is removed. Use `output="pandas"`.
+- **Breaking:** no frame carries an index any more, on any backend. `timestamp` (time
+  series), the metric value (mean-max and AWD curves) and `date` (dailies) are now regular
+  columns, in first position. The set of columns is unchanged. Code that relied on the
+  index needs `.set_index("timestamp")` (or `"power"`, `"date"`, ...) once, or should use
+  the column directly. This also applies to the fatigue mean-max (`after=`) frame, which was
+  previously re-indexed by the client.
+- pandas frames keep the float64 / nanosecond dtype policy. Polars and Arrow do not upcast.
+
+### Upgrading
+
+1. Change the install line: `uv add "sweatstack[pandas]"` (or `[polars]`, or `[arrow]` for
+   DuckDB). Streamlit and
+   Jupyter users: `sweatstack[streamlit]` / `sweatstack[jupyter]` already include pandas.
+2. To keep pandas frames in an environment that also has Polars, add
+   `sweatstack.set_output("pandas")` once (or `Client(output="pandas")`).
+3. Replace `as_dataframe=True` with `output="pandas"`.
+4. Search for `.index`, `.loc[<timestamp>]`, `.resample(`, `.plot()` on frames from the
+   time-series, mean-max, AWD and dailies methods. Where the index mattered, add
+   `.set_index("timestamp")` (or the metric name, or `"date"`) right after the call.
+
 ## [0.88.0] - 2026-08-06
 
 ### Changed