@trainheroic-unofficial/cli 3.3.2 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.mjs CHANGED
@@ -266,6 +266,12 @@ const athleteSessionRemoveArgsSchema = z.object({
266
266
  programWorkoutId: idArgSchema,
267
267
  date: dateString
268
268
  });
269
+ const athleteWorkoutNoteArgsSchema = z.object({
270
+ date: dateString,
271
+ programWorkoutId: idArgSchema,
272
+ notes: z.string().optional(),
273
+ rpe: z.number().int().min(1).max(10).optional()
274
+ }).refine((v) => v.notes !== void 0 || v.rpe !== void 0, { message: "Provide notes and/or rpe" });
269
275
  const presentedNullNumber = z.number().nullable();
270
276
  const presentedNullString = z.string().nullable();
271
277
  /** Flattened exercise within a presented workout: prescriptions, logged results, units. */
@@ -291,6 +297,8 @@ const athleteWorkoutViewSchema = z.object({
291
297
  program: presentedNullString,
292
298
  team: presentedNullString,
293
299
  instruction: presentedNullString,
300
+ notes: presentedNullString,
301
+ rpe: presentedNullNumber,
294
302
  logged: z.boolean(),
295
303
  personal: z.boolean(),
296
304
  blocks: z.array(athleteWorkoutBlockSchema)
@@ -585,6 +593,13 @@ z.object({
585
593
  groupId: z.number(),
586
594
  date: z.string()
587
595
  });
596
+ z.object({
597
+ programWorkoutId: z.number(),
598
+ savedWorkoutId: z.number(),
599
+ date: z.string(),
600
+ notes: z.string(),
601
+ rpe: nullableNumber
602
+ });
588
603
  const workoutReadExerciseOutputSchema = z.object({
589
604
  order: z.number(),
590
605
  title: z.string(),
@@ -1074,6 +1089,15 @@ function isPersonalSession(pw) {
1074
1089
  return isRecord(pw) && pw.personal_cal === true;
1075
1090
  }
1076
1091
  /**
1092
+ * The `saved_workout` blob on a program-workout range item, or null if the athlete has no saved
1093
+ * copy yet. Session notes, RPE, and set writes all resolve through this.
1094
+ */
1095
+ function savedWorkoutOf(pw) {
1096
+ if (!isRecord(pw)) return null;
1097
+ const ssw = isRecord(pw.summarizedSavedWorkout) ? pw.summarizedSavedWorkout : {};
1098
+ return isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
1099
+ }
1100
+ /**
1077
1101
  * Rank candidate rows for a free-text query (FTS5 replacement). Higher is better:
1078
1102
  * exact title, then prefix, then count of matched tokens, with shorter titles and
1079
1103
  * standard (non-custom) exercises preferred on ties.
@@ -1236,6 +1260,15 @@ function fetchExerciseStats(client, exerciseId, userId, date) {
1236
1260
  function fetchAthleteWorkouts(client, startDate, endDate) {
1237
1261
  return getArray$1(client, `/3.0/athlete/programworkout/range?startDate=${startDate}&endDate=${endDate}`, "athlete workouts");
1238
1262
  }
1263
+ /**
1264
+ * The program-workout row with this id on this date. Throws if that id is not on the day's range;
1265
+ * callers should take the id from `athlete_workouts`.
1266
+ */
1267
+ async function programWorkoutOnDate(client, date, programWorkoutId) {
1268
+ const target = (await fetchAthleteWorkouts(client, date, date)).find((pw) => coerceInt(pw.id) === programWorkoutId);
1269
+ if (target === void 0) throw new Error(`No workout with id ${programWorkoutId} on ${date}. Get the id and date from athlete_workouts.`);
1270
+ return target;
1271
+ }
1239
1272
  /** Add `days` to a `YYYY-MM-DD` date (UTC), returning `YYYY-MM-DD`. */
1240
1273
  function shiftDate(iso, days) {
1241
1274
  const d = /* @__PURE__ */ new Date(`${iso}T00:00:00Z`);
@@ -1431,7 +1464,7 @@ function mergeAthleteWorkout(raw) {
1431
1464
  const rec = raw;
1432
1465
  const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
1433
1466
  const workout = isRecord(ssw.workout) ? ssw.workout : {};
1434
- const saved = isRecord(ssw.saved_workout) ? ssw.saved_workout : {};
1467
+ const saved = savedWorkoutOf(rec) ?? {};
1435
1468
  const prescriptionSets = (Array.isArray(workout.workoutSets) ? workout.workoutSets : []).filter(isRecord);
1436
1469
  const logged = savedSets(saved);
1437
1470
  const performedById = performedSlotsByExerciseId(logged);
@@ -1460,6 +1493,8 @@ function mergeAthleteWorkout(raw) {
1460
1493
  program: str$1(rec.program_title),
1461
1494
  team: str$1(rec.team_title),
1462
1495
  instruction: str$1(workout.instruction),
1496
+ notes: str$1(saved.notes),
1497
+ rpe: coerceInt(saved.rpe),
1463
1498
  logged: blocks.some((b) => b.exercises.some((e) => e.sets.some((s) => s.performed !== null))),
1464
1499
  personal: isPersonalSession(rec),
1465
1500
  blocks
@@ -1507,6 +1542,8 @@ function presentAthleteWorkout(raw) {
1507
1542
  program: w.program,
1508
1543
  team: w.team,
1509
1544
  instruction: w.instruction,
1545
+ notes: w.notes,
1546
+ rpe: w.rpe,
1510
1547
  logged: w.logged,
1511
1548
  personal: w.personal,
1512
1549
  blocks: w.blocks.map(toStringBlock)
@@ -1726,7 +1763,7 @@ function presentCoachAthleteTraining(raw, athleteId, year, month) {
1726
1763
  completed: coerceInt(item.completed) === 1,
1727
1764
  rpe: coerceInt(item.rpe),
1728
1765
  durationMin: coerceInt(item.session_duration),
1729
- notes: typeof item.notes === "string" && item.notes !== "" ? item.notes : null,
1766
+ notes: str$1(item.notes),
1730
1767
  exercises
1731
1768
  });
1732
1769
  }
@@ -1946,9 +1983,7 @@ function assertUniqueExerciseResults(results) {
1946
1983
  function findSavedWorkoutSet(workouts, savedWorkoutSetId) {
1947
1984
  const available = [];
1948
1985
  for (const pw of workouts) {
1949
- const rec = pw;
1950
- const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
1951
- const sw = isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
1986
+ const sw = savedWorkoutOf(pw);
1952
1987
  if (!sw) continue;
1953
1988
  const sets = Array.isArray(sw.workoutSets) ? sw.workoutSets : [];
1954
1989
  for (const s of sets) {
@@ -2246,9 +2281,7 @@ async function addExercisesToWorkout(client, workoutId, exercises) {
2246
2281
  * Throws on a non-ok response.
2247
2282
  */
2248
2283
  async function removePersonalWorkout(client, args) {
2249
- const target = (await fetchAthleteWorkouts(client, args.date, args.date)).find((pw) => coerceInt(pw.id) === args.programWorkoutId);
2250
- if (target === void 0) throw new Error(`No workout with id ${args.programWorkoutId} on ${args.date}. Get the id and date from athlete_workouts.`);
2251
- if (!isPersonalSession(target)) throw new Error(`Workout ${args.programWorkoutId} on ${args.date} is a coach-scheduled workout, not a personal session, so it can't be removed. To change logged results on a scheduled workout, use athlete_log_set.`);
2284
+ if (!isPersonalSession(await programWorkoutOnDate(client, args.date, args.programWorkoutId))) throw new Error(`Workout ${args.programWorkoutId} on ${args.date} is a coach-scheduled workout, not a personal session, so it can't be removed. To change logged results on a scheduled workout, use athlete_log_set.`);
2252
2285
  const res = await client.request("DELETE", `/v5/programWorkouts/${args.programWorkoutId}`);
2253
2286
  if (!res.ok) throw new Error(`Remove personal workout failed (HTTP ${res.status}).`);
2254
2287
  }
@@ -2301,8 +2334,7 @@ function eachPrescribedExercise(workouts) {
2301
2334
  const rows = [];
2302
2335
  for (const pw of workouts) {
2303
2336
  const rec = pw;
2304
- const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
2305
- const sw = isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
2337
+ const sw = savedWorkoutOf(rec);
2306
2338
  if (!sw) continue;
2307
2339
  const sets = [...Array.isArray(sw.workoutSets) ? sw.workoutSets : [], ...Array.isArray(sw.addedWorkoutSets) ? sw.addedWorkoutSets : []];
2308
2340
  for (const s of sets) {
@@ -2472,6 +2504,53 @@ async function logSessionForAthlete(client, args) {
2472
2504
  };
2473
2505
  }
2474
2506
  //#endregion
2507
+ //#region ../js/src/util.ts
2508
+ /**
2509
+ * Drop the keys whose value is `undefined`, so the result can be passed to a function or
2510
+ * spread into an object under `exactOptionalPropertyTypes` without the per-key
2511
+ * `...(x !== undefined ? { x } : {})` dance. Required keys stay required in the result type;
2512
+ * optional ones lose `undefined` from their value type.
2513
+ *
2514
+ * Example:
2515
+ * definedProps({ metric, teamId: maybeId, date }) // omits teamId/date if they're undefined
2516
+ */
2517
+ function definedProps(obj) {
2518
+ const result = {};
2519
+ for (const [key, value] of Object.entries(obj)) if (value !== void 0) result[key] = value;
2520
+ return result;
2521
+ }
2522
+ //#endregion
2523
+ //#region ../js/src/athlete-workout-note.ts
2524
+ /**
2525
+ * PUT /1.0/athlete/savedworkout/{id} — set the athlete's session note (the free-text box on the
2526
+ * workout screen) and/or session RPE. The date + programWorkoutId (`athlete_workouts` `id`) locate
2527
+ * the saved workout; GET on that path 405s, so the range read is the lookup. A notes-only body
2528
+ * leaves rpe untouched and vice versa. Empty `notes` clears the note. Coach-visible.
2529
+ */
2530
+ async function setAthleteWorkoutNote(client, args) {
2531
+ if (args.notes === void 0 && args.rpe === void 0) throw new Error("Provide notes and/or rpe.");
2532
+ const programWorkoutId = coerceInt(args.programWorkoutId);
2533
+ if (programWorkoutId === null) throw new Error(`Invalid programWorkoutId ${String(args.programWorkoutId)}.`);
2534
+ const saved = savedWorkoutOf(await programWorkoutOnDate(client, args.date, programWorkoutId));
2535
+ const savedWorkoutId = saved !== null ? coerceInt(saved.id) : null;
2536
+ if (savedWorkoutId === null) throw new Error(`Workout ${programWorkoutId} on ${args.date} has no saved workout to attach a note to.`);
2537
+ const body = definedProps({
2538
+ id: savedWorkoutId,
2539
+ notes: args.notes,
2540
+ rpe: args.rpe
2541
+ });
2542
+ const res = await client.request("PUT", `/1.0/athlete/savedworkout/${savedWorkoutId}`, { body });
2543
+ if (!res.ok) throw new Error(`Set workout note failed (HTTP ${res.status}).`);
2544
+ const data = isRecord(res.data) ? res.data : {};
2545
+ return {
2546
+ programWorkoutId,
2547
+ savedWorkoutId,
2548
+ date: args.date,
2549
+ notes: typeof data.notes === "string" ? data.notes : args.notes ?? "",
2550
+ rpe: coerceInt(data.rpe) ?? (args.rpe !== void 0 ? args.rpe : null)
2551
+ };
2552
+ }
2553
+ //#endregion
2475
2554
  //#region ../js/src/workout-export.ts
2476
2555
  const DEFAULT_FILENAME_BASE = "trainheroic-workout-history";
2477
2556
  /** Pretty-printed JSON of the structured workouts, exactly as `presentAthleteWorkoutsExport` yields. */
@@ -2598,22 +2677,6 @@ function serializeWorkoutHistory(workouts, format, opts = {}) {
2598
2677
  };
2599
2678
  }
2600
2679
  //#endregion
2601
- //#region ../js/src/util.ts
2602
- /**
2603
- * Drop the keys whose value is `undefined`, so the result can be passed to a function or
2604
- * spread into an object under `exactOptionalPropertyTypes` without the per-key
2605
- * `...(x !== undefined ? { x } : {})` dance. Required keys stay required in the result type;
2606
- * optional ones lose `undefined` from their value type.
2607
- *
2608
- * Example:
2609
- * definedProps({ metric, teamId: maybeId, date }) // omits teamId/date if they're undefined
2610
- */
2611
- function definedProps(obj) {
2612
- const result = {};
2613
- for (const [key, value] of Object.entries(obj)) if (value !== void 0) result[key] = value;
2614
- return result;
2615
- }
2616
- //#endregion
2617
2680
  //#region ../js/src/workout-encode.ts
2618
2681
  const LEADERBOARD_TYPE = {
2619
2682
  completion: 0,
@@ -4092,6 +4155,7 @@ Athlete — the logged-in user's own training (a coach account works too):
4092
4155
  athlete log-session --date Y-M-D <exercisesJson>|--file f --yes (log OFF-PLAN work with no prescription — creates/reuses a personal session for the date, then logs it; exerciseIds from 'athlete exercises')
4093
4156
  athlete session-remove --id <programWorkoutId> --date Y-M-D --yes (delete a stray PERSONAL session; the id is the session 'id' from 'athlete workouts')
4094
4157
  athlete swap-exercise --set-exercise <savedWorkoutSetExerciseId> --exercise <exerciseId> --yes (substitute one prescribed exercise in a COACH-SCHEDULED slot for a different one — your copy only; slot id from 'athlete log-targets', exerciseId from 'athlete exercises')
4158
+ athlete workout-note --date Y-M-D --id <programWorkoutId> [--notes "..."] [--rpe 1-10] --yes (the free-text note / session RPE on a workout, coach-visible; id is the session 'id' from 'athlete workouts'; empty --notes clears; notes-only leaves rpe untouched and vice versa)
4095
4159
  JSON is the exercises array: [{"exerciseId":N,"sets":[{"param1":reps,"param2":weight}, ...]}, ...]
4096
4160
  `;
4097
4161
  function out(value) {
@@ -4575,6 +4639,24 @@ async function cmdAthleteSwapExercise(client, a) {
4575
4639
  exerciseId
4576
4640
  }));
4577
4641
  }
4642
+ const ATHLETE_WORKOUT_NOTE_USAGE = "athlete workout-note --date Y-M-D --id <programWorkoutId> [--notes \"...\"] [--rpe 1-10] --yes";
4643
+ async function cmdAthleteWorkoutNote(client, a) {
4644
+ const { values } = parse(a, {
4645
+ date: { type: "string" },
4646
+ id: { type: "string" },
4647
+ notes: { type: "string" },
4648
+ rpe: { type: "string" },
4649
+ yes: { type: "boolean" }
4650
+ });
4651
+ const args = validate(athleteWorkoutNoteArgsSchema, definedProps({
4652
+ date: isoDate(need(values.date, ATHLETE_WORKOUT_NOTE_USAGE), "--date"),
4653
+ programWorkoutId: need(values.id, ATHLETE_WORKOUT_NOTE_USAGE),
4654
+ notes: values.notes,
4655
+ rpe: values.rpe !== void 0 ? toInt(values.rpe, "--rpe") : void 0
4656
+ }), "workout-note args");
4657
+ if (values.yes !== true) fail(`setting the session note on workout ${args.programWorkoutId} is coach-visible; add --yes.`);
4658
+ return out(await setAthleteWorkoutNote(client, args));
4659
+ }
4578
4660
  async function cmdAthleteWorkouts(client, a) {
4579
4661
  const { values } = parse(a, {
4580
4662
  start: { type: "string" },
@@ -4669,7 +4751,8 @@ async function cmdAthlete(client, rest) {
4669
4751
  case "log-session": return cmdAthleteLogSession(client, a);
4670
4752
  case "session-remove": return cmdAthleteSessionRemove(client, a);
4671
4753
  case "swap-exercise": return cmdAthleteSwapExercise(client, a);
4672
- default: return fail("usage: trainheroic athlete <whoami|profile|prefs|workouts|log-targets|exercises|recent-exercises|circuits|programs|history|prs|stats|working-maxes|leaderboard|export|log-set|prescribe-set|log-session|session-remove|swap-exercise>");
4754
+ case "workout-note": return cmdAthleteWorkoutNote(client, a);
4755
+ default: return fail("usage: trainheroic athlete <whoami|profile|prefs|workouts|log-targets|exercises|recent-exercises|circuits|programs|history|prs|stats|working-maxes|leaderboard|export|log-set|prescribe-set|log-session|session-remove|swap-exercise|workout-note>");
4673
4756
  }
4674
4757
  }
4675
4758
  async function cmdSkill(rest) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/cli",
3
- "version": "3.3.2",
3
+ "version": "3.4.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -21,15 +21,15 @@
21
21
  ],
22
22
  "dependencies": {
23
23
  "zod": "^4.4.3",
24
- "@trainheroic-unofficial/dto": "3.3.2",
25
- "@trainheroic-unofficial/js": "3.3.2"
24
+ "@trainheroic-unofficial/dto": "3.4.0",
25
+ "@trainheroic-unofficial/js": "3.4.0"
26
26
  },
27
27
  "devDependencies": {
28
- "@types/node": "^26.2.0",
28
+ "@types/node": "^26.3.0",
29
29
  "tsdown": "^0.22.14",
30
30
  "tsx": "^4.23.12",
31
31
  "typescript": "^7.0.2",
32
- "vitest": "^4.1.10"
32
+ "vitest": "^4.1.11"
33
33
  },
34
34
  "scripts": {
35
35
  "start": "tsx src/cli.ts",
@@ -52,23 +52,24 @@ on a 401/403. Start with `$TH athlete whoami` to confirm auth and get your `id`.
52
52
 
53
53
  ## What you can do
54
54
 
55
- | Goal | Command |
56
- | ------------------------------------- | -------------------------------------------------------------------------------- |
57
- | Lifetime totals + profile | `$TH athlete profile [--metric]` |
58
- | Scheduled / completed workouts | `$TH athlete workouts --start Y-M-D --end Y-M-D [--raw] [--summary]` |
59
- | Find an exercise you've logged | `$TH athlete exercises [--q <text>] [--limit N]` |
60
- | One lift's PRs + history over time | `$TH athlete history <exerciseId> [--raw]` |
61
- | Personal records for a lift | `$TH athlete prs <exerciseId>` |
62
- | Last performance + PR as of a date | `$TH athlete stats <exerciseId> --date Y-M-D` |
63
- | Working maxes (drive % prescriptions) | `$TH athlete working-maxes` |
64
- | Benchmark leaderboard | `$TH athlete leaderboard <workoutId>` |
65
- | Download all historicals to JSON | `$TH athlete export [--out dir] [--full]` |
66
- | Log ids for a scheduled workout | `$TH athlete log-targets --start Y-M-D --end Y-M-D [--program <title>]` |
67
- | Log completed set results (gated) | `$TH athlete log-set --date Y-M-D --set <id> ... --yes` |
68
- | Set planned reps/weight (gated) | `$TH athlete prescribe-set --date Y-M-D --set <id> ... --yes` |
69
- | Log an off-plan session (gated) | `$TH athlete log-session --date Y-M-D '[{"exerciseId":N,"sets":[...]}]' --yes` |
70
- | Swap a prescribed exercise (gated) | `$TH athlete swap-exercise --set-exercise <sweId> --exercise <exerciseId> --yes` |
71
- | Remove a stray personal session | `$TH athlete session-remove --id <programWorkoutId> --date Y-M-D --yes` |
55
+ | Goal | Command |
56
+ | ------------------------------------- | ----------------------------------------------------------------------------------- |
57
+ | Lifetime totals + profile | `$TH athlete profile [--metric]` |
58
+ | Scheduled / completed workouts | `$TH athlete workouts --start Y-M-D --end Y-M-D [--raw] [--summary]` |
59
+ | Find an exercise you've logged | `$TH athlete exercises [--q <text>] [--limit N]` |
60
+ | One lift's PRs + history over time | `$TH athlete history <exerciseId> [--raw]` |
61
+ | Personal records for a lift | `$TH athlete prs <exerciseId>` |
62
+ | Last performance + PR as of a date | `$TH athlete stats <exerciseId> --date Y-M-D` |
63
+ | Working maxes (drive % prescriptions) | `$TH athlete working-maxes` |
64
+ | Benchmark leaderboard | `$TH athlete leaderboard <workoutId>` |
65
+ | Download all historicals to JSON | `$TH athlete export [--out dir] [--full]` |
66
+ | Log ids for a scheduled workout | `$TH athlete log-targets --start Y-M-D --end Y-M-D [--program <title>]` |
67
+ | Log completed set results (gated) | `$TH athlete log-set --date Y-M-D --set <id> ... --yes` |
68
+ | Set planned reps/weight (gated) | `$TH athlete prescribe-set --date Y-M-D --set <id> ... --yes` |
69
+ | Log an off-plan session (gated) | `$TH athlete log-session --date Y-M-D '[{"exerciseId":N,"sets":[...]}]' --yes` |
70
+ | Swap a prescribed exercise (gated) | `$TH athlete swap-exercise --set-exercise <sweId> --exercise <exerciseId> --yes` |
71
+ | Add a session note / RPE (gated) | `$TH athlete workout-note --date Y-M-D --id <programWorkoutId> --notes "..." --yes` |
72
+ | Remove a stray personal session | `$TH athlete session-remove --id <programWorkoutId> --date Y-M-D --yes` |
72
73
 
73
74
  ## Reading training
74
75
 
@@ -180,15 +181,28 @@ exercise, so swap first, then log against the new movement as usual. Same `--yes
180
181
  the workout with `$TH athlete workouts --start Y-M-D --end Y-M-D` to confirm the slot now shows
181
182
  the replacement.
182
183
 
184
+ ## Session note / RPE
185
+
186
+ `$TH athlete workout-note` writes the free-text note (and optional session RPE) on a workout —
187
+ the box on the workout screen, not the coach's Instructions. It is coach-visible. The `id` is
188
+ the session `id` from `$TH athlete workouts`. Empty `--notes` clears the note; a notes-only
189
+ write leaves RPE untouched and vice versa.
190
+
191
+ ```bash
192
+ $TH athlete workouts --start 2026-06-01 --end 2026-06-01 --summary
193
+ $TH athlete workout-note --date 2026-06-01 --id 149542413 --notes "Hips felt tight." --rpe 8 --yes
194
+ ```
195
+
183
196
  ## Gotchas
184
197
 
185
198
  - `profile` must send `use_metric` and `stats` must send `date`, or the API returns 400.
186
199
  The CLI fills `use_metric` (toggle with `--metric`); pass `--date` to `stats`.
187
200
  - Units are **fixed per exercise** and surfaced positionally as `[param 1, param 2]` (e.g.
188
201
  `["reps", "lb"]`). They are not labelled by role: some exercises reverse the slots.
189
- - `log-set` writes to your coach-visible log. Gate it behind explicit user confirmation,
190
- never run it autonomously, and verify the result. Its request shape was reverse-engineered
191
- from the mobile app (a two-step write: log the exercise data, then mark the set completed).
202
+ - `log-set` and `workout-note` write to your coach-visible log. Gate them behind explicit user
203
+ confirmation, never run them autonomously, and verify the result. `log-set`'s request shape
204
+ was reverse-engineered from the mobile app (a two-step write: log the exercise data, then
205
+ mark the set completed).
192
206
  - This API is undocumented and can change. `references/athlete-api.md` lists the endpoints
193
207
  and shapes.
194
208
 
@@ -40,8 +40,10 @@ completed workouts in an inclusive window. Each item:
40
40
  at 0.
41
41
 
42
42
  The SDK's `presentAthleteWorkout` merges the two copies into `{ id, date, title, program, team,
43
- instruction, logged, blocks: [{ order, title, instruction, isTest, exercises: [{ exerciseId,
44
- title, instruction, units, prescribed, performed }] }] }`. `performed` holds the per-set values
43
+ instruction, notes, rpe, logged, blocks: [{ order, title, instruction, isTest, exercises: [{ exerciseId,
44
+ title, instruction, units, prescribed, performed }] }] }`. `instruction` is the coach's session
45
+ note; `notes` / `rpe` are the athlete's own session note and RPE on `saved_workout` (null when
46
+ unset). `performed` holds the per-set values
45
47
  the athlete logged (made-gated; empty when nothing was recorded), `logged` is true when any
46
48
  exercise has `performed` values, and athlete-added/personal work with no prescription is
47
49
  appended as its own blocks. No `--raw` is needed to read logged results.
@@ -69,12 +71,19 @@ resolve the ids from `summarizedSavedWorkout.saved_workout`.
69
71
  param_1_data_N, param_2_data_N (10 slots) }`. This is the only path that actually stores
70
72
  reps/weight (and it alone surfaces the result in exercise history). The
71
73
  `savedworkoutset`/`savedworkout` PUTs accept the same fields but **silently discard** the
72
- `param_N_data` values.
74
+ `param_N_data` values (the savedworkout PUT is the session-note / RPE write, not a log path).
73
75
  2. **Mark the set completed** — `PUT /1.0/athlete/savedworkoutset/{savedWorkoutSetId}` with
74
76
  the camelCase in-memory model (`sessionId` ← `saved_workout.id`, `workoutSetId` ←
75
77
  `workout_set_id`, `isSuperSet`, `exercises: [savedWorkoutSetExerciseId, …]`, `completed`).
76
78
  A minimal `{id, sessionId, completed}` body returns 500 — the full mapped body is required.
77
79
 
80
+ 3. **Session note / RPE** — `PUT /1.0/athlete/savedworkout/{savedWorkoutId}` with `{ id, notes?, rpe? }`.
81
+ GET on that path 405s; resolve `savedWorkoutId` from the range item's
82
+ `summarizedSavedWorkout.saved_workout.id`. A notes-only body leaves rpe untouched and vice versa.
83
+ Empty `notes` clears the note. `session_duration` is not a field on this object (the coach
84
+ calendar summary's duration is separate). The SDK's `setAthleteWorkoutNote` looks the saved id
85
+ up from `date` + `programWorkoutId` (the range item's top-level `id`).
86
+
78
87
  There is no GET for a single saved workout set; read it from the workout range's
79
88
  `saved_workout.workoutSets[]` (`id` = savedWorkoutSetId, `workoutSetExercises[].id` =
80
89
  savedWorkoutSetExerciseId, `workoutSetExercises[].workout_set_exercise_id` = the template id).
@@ -87,8 +96,9 @@ account) expose:
87
96
  - Live reads: `athlete_whoami`, `athlete_profile`, `athlete_prefs`, `athlete_workouts`,
88
97
  `athlete_exercises`, `athlete_exercise_history`, `athlete_personal_records`,
89
98
  `athlete_exercise_stats`, `athlete_working_maxes`, `athlete_leaderboard`.
90
- - Gated writes include `athlete_log_set` for performed results and `athlete_prescribe_set` for
91
- planned reps/weight that must not mark a set completed (elicitation or `confirm:true`).
99
+ - Gated writes include `athlete_log_set` for performed results, `athlete_prescribe_set` for
100
+ planned reps/weight that must not mark a set completed, and `athlete_workout_note` for the
101
+ session note / RPE (elicitation or `confirm:true`).
92
102
 
93
103
  ## Warehouse tools (hosted worker only, D1-backed)
94
104
 
@@ -108,5 +118,6 @@ startDate?/endDate? }`.
108
118
  Living status table: `.agents/skills/reverse-engineer-api/coverage.md`.
109
119
 
110
120
  In-scope athlete reads are wrapped (`athlete_circuits`, `athlete_programming_programs`,
111
- `athlete_recent_exercises`). Closed without a wrap: `PUT /1.0/athlete/savedworkout/{id}`
112
- (per-set logging is enough); working-max write (read exists; set/update never found).
121
+ `athlete_recent_exercises`). Closed without a wrap: working-max write (read exists; set/update
122
+ never found). `PUT /1.0/athlete/savedworkout/{id}` is wrapped as the session-note / RPE write
123
+ (`athlete_workout_note`); it is not a set-logging path.
@@ -1011,33 +1011,33 @@ Returns all available analytics categories and their instances:
1011
1011
 
1012
1012
  These are used by the mobile app / athlete-facing client (documented in `train-heroic-schema.yml`):
1013
1013
 
1014
- | Method | Endpoint | Description |
1015
- | ------ | ------------------------------------------------------- | ---------------------------------------------------------- |
1016
- | POST | `/auth` | Login |
1017
- | GET | `/v5/users/exercises/history` | All exercise history |
1018
- | GET | `/v5/users/exercises/recent` | Recent exercises |
1019
- | GET | `/v5/exercises/{id}/history` | Single exercise history |
1020
- | GET | `/v5/exercises/{id}` | Exercise details |
1021
- | GET | `/v5/exercises/{id}/personalRecords` | Exercise PRs |
1022
- | GET | `/v5/exercises/{id}/stats` | Exercise stats |
1023
- | GET | `/v5/exercises/{id}/stackUp/isSupportedExercise` | Stack-up support check |
1024
- | GET | `/v5/users/circuits/recent` | Recent circuits |
1025
- | GET | `/v5/users/circuits/history` | Circuit history |
1026
- | GET | `/3.0/athlete/programworkout/range?startDate=&endDate=` | Workouts by date range |
1027
- | GET | `/1.0/athlete/programming/programs` | Athlete programs |
1028
- | GET | `/v5/users/{id}` | User profile |
1029
- | GET | `/1.0/athlete/prefs` | Athlete preferences |
1030
- | GET | `/2.0/athlete/workingMax` | Working maxes (all exercises with WM tracking) |
1031
- | GET | `/1.0/athlete/savedworkoutset/{id}` | Saved workout set |
1032
- | GET | `/1.0/athlete/savedworkout/{id}` | Saved workout |
1033
- | GET | `/1.0/user/userInfo` | User info |
1034
- | GET | `/v5/calendars/athletes/{id}?year=&month=` | **Athlete coach calendar** (program id for CREATE SESSION) |
1035
- | GET | `/v5/calendars/athletes/{id}/coachAthleteTeam` | Coach-athlete team calendar |
1036
- | GET | `/v5/users/{id}/workingMaxes/{id1}` | Specific working max |
1037
- | GET | `/v5/programs/new` | New programs |
1038
- | GET | `/v5/programs/free` | Free programs |
1039
- | GET | `/v5/athleteProfile/summary` | Athlete profile summary |
1040
- | GET | `/3.0/athlete/leaderboard/{id}` | Leaderboard |
1014
+ | Method | Endpoint | Description |
1015
+ | ------ | ------------------------------------------------------- | ------------------------------------------------------------- |
1016
+ | POST | `/auth` | Login |
1017
+ | GET | `/v5/users/exercises/history` | All exercise history |
1018
+ | GET | `/v5/users/exercises/recent` | Recent exercises |
1019
+ | GET | `/v5/exercises/{id}/history` | Single exercise history |
1020
+ | GET | `/v5/exercises/{id}` | Exercise details |
1021
+ | GET | `/v5/exercises/{id}/personalRecords` | Exercise PRs |
1022
+ | GET | `/v5/exercises/{id}/stats` | Exercise stats |
1023
+ | GET | `/v5/exercises/{id}/stackUp/isSupportedExercise` | Stack-up support check |
1024
+ | GET | `/v5/users/circuits/recent` | Recent circuits |
1025
+ | GET | `/v5/users/circuits/history` | Circuit history |
1026
+ | GET | `/3.0/athlete/programworkout/range?startDate=&endDate=` | Workouts by date range |
1027
+ | GET | `/1.0/athlete/programming/programs` | Athlete programs |
1028
+ | GET | `/v5/users/{id}` | User profile |
1029
+ | GET | `/1.0/athlete/prefs` | Athlete preferences |
1030
+ | GET | `/2.0/athlete/workingMax` | Working maxes (all exercises with WM tracking) |
1031
+ | GET | `/1.0/athlete/savedworkoutset/{id}` | Saved workout set |
1032
+ | PUT | `/1.0/athlete/savedworkout/{id}` | **Set session note / RPE** (`{ id, notes?, rpe? }`; GET 405s) |
1033
+ | GET | `/1.0/user/userInfo` | User info |
1034
+ | GET | `/v5/calendars/athletes/{id}?year=&month=` | **Athlete coach calendar** (program id for CREATE SESSION) |
1035
+ | GET | `/v5/calendars/athletes/{id}/coachAthleteTeam` | Coach-athlete team calendar |
1036
+ | GET | `/v5/users/{id}/workingMaxes/{id1}` | Specific working max |
1037
+ | GET | `/v5/programs/new` | New programs |
1038
+ | GET | `/v5/programs/free` | Free programs |
1039
+ | GET | `/v5/athleteProfile/summary` | Athlete profile summary |
1040
+ | GET | `/3.0/athlete/leaderboard/{id}` | Leaderboard |
1041
1041
 
1042
1042
  ---
1043
1043