@trainheroic-unofficial/core 0.6.4 → 0.6.5

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.
Files changed (2) hide show
  1. package/dist/index.mjs +76 -148
  2. package/package.json +3 -3
package/dist/index.mjs CHANGED
@@ -1,6 +1,6 @@
1
- import { blockSpecSchema, commentDraftSchema, dateString, exerciseCreateSchema, idArgSchema, logSetArgsSchema, parseWorkoutDate } from "@trainheroic-unofficial/dto";
1
+ import { blockSpecSchema, coachLogSetArgsSchema, commentDraftSchema, dateString, exerciseCreateSchema, idArgSchema, logSetArgsSchema, parseWorkoutDate } from "@trainheroic-unofficial/dto";
2
2
  import { z } from "zod";
3
- import { addExercisesToWorkout, buildCommentPayload, buildSession, coerceInt, collectAdvisories, createPersonalWorkout, deleteComment, exerciseUnits, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteUser, fetchAthleteWorkouts, fetchCoachAthleteCalendarSummary, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchRosterActivity, fetchStreams, fetchWorkingMaxes, isRecord, logAthleteSet, presentAthleteWorkouts, presentCoachAthleteTraining, presentExerciseHistory, publishSession, readLive, readSession, removeSession, searchExerciseHistory, selectWorkouts, sendComment, summarizeAthleteWorkouts } from "@trainheroic-unofficial/js";
3
+ import { ANALYTICS_METRIC_KEYS, addExercisesToWorkout, buildCommentPayload, buildSession, coerceInt, collectAdvisories, copySession, createPersonalWorkout, definedProps, deleteComment, exerciseUnits, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteUser, fetchAthleteWorkouts, fetchCoachAthleteCalendarSummary, fetchCoachAthleteWorkouts, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchRosterActivity, fetchStreams, fetchWorkingMaxes, inviteAthletes, isRecord, logAthleteSet, logForAthlete, presentAthleteWorkouts, presentCoachAthleteTraining, presentExerciseHistory, publishSession, queryAnalytics, readLive, readSession, removeSession, searchExerciseHistory, selectWorkouts, sendComment, summarizeAthleteWorkouts } from "@trainheroic-unofficial/js";
4
4
  //#region src/context.ts
5
5
  /** A tool argument that accepts a numeric id as a number or a string of digits. */
6
6
  const idParam = idArgSchema;
@@ -602,7 +602,6 @@ function registerAthleteTrainingTools(server, ctx) {
602
602
  }
603
603
  //#endregion
604
604
  //#region src/tools/athletes.ts
605
- const DEFAULT_INVITE_MESSAGE = "Follow these steps and you'll be set up and ready to go!";
606
605
  /** Normalize one-or-many emails into a deduped, trimmed list. */
607
606
  function asEmailList(emails) {
608
607
  return [...new Set((Array.isArray(emails) ? emails : [emails]).map((e) => e.trim()).filter((e) => e.length > 0))];
@@ -630,28 +629,14 @@ function registerAthleteTools(server, ctx) {
630
629
  if (list.length === 0) return errorResult("Provide at least one email address to invite.");
631
630
  const id = toId(teamId);
632
631
  if (!await confirmGate(server, extra.requestId, `Invite ${list.join(", ")} to team ${id}? This emails them a real TrainHeroic invitation.`, confirm)) return errorResult(NOT_CONFIRMED);
633
- const validation = await ctx.client.request("POST", "/v5/emails/validate", { body: { emails: list.join(",") } });
634
- if (!validation.ok) {
635
- const detail = typeof validation.data === "string" ? validation.data : JSON.stringify(validation.data);
636
- return errorResult(`Email validation failed (HTTP ${validation.status}): ${detail}`);
637
- }
638
- const valid = Array.isArray(validation.data) ? validation.data : list;
639
- if (valid.length === 0) return errorResult(`No valid addresses among: ${list.join(", ")}. They may be malformed or already on the team.`);
640
- const invite = await ctx.client.request("POST", "/v5/athletes/inviteToTeam", { body: {
641
- teamType: 0,
642
- teamId: id,
643
- orgId: null,
644
- emails: valid,
645
- message: message ?? DEFAULT_INVITE_MESSAGE
646
- } });
647
- if (!invite.ok) {
648
- const detail = typeof invite.data === "string" ? invite.data : JSON.stringify(invite.data);
649
- return errorResult(`Invite failed (HTTP ${invite.status}): ${detail}`);
650
- }
651
632
  return jsonResult({
652
633
  invited: true,
653
634
  teamId: id,
654
- result: invite.data
635
+ result: (await inviteAthletes(ctx.client, definedProps({
636
+ teamId: id,
637
+ emails: list,
638
+ message
639
+ }))).result
655
640
  });
656
641
  }));
