@trainheroic-unofficial/cli 3.4.0 → 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
@@ -272,6 +272,15 @@ const athleteWorkoutNoteArgsSchema = z.object({
272
272
  notes: z.string().optional(),
273
273
  rpe: z.number().int().min(1).max(10).optional()
274
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
+ });
275
284
  const presentedNullNumber = z.number().nullable();
276
285
  const presentedNullString = z.string().nullable();
277
286
  /** Flattened exercise within a presented workout: prescriptions, logged results, units. */
@@ -279,6 +288,7 @@ const athleteWorkoutExerciseSchema = z.object({
279
288
  exerciseId: presentedNullNumber,
280
289
  title: z.string(),
281
290
  instruction: presentedNullString,
291
+ notes: presentedNullString,
282
292
  units: z.array(presentedNullString),
283
293
  prescribed: z.array(z.string()),
284
294
  performed: z.array(z.string())
@@ -387,6 +397,7 @@ z.array(rosterActivityRowSchema);
387
397
  const presentedExerciseSessionSchema = z.object({
388
398
  date: z.string(),
389
399
  abr: presentedNullString,
400
+ notes: presentedNullString,
390
401
  estimated1RM: presentedNullNumber,
391
402
  sets: z.array(z.object({
392
403
  setNumber: z.number(),
@@ -526,6 +537,7 @@ const logSetTargetOutputSchema = z.object({
526
537
  savedWorkoutSetExerciseId: z.number(),
527
538
  title: z.string(),
528
539
  units: z.array(nullableString),
540
+ notes: nullableString,
529
541
  prescribed: z.array(z.string()),
530
542
  performed: z.array(z.string())
531
543
  }))
@@ -600,6 +612,10 @@ z.object({
600
612
  notes: z.string(),
601
613
  rpe: nullableNumber
602
614
  });
615
+ z.object({
616
+ savedWorkoutSetExerciseId: z.number(),
617
+ notes: z.string()
618
+ });
603
619
  const workoutReadExerciseOutputSchema = z.object({
604
620
  order: z.number(),
605
621
  title: z.string(),
@@ -1407,6 +1423,16 @@ function performedSlotsByExerciseId(sets) {
1407
1423
  }
1408
1424
  return map;
1409
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
+ }
1410
1436
  /** Align an exercise's prescribed slots with the slots the athlete logged, per set index. */
1411
1437
  function mergeExercise(prescribed, performed, meta) {
1412
1438
  const indices = [.../* @__PURE__ */ new Set([...prescribed.keys(), ...performed.keys()])].sort((a, b) => a - b);
@@ -1420,7 +1446,7 @@ function mergeExercise(prescribed, performed, meta) {
1420
1446
  };
1421
1447
  }
1422
1448
  /** A prescription block, each exercise aligned with the slots the athlete logged against it. */
1423
- function mergePrescriptionBlock(set, performedById) {
1449
+ function mergePrescriptionBlock(set, performedById, notesById) {
1424
1450
  const exercises = Array.isArray(set.workoutSetExercises) ? set.workoutSetExercises : [];
1425
1451
  return {
1426
1452
  order: coerceInt(set.order) ?? 0,
@@ -1434,6 +1460,7 @@ function mergePrescriptionBlock(set, performedById) {
1434
1460
  exerciseId: coerceInt(ex.exercise_id),
1435
1461
  title: typeof ex.title === "string" ? ex.title : "",
1436
1462
  instruction: str$1(ex.instruction),
1463
+ notes: id !== null ? notesById.get(id) ?? null : null,
1437
1464
  units: exerciseUnits(ex.param_1_type, ex.param_2_type)
1438
1465
  });
1439
1466
  })
@@ -1450,6 +1477,7 @@ function mergeSavedBlock(set, exercises) {
1450
1477
  exerciseId: coerceInt(ex.exercise_id),
1451
1478
  title: typeof ex.exercise_title === "string" ? ex.exercise_title : "",
1452
1479
  instruction: str$1(ex.instruction),
1480
+ notes: str$1(ex.notes),
1453
1481
  units: exerciseUnits(ex.param_1_type, ex.param_2_type)
1454
1482
  }))
1455
1483
  };
@@ -1468,7 +1496,8 @@ function mergeAthleteWorkout(raw) {
1468
1496
  const prescriptionSets = (Array.isArray(workout.workoutSets) ? workout.workoutSets : []).filter(isRecord);
1469
1497
  const logged = savedSets(saved);
1470
1498
  const performedById = performedSlotsByExerciseId(logged);
1471
- 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);
1472
1501
  const prescribedIds = /* @__PURE__ */ new Set();
1473
1502
  for (const s of prescriptionSets) {
1474
1503
  const exs = Array.isArray(s.workoutSetExercises) ? s.workoutSetExercises : [];
@@ -1514,6 +1543,7 @@ function toStringExercise(ex) {
1514
1543
  exerciseId: ex.exerciseId,
1515
1544
  title: ex.title,
1516
1545
  instruction: ex.instruction,
1546
+ notes: ex.notes,
1517
1547
  units: ex.units,
1518
1548
  prescribed: sideStrings(ex.sets, (s) => s.prescribed),
1519
1549
  performed: sideStrings(ex.sets, (s) => s.performed)
@@ -1673,6 +1703,7 @@ function presentLogTargets(list) {
1673
1703
  savedWorkoutSetExerciseId: id,
1674
1704
  title: exerciseTitle(ex),
1675
1705
  units: exerciseUnits(ex.param_1_type, ex.param_2_type),
1706
+ notes: str$1(ex.notes),
1676
1707
  prescribed: prescribedStrings(ex),
1677
1708
  performed: performedStrings(ex)
1678
1709
  };
@@ -1788,6 +1819,7 @@ function presentExerciseHistory(detail) {
1788
1819
  sessions: (detail.history ?? []).map((h) => ({
1789
1820
  date: h.dateCompleted,
1790
1821
  abr: h.abr ?? null,
1822
+ notes: str$1(h.notes),
1791
1823
  estimated1RM: h.bestEstimated1RM ?? null,
1792
1824
  sets: (h.sets ?? []).map((s) => ({
1793
1825
  setNumber: s.setNumber,
@@ -2551,6 +2583,28 @@ async function setAthleteWorkoutNote(client, args) {
2551
2583
  };
2552
2584
  }
2553
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
2554
2608
  //#region ../js/src/workout-export.ts
2555
2609
  const DEFAULT_FILENAME_BASE = "trainheroic-workout-history";
2556
2610
  /** Pretty-printed JSON of the structured workouts, exactly as `presentAthleteWorkoutsExport` yields. */
@@ -4156,6 +4210,7 @@ Athlete — the logged-in user's own training (a coach account works too):
4156
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')
4157
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')
4158
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)
4159
4214
  JSON is the exercises array: [{"exerciseId":N,"sets":[{"param1":reps,"param2":weight}, ...]}, ...]
4160
4215
  `;
4161
4216
  function out(value) {
@@ -4657,6 +4712,22 @@ async function cmdAthleteWorkoutNote(client, a) {
4657
4712
  if (values.yes !== true) fail(`setting the session note on workout ${args.programWorkoutId} is coach-visible; add --yes.`);
4658
4713
  return out(await setAthleteWorkoutNote(client, args));
4659
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
+ }
4660
4731
  async function cmdAthleteWorkouts(client, a) {
4661
4732
  const { values } = parse(a, {
4662
4733
  start: { type: "string" },
@@ -4752,7 +4823,8 @@ async function cmdAthlete(client, rest) {
4752
4823
  case "session-remove": return cmdAthleteSessionRemove(client, a);
4753
4824
  case "swap-exercise": return cmdAthleteSwapExercise(client, a);
4754
4825
  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>");
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>");
4756
4828
  }
4757
4829
  }
4758
4830
  async function cmdSkill(rest) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/cli",
3
- "version": "3.4.0",
3
+ "version": "3.5.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -21,8 +21,8 @@
21
21
  ],
22
22
  "dependencies": {
23
23
  "zod": "^4.4.3",
24
- "@trainheroic-unofficial/dto": "3.4.0",
25
- "@trainheroic-unofficial/js": "3.4.0"
24
+ "@trainheroic-unofficial/dto": "3.5.0",
25
+ "@trainheroic-unofficial/js": "3.5.0"
26
26
  },
27
27
  "devDependencies": {
28
28
  "@types/node": "^26.3.0",
@@ -69,6 +69,7 @@ on a 401/403. Start with `$TH athlete whoami` to confirm auth and get your `id`.
69
69
  | Log an off-plan session (gated) | `$TH athlete log-session --date Y-M-D '[{"exerciseId":N,"sets":[...]}]' --yes` |
70
70
  | Swap a prescribed exercise (gated) | `$TH athlete swap-exercise --set-exercise <sweId> --exercise <exerciseId> --yes` |
71
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` |
72
73
  | Remove a stray personal session | `$TH athlete session-remove --id <programWorkoutId> --date Y-M-D --yes` |
73
74
 
74
75
  ## Reading training
@@ -193,16 +194,28 @@ $TH athlete workouts --start 2026-06-01 --end 2026-06-01 --summary
193
194
  $TH athlete workout-note --date 2026-06-01 --id 149542413 --notes "Hips felt tight." --rpe 8 --yes
194
195
  ```
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
+
196
209
  ## Gotchas
197
210
 
198
211
  - `profile` must send `use_metric` and `stats` must send `date`, or the API returns 400.
199
212
  The CLI fills `use_metric` (toggle with `--metric`); pass `--date` to `stats`.
200
213
  - Units are **fixed per exercise** and surfaced positionally as `[param 1, param 2]` (e.g.
201
214
  `["reps", "lb"]`). They are not labelled by role: some exercises reverse the slots.
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).
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).
206
219
  - This API is undocumented and can change. `references/athlete-api.md` lists the endpoints
207
220
  and shapes.
208
221
 
@@ -41,9 +41,9 @@ completed workouts in an inclusive window. Each item:
41
41
 
42
42
  The SDK's `presentAthleteWorkout` merges the two copies into `{ id, date, title, program, team,
43
43
  instruction, notes, rpe, logged, blocks: [{ order, title, instruction, isTest, exercises: [{ exerciseId,
44
- title, instruction, units, prescribed, performed }] }] }`. `instruction` is the coach's session
44
+ title, instruction, notes, units, prescribed, performed }] }] }`. `instruction` is the coach's session
45
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
46
+ unset). Each exercise's `notes` is the per-exercise athlete note (null when unset). `performed` holds the per-set values
47
47
  the athlete logged (made-gated; empty when nothing was recorded), `logged` is true when any
48
48
  exercise has `performed` values, and athlete-added/personal work with no prescription is
49
49
  appended as its own blocks. No `--raw` is needed to read logged results.
@@ -84,6 +84,13 @@ param_1_data_N, param_2_data_N (10 slots) }`. This is the only path that actuall
84
84
  calendar summary's duration is separate). The SDK's `setAthleteWorkoutNote` looks the saved id
85
85
  up from `date` + `programWorkoutId` (the range item's top-level `id`).
86
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
+
87
94
  There is no GET for a single saved workout set; read it from the workout range's
88
95
  `saved_workout.workoutSets[]` (`id` = savedWorkoutSetId, `workoutSetExercises[].id` =
89
96
  savedWorkoutSetExerciseId, `workoutSetExercises[].workout_set_exercise_id` = the template id).
@@ -97,8 +104,9 @@ account) expose:
97
104
  `athlete_exercises`, `athlete_exercise_history`, `athlete_personal_records`,
98
105
  `athlete_exercise_stats`, `athlete_working_maxes`, `athlete_leaderboard`.
99
106
  - 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`).
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`).
102
110
 
103
111
  ## Warehouse tools (hosted worker only, D1-backed)
104
112
 
@@ -120,4 +128,6 @@ Living status table: `.agents/skills/reverse-engineer-api/coverage.md`.
120
128
  In-scope athlete reads are wrapped (`athlete_circuits`, `athlete_programming_programs`,
121
129
  `athlete_recent_exercises`). Closed without a wrap: working-max write (read exists; set/update
122
130
  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.
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.