@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
|
|
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
|
-
|
|
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.
|
|
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.
|
|
25
|
-
"@trainheroic-unofficial/js": "3.
|
|
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 `
|
|
203
|
-
confirmation, never run them autonomously, and verify the result.
|
|
204
|
-
was reverse-engineered from the mobile app (a two-step write:
|
|
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,
|
|
101
|
-
session note / RPE (elicitation or
|
|
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.
|