@trainheroic-unofficial/cli 3.0.1 → 3.1.1

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/README.md CHANGED
@@ -84,7 +84,7 @@ trainheroic coach workout build --program 988 --date 2026-6-22 --file day.json -
84
84
  validation path on bad input.
85
85
  - Actions that touch an athlete or delete data require an explicit `--yes`:
86
86
  `coach workout publish`, `coach workout remove`, `coach exercise forget`,
87
- `coach message send`, `coach message delete`, `athlete log-set`, and
87
+ `coach message send`, `coach message delete`, `athlete log-set`, `athlete prescribe-set`, and
88
88
  `coach workout build --publish`. (`coach workout build` alone creates a draft; `--publish`
89
89
  makes it visible to athletes, which is why that combination needs `--yes`.)
90
90
  - JSON input can be passed inline, with `--file <path>`, or piped on stdin. Inputs are
package/dist/cli.mjs CHANGED
@@ -211,20 +211,18 @@ const logSetArgsSchema = z.object({
211
211
  */
212
212
  const coachLogSetArgsSchema = logSetArgsSchema.extend({ athleteId: idArgSchema });
213
213
  /**
214
- * Args for the coach prescription-override write. Like {@link coachLogSetArgsSchema}
215
- * (athleteId + date + savedWorkoutSetId + per-exercise `sets`), but the values are prescribed
216
- * targets (param1 = reps, param2 = weight) written to the athlete's plan without marking the set
217
- * performed. The write replaces this athlete's whole prescription for the set, so its sets are
218
- * positional and sequential by definition: it deliberately omits the log path's `slot` field (a
219
- * sparse, slot-targeted prescription has no meaning here) by building its results off
220
- * {@link loggedSetSchema} rather than {@link loggedSetWithSlotSchema}.
214
+ * Args for changing the logged-in athlete's prescribed targets without marking the set performed.
215
+ * The write replaces the exercise's whole prescription, so its sets are positional and sequential
216
+ * by definition: it deliberately omits the log path's `slot` field because a sparse prescription
217
+ * has no meaning here.
221
218
  */
222
- const coachPrescribeSetArgsSchema = z.object({
219
+ const athletePrescribeSetArgsSchema = z.object({
223
220
  date: dateString,
224
221
  savedWorkoutSetId: idArgSchema,
225
- athleteId: idArgSchema,
226
222
  results: prescribedExerciseResultsSchema
227
223
  });
224
+ /** Coach variant of {@link athletePrescribeSetArgsSchema}, with the roster athlete to update. */
225
+ const coachPrescribeSetArgsSchema = athletePrescribeSetArgsSchema.extend({ athleteId: idArgSchema });
228
226
  /**
229
227
  * Args for the coach per-athlete exercise swap: replace the exercise prescribed in one of a
230
228
  * roster athlete's saved-workout slots with a different exercise, the API equivalent of the
@@ -307,6 +305,18 @@ const programWorkoutResponseSchema = z.looseObject({
307
305
  });
308
306
  /** The calendar edit-view response we read sessions back from. */
309
307
  const programsEditResponseSchema = z.looseObject({ programWorkouts: z.array(programWorkoutResponseSchema).optional() });
308
+ /** A standalone program create response (container id + usable calendar/program id). */
309
+ const programCreateResponseSchema = z.looseObject({
310
+ id: intLike,
311
+ title: z.string(),
312
+ programId: intLike,
313
+ group_program: intLike,
314
+ type: intLike,
315
+ program: z.looseObject({
316
+ id: intLike,
317
+ program_type: intLike
318
+ }).optional()
319
+ });
310
320
  //#endregion
311
321
  //#region ../dto/src/workout.ts
312
322
  /** A single exercise prescription inside a block. */
@@ -523,7 +533,7 @@ var TrainHeroicClient = class {
523
533
  session = await this.#ensureSession();
524
534
  res = await this.#send(method, url, session, options.body);
525
535
  }
526
- if (!res.ok) notifyHttpError(this.#onHttpError, method, url, res.status);
536
+ if (!res.ok && !options.expectedStatuses?.includes(res.status)) notifyHttpError(this.#onHttpError, method, url, res.status);
527
537
  const text = await res.text();
528
538
  let data = text;
529
539
  if (text.length > 0) try {
@@ -1662,6 +1672,21 @@ async function logAthleteSet(client, args) {
1662
1672
  };
1663
1673
  }
1664
1674
  /**
1675
+ * Set the logged-in athlete's prescribed reps/weight for one saved workout set WITHOUT marking it
1676
+ * performed. This is the athlete-side equivalent of editing target values in the app: it writes
1677
+ * `param_N_data_M` with every made/completed flag cleared and skips the set-completion PUT.
1678
+ *
1679
+ * The write replaces the selected exercise's whole prescription, so callers must pass every set
1680
+ * they want to keep. An omitted param is cleared rather than preserved.
1681
+ */
1682
+ async function prescribeAthleteSet(client, args) {
1683
+ const r = await writeSetResults(client, { role: "athlete" }, await fetchAthleteWorkouts(client, args.date, args.date), args.savedWorkoutSetId, args.results, "prescribe");
1684
+ return {
1685
+ savedWorkoutSetId: r.savedWorkoutSetId,
1686
+ exercisesPrescribed: r.exercisesWritten
1687
+ };
1688
+ }
1689
+ /**
1665
1690
  * Coach "Log for Athlete": record set results for a roster athlete on their behalf, via the
1666
1691
  * coach surface — `PUT /1.0/coach/savedworkoutsetexercise/{id}/{athleteId}` (the data write)
1667
1692
  * then `PUT /1.0/coach/savedworkoutset/{id}/{athleteId}` (mark complete). Same two-step
@@ -1746,9 +1771,10 @@ async function swapAthleteExercise(client, args) {
1746
1771
  };
1747
1772
  }
1748
1773
  /**
1749
- * Shared set-write behind {@link logAthleteSet}, {@link logForAthlete}, and
1750
- * {@link prescribeForAthlete}. `target` selects the surface: `athlete` writes `/1.0/athlete/...`;
1751
- * `coach` writes `/1.0/coach/...{athleteId}` and stamps `athleteId` into each body.
1774
+ * Shared set-write behind {@link logAthleteSet}, {@link prescribeAthleteSet},
1775
+ * {@link logForAthlete}, and {@link prescribeForAthlete}. `target` selects the surface: `athlete`
1776
+ * writes `/1.0/athlete/...`; `coach` writes `/1.0/coach/...{athleteId}` and stamps `athleteId` into
1777
+ * each body.
1752
1778
  *
1753
1779
  * Step 1 PUTs each exercise's per-set values to its own endpoint (the only path that actually
1754
1780
  * stores reps and weight). `mode` decides what those values mean: `"log"` records them as a
@@ -2558,6 +2584,45 @@ function readExercise(ex) {
2558
2584
  instruction: str(ex.instruction)
2559
2585
  };
2560
2586
  }
2587
+ const PROGRAM_KINDS = ["calendar", "fixed"];
2588
+ /**
2589
+ * Create a standalone ongoing calendar or fixed-length program.
2590
+ *
2591
+ * TrainHeroic returns both a container id and the underlying program id. They are deliberately
2592
+ * named separately here because `/3.0/coach/program/{containerId}` returns 401, while the
2593
+ * `programId` works. This write is not idempotent: callers must not blindly retry an uncertain
2594
+ * result. The live API currently accepts `name` but may generate its own title; `nameApplied`
2595
+ * reports what happened.
2596
+ */
2597
+ async function createProgram(client, args) {
2598
+ if (!PROGRAM_KINDS.includes(args.kind)) throw new Error(`Unknown program kind: ${String(args.kind)}.`);
2599
+ if (typeof args.name !== "string" || args.name.trim() === "") throw new Error("Program name must not be blank.");
2600
+ const requestedName = args.name.trim();
2601
+ const res = await client.request("POST", "/1.0/coach/programs/create", { body: {
2602
+ finite: args.kind === "fixed",
2603
+ name: requestedName
2604
+ } });
2605
+ if (!res.ok) {
2606
+ const detail = typeof res.data === "string" ? res.data : JSON.stringify(res.data);
2607
+ throw new Error(`Program create failed (HTTP ${res.status}): ${detail}`);
2608
+ }
2609
+ checkResponse(programCreateResponseSchema, res.data, "program create");
2610
+ const rec = isRecord(res.data) ? res.data : {};
2611
+ const nested = isRecord(rec.program) ? rec.program : {};
2612
+ const containerId = coerceInt(rec.id);
2613
+ const programId = coerceInt(rec.programId) ?? coerceInt(rec.group_program) ?? coerceInt(nested.id);
2614
+ if (containerId === null || programId === null) throw new Error("Program create response is missing the container id or program id.");
2615
+ if (typeof rec.title !== "string" || rec.title.trim() === "") throw new Error("Program create response is missing the assigned title.");
2616
+ const title = rec.title;
2617
+ return {
2618
+ containerId,
2619
+ programId,
2620
+ title,
2621
+ kind: args.kind,
2622
+ requestedName,
2623
+ nameApplied: title === requestedName
2624
+ };
2625
+ }
2561
2626
  /** Normalize one-or-many emails into a deduped, trimmed list. */
2562
2627
  function emailList(emails) {
2563
2628
  return [...new Set(emails.map((e) => e.trim()).filter((e) => e.length > 0))];
@@ -3472,6 +3537,7 @@ Coach — manage a roster (needs a coach account):
3472
3537
  coach athlete-restore --athletes <id,id,...>
3473
3538
 
3474
3539
  teams & join codes:
3540
+ coach program-create --kind calendar|fixed --name "..."
3475
3541
  coach team-create --title "..."
3476
3542
  coach team-update --team <id> [--title "..."] [--group-program <id>]
3477
3543
  coach team-delete --team <id> --yes
@@ -3522,6 +3588,7 @@ Athlete — the logged-in user's own training (a coach account works too):
3522
3588
  athlete leaderboard <workoutId> [--page N] [--page-size N] [--gender N]
3523
3589
  athlete export [--out dir] [--start Y-M-D] [--end Y-M-D] [--full]
3524
3590
  athlete log-set --date Y-M-D --set <savedWorkoutSetId> <resultsJson>|--file f --yes (logs to a PRESCRIBED workout on that date; ids from 'athlete log-targets'; each set fills the next position, add "slot":K to target the K-th; a partial log records only what you send)
3591
+ athlete prescribe-set --date Y-M-D --set <savedWorkoutSetId> <resultsJson>|--file f --yes (sets your PLANNED reps/weight without logging completion; replaces the selected exercise's whole prescription, so pass every set/value to keep)
3525
3592
  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')
3526
3593
  athlete session-remove --id <programWorkoutId> --date Y-M-D --yes (delete a stray PERSONAL session; the id is the session 'id' from 'athlete workouts')
3527
3594
  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')
@@ -3869,6 +3936,29 @@ async function cmdAthleteLogSet(client, a) {
3869
3936
  results: toSetResults(args.results)
3870
3937
  }));
3871
3938
  }
3939
+ const ATHLETE_PRESCRIBE_SET_USAGE = "athlete prescribe-set --date Y-M-D --set <id> <resultsJson> --yes";
3940
+ async function cmdAthletePrescribeSet(client, a) {
3941
+ const { values, positionals } = parse(a, {
3942
+ date: { type: "string" },
3943
+ set: { type: "string" },
3944
+ file: { type: "string" },
3945
+ yes: { type: "boolean" }
3946
+ });
3947
+ const date = isoDate(need(values.date, ATHLETE_PRESCRIBE_SET_USAGE), "--date");
3948
+ const savedWorkoutSetId = toInt(need(values.set, ATHLETE_PRESCRIBE_SET_USAGE), "--set");
3949
+ const results = await jsonInput(positionals[0], values.file);
3950
+ const args = validate(athletePrescribeSetArgsSchema, {
3951
+ date,
3952
+ savedWorkoutSetId,
3953
+ results
3954
+ }, "athlete prescribe-set args");
3955
+ if (values.yes !== true) fail(`changing the prescribed values for set ${savedWorkoutSetId} requires --yes.`);
3956
+ return out(await prescribeAthleteSet(client, {
3957
+ date: args.date,
3958
+ savedWorkoutSetId,
3959
+ results: toSetResults(args.results)
3960
+ }));
3961
+ }
3872
3962
  const LOG_SESSION_USAGE = "athlete log-session --date Y-M-D <exercisesJson>|--file f --yes";
3873
3963
  /** Map validated logSession exercises to the SDK's SessionExercise[] (ids coerced, slots trimmed). */
3874
3964
  function toSessionExercises(exercises) {
@@ -4053,10 +4143,11 @@ async function cmdAthlete(client, rest) {
4053
4143
  case "export": return cmdAthleteExport(client, a);
4054
4144
  case "log-targets": return cmdAthleteLogTargets(client, a);
4055
4145
  case "log-set": return cmdAthleteLogSet(client, a);
4146
+ case "prescribe-set": return cmdAthletePrescribeSet(client, a);
4056
4147
  case "log-session": return cmdAthleteLogSession(client, a);
4057
4148
  case "session-remove": return cmdAthleteSessionRemove(client, a);
4058
4149
  case "swap-exercise": return cmdAthleteSwapExercise(client, a);
4059
- default: return fail("usage: trainheroic athlete <whoami|profile|prefs|workouts|log-targets|exercises|history|prs|stats|working-maxes|leaderboard|export|log-set|log-session|session-remove|swap-exercise>");
4150
+ default: return fail("usage: trainheroic athlete <whoami|profile|prefs|workouts|log-targets|exercises|history|prs|stats|working-maxes|leaderboard|export|log-set|prescribe-set|log-session|session-remove|swap-exercise>");
4060
4151
  }
4061
4152
  }
4062
4153
  async function cmdSkill(rest) {
@@ -4100,7 +4191,7 @@ async function cmdInstallSkill() {
4100
4191
  }
4101
4192
  out({ installed });
4102
4193
  }
4103
- const COACH_USAGE = "usage: trainheroic coach <head-coach|athletes|programs|teams|notifications|analytics|program <id>|team <id>|team-codes <id>|roster-activity|team-volume|athlete-training|athlete-lift-history|main-lift-prs|athlete-workouts|log-set|log-session|prescribe-set|swap-exercise|athlete-invite|athlete-archive|athlete-restore|team-create|team-update|team-delete|team-code-create|team-code-delete|session-copy|session-unpublish|session-save-template|analytics-query|exercise|workout|message>";
4194
+ const COACH_USAGE = "usage: trainheroic coach <head-coach|athletes|programs|teams|notifications|analytics|program <id>|program-create|team <id>|team-codes <id>|roster-activity|team-volume|athlete-training|athlete-lift-history|main-lift-prs|athlete-workouts|log-set|log-session|prescribe-set|swap-exercise|athlete-invite|athlete-archive|athlete-restore|team-create|team-update|team-delete|team-code-create|team-code-delete|session-copy|session-unpublish|session-save-template|analytics-query|exercise|workout|message>";
4104
4195
  const COACH_LOG_SET_USAGE = "coach log-set --athlete <id> --date Y-M-D --set <savedWorkoutSetId> <resultsJson> --yes";
4105
4196
  async function cmdCoachLogSet(client, a) {
4106
4197
  const { values, positionals } = parse(a, {
@@ -4288,6 +4379,20 @@ async function cmdCoachTeamCreate(client, a) {
4288
4379
  const { values } = parse(a, { title: { type: "string" } });
4289
4380
  return out(await mutate(client, "POST", "/1.0/coach/team/createWithTitleAndCode", { title: need(values.title, "coach team-create --title \"...\"") }));
4290
4381
  }
4382
+ async function cmdCoachProgramCreate(client, a) {
4383
+ const usage = "coach program-create --kind calendar|fixed --name \"...\"";
4384
+ const { values } = parse(a, {
4385
+ kind: { type: "string" },
4386
+ name: { type: "string" }
4387
+ });
4388
+ const kind = need(values.kind, usage);
4389
+ const name = need(values.name, usage);
4390
+ if (!PROGRAM_KINDS.includes(kind)) fail(usage);
4391
+ return out(await createProgram(client, {
4392
+ kind,
4393
+ name
4394
+ }));
4395
+ }
4291
4396
  async function cmdCoachTeamUpdate(client, a) {
4292
4397
  const usage = "coach team-update --team <id> [--title \"...\"] [--group-program <id>] (at least one of --title / --group-program)";
4293
4398
  const { values } = parse(a, {
@@ -4474,6 +4579,7 @@ async function cmdCoach(client, rest) {
4474
4579
  case "athlete-archive": return cmdCoachAthleteArchive(client, a);
4475
4580
  case "athlete-restore": return cmdCoachAthleteRestore(client, a);
4476
4581
  case "team-create": return cmdCoachTeamCreate(client, a);
4582
+ case "program-create": return cmdCoachProgramCreate(client, a);
4477
4583
  case "team-update": return cmdCoachTeamUpdate(client, a);
4478
4584
  case "team-delete": return cmdCoachTeamDelete(client, a);
4479
4585
  case "team-code-create": return cmdCoachTeamCodeCreate(client, a);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/cli",
3
- "version": "3.0.1",
3
+ "version": "3.1.1",
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.0.1",
25
- "@trainheroic-unofficial/js": "3.0.1"
24
+ "@trainheroic-unofficial/dto": "3.1.1",
25
+ "@trainheroic-unofficial/js": "3.1.1"
26
26
  },
27
27
  "devDependencies": {
28
28
  "@types/node": "^26.2.0",
@@ -65,6 +65,7 @@ on a 401/403. Start with `$TH athlete whoami` to confirm auth and get your `id`.
65
65
  | Download all historicals to JSON | `$TH athlete export [--out dir] [--full]` |
66
66
  | Log ids for a scheduled workout | `$TH athlete log-targets --start Y-M-D --end Y-M-D [--program <title>]` |
67
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` |
68
69
  | Log an off-plan session (gated) | `$TH athlete log-session --date Y-M-D '[{"exerciseId":N,"sets":[...]}]' --yes` |
69
70
  | Swap a prescribed exercise (gated) | `$TH athlete swap-exercise --set-exercise <sweId> --exercise <exerciseId> --yes` |
70
71
  | Remove a stray personal session | `$TH athlete session-remove --id <programWorkoutId> --date Y-M-D --yes` |
@@ -131,6 +132,21 @@ $TH athlete log-set --date 2026-06-01 --set 1593305783 --yes \
131
132
  check the result landed as intended. `param1`/`param2` are the entered values by entry slot
132
133
  (check the exercise's positional units first).
133
134
 
135
+ ### Setting planned weight without logging
136
+
137
+ Use `$TH athlete prescribe-set` when you know the target reps or weight but have not performed the
138
+ set. It writes the prescription with every completion flag clear, so the workout remains open and
139
+ nothing is added to exercise history:
140
+
141
+ ```bash
142
+ $TH athlete prescribe-set --date 2026-06-01 --set 1593305783 --yes \
143
+ '[{"savedWorkoutSetExerciseId": 2712369448, "sets": [{"param1": 5, "param2": 225}]}]'
144
+ ```
145
+
146
+ The write replaces that exercise's whole prescription. Include every planned set and every value
147
+ you want to keep; an omitted parameter is cleared. Get both ids from `athlete log-targets`, just as
148
+ for `log-set`.
149
+
134
150
  ### Logging an off-plan session
135
151
 
136
152
  When you trained something a coach never scheduled (accessory work, a makeup lift, an
@@ -87,7 +87,8 @@ account) expose:
87
87
  - Live reads: `athlete_whoami`, `athlete_profile`, `athlete_prefs`, `athlete_workouts`,
88
88
  `athlete_exercises`, `athlete_exercise_history`, `athlete_personal_records`,
89
89
  `athlete_exercise_stats`, `athlete_working_maxes`, `athlete_leaderboard`.
90
- - Gated write: `athlete_log_set` (elicitation or `confirm:true`).
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`).
91
92
 
92
93
  ## Warehouse tools (hosted worker only, D1-backed)
93
94
 
@@ -90,7 +90,7 @@ response shape, or an area not covered here.
90
90
  | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
91
91
  | Athletes | `$TH coach athletes`; `coach athlete-invite\|athlete-archive\|athlete-restore` |
92
92
  | Teams / join codes | `$TH coach teams\|team <id>\|team-codes <id>`; `coach team-create\|team-update\|team-delete\|team-code-create\|team-code-delete` |
93
- | Programs | `$TH coach programs`, `$TH coach program <id>` |
93
+ | Programs | `$TH coach programs`, `$TH coach program <id>`, `$TH coach program-create --kind calendar\|fixed --name "..."` |
94
94
  | Exercises | `$TH coach exercise resolve\|search\|get\|sync\|create\|forget\|stats` (below) |
95
95
  | Sessions / workouts | `$TH coach workout build\|read\|publish\|remove`; `coach session-copy\|session-unpublish\|session-save-template` |
96
96
  | Roster training | `$TH coach roster-activity\|athlete-training\|athlete-lift-history\|athlete-workouts` (read another athlete's training) |
@@ -286,16 +286,17 @@ Deletes an access code. No request body needed.
286
286
 
287
287
  ### Programs
288
288
 
289
- | Method | Endpoint | Description |
290
- | ------ | ------------------------------- | ------------------------------- |
291
- | GET | `/v5/programs` | List programs |
292
- | GET | `/v5/programs/new` | New programs |
293
- | GET | `/v5/programs/free` | Free programs |
294
- | GET | `/v5/programs/fixed` | Fixed programs |
295
- | GET | `/1.0/coach/programs` | Coach programs list |
296
- | GET | `/1.0/coach/programs/edit/{id}` | Program edit data |
297
- | GET | `/3.0/coach/program/{id}` | Program detail (full structure) |
298
- | GET | `/1.0/coach/subscriptions` | Program subscriptions |
289
+ | Method | Endpoint | Description |
290
+ | ------ | ------------------------------- | --------------------------- |
291
+ | GET | `/v5/programs` | List programs |
292
+ | GET | `/v5/programs/new` | New programs |
293
+ | GET | `/v5/programs/free` | Free programs |
294
+ | GET | `/v5/programs/fixed` | Fixed programs |
295
+ | GET | `/1.0/coach/programs` | Coach programs list |
296
+ | POST | `/1.0/coach/programs/create` | Create a standalone program |
297
+ | GET | `/1.0/coach/programs/edit/{id}` | Program edit data |
298
+ | GET | `/3.0/coach/program/{id}` | Program metadata/detail |
299
+ | GET | `/1.0/coach/subscriptions` | Program subscriptions |
299
300
 
300
301
  #### `GET /3.0/coach/program/{id}` Response
301
302
 
@@ -336,6 +337,14 @@ Deletes an access code. No request body needed.
336
337
  ]
337
338
  ```
338
339
 
340
+ #### `POST /1.0/coach/programs/create`
341
+
342
+ Send `{ "finite": false, "name": "..." }` for an ongoing calendar or `finite: true` for a
343
+ fixed-length program. The endpoint is not idempotent. Its response contains two different ids:
344
+ `id` is the container returned by `GET /1.0/coach/programs`, while `programId` (also
345
+ `group_program`) is the actual program id used by `/3.0/coach/program/{id}` and workout writes.
346
+ The live API may ignore `name` and assign a generated title; use the response's `title` as truth.
347
+
339
348
  ---
340
349
 
341
350
  ### Exercises