technogym-js 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,83 @@
+# AGENTS.md — technogym-js
+
+Briefing for coding agents. Not a tutorial; see `README.md` for that. This file states facts an
+agent needs to avoid confidently wrong code.
+
+## 1. What this is, and the hard constraints
+
+`technogym-js` is a zero-dependency TypeScript client for Technogym's mywellness cloud, for **Node
+and Next.js server runtimes**. It talks to the undocumented JSON API of the official end-user web
+app. There is no official public API; do not invent endpoints.
+
+- **Read-only.** No method changes anything on the account. Every mywellness call, reads
+  included, is an HTTP POST; the transport retries reads (`ServiceOptions.retry`, default `true`)
+  but never the login POST.
+- **A session is addressed by `sessionId` AND its date.** Sessions are partitioned by day. Methods
+  take `date` as optional only for convenience: without it `findSessionDate` scans a year of
+  history first (one extra request). Pass it whenever you have it.
+- **`partitionDate` is a STRING (`"20260908"`) for `GetPerformedWorkoutSessionByIdCr` but a
+  NUMBER (`20260908`) for `GetHrSession`.** This mirrors the web app; do not "fix" it.
+- **The API spells two keys wrong, and the parsers depend on it:** `analitics` (the analytics
+  block; `analytics` is accepted as a fallback) and `displayPrescibedPhysicalActivity`.
+- **Every request carries `X-MWAPPS-APPID` / `X-MWAPPS-CLIENT` / `X-MWAPPS-CLIENTVERSION`**
+  (`src/auth/constants.ts`). Without them mywellness answers `ClientApplicationNotTrusted`.
+- **Errors come in a 200.** mywellness returns `{ data, errors }`; a non-empty `errors` is a
+  failure. Auth-looking `details` (`TokenNotValid`, `TokenExpired`, anything containing "token")
+  become `TechnogymAuthError`; the rest `TechnogymApiError`.
+- **Re-login is automatic only with credentials** (constructor `credentials`, or a prior
+  `login()` on the same client). A session loaded from a store with no credentials throws
+  `TechnogymAuthError` when rejected. Concurrent re-logins collapse into one request.
+- **Rotated tokens:** when a response envelope carries a new `token`, the client adopts it and
+  saves it to the store.
+- **Property units:** `value` is the base unit (s, m, kg); `unit` belongs to `displayValue`, not
+  to `value`. A Skillrun `Duration` is `value: 1847` (seconds) with `displayValue: 30.78`,
+  `unit: "min"`.
+- **Strength exercises have no time series.** Use `Exercise.sets`, not `getExerciseAnalytics`.
+- **Node runtime only, server-only, zero runtime dependencies, Node >= 18.**
+
+## 2. Minimal working example
+
+```ts
+import { FileSessionStore, Technogym, TechnogymClient } from "technogym-js";
+
+const client = new TechnogymClient({ sessionStore: new FileSessionStore("./session") });
+if (!(await client.loadSession())) await client.login(process.env.TECHNOGYM_EMAIL!, process.env.TECHNOGYM_PASSWORD!);
+
+const technogym = new Technogym(client);
+const [latest] = await technogym.listSessions("2026-09-01", "2026-09-30");
+const session = await technogym.getWorkoutSession(latest!.sessionId, latest!.date);
+```
+
+## 3. Methods and endpoints
+
+All training paths are `POST https://services.mywellness.com/{facilityUrl}{path}`. An account can
+have NO facilities (the login's `facilities` is `[]`); then paths go out with no prefix. Verified
+live 2026-10-31: on such an account the server answered identically with no prefix and with any
+made-up prefix.
+
+Live-verified on 2026-10-31 (one account, bike sessions): login, `getMovergy`, `listSessions`,
+`findSessionDate`, `getWorkoutSession`, `getExerciseAnalytics` / `analyzeExercise` (channels
+Power, Rpm, HDistance, Level, Calories). `getSessionHeartRate` returned an empty trace for a bike
+session whose exercise analytics did carry HR; for per-exercise HR use `ExerciseAnalytics.hr`.
+
+| Method | Path | Body |
+|---|---|---|
+| `TechnogymClient.login` | `POST core.mywellness.com/v2/enduser/authentication/login` | `{username, password, keepMeLoggedIn: true}` |
+| `getMovergy` | `/Training/User/{userId}/MyMovergy` | `{}` |
+| `listSessions`, `getActivityHistoryRaw`, `findSessionDate` | `/Training/User/{userId}/ActivityHistory` | `{startDay, endDay[, justThisType: "WorkoutSession"]}` |
+| `getWorkoutSession[Raw]` | `/Training/User/{userId}/GetPerformedWorkoutSessionByIdCr` | `{idCr: number, partitionDate: "yyyyMMdd"}` |
+| `getSessionHeartRate[Raw]` | `/Training/User/{userId}/GetHrSession` | `{idCr: number, partitionDate: yyyyMMdd}` |
+| `getExerciseAnalytics[Raw]`, `analyzeExercise` | `/Training/CardioLog/{analyticsId}/Details` | `{}` |
+
+`getUser()` makes no request. `findSessionDate` searches every activity type
+(`onlyWorkouts: false`). `getRecentWorkouts` loads sessions sequentially on purpose.
+
+Request shapes follow health_mcp's working Python client.
+
+## 4. Layout
+
+`src/client.ts` transport and session · `src/technogym.ts` endpoint methods · `src/parse.ts`
+pure parsers · `src/analysis.ts` stats and segmentation · `src/auth/` constants and session
+stores · `mcp/` the MCP server, which may import only from `"technogym-js"` (lint-enforced).
+
+`npm run check` runs typecheck, lint, build and both test suites.

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 — 2026-10-31
+
+First release.
+
+- `TechnogymClient`: mywellness sign-in, session stores (`FileSessionStore`,
+  `MemorySessionStore`), automatic re-login with credentials, rotated-token adoption, retries for
+  reads, typed error hierarchy.
+- `Technogym`: `getUser`, `getMovergy`, `listSessions`, `findSessionDate`, `getWorkoutSession`,
+  `getRecentWorkouts`, `getExerciseAnalytics`, `analyzeExercise`, `getSessionHeartRate`, and raw
+  twins of each read.
+- Analytics helpers: `channelStats`, `segmentAnalytics` (interval detection from setpoint
+  changes, laps, fixed windows), `windowSamples`, `downsample`.
+- `@dynamicsninja/technogym-mcp`: an MCP server with six read-only tools.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Ficko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,12 @@
+technogym-js
+
+The endpoint surface, request shapes and response parsing of this library follow the MIT-licensed
+Technogym MCP server in health_mcp:
+
+  health_mcp/technogym — https://github.com/ErikAnkerKilbergSkallevold/health_mcp/tree/main/technogym
+    Copyright (c) Erik Anker Kilberg Skallevold and contributors
+
+That project is not affiliated with this one.
+
+Technogym and mywellness are trademarks of Technogym S.p.A. This project is not affiliated with,
+endorsed by, or supported by Technogym.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# technogym-js
+
+**TypeScript client for Technogym mywellness**
+
+<sub>**Unofficial.** Not affiliated with, endorsed by, or supported by Technogym. Technogym and
+mywellness are trademarks of Technogym S.p.A.</sub>
+
+</div>
+
+A zero-dependency TypeScript client for Technogym's **mywellness** cloud, for **Node and Next.js
+server runtimes**. It reads your gym training history: workout sessions, every exercise with
+per-set reps and weight, the machine's full summary (a Skillrun's running cadence, power, step
+length and ground contact time; a strength machine's estimated 1RM), per-second treadmill and
+bike data, and whole-session heart rate.
+
+Technogym's official API is partner-only. This library speaks the same JSON API the official
+end-user web app (endusernext.mywellness.com) uses, signing in with your normal email and password.
+No HTML scraping, but it will break if Technogym changes the login flow or its client-trust rules.
+
+On top of the endpoints, it does the analysis the API leaves out: the summary block omits most
+machine channels, so `analyzeExercise` computes per-channel stats and splits a run into **intervals
+detected from setpoint changes** (speed, grade, level), console laps, or fixed windows.
+
+If you're an AI coding agent (or configuring one), read [`AGENTS.md`](AGENTS.md) first.
+
+## 📦 Install
+
+```sh
+npm install technogym-js
+```
+
+Node 18 or later. Server-only: credentials and the session token must never reach a browser.
+
+## 🚀 Quick start
+
+```ts
+import { FileSessionStore, Technogym, TechnogymClient } from "technogym-js";
+
+const client = new TechnogymClient({ sessionStore: new FileSessionStore("./session") });
+if (!(await client.loadSession())) {
+  await client.login(process.env.TECHNOGYM_EMAIL!, process.env.TECHNOGYM_PASSWORD!);
+}
+
+const technogym = new Technogym(client);
+
+// Overview: newest first. sessionId + date address a session.
+const sessions = await technogym.listSessions("2026-09-01", "2026-09-30");
+
+// Every exercise, sets, machine summary, efficacy and muscle scores.
+const session = await technogym.getWorkoutSession(sessions[0].sessionId, sessions[0].date);
+
+// Per-second data of a cardio exercise, plus intervals and per-channel stats.
+const run = session.exercises.find((e) => e.isCardio)!;
+const analyzed = await technogym.analyzeExercise(run.analyticsId);
+for (const s of analyzed.segments) {
+  console.log(s.interval, s.setpoint, s.paceMinPerKm, s.channels.RunningCadence);
+}
+```
+
+Or let the client sign in on its own, lazily and again whenever the token is rejected:
+
+```ts
+const client = new TechnogymClient({
+  credentials: { email: process.env.TECHNOGYM_EMAIL!, password: process.env.TECHNOGYM_PASSWORD! },
+});
+```
+
+In a Next.js route handler add `export const runtime = "nodejs";`.
+
+## 📚 API
+
+### `Technogym`
+
+| Method | Returns |
+|---|---|
+| `getUser()` | The account: user id, name, culture, measurement system, facilities. From the session, no request. |
+| `getMovergy()` | The current Movergy score, or `null`. |
+| `listSessions(from, to, { onlyWorkouts = true })` | `SessionSummary[]`, newest first: id, date, time, name, duration, MOVEs, calories, exercise counts, effectiveness and compliance. |
+| `findSessionDate(sessionId, lookbackDays = 365)` | A session's `YYYY-MM-DD`, found by scanning history. |
+| `getWorkoutSession(sessionId, date?)` | `WorkoutSession`: every performed exercise with machine, sets, prescribed sets, summary, workload ranges, estimated figures, console metadata; session efficacy, muscle scores, totals. |
+| `getRecentWorkouts(days = 14)` | `WorkoutSession[]` for the last N days. |
+| `getExerciseAnalytics(analyticsId)` | `ExerciseAnalytics`: channel names, 1 Hz samples, HR, HR zones, laps, summary. |
+| `analyzeExercise(analyticsId, { segmentBy, segmentSeconds })` | The above plus `channelStats`, `segmentMode` and `segments`. |
+| `getSessionHeartRate(sessionId, date?)` | `HrSession`: timestamped HR, zones, avg/min/max HR. |
+| `getWorkoutSessionRaw`, `getExerciseAnalyticsRaw`, `getSessionHeartRateRaw`, `getActivityHistoryRaw` | The untouched payloads, for anything the types do not model. |
+
+Pass `date` whenever you have it: the API partitions sessions by day, and without it the last year
+of history is scanned first. Dates are `YYYY-MM-DD` strings or `Date`s (their local calendar day).
+
+Every metric is a `Property` of `{ value, displayValue, unit, formatted }`: `value` is in the API's
+base unit (seconds, metres, kg), `displayValue` is in `unit` (what the console shows), and
+`formatted` is the localised string. Names and units come back in the account's culture.
+
+### Analytics helpers
+
+Pure functions, exported for samples you already hold: `channelStats(samples, channels)`,
+`segmentAnalytics(samples, channels, laps, { segmentBy, segmentSeconds })`,
+`windowSamples(rows, fromSec, toSec)`, `downsample(rows, step)`.
+
+`segmentBy` is `auto` (default: intervals when there are at least two, else laps, else fixed
+windows), `workload`, `laps` or `fixed`. A 10 × (1 min hard / 1 min easy) treadmill session yields
+20 segments, each with its setpoint, pace, distance covered and avg / max / min of every channel.
+Ramps between setpoints are folded into the interval they lead into.
+
+### `TechnogymClient`
+
+| Member | |
+|---|---|
+| `new TechnogymClient(options)` | `sessionStore`, `credentials`, `facility` (id or url slug; default the first), `timeoutMs` (30 s), `retries` (3), `backoffMs`, `fetchImpl`. |
+| `login(email, password)` | Signs in and saves the session. Keeps the credentials in memory to renew a rejected token. |
+| `loadSession()` / `setSession()` / `getSession()` / `logout()` | Session handling. |
+| `services(path, body?)` | POST to any training endpoint under the facility; `{userId}` in `path` is filled in. For endpoints `Technogym` has no method for. |
+
+Sessions are stored by `FileSessionStore(dir)` (`session.json`, mode 0600) or
+`MemorySessionStore`; implement `SessionStore` for a database.
+
+### Errors
+
+All extend `TechnogymError`: `TechnogymAuthError` (login failed, no session, token rejected),
+`TechnogymApiError` (a 200 whose `errors` envelope is not about the session; `.action`,
+`.errors`), `TechnogymNotFoundError`, `TechnogymRateLimitError` (`.retryAfter`),
+`TechnogymHttpError` (`.status`, `.url`, `.body`), `TechnogymConnectionError`.
+
+## 🤖 MCP server
+
+[`mcp/`](mcp/README.md) is an MCP server built on this library, exposing six read-only tools to
+Claude and other MCP clients.
+
+## 🛠️ Development
+
+```sh
+cp .env.example .env     # fill in TECHNOGYM_EMAIL / TECHNOGYM_PASSWORD
+npm install
+npm run check            # typecheck, lint, build, test (library and MCP server)
+npm run login && npm run demo
+```
+
+## 🙏 Credits
+
+The endpoint surface and parsing follow the Technogym server in
+[health_mcp](https://github.com/ErikAnkerKilbergSkallevold/health_mcp/tree/main/technogym)
+(MIT). See [`NOTICE`](NOTICE).
+
+## License
+
+MIT