657
642
  server.registerTool("athlete_archive", {
@@ -678,6 +663,57 @@ function registerAthleteTools(server, ctx) {
678
663
  openWorldHint: true
679
664
  }
680
665
  }, ({ athleteIds }) => apiCall(ctx, "PUT", "/v5/athletes/restore", { body: { athleteIds: athleteIds.map(toId) } }));
666
+ registerAthleteLogTools(server, ctx);
667
+ }
668
+ /**
669
+ * Coach "Log for Athlete": read a roster athlete's saved workouts (to get the log ids), then
670
+ * record set results on their behalf. The write is the API equivalent of the app's mobile
671
+ * "Log for Athlete" flow. Kept in its own function so registerAthleteTools stays under the
672
+ * oxlint max-lines-per-function cap.
673
+ */
674
+ function registerAthleteLogTools(server, ctx) {
675
+ server.registerTool("athlete_saved_workouts", {
676
+ title: "Roster athlete's saved workouts (with log ids)",
677
+ description: "A roster athlete's scheduled/logged workouts in an inclusive YYYY-MM-DD window — the coach-side view that carries the savedWorkoutSetId and savedWorkoutSetExerciseId that log_athlete_set needs. Get athleteId from list_athletes. Defaults to a presented view; set raw:true for the untouched API objects that expose those ids (each set's id is the savedWorkoutSetId; each savedWorkoutSetExercises[].id is the savedWorkoutSetExerciseId). athlete_training gives a whole-month overview but not these ids.",
678
+ inputSchema: {
679
+ athleteId: idParam,
680
+ startDate: dateString,
681
+ endDate: dateString,
682
+ raw: z.boolean().optional()
683
+ },
684
+ annotations: READ
685
+ }, ({ athleteId, startDate, endDate, raw }) => attempt(async () => {
686
+ const workouts = await fetchCoachAthleteWorkouts(ctx.client, toId(athleteId), startDate, endDate);
687
+ if (raw === true) return jsonResult(workouts, { hint: "Each set's id is the savedWorkoutSetId; each savedWorkoutSetExercises[].id is the savedWorkoutSetExerciseId. Pass both to log_athlete_set. Narrow the dates to shrink this." });
688
+ return jsonResult(presentAthleteWorkouts(workouts), { hint: "Set raw:true to get savedWorkoutSetId + savedWorkoutSetExerciseId for log_athlete_set." });
689
+ }));
690
+ server.registerTool("log_athlete_set", {
691
+ title: "Log set results for a roster athlete",
692
+ description: "Coach-facing write: record entered results (reps/weight per set) for one of a roster athlete's saved workout sets on a given day, marking the set completed — the API equivalent of the app's \"Log for Athlete\". Writes to that athlete's training log and shows in their history. Get athleteId from list_athletes; get savedWorkoutSetId + savedWorkoutSetExerciseId from athlete_saved_workouts (raw:true) for that athlete/day. Seeded demo athletes are read-only and will fail; use a real (invited) athlete. Requires confirmation (elicitation or confirm:true).",
693
+ inputSchema: {
694
+ ...coachLogSetArgsSchema.shape,
695
+ confirm: z.boolean().optional()
696
+ },
697
+ annotations: DESTRUCTIVE
698
+ }, ({ athleteId, date, savedWorkoutSetId, results, confirm }, extra) => attempt(async () => {
699
+ const aId = toId(athleteId);
700
+ if (!await confirmGate(server, extra.requestId, `Log results to athlete ${aId}'s saved workout set ${toId(savedWorkoutSetId)} on ${date}? This writes to their coach-visible training log.`, confirm)) return errorResult(NOT_CONFIRMED);
701
+ const mapped = results.map((r) => ({
702
+ savedWorkoutSetExerciseId: toId(r.savedWorkoutSetExerciseId),
703
+ sets: r.sets.map((s) => {
704
+ const slot = {};
705
+ if (s.param1 !== void 0) slot.param1 = s.param1;
706
+ if (s.param2 !== void 0) slot.param2 = s.param2;
707
+ return slot;
708
+ })
709
+ }));
710
+ return jsonResult(await logForAthlete(ctx.client, {
711
+ athleteId: aId,
712
+ date,
713
+ savedWorkoutSetId: toId(savedWorkoutSetId),
714
+ results: mapped
715
+ }));
716
+ }));
681
717
  }
682
718
  //#endregion
683
719
  //#region src/tools/teams.ts
@@ -744,95 +780,14 @@ function registerTeamTools(server, ctx) {
744
780
  }
745
781
  //#endregion
746
782
  //#region src/tools/analytics.ts
