@trainheroic-unofficial/cli 3.3.3 → 3.5.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,21 @@ 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" });
275
+ /**
276
+ * Args for the athlete per-exercise note write (the "Add exercise note" box on the exercise
277
+ * screen — band color, etc.). `savedWorkoutSetExerciseId` is the slot id from athlete_log_targets.
278
+ * Empty `notes` clears the note. Distinct from {@link athleteWorkoutNoteArgsSchema} (session note).
279
+ */
280
+ const athleteExerciseNoteArgsSchema = z.object({
281
+ savedWorkoutSetExerciseId: idArgSchema,
282
+ notes: z.string()
283
+ });
269
284
  const presentedNullNumber = z.number().nullable();
270
285
  const presentedNullString = z.string().nullable();
271
286
  /** Flattened exercise within a presented workout: prescriptions, logged results, units. */
@@ -273,6 +288,7 @@ const athleteWorkoutExerciseSchema = z.object({
273
288
  exerciseId: presentedNullNumber,
274
289
  title: z.string(),
275
290
  instruction: presentedNullString,
291
+ notes: presentedNullString,
276
292
  units: z.array(presentedNullString),
277
293
  prescribed: z.array(z.string()),
278
294
  performed: z.array(z.string())
@@ -291,6 +307,8 @@ const athleteWorkoutViewSchema = z.object({
291
307
  program: presentedNullString,
292
308
  team: presentedNullString,
293
309
  instruction: presentedNullString,
310
+ notes: presentedNullString,
311
+ rpe: presentedNullNumber,
294
312
  logged: z.boolean(),
295
313
  personal: z.boolean(),
296
314
  blocks: z.array(athleteWorkoutBlockSchema)
@@ -379,6 +397,7 @@ z.array(rosterActivityRowSchema);
379
397
  const presentedExerciseSessionSchema = z.object({
380
398
  date: z.string(),
381
399
  abr: presentedNullString,
400
+ notes: presentedNullString,
382
401
  estimated1RM: presentedNullNumber,
383
402
  sets: z.array(z.object({
384
403
  setNumber: z.number(),
@@ -518,6 +537,7 @@ const logSetTargetOutputSchema = z.object({
518
537
  savedWorkoutSetExerciseId: z.number(),
519
538
  title: z.string(),
520
539
  units: z.array(nullableString),
540
+ notes: nullableString,
521
541
  prescribed: z.array(z.string()),
522
542
  performed: z.array(z.string())
523
543
  }))
@@ -585,6 +605,17 @@ z.object({
585
605
  groupId: z.number(),
586
606
  date: z.string()
587
607
  });
608
+ z.object({
609
+ programWorkoutId: z.number(),
610
+ savedWorkoutId: z.number(),
611
+ date: z.string(),
612
+ notes: z.string(),
613
+ rpe: nullableNumber
614
+ });
615
+ z.object({
616
+ savedWorkoutSetExerciseId: z.number(),
617
+ notes: z.string()
618
+ });
588
619
  const workoutReadExerciseOutputSchema = z.object({
589
620
  order: z.number(),
590
621
  title: z.string(),
@@ -1074,6 +1105,15 @@ function isPersonalSession(pw) {
1074
1105
  return isRecord(pw) && pw.personal_cal === true;
1075
1106
  }
1076
1107
  /**
1108
+ * The `saved_workout` blob on a program-workout range item, or null if the athlete has no saved
1109
+ * copy yet. Session notes, RPE, and set writes all resolve through this.
1110
+ */
1111
+ function savedWorkoutOf(pw) {
1112
+ if (!isRecord(pw)) return null;
1113
+ const ssw = isRecord(pw.summarizedSavedWorkout) ? pw.summarizedSavedWorkout : {};
1114
+ return isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
1115
+ }
1116
+ /**
1077
1117
  * Rank candidate rows for a free-text query (FTS5 replacement). Higher is better:
1078
1118
  * exact title, then prefix, then count of matched tokens, with shorter titles and
1079
1119
  * standard (non-custom) exercises preferred on ties.
@@ -1236,6 +1276,15 @@ function fetchExerciseStats(client, exerciseId, userId, date) {
1236
1276
  function fetchAthleteWorkouts(client, startDate, endDate) {
1237
1277
  return getArray$1(client, `/3.0/athlete/programworkout/range?startDate=${startDate}&endDate=${endDate}`, "athlete workouts");
1238
1278
  }
1279
+ /**
1280
+ * The program-workout row with this id on this date. Throws if that id is not on the day's range;
1281
+ * callers should take the id from `athlete_workouts`.
1282
+ */
1283
+ async function programWorkoutOnDate(client, date, programWorkoutId) {
1284
+ const target = (await fetchAthleteWorkouts(client, date, date)).find((pw) => coerceInt(pw.id) === programWorkoutId);
1285
+ if (target === void 0) throw new Error(`No workout with id ${programWorkoutId} on ${date}. Get the id and date from athlete_workouts.`);
1286
+ return target;
1287
+ }
1239
1288
  /** Add `days` to a `YYYY-MM-DD` date (UTC), returning `YYYY-MM-DD`. */
1240
1289
  function shiftDate(iso, days) {
1241
1290
  const d = /* @__PURE__ */ new Date(`${iso}T00:00:00Z`);
@@ -1374,6 +1423,16 @@ function performedSlotsByExerciseId(sets) {
1374
1423
  }
1375
1424
  return map;
1376
1425
  }
1426
+ /** Per-exercise athlete notes keyed by the prescription template id (`workout_set_exercise_id`). */
1427
+ function notesByTemplateId(sets) {
1428
+ const map = /* @__PURE__ */ new Map();
1429
+ for (const { exercises } of sets) for (const ex of exercises) {
1430
+ const id = coerceInt(ex.workout_set_exercise_id);
1431
+ const notes = str$1(ex.notes);
1432
+ if (id !== null && notes !== null) map.set(id, notes);
1433
+ }
1434
+ return map;
1435
+ }
1377
1436
  /** Align an exercise's prescribed slots with the slots the athlete logged, per set index. */
1378
1437
  function mergeExercise(prescribed, performed, meta) {
1379
1438
  const indices = [.../* @__PURE__ */ new Set([...prescribed.keys(), ...performed.keys()])].sort((a, b) => a - b);
@@ -1387,7 +1446,7 @@ function mergeExercise(prescribed, performed, meta) {
1387
1446
  };
1388
1447
  }
1389
1448
  /** A prescription block, each exercise aligned with the slots the athlete logged against it. */
1390
- function mergePrescriptionBlock(set, performedById) {
1449
+ function mergePrescriptionBlock(set, performedById, notesById) {
1391
1450
  const exercises = Array.isArray(set.workoutSetExercises) ? set.workoutSetExercises : [];
1392
1451
  return {
1393
1452
  order: coerceInt(set.order) ?? 0,
@@ -1401,6 +1460,7 @@ function mergePrescriptionBlock(set, performedById) {
1401
1460
  exerciseId: coerceInt(ex.exercise_id),
1402
1461
  title: typeof ex.title === "string" ? ex.title : "",
1403
1462
  instruction: str$1(ex.instruction),
1463
+ notes: id !== null ? notesById.get(id) ?? null : null,
1404
1464
  units: exerciseUnits(ex.param_1_type, ex.param_2_type)
1405
1465
  });
1406
1466
  })
@@ -1417,6 +1477,7 @@ function mergeSavedBlock(set, exercises) {
1417
1477
  exerciseId: coerceInt(ex.exercise_id),
1418
1478
  title: typeof ex.exercise_title === "string" ? ex.exercise_title : "",
1419
1479
  instruction: str$1(ex.instruction),
1480
+ notes: str$1(ex.notes),
1420
1481
  units: exerciseUnits(ex.param_1_type, ex.param_2_type)
1421
1482
  }))
1422
1483
  };
@@ -1431,11 +1492,12 @@ function mergeAthleteWorkout(raw) {
1431
1492
  const rec = raw;
1432
1493
  const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
1433
1494
  const workout = isRecord(ssw.workout) ? ssw.workout : {};
1434
- const saved = isRecord(ssw.saved_workout) ? ssw.saved_workout : {};
1495
+ const saved = savedWorkoutOf(rec) ?? {};
1435
1496
  const prescriptionSets = (Array.isArray(workout.workoutSets) ? workout.workoutSets : []).filter(isRecord);
1436
1497
  const logged = savedSets(saved);
1437
1498
  const performedById = performedSlotsByExerciseId(logged);
1438
- const blocks = prescriptionSets.map((s) => mergePrescriptionBlock(s, performedById)).sort((a, b) => a.order - b.order);
1499
+ const notesById = notesByTemplateId(logged);
1500
+ const blocks = prescriptionSets.map((s) => mergePrescriptionBlock(s, performedById, notesById)).sort((a, b) => a.order - b.order);
1439
1501
  const prescribedIds = /* @__PURE__ */ new Set();
1440
1502
  for (const s of prescriptionSets) {
1441
1503
  const exs = Array.isArray(s.workoutSetExercises) ? s.workoutSetExercises : [];
@@ -1460,6 +1522,8 @@ function mergeAthleteWorkout(raw) {
1460
1522
  program: str$1(rec.program_title),
1461
1523
  team: str$1(rec.team_title),
1462
1524
  instruction: str$1(workout.instruction),
1525
+ notes: str$1(saved.notes),
1526
+ rpe: coerceInt(saved.rpe),
1463
1527
  logged: blocks.some((b) => b.exercises.some((e) => e.sets.some((s) => s.performed !== null))),
1464
1528
  personal: isPersonalSession(rec),
1465
1529
  blocks
@@ -1479,6 +1543,7 @@ function toStringExercise(ex) {
1479
1543
  exerciseId: ex.exerciseId,
1480
1544
  title: ex.title,
1481
1545
  instruction: ex.instruction,
1546
+ notes: ex.notes,
1482
1547
  units: ex.units,
1483
1548
  prescribed: sideStrings(ex.sets, (s) => s.prescribed),
1484
1549
  performed: sideStrings(ex.sets, (s) => s.performed)
@@ -1507,6 +1572,8 @@ function presentAthleteWorkout(raw) {
1507
1572
  program: w.program,
1508
1573
  team: w.team,
1509
1574
  instruction: w.instruction,
1575
+ notes: w.notes,
1576
+ rpe: w.rpe,
1510
1577
  logged: w.logged,
1511
1578
  personal: w.personal,
1512
1579
  blocks: w.blocks.map(toStringBlock)
@@ -1636,6 +1703,7 @@ function presentLogTargets(list) {
1636
1703
  savedWorkoutSetExerciseId: id,
1637
1704
  title: exerciseTitle(ex),
1638
1705
  units: exerciseUnits(ex.param_1_type, ex.param_2_type),
1706
+ notes: str$1(ex.notes),
1639
1707
  prescribed: prescribedStrings(ex),
1640
1708
  performed: performedStrings(ex)
1641
1709
  };
@@ -1726,7 +1794,7 @@ function presentCoachAthleteTraining(raw, athleteId, year, month) {
1726
1794
  completed: coerceInt(item.completed) === 1,
1727
1795
  rpe: coerceInt(item.rpe),
1728
1796
  durationMin: coerceInt(item.session_duration),
1729
- notes: typeof item.notes === "string" && item.notes !== "" ? item.notes : null,
1797
+ notes: str$1(item.notes),
1730
1798
  exercises
1731
1799
  });
1732
1800
  }
@@ -1751,6 +1819,7 @@ function presentExerciseHistory(detail) {
1751
1819
  sessions: (detail.history ?? []).map((h) => ({
1752
1820
  date: h.dateCompleted,
1753
1821
  abr: h.abr ?? null,
1822
+ notes: str$1(h.notes),
1754
1823
  estimated1RM: h.bestEstimated1RM ?? null,
1755
1824
  sets: (h.sets ?? []).map((s) => ({
1756
1825
  setNumber: s.setNumber,
@@ -1946,9 +2015,7 @@ function assertUniqueExerciseResults(results) {
1946
2015
  function findSavedWorkoutSet(workouts, savedWorkoutSetId) {
1947
2016
  const available = [];
1948
2017
  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;
2018
+ const sw = savedWorkoutOf(pw);
1952
2019
  if (!sw) continue;
1953
2020
  const sets = Array.isArray(sw.workoutSets) ? sw.workoutSets : [];
1954
2021
  for (const s of sets) {
@@ -2246,9 +2313,7 @@ async function addExercisesToWorkout(client, workoutId, exercises) {
2246
2313
  * Throws on a non-ok response.
2247
2314
  */
2248
2315
  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.`);
2316
+ 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
2317
  const res = await client.request("DELETE", `/v5/programWorkouts/${args.programWorkoutId}`);
2253
2318
  if (!res.ok) throw new Error(`Remove personal workout failed (HTTP ${res.status}).`);
2254
2319
  }
@@ -2301,8 +2366,7 @@ function eachPrescribedExercise(workouts) {
2301
2366
  const rows = [];
2302
2367
  for (const pw of workouts) {
2303
2368
  const rec = pw;
2304
- const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
2305
- const sw = isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
2369
+ const sw = savedWorkoutOf(rec);
2306
2370
  if (!sw) continue;
2307
2371
  const sets = [...Array.isArray(sw.workoutSets) ? sw.workoutSets : [], ...Array.isArray(sw.addedWorkoutSets) ? sw.addedWorkoutSets : []];
2308
2372
  for (const s of sets) {
@@ -2472,6 +2536,75 @@ async function logSessionForAthlete(client, args) {
2472
2536
  };
2473
2537
  }
2474
2538
  //#endregion
2539
+ //#region ../js/src/util.ts
2540
+ /**
2541
+ * Drop the keys whose value is `undefined`, so the result can be passed to a function or
2542
+ * spread into an object under `exactOptionalPropertyTypes` without the per-key
2543
+ * `...(x !== undefined ? { x } : {})` dance. Required keys stay required in the result type;
2544
+ * optional ones lose `undefined` from their value type.
2545
+ *
2546
+ * Example:
2547
+ * definedProps({ metric, teamId: maybeId, date }) // omits teamId/date if they're undefined
2548
+ */
2549
+ function definedProps(obj) {
2550
+ const result = {};
2551
+ for (const [key, value] of Object.entries(obj)) if (value !== void 0) result[key] = value;
2552
+ return result;
2553
+ }
2554
+ //#endregion
2555
+ //#region ../js/src/athlete-workout-note.ts
2556
+ /**
2557
+ * PUT /1.0/athlete/savedworkout/{id} — set the athlete's session note (the free-text box on the
2558
+ * workout screen) and/or session RPE. The date + programWorkoutId (`athlete_workouts` `id`) locate
2559
+ * the saved workout; GET on that path 405s, so the range read is the lookup. A notes-only body
2560
+ * leaves rpe untouched and vice versa. Empty `notes` clears the note. Coach-visible.
2561
+ */
2562
+ async function setAthleteWorkoutNote(client, args) {
2563
+ if (args.notes === void 0 && args.rpe === void 0) throw new Error("Provide notes and/or rpe.");
2564
+ const programWorkoutId = coerceInt(args.programWorkoutId);
2565
+ if (programWorkoutId === null) throw new Error(`Invalid programWorkoutId ${String(args.programWorkoutId)}.`);
2566
+ const saved = savedWorkoutOf(await programWorkoutOnDate(client, args.date, programWorkoutId));
2567
+ const savedWorkoutId = saved !== null ? coerceInt(saved.id) : null;
2568
+ if (savedWorkoutId === null) throw new Error(`Workout ${programWorkoutId} on ${args.date} has no saved workout to attach a note to.`);
2569
+ const body = definedProps({
2570
+ id: savedWorkoutId,
2571
+ notes: args.notes,
2572
+ rpe: args.rpe
2573
+ });
2574
+ const res = await client.request("PUT", `/1.0/athlete/savedworkout/${savedWorkoutId}`, { body });
2575
+ if (!res.ok) throw new Error(`Set workout note failed (HTTP ${res.status}).`);
2576
+ const data = isRecord(res.data) ? res.data : {};
2577
+ return {
2578
+ programWorkoutId,
2579
+ savedWorkoutId,
2580
+ date: args.date,
2581
+ notes: typeof data.notes === "string" ? data.notes : args.notes ?? "",
2582
+ rpe: coerceInt(data.rpe) ?? (args.rpe !== void 0 ? args.rpe : null)
2583
+ };
2584
+ }
2585
+ //#endregion
2586
+ //#region ../js/src/athlete-exercise-note.ts
2587
+ /**
2588
+ * PUT /1.0/athlete/savedworkoutsetexercise/{id} — set the athlete's per-exercise note (the
2589
+ * "Add exercise note" box on the exercise screen). A notes-only body leaves logged reps/weight
2590
+ * untouched. Empty `notes` clears the note. GET on that path 405s; the range read and exercise
2591
+ * history both echo the stored string. Coach-visible.
2592
+ */
2593
+ async function setAthleteExerciseNote(client, args) {
2594
+ const savedWorkoutSetExerciseId = coerceInt(args.savedWorkoutSetExerciseId);
2595
+ if (savedWorkoutSetExerciseId === null) throw new Error(`Invalid savedWorkoutSetExerciseId ${String(args.savedWorkoutSetExerciseId)}.`);
2596
+ const res = await client.request("PUT", `/1.0/athlete/savedworkoutsetexercise/${savedWorkoutSetExerciseId}`, { body: {
2597
+ id: savedWorkoutSetExerciseId,
2598
+ notes: args.notes
2599
+ } });
2600
+ if (!res.ok) throw new Error(`Set exercise note failed (HTTP ${res.status}).`);
2601
+ const data = isRecord(res.data) ? res.data : {};
2602
+ return {
2603
+ savedWorkoutSetExerciseId,
2604
+ notes: typeof data.notes === "string" ? data.notes : args.notes
2605
+ };
2606
+ }
2607
+ //#endregion
2475
2608
  //#region ../js/src/workout-export.ts
2476
2609
  const DEFAULT_FILENAME_BASE = "trainheroic-workout-history";
2477
2610
  /** Pretty-printed JSON of the structured workouts, exactly as `presentAthleteWorkoutsExport` yields. */
@@ -2598,22 +2731,6 @@ function serializeWorkoutHistory(workouts, format, opts = {}) {
2598
2731
  };
2599
2732
  }
2600
2733
  //#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
2734
  //#region ../js/src/workout-encode.ts
2618
2735
  const LEADERBOARD_TYPE = {
2619
2736
  completion: 0,
@@ -4092,6 +4209,8 @@ Athlete — the logged-in user's own training (a coach account works too):
4092
4209
  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
4210
  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
4211
  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')
4212
+ 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)
4213
+ athlete exercise-note --set-exercise <savedWorkoutSetExerciseId> --notes "..." --yes (the per-exercise note on the exercise screen — band color, etc.; slot id from 'athlete log-targets'; empty --notes clears; distinct from workout-note)
4095
4214
  JSON is the exercises array: [{"exerciseId":N,"sets":[{"param1":reps,"param2":weight}, ...]}, ...]
4096
4215
  `;
4097
4216
  function out(value) {
@@ -4575,6 +4694,40 @@ async function cmdAthleteSwapExercise(client, a) {
4575
4694
  exerciseId
4576
4695
  }));
4577
4696
  }
4697
+ const ATHLETE_WORKOUT_NOTE_USAGE = "athlete workout-note --date Y-M-D --id <programWorkoutId> [--notes \"...\"] [--rpe 1-10] --yes";
4698
+ async function cmdAthleteWorkoutNote(client, a) {
4699
+ const { values } = parse(a, {
4700
+ date: { type: "string" },
4701
+ id: { type: "string" },
4702
+ notes: { type: "string" },
4703
+ rpe: { type: "string" },
4704
+ yes: { type: "boolean" }
4705
+ });
4706
+ const args = validate(athleteWorkoutNoteArgsSchema, definedProps({
4707
+ date: isoDate(need(values.date, ATHLETE_WORKOUT_NOTE_USAGE), "--date"),
4708
+ programWorkoutId: need(values.id, ATHLETE_WORKOUT_NOTE_USAGE),
4709
+ notes: values.notes,
4710
+ rpe: values.rpe !== void 0 ? toInt(values.rpe, "--rpe") : void 0
4711
+ }), "workout-note args");
4712
+ if (values.yes !== true) fail(`setting the session note on workout ${args.programWorkoutId} is coach-visible; add --yes.`);
4713
+ return out(await setAthleteWorkoutNote(client, args));
4714
+ }
4715
+ const ATHLETE_EXERCISE_NOTE_USAGE = "athlete exercise-note --set-exercise <savedWorkoutSetExerciseId> --notes \"...\" --yes";
4716
+ async function cmdAthleteExerciseNote(client, a) {
4717
+ const { values } = parse(a, {
4718
+ "set-exercise": { type: "string" },
4719
+ notes: { type: "string" },
4720
+ yes: { type: "boolean" }
4721
+ });
4722
+ const notes = values.notes;
4723
+ if (notes === void 0) fail(`usage: trainheroic ${ATHLETE_EXERCISE_NOTE_USAGE}`);
4724
+ const args = validate(athleteExerciseNoteArgsSchema, {
4725
+ savedWorkoutSetExerciseId: need(values["set-exercise"], ATHLETE_EXERCISE_NOTE_USAGE),
4726
+ notes
4727
+ }, "exercise-note args");
4728
+ if (values.yes !== true) fail(`setting the exercise note on slot ${args.savedWorkoutSetExerciseId} is coach-visible; add --yes.`);
4729
+ return out(await setAthleteExerciseNote(client, args));
4730
+ }
4578
4731
  async function cmdAthleteWorkouts(client, a) {
4579
4732
  const { values } = parse(a, {
4580
4733
  start: { type: "string" },
@@ -4669,7 +4822,9 @@ async function cmdAthlete(client, rest) {
4669
4822
  case "log-session": return cmdAthleteLogSession(client, a);
4670
4823
  case "session-remove": return cmdAthleteSessionRemove(client, a);
4671
4824
  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>");
4825
+ case "workout-note": return cmdAthleteWorkoutNote(client, a);
4826
+ case "exercise-note": return cmdAthleteExerciseNote(client, a);
4827
+ 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|exercise-note>");
4673
4828
  }
4674
4829
  }
4675
4830
  async function cmdSkill(rest) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/cli",
3
- "version": "3.3.3",
3
+ "version": "3.5.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.3",
25
- "@trainheroic-unofficial/js": "3.3.3"
24
+ "@trainheroic-unofficial/dto": "3.5.0",
25
+ "@trainheroic-unofficial/js": "3.5.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,25 @@ 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
+ | Add a per-exercise note (gated) | `$TH athlete exercise-note --set-exercise <sweId> --notes "..." --yes` |
73
+ | Remove a stray personal session | `$TH athlete session-remove --id <programWorkoutId> --date Y-M-D --yes` |
72
74
 
73
75
  ## Reading training
74
76
 
@@ -180,15 +182,40 @@ exercise, so swap first, then log against the new movement as usual. Same `--yes
180
182
  the workout with `$TH athlete workouts --start Y-M-D --end Y-M-D` to confirm the slot now shows
181
183
  the replacement.
182
184
 
185
+ ## Session note / RPE
186
+
187
+ `$TH athlete workout-note` writes the free-text note (and optional session RPE) on a workout —
188
+ the box on the workout screen, not the coach's Instructions. It is coach-visible. The `id` is
189
+ the session `id` from `$TH athlete workouts`. Empty `--notes` clears the note; a notes-only
190
+ write leaves RPE untouched and vice versa.
191
+
192
+ ```bash
193
+ $TH athlete workouts --start 2026-06-01 --end 2026-06-01 --summary
194
+ $TH athlete workout-note --date 2026-06-01 --id 149542413 --notes "Hips felt tight." --rpe 8 --yes
195
+ ```
196
+
197
+ ## Per-exercise note
198
+
199
+ `$TH athlete exercise-note` writes the "Add exercise note" field on one exercise — the place
200
+ an athlete records band color, setup cues, or anything the weight field cannot hold. It is
201
+ coach-visible and distinct from the session note. The slot id is `savedWorkoutSetExerciseId`
202
+ from `$TH athlete log-targets`. Empty `--notes` clears the note.
203
+
204
+ ```bash
205
+ $TH athlete log-targets --start 2026-06-01 --end 2026-06-01
206
+ $TH athlete exercise-note --set-exercise 2712369448 --notes "green band" --yes
207
+ ```
208
+
183
209
  ## Gotchas
184
210
 
185
211
  - `profile` must send `use_metric` and `stats` must send `date`, or the API returns 400.
186
212
  The CLI fills `use_metric` (toggle with `--metric`); pass `--date` to `stats`.
187
213
  - Units are **fixed per exercise** and surfaced positionally as `[param 1, param 2]` (e.g.
188
214
  `["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).
215
+ - `log-set`, `workout-note`, and `exercise-note` write to your coach-visible log. Gate them
216
+ behind explicit user confirmation, never run them autonomously, and verify the result.
217
+ `log-set`'s request shape was reverse-engineered from the mobile app (a two-step write:
218
+ log the exercise data, then mark the set completed).
192
219
  - This API is undocumented and can change. `references/athlete-api.md` lists the endpoints
193
220
  and shapes.
194
221
 
@@ -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, notes, 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). Each exercise's `notes` is the per-exercise athlete note (null when 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,26 @@ 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
+
87
+ 4. **Per-exercise note** — `PUT /1.0/athlete/savedworkoutsetexercise/{savedWorkoutSetExerciseId}`
88
+ with `{ id, notes }`. A notes-only body leaves logged reps/weight untouched; empty `notes`
89
+ clears. GET on that path 405s. The range read's saved copy and
90
+ `GET /v5/exercises/{id}/history[].notes` both echo the stored string. Distinct from the
91
+ session note (step 3) and from coach `instruction`. The SDK's `setAthleteExerciseNote` takes
92
+ the slot id from `athlete_log_targets`.
93
+
78
94
  There is no GET for a single saved workout set; read it from the workout range's
79
95
  `saved_workout.workoutSets[]` (`id` = savedWorkoutSetId, `workoutSetExercises[].id` =
80
96
  savedWorkoutSetExerciseId, `workoutSetExercises[].workout_set_exercise_id` = the template id).
@@ -87,8 +103,10 @@ account) expose:
87
103
  - Live reads: `athlete_whoami`, `athlete_profile`, `athlete_prefs`, `athlete_workouts`,
88
104
  `athlete_exercises`, `athlete_exercise_history`, `athlete_personal_records`,
89
105
  `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`).
106
+ - Gated writes include `athlete_log_set` for performed results, `athlete_prescribe_set` for
107
+ planned reps/weight that must not mark a set completed, `athlete_workout_note` for the
108
+ session note / RPE, and `athlete_exercise_note` for the per-exercise note (elicitation or
109
+ `confirm:true`).
92
110
 
93
111
  ## Warehouse tools (hosted worker only, D1-backed)
94
112
 
@@ -108,5 +126,8 @@ startDate?/endDate? }`.
108
126
  Living status table: `.agents/skills/reverse-engineer-api/coverage.md`.
109
127
 
110
128
  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).
129
+ `athlete_recent_exercises`). Closed without a wrap: working-max write (read exists; set/update
130
+ never found). `PUT /1.0/athlete/savedworkout/{id}` is wrapped as the session-note / RPE write
131
+ (`athlete_workout_note`); it is not a set-logging path. `PUT /1.0/athlete/savedworkoutsetexercise/{id}`
132
+ with `{id, notes}` is the per-exercise note write (`athlete_exercise_note`); a notes-only body
133
+ does not wipe logged reps/weight.
@@ -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