@trainheroic-unofficial/core 3.3.2 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -9,23 +9,23 @@ declare function toId(value: string | number): number;
9
9
  declare const READ: {
10
10
  readonly readOnlyHint: true;
11
11
  readonly destructiveHint: false;
12
- readonly openWorldHint: true;
12
+ readonly openWorldHint: false;
13
13
  };
14
14
  declare const ADDITIVE: {
15
15
  readonly readOnlyHint: false;
16
16
  readonly destructiveHint: false;
17
- readonly openWorldHint: true;
17
+ readonly openWorldHint: false;
18
18
  };
19
19
  declare const SYNC: {
20
20
  readonly readOnlyHint: false;
21
21
  readonly idempotentHint: true;
22
22
  readonly destructiveHint: false;
23
- readonly openWorldHint: true;
23
+ readonly openWorldHint: false;
24
24
  };
25
25
  declare const DESTRUCTIVE: {
26
26
  readonly readOnlyHint: false;
27
27
  readonly destructiveHint: true;
28
- readonly openWorldHint: true;
28
+ readonly openWorldHint: false;
29
29
  };
30
30
  /** Everything a tool handler needs: the authenticated client and the exercise index. */
31
31
  type ToolContext = {
package/dist/index.mjs CHANGED
@@ -1,7 +1,7 @@
1
- import { athleteExerciseCatalogOutputSchema, athleteInviteOutputSchema, athleteMainLiftPrsOutputSchema, athletePrefsSchema, athletePrescribeSetArgsSchema, athleteProfileOutputSchema, athleteSessionRemoveArgsSchema, athleteSessionRemovedOutputSchema, athleteWorkingMaxListSchema, athleteWorkoutsOutputSchema, blockSpecSchema, coachAthleteTrainingOutputSchema, coachLogSessionArgsSchema, coachLogSetArgsSchema, coachPrescribeSetArgsSchema, commentDraftSchema, dateString, exerciseCreateSchema, exerciseCreatedOutputSchema, exerciseDeletedOutputSchema, exerciseForgottenOutputSchema, exerciseGetOutputSchema, exerciseHistoryOutputSchema, exerciseResolveOutputSchema, exerciseStatsSchema, exerciseSwapOutputSchema, exerciseViewSchema, idArgSchema, logSessionArgsSchema, logSetArgsSchema, logTargetsOutputSchema, messageDeletedOutputSchema, messageDraftOutputSchema, messageSentOutputSchema, opaqueOutputSchema, parseWorkoutDate, personalRecordListSchema, personalWorkoutCreatedOutputSchema, programCreatedOutputSchema, programDeletedOutputSchema, removedSessionOutputSchema, rosterActivityOutputSchema, sessionLogOutputSchema, sessionTemplateCreateSchema, sessionTemplateCreatedOutputSchema, setLogOutputSchema, setPrescriptionOutputSchema, swapAthleteExerciseArgsSchema, teamPublishPatchObject, teamPublishPatchSchema, teamVolumeOutputSchema, toolOutputSchema, userSimpleSchema, workoutBuildOutputSchema, workoutPublishOutputSchema, workoutReadOutputSchema } from "@trainheroic-unofficial/dto";
1
+ import { athleteExerciseCatalogOutputSchema, athleteInviteOutputSchema, athleteMainLiftPrsOutputSchema, athletePrefsSchema, athletePrescribeSetArgsSchema, athleteProfileOutputSchema, athleteSessionRemoveArgsSchema, athleteSessionRemovedOutputSchema, athleteWorkingMaxListSchema, athleteWorkoutNoteArgsSchema, athleteWorkoutNoteObject, athleteWorkoutNoteOutputSchema, athleteWorkoutsOutputSchema, blockSpecSchema, coachAthleteTrainingOutputSchema, coachLogSessionArgsSchema, coachLogSetArgsSchema, coachPrescribeSetArgsSchema, commentDraftSchema, dateString, exerciseCreateSchema, exerciseCreatedOutputSchema, exerciseDeletedOutputSchema, exerciseForgottenOutputSchema, exerciseGetOutputSchema, exerciseHistoryOutputSchema, exerciseResolveOutputSchema, exerciseStatsSchema, exerciseSwapOutputSchema, exerciseViewSchema, idArgSchema, logSessionArgsSchema, logSetArgsSchema, logTargetsOutputSchema, messageDeletedOutputSchema, messageDraftOutputSchema, messageSentOutputSchema, opaqueOutputSchema, parseWorkoutDate, personalRecordListSchema, personalWorkoutCreatedOutputSchema, programCreatedOutputSchema, programDeletedOutputSchema, removedSessionOutputSchema, rosterActivityOutputSchema, sessionLogOutputSchema, sessionTemplateCreateSchema, sessionTemplateCreatedOutputSchema, setLogOutputSchema, setPrescriptionOutputSchema, swapAthleteExerciseArgsSchema, teamPublishPatchObject, teamPublishPatchSchema, teamVolumeOutputSchema, toolOutputSchema, userSimpleSchema, workoutBuildOutputSchema, workoutPublishOutputSchema, workoutReadOutputSchema } from "@trainheroic-unofficial/dto";
2
2
  import { acceptedContent, inputRequired, inputResponse } from "@modelcontextprotocol/server";
3
3
  import { z } from "zod";
4
- import { ANALYTICS_METRIC_KEYS, PROGRAM_KINDS, SESSION_TEMPLATES_LIST_PATH, addExercisesToWorkout, buildCommentPayload, buildSession, coerceInt, collectAdvisories, copySession, createPersonalWorkout, createProgram, createSessionTemplate, definedProps, deleteComment, deleteProgram, exerciseUnits, fetchAthleteCircuits, fetchAthleteMainLiftPRs, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteProgrammingPrograms, fetchAthleteUser, fetchAthleteWorkouts, fetchCoachAthleteCalendarSummary, fetchCoachAthleteWorkouts, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchRecentExercises, fetchRosterActivity, fetchRosterMainLiftPRs, fetchStreams, fetchTeamAthleteIds, fetchWorkingMaxes, inviteAthletes, isRecord, logAdHocSession, logAthleteSet, logForAthlete, logSessionForAthlete, prescribeAthleteSet, prescribeForAthlete, presentAthleteWorkouts, presentCoachAthleteTraining, presentExerciseHistory, presentLogTargets, publishSession, queryAnalytics, readLive, readSession, removePersonalWorkout, removeSession, resolveBuildProgramId, searchExerciseHistory, selectWorkouts, selectWorkoutsByProgram, sendComment, summarizeAthleteWorkouts, swapAthleteExercise, teamPublishTarget, teamVolume, toSetResults, updateTeam, updateTeamPublishSettings } from "@trainheroic-unofficial/js";
4
+ import { ANALYTICS_METRIC_KEYS, PROGRAM_KINDS, SESSION_TEMPLATES_LIST_PATH, addExercisesToWorkout, buildCommentPayload, buildSession, coerceInt, collectAdvisories, copySession, createPersonalWorkout, createProgram, createSessionTemplate, definedProps, deleteComment, deleteProgram, exerciseUnits, fetchAthleteCircuits, fetchAthleteMainLiftPRs, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteProgrammingPrograms, fetchAthleteUser, fetchAthleteWorkouts, fetchCoachAthleteCalendarSummary, fetchCoachAthleteWorkouts, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchRecentExercises, fetchRosterActivity, fetchRosterMainLiftPRs, fetchStreams, fetchTeamAthleteIds, fetchWorkingMaxes, inviteAthletes, isRecord, logAdHocSession, logAthleteSet, logForAthlete, logSessionForAthlete, prescribeAthleteSet, prescribeForAthlete, presentAthleteWorkouts, presentCoachAthleteTraining, presentExerciseHistory, presentLogTargets, publishSession, queryAnalytics, readLive, readSession, removePersonalWorkout, removeSession, resolveBuildProgramId, searchExerciseHistory, selectWorkouts, selectWorkoutsByProgram, sendComment, setAthleteWorkoutNote, summarizeAthleteWorkouts, swapAthleteExercise, teamPublishTarget, teamVolume, toSetResults, updateTeam, updateTeamPublishSettings } from "@trainheroic-unofficial/js";
5
5
  //#region src/context.ts
6
6
  /** A tool argument that accepts a numeric id as a number or a string of digits. */
7
7
  const idParam = idArgSchema;
@@ -11,23 +11,23 @@ function toId(value) {
11
11
  const READ = {
12
12
  readOnlyHint: true,
13
13
  destructiveHint: false,
14
- openWorldHint: true
14
+ openWorldHint: false
15
15
  };
16
16
  const ADDITIVE = {
17
17
  readOnlyHint: false,
18
18
  destructiveHint: false,
19
- openWorldHint: true
19
+ openWorldHint: false
20
20
  };
21
21
  const SYNC = {
22
22
  readOnlyHint: false,
23
23
  idempotentHint: true,
24
24
  destructiveHint: false,
25
- openWorldHint: true
25
+ openWorldHint: false
26
26
  };
27
27
  const DESTRUCTIVE = {
28
28
  readOnlyHint: false,
29
29
  destructiveHint: true,
30
- openWorldHint: true
30
+ openWorldHint: false
31
31
  };
32
32
  /**
33
33
  * Run a tool body, converting thrown errors into an in-band tool error. Generic so a caller that
@@ -628,7 +628,7 @@ function registerProfileTools(server, ctx, whoami, userId) {
628
628
  return jsonResult(await fetchLeaderboard(ctx.client, toId(workoutId), opts));
629
629
  }));
630
630
  }
631
- const ATHLETE_WORKOUTS_DESC = "Workouts on the AUTHENTICATED user's own athlete calendar in an inclusive YYYY-MM-DD window, flattened to blocks/exercises. When a coach account calls this, it returns the coach's own training schedule — not a roster athlete's. To inspect a roster athlete use athlete_saved_workouts (or athlete_training for a month overview); to verify a coach-published team session from the calendar side use workout_read. Each exercise carries both its `prescribed` sets (what the program called for) and `performed` sets (what the athlete actually logged); each workout has a top-level `logged` flag. Use `performed`/`logged` to tell what was recorded or done. That is the reliable signal: a session can hold logged sets while the API's own completion flags stay 0, and an empty `performed` means nothing was logged for that exercise. For 'did I record anything / what did I do', set loggedOnly:true to return only sessions with logged sets (it keeps whole sessions that have any logged set, so individual exercises inside can still show empty `performed`; it also shrinks a large result); limit returns the most recent N workouts (newest first). For a high-level overview ('what's on my schedule this week', 'what have I been training lately') set summary:true to get one compact row per session (date, program, title, logged flag, and exerciseCount/performedCount — read performedCount against exerciseCount, e.g. 1 of 12 logged) instead of every set — a multi-program week of full detail is large, so prefer summary first, then re-query a single day without it to drill into that day's sets. For 'what's my next workout', query a forward window from today; if it comes back empty, the most recent session is likely yesterday's still-unlogged one, so widen the window backward a day or two. Both filters apply to the presented view, not raw. raw:true returns the untouched API objects. This is a date-windowed fetch, NOT an aggregate: for lifetime totals (all-time session count, total volume, first/last logged date) call athlete_profile instead of summing windows — a multi-year range here can time out. Narrow the window if the result is truncated.";
631
+ const ATHLETE_WORKOUTS_DESC = "Workouts on the AUTHENTICATED user's own athlete calendar in an inclusive YYYY-MM-DD window, flattened to blocks/exercises. When a coach account calls this, it returns the coach's own training schedule — not a roster athlete's. To inspect a roster athlete use athlete_saved_workouts (or athlete_training for a month overview); to verify a coach-published team session from the calendar side use workout_read. Each exercise carries both its `prescribed` sets (what the program called for) and `performed` sets (what the athlete actually logged); each workout has a top-level `logged` flag. Session `notes` and `rpe` are the athlete's own note/RPE on that workout (null when unset), distinct from coach `instruction`. Use `performed`/`logged` to tell what was recorded or done. That is the reliable signal: a session can hold logged sets while the API's own completion flags stay 0, and an empty `performed` means nothing was logged for that exercise. For 'did I record anything / what did I do', set loggedOnly:true to return only sessions with logged sets (it keeps whole sessions that have any logged set, so individual exercises inside can still show empty `performed`; it also shrinks a large result); limit returns the most recent N workouts (newest first). For a high-level overview ('what's on my schedule this week', 'what have I been training lately') set summary:true to get one compact row per session (date, program, title, logged flag, and exerciseCount/performedCount — read performedCount against exerciseCount, e.g. 1 of 12 logged) instead of every set — a multi-program week of full detail is large, so prefer summary first, then re-query a single day without it to drill into that day's sets. For 'what's my next workout', query a forward window from today; if it comes back empty, the most recent session is likely yesterday's still-unlogged one, so widen the window backward a day or two. Both filters apply to the presented view, not raw. raw:true returns the untouched API objects. This is a date-windowed fetch, NOT an aggregate: for lifetime totals (all-time session count, total volume, first/last logged date) call athlete_profile instead of summing windows — a multi-year range here can time out. Narrow the window if the result is truncated.";
632
632
  const ATHLETE_LOG_TARGETS_DESC = "The savedWorkoutSetId + savedWorkoutSetExerciseId that athlete_log_set needs, read straight off your scheduled/logged workouts in an inclusive YYYY-MM-DD window — no raw needed. This is the self-service path for logging into a COACH-SCHEDULED workout: read the ids here, then pass them to athlete_log_set. The default view is COMPACT: one row per saved set, each carrying its program/programId, the savedWorkoutSetId, and every exercise's savedWorkoutSetExerciseId with prescribed/performed values. When several workouts fall on the same day (you're on more than one program), narrow to one with program (a case-insensitive title substring, e.g. 'bodybuilding' — no id lookup needed), or programId/teamId if you have the id. raw:true returns the untouched API objects, but that blob is large and can be truncated when several workouts share a date — prefer the program filter + the default view. For reading what you actually did (not the log ids), use athlete_workouts.";
633
633
  const ATHLETE_EXERCISE_HISTORY_DESC = "Per-exercise PRs and the dated session time-series (sets performed, estimated 1RM). The returned `sessions` run all-time, newest first; pass since/until (YYYY-MM-DD, inclusive) to keep only sessions in that window — use it for 'last 3 months' / 'this year' questions so the result stays small. estimated1RM is a formula off the session's best set and reads high when a session mixes a heavy single with high-rep backdown work, so treat it as approximate, not a logged single. `liftPRs` are always all-time and ignore since/until, but each carries the date it was set, so filter those dates yourself to answer 'PRs set this year'. Set raw:true for the untouched API object. Get the exercise id from athlete_exercises.";
634
634
  const ATHLETE_EXERCISES_DESC = "The exercises the athlete has logged (id + title + positional units). Call with no arguments to get the athlete's complete catalog, which often runs to several hundred entries; leave limit off when you want the whole list, since a no-q call returns everything by default. Pass q to free-text search by name (returns the top ranked matches, capped by limit, default 20). Use a returned id with athlete_exercise_history, athlete_personal_records, or athlete_exercise_stats (all of which require an exercise id). If a no-q result comes back wrapped with a __truncated marker, you passed a limit smaller than the catalog and are seeing a partial list; re-call without limit for all of it. A common name returns several variants (e.g. plain 'Bench Press' id 1162 vs 'BARBELL BENCH PRESS'); each variant keeps its own separate history and PR board, so prefer the plain canonical entry, and if a PR or trend looks incomplete, the work may be split across variants, so check the others.";
@@ -801,6 +801,29 @@ function registerSessionTools(server, ctx) {
801
801
  });
802
802
  }));
803
803
  }
804
+ /** Set the athlete's session note / RPE on a saved workout (coach-visible). */
805
+ function registerWorkoutNoteTool(server, ctx) {
806
+ server.registerTool("athlete_workout_note", {
807
+ title: "Set your session note or RPE",
808
+ description: "Athlete-facing write: set the free-text note (and/or session RPE 1–10) on a workout. This is the note box on the workout screen, not the coach's Instructions. programWorkoutId is the `id` from athlete_workouts for that date. Pass notes (empty string clears) and/or rpe; a notes-only write leaves rpe untouched and vice versa. Visible to your coach. Requires confirmation (elicitation or confirm:true).",
809
+ inputSchema: {
810
+ ...athleteWorkoutNoteObject.shape,
811
+ confirm: z.boolean().optional()
812
+ },
813
+ outputSchema: toolOutputSchema(athleteWorkoutNoteOutputSchema),
814
+ annotations: DESTRUCTIVE
815
+ }, ({ date, programWorkoutId, notes, rpe, confirm }, extra) => attempt(async () => {
816
+ const patch = athleteWorkoutNoteArgsSchema.parse(definedProps({
817
+ date,
818
+ programWorkoutId,
819
+ notes,
820
+ rpe
821
+ }));
822
+ const blocked = confirmGate(extra, `Set the session note on workout ${toId(patch.programWorkoutId)} on ${patch.date}? This is visible to your coach.`, confirm);
823
+ if (blocked) return blocked;
824
+ return jsonResult(await setAthleteWorkoutNote(ctx.client, patch));
825
+ }));
826
+ }
804
827
  /** Map validated logSession exercises to the SDK's SessionExercise[] (ids coerced, slots trimmed). */
805
828
  function mapSessionExercises(exercises) {
806
829
  return exercises.map((e) => {
@@ -952,6 +975,7 @@ function registerAthleteTrainingTools(server, ctx) {
952
975
  registerCatalogReads(server, ctx);
953
976
  registerLogTargetsTool(server, ctx);
954
977
  registerSessionTools(server, ctx);
978
+ registerWorkoutNoteTool(server, ctx);
955
979
  registerLogTool(server, ctx);
956
980
  registerSwapTool(server, ctx);
957
981
  }
@@ -979,7 +1003,10 @@ function registerAthleteTools(server, ctx) {
979
1003
  confirm: z.boolean().optional()
980
1004
  },
981
1005
  outputSchema: toolOutputSchema(athleteInviteOutputSchema),
982
- annotations: DESTRUCTIVE
1006
+ annotations: {
1007
+ ...DESTRUCTIVE,
1008
+ openWorldHint: true
1009
+ }
983
1010
  }, ({ teamId, emails, message, confirm }, extra) => attempt(async () => {
984
1011
  const list = asEmailList(emails);
985
1012
  if (list.length === 0) return errorResult("Provide at least one email address to invite.");
@@ -1020,7 +1047,7 @@ function registerAthleteTools(server, ctx) {
1020
1047
  readOnlyHint: false,
1021
1048
  idempotentHint: true,
1022
1049
  destructiveHint: false,
1023
- openWorldHint: true
1050
+ openWorldHint: false
1024
1051
  }
1025
1052
  }, ({ athleteIds }) => apiCall(ctx, "PUT", "/v5/athletes/restore", { body: { athleteIds: athleteIds.map(toId) } }));
1026
1053
  registerAthleteLogTools(server, ctx);
@@ -1667,7 +1694,10 @@ function registerWrites(server, ctx) {
1667
1694
  confirm: z.boolean().optional()
1668
1695
  },
1669
1696
  outputSchema: toolOutputSchema(messageSentOutputSchema),
1670
- annotations: DESTRUCTIVE
1697
+ annotations: {
1698
+ ...DESTRUCTIVE,
1699
+ openWorldHint: true
1700
+ }
1671
1701
  }, ({ streamId, text, replyTo, confirm }, extra) => attempt(async () => {
1672
1702
  const id = toId(streamId);
1673
1703
  const blocked = confirmGate(extra, `Send this message to stream ${id}? It is athlete-facing and immediate.`, confirm);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/core",
3
- "version": "3.3.2",
3
+ "version": "3.4.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -25,14 +25,14 @@
25
25
  "@cfworker/json-schema": "^4.1.1",
26
26
  "@modelcontextprotocol/server": "2.0.0",
27
27
  "zod": "^4.4.3",
28
- "@trainheroic-unofficial/dto": "3.3.2",
29
- "@trainheroic-unofficial/js": "3.3.2"
28
+ "@trainheroic-unofficial/dto": "3.4.0",
29
+ "@trainheroic-unofficial/js": "3.4.0"
30
30
  },
31
31
  "devDependencies": {
32
- "@types/node": "^26.2.0",
32
+ "@types/node": "^26.3.0",
33
33
  "tsdown": "^0.22.14",
34
34
  "typescript": "^7.0.2",
35
- "vitest": "^4.1.10"
35
+ "vitest": "^4.1.11"
36
36
  },
37
37
  "scripts": {
38
38
  "build": "tsdown",