747
- const METRIC_KEYS = [
748
- "readiness-team",
749
- "readiness-athlete",
750
- "lift-1rm-history",
751
- "training-summary-athlete",
752
- "compliance-team",
753
- "lift-progress-team",
754
- "working-max-history"
755
- ];
756
- const METRICS = {
757
- "readiness-team": {
758
- path: "/v5/analytics/readiness/teams",
759
- scope: "team",
760
- inputs: ["date"],
761
- requires: ["date"]
762
- },
763
- "readiness-athlete": {
764
- path: "/v5/analytics/readiness/users",
765
- scope: "user",
766
- inputs: ["dateStart", "dateEnd"],
767
- requires: ["dateStart", "dateEnd"]
768
- },
769
- "lift-1rm-history": {
770
- path: "/v5/analytics/lift-one-rep-max-history/users",
771
- scope: "user",
772
- inputs: [
773
- "dateStart",
774
- "dateEnd",
775
- "exerciseId",
776
- "useMetric"
777
- ],
778
- requires: [
779
- "dateStart",
780
- "dateEnd",
781
- "exerciseId"
782
- ]
783
- },
784
- "training-summary-athlete": {
785
- path: "/v5/analytics/training-summary/users",
786
- scope: "user",
787
- inputs: ["dateStart", "dateEnd"],
788
- requires: ["dateStart", "dateEnd"]
789
- },
790
- "compliance-team": {
791
- path: "/v5/analytics/compliance",
792
- scope: "team",
793
- inputs: ["dateStart", "dateEnd"],
794
- requires: ["dateStart", "dateEnd"]
795
- },
796
- "lift-progress-team": {
797
- path: "/v5/analytics/lift-progress/teams",
798
- scope: "team",
799
- inputs: [
800
- "exerciseId",
801
- "dateStart",
802
- "dateEnd"
803
- ],
804
- requires: [
805
- "exerciseId",
806
- "dateStart",
807
- "dateEnd"
808
- ]
809
- },
810
- "working-max-history": {
811
- path: "/v5/analytics/working-max-history/users",
812
- scope: "user",
813
- inputs: [
814
- "exerciseId",
815
- "dateStart",
816
- "dateEnd",
817
- "useMetric"
818
- ],
819
- requires: ["exerciseId"]
820
- }
821
- };
822
- const BODY_KEY = {
823
- date: "date",
824
- dateStart: "date_start",
825
- dateEnd: "date_end",
826
- exerciseId: "exercise_id",
827
- useMetric: "use_metric"
828
- };
783
+ const ANALYTICS_QUERY_DESC = "Read a TrainHeroic analytics report. The `metric` enum below IS the catalog — pick from it directly (analytics_categories lists the API's raw category names, which do NOT match these keys; you rarely need it). Team metrics (readiness-team, compliance-team, lift-progress-team) need teamId; athlete metrics (readiness-athlete, training-summary-athlete, lift-1rm-history, working-max-history) need userIds — get those from list_athletes. userIds takes MANY athletes in ONE call (pass the whole roster's ids at once); the report comes back with a row per athlete, so do not loop one id per call. For team-wide training volume there is no team summary metric: pass every athlete's userId to training-summary-athlete in a single call and the rows cover the team. An athlete with no logged sessions in range simply returns no rows (not an error). Use that for triage: training-summary-athlete with a single athleteId is the fastest 'has this athlete trained at all, and when' check — no rows means no logged training in range, so don't then fan out blind per-lift athlete_lift_history calls. Despite 'athlete' in the name this metric accepts 1–N userIds. readiness-team takes a single `date`; every other metric takes dateStart/dateEnd. lift-1rm-history, lift-progress-team, and working-max-history also need exerciseId. All dates are YYYY-MM-DD.";
829
784
  /** Analytics report pulls. Read-only despite the POST verb, so ungated. */
830
785
  function registerAnalyticsTools(server, ctx) {
831
786
  server.registerTool("analytics_query", {
832
787
  title: "Pull an analytics report",
833
- description: "Read a TrainHeroic analytics report. The `metric` enum below IS the catalog — pick from it directly (analytics_categories lists the API's raw category names, which do NOT match these keys; you rarely need it). Team metrics (readiness-team, compliance-team, lift-progress-team) need teamId; athlete metrics (readiness-athlete, training-summary-athlete, lift-1rm-history, working-max-history) need userIds — get those from list_athletes. userIds takes MANY athletes in ONE call (pass the whole roster's ids at once); the report comes back with a row per athlete, so do not loop one id per call. For team-wide training volume there is no team summary metric: pass every athlete's userId to training-summary-athlete in a single call and the rows cover the team. An athlete with no logged sessions in range simply returns no rows (not an error). Use that for triage: training-summary-athlete with a single athleteId is the fastest 'has this athlete trained at all, and when' check — no rows means no logged training in range, so don't then fan out blind per-lift athlete_lift_history calls. Despite 'athlete' in the name this metric accepts 1–N userIds. readiness-team takes a single `date`; every other metric takes dateStart/dateEnd. lift-1rm-history, lift-progress-team, and working-max-history also need exerciseId. All dates are YYYY-MM-DD.",
788
+ description: ANALYTICS_QUERY_DESC,
834
789
  inputSchema: {
835
- metric: z.enum(METRIC_KEYS),
790
+ metric: z.enum(ANALYTICS_METRIC_KEYS),
836
791
  teamId: idParam.optional(),
837
792
  userIds: z.array(idParam).optional(),
838
793
  exerciseId: idParam.optional(),
@@ -842,32 +797,16 @@ function registerAnalyticsTools(server, ctx) {
842
797
  useMetric: z.boolean().optional()
843
798
  },
844
799
  annotations: READ
845
- }, async ({ metric, teamId, userIds, exerciseId, date, dateStart, dateEnd, useMetric }) => {
846
- const spec = METRICS[metric];
847
- const inputs = {
848
- date,
849
- dateStart,
850
- dateEnd,
851
- exerciseId,
852
- useMetric
853
- };
854
- const body = {};
855
- if (spec.scope === "team") {
856
- if (teamId === void 0) return errorResult(`${metric} needs teamId.`);
857
- body.teamId = toId(teamId);
858
- } else {
859
- if (userIds === void 0 || userIds.length === 0) return errorResult(`${metric} needs userIds (one or more athlete ids).`);
860
- body.user_ids = userIds.map((u) => String(toId(u)));
861
- }
862
- const missing = spec.requires.filter((k) => inputs[k] === void 0);
863
- if (missing.length > 0) return errorResult(`${metric} also needs: ${missing.join(", ")}.`);
864
- for (const k of spec.inputs) {
865
- const v = inputs[k];
866
- if (v === void 0) continue;
867
- body[BODY_KEY[k]] = k === "exerciseId" ? String(toId(v)) : v;
868
- }
869
- return apiCall(ctx, "POST", spec.path, { body }, "Narrow with a tighter date range or fewer athletes.");
870
- });
800
+ }, ({ metric, teamId, userIds, exerciseId, date, dateStart, dateEnd, useMetric }) => attempt(async () => jsonResult(await queryAnalytics(ctx.client, definedProps({
801
+ metric,
802
+ teamId: teamId !== void 0 ? toId(teamId) : void 0,
803
+ userIds: userIds?.map(toId),
804
+ exerciseId: exerciseId !== void 0 ? toId(exerciseId) : void 0,
805
+ date,
806
+ dateStart,
807
+ dateEnd,
808
+ useMetric
809
+ })), { hint: "Narrow with a tighter date range or fewer athletes." })));
871
810
  }
872
811
  //#endregion
873
812
  //#region src/tools/exercises.ts
@@ -1068,22 +1007,11 @@ function registerLifecycle(server, ctx) {
1068
1007
  destructiveHint: false,
1069
1008
  openWorldHint: true
1070
1009
  }
1071
- }, ({ toProgramId, pwId, toDate }) => attempt(async () => {
1072
- const [year, month, day] = parseWorkoutDate(toDate);
1073
- const dayOfWeek = new Date(Date.UTC(year, month - 1, day)).getUTCDay();
1074
- return apiCall(ctx, "POST", "/2.0/coach/calendar/copyProgramWorkout", { body: {
1075
- toProgramId,
1076
- pwId,
1077
- toDate: {
1078
- date: `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`,
1079
- day,
1080
- month,
1081
- year,
1082
- dayOfWeek,
1083
- isToday: false
1084
- }
1085
- } });
1086
- }));
1010
+ }, ({ toProgramId, pwId, toDate }) => attempt(async () => jsonResult(await copySession(ctx.client, {
1011
+ toProgramId,
1012
+ pwId,
1013
+ toDate
1014
+ }))));
1087
1015
  server.registerTool("session_save_as_template", {
1088
1016
  title: "Save a session to the library",
1089
1017
  description: "Save an existing session as a reusable template in the session library (POST .../programWorkout/saveWorkoutAsTemplate/{workoutId}). Pass the workout_id.",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/core",
3
- "version": "0.6.4",
3
+ "version": "0.6.5",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -25,8 +25,8 @@
25
25
  "@cfworker/json-schema": "^4.1.1",
26
26
  "@modelcontextprotocol/sdk": "^1.29.0",
27
27
  "zod": "^4.4.3",
28
- "@trainheroic-unofficial/dto": "0.6.4",
29
- "@trainheroic-unofficial/js": "0.6.4"
28
+ "@trainheroic-unofficial/dto": "0.6.5",
29
+ "@trainheroic-unofficial/js": "0.6.5"
30
30
  },
31
31
  "devDependencies": {
32
32
  "@types/node": "^26.0.0",