@trainheroic-unofficial/core 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -63,6 +63,22 @@ declare function confirmGate(server: McpServer, requestId: string | number | und
 /** Read-only coach/athlete queries. Exercise lookups live in the exercise store tools. */
 declare function registerReadTools(server: McpServer, ctx: ToolContext): void;
 //#endregion
+//#region src/tools/athlete-training.d.ts
+/**
+ * Athlete tools need only the client (no exercise-library index), so they take a narrower
+ * context than the coach tools. A full `ToolContext` also satisfies this, so the same ctx
+ * object can be passed.
+ */
+type AthleteContext = {
+  client: TrainHeroicClient;
+};
+/**
+ * Live tools over the logged-in user's own training (history, scheduled/completed workouts,
+ * PRs, working maxes), plus a gated set-logging write. The athlete user id is
+ * resolved once from /user/simple and reused across tools.
+ */
+declare function registerAthleteTrainingTools(server: McpServer, ctx: AthleteContext): void;
+//#endregion
 //#region src/tools/athletes.d.ts
 /**
  * Athlete management. TrainHeroic has no "create athlete" primitive: a coach invites a
@@ -100,4 +116,4 @@ declare function registerWorkoutTools(server: McpServer, ctx: ToolContext): void
 /** Live messaging: list/read conversations, draft a message, and the gated send/delete. */
 declare function registerMessagingTools(server: McpServer, ctx: ToolContext): void;
 //#endregion
-export { BudgetHint, DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SYNC, ToolContext, apiCall, attempt, boundedSerialize, confirmGate, errorResult, idParam, jsonResult, registerAnalyticsTools, registerAthleteTools, registerExerciseTools, registerMessagingTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };
+export { AthleteContext, BudgetHint, DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SYNC, ToolContext, apiCall, attempt, boundedSerialize, confirmGate, errorResult, idParam, jsonResult, registerAnalyticsTools, registerAthleteTools, registerAthleteTrainingTools, registerExerciseTools, registerMessagingTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { blockSpecSchema, commentDraftSchema, exerciseCreateSchema, idArgSchema, parseWorkoutDate } from "@trainheroic-unofficial/dto";
+import { blockSpecSchema, commentDraftSchema, dateString, exerciseCreateSchema, idArgSchema, logSetArgsSchema, parseWorkoutDate } from "@trainheroic-unofficial/dto";
 import { z } from "zod";
-import { buildCommentPayload, buildSession, collectAdvisories, deleteComment, fetchStreams, publishSession, readLive, readSession, removeSession, sendComment } from "@trainheroic-unofficial/js";
+import { buildCommentPayload, buildSession, coerceInt, collectAdvisories, deleteComment, exerciseUnits, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteUser, fetchAthleteWorkouts, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchStreams, fetchWorkingMaxes, isRecord, logAthleteSet, presentAthleteWorkouts, presentExerciseHistory, publishSession, readLive, readSession, removeSession, searchExerciseHistory, sendComment } from "@trainheroic-unofficial/js";
 //#region src/context.ts
 /** A tool argument that accepts a numeric id as a number or a string of digits. */
 const idParam = idArgSchema;
@@ -300,42 +300,175 @@ function registerEntityReads(server, ctx) {
 		inputSchema: { programId: idParam },
 		annotations: READ
 	}, ({ programId }) => apiCall(ctx, "GET", `/3.0/coach/program/${enc(programId)}`, void 0, "This is a large, deep object. If it is truncated, fetch a narrower view (a specific session) instead."));
-	server.registerTool("coach_activity_feed", {
-		title: "Coach activity feed",
-		description: "Recent athlete activity across the roster (GET /v5/coaches/activityFeed): completed workouts, PRs, and posts. Paginate with page/pageSize.",
+}
+/** Read-only coach/athlete queries. Exercise lookups live in the exercise store tools. */
+function registerReadTools(server, ctx) {
+	registerRosterReads(server, ctx);
+	registerEntityReads(server, ctx);
+}
+//#endregion
+//#region src/tools/athlete-training.ts
+/** Identity, profile, prefs, working maxes, leaderboard. */
+function registerProfileTools(server, ctx, whoami, userId) {
+	server.registerTool("athlete_whoami", {
+		title: "Who am I (athlete)",
+		description: "The logged-in account's identity (id, name, roles) from /user/simple.",
+		inputSchema: {},
+		annotations: READ
+	}, () => attempt(async () => jsonResult(await whoami())));
+	server.registerTool("athlete_profile", {
+		title: "Athlete profile + lifetime totals",
+		description: "Lifetime training totals (reps, volume, sessions, first/last logged) plus the profile (name, units, dob). Set useMetric for kg/metric totals.",
+		inputSchema: { useMetric: z.boolean().optional() },
+		annotations: READ
+	}, ({ useMetric }) => attempt(async () => {
+		const id = await userId();
+		const [summary, user] = await Promise.all([fetchAthleteProfileSummary(ctx.client, id, useMetric ?? false), fetchAthleteUser(ctx.client, id)]);
+		return jsonResult({
+			summary,
+			user
+		});
+	}));
+	server.registerTool("athlete_prefs", {
+		title: "Athlete preferences",
+		description: "Notification and display preference flags for the athlete account.",
+		inputSchema: {},
+		annotations: READ
+	}, () => attempt(async () => jsonResult(await fetchAthletePrefs(ctx.client))));
+	server.registerTool("athlete_working_maxes", {
+		title: "Working maxes",
+		description: "The athlete's working max per exercise (drives % prescriptions).",
+		inputSchema: {},
+		annotations: READ
+	}, () => attempt(async () => jsonResult(await fetchWorkingMaxes(ctx.client))));
+	server.registerTool("athlete_leaderboard", {
+		title: "Benchmark leaderboard",
+		description: "Leaderboard for a benchmark/test workout by its workout id.",
 		inputSchema: {
+			workoutId: idParam,
 			page: z.number().int().positive().optional(),
-			pageSize: z.number().int().positive().optional()
+			pageSize: z.number().int().positive().max(200).optional(),
+			gender: z.number().int().optional()
 		},
 		annotations: READ
-	}, ({ page, pageSize }) => {
-		const qs = new URLSearchParams();
-		if (page !== void 0) qs.set("page", String(page));
-		if (pageSize !== void 0) qs.set("pageSize", String(pageSize));
-		const query = qs.toString();
-		return apiCall(ctx, "GET", `/v5/coaches/activityFeed${query ? `?${query}` : ""}`);
-	});
+	}, ({ workoutId, page, pageSize, gender }) => attempt(async () => {
+		const opts = {};
+		if (page !== void 0) opts.page = page;
+		if (pageSize !== void 0) opts.pageSize = pageSize;
+		if (gender !== void 0) opts.gender = gender;
+		return jsonResult(await fetchLeaderboard(ctx.client, toId(workoutId), opts));
+	}));
+}
+/** Workouts, exercise catalog, per-exercise history/PRs/stats. */
+function registerExerciseTools$1(server, ctx, userId) {
 	server.registerTool("athlete_workouts", {
-		title: "Athlete workout history",
-		description: "One athlete's workouts with their survey/readiness data (GET /v5/coaches/athletes/{athleteId}/workouts). Bound it with startDate/endDate (YYYY-MM-DD) to keep the response small.",
+		title: "Workouts in a date range",
+		description: "Scheduled + completed workouts in an inclusive YYYY-MM-DD window, flattened to blocks/exercises with per-set prescriptions and positional units. Set raw:true for the untouched API objects. Narrow the window if the result is truncated.",
 		inputSchema: {
-			athleteId: idParam,
-			startDate: z.string().optional(),
-			endDate: z.string().optional()
+			startDate: dateString,
+			endDate: dateString,
+			raw: z.boolean().optional()
 		},
 		annotations: READ
-	}, ({ athleteId, startDate, endDate }) => {
-		const qs = new URLSearchParams();
-		if (startDate !== void 0) qs.set("startDate", startDate);
-		if (endDate !== void 0) qs.set("endDate", endDate);
-		const query = qs.toString();
-		return apiCall(ctx, "GET", `/v5/coaches/athletes/${enc(athleteId)}/workouts${query ? `?${query}` : ""}`, void 0, "Narrow the date range to shrink this if it is truncated.");
-	});
+	}, ({ startDate, endDate, raw }) => attempt(async () => {
+		const workouts = await fetchAthleteWorkouts(ctx.client, startDate, endDate);
+		return jsonResult(raw === true ? workouts : presentAthleteWorkouts(workouts), { hint: "Narrow startDate/endDate to shrink this result." });
+	}));
+	server.registerTool("athlete_exercises", {
+		title: "Search logged exercises",
+		description: "The exercises the athlete has logged (id + title + positional units). Pass q to free-text search by name; use the returned id with athlete_exercise_history / _stats.",
+		inputSchema: {
+			q: z.string().optional(),
+			limit: z.number().int().positive().max(200).optional()
+		},
+		annotations: READ
+	}, ({ q, limit }) => attempt(async () => {
+		return jsonResult((q !== void 0 && q.trim() !== "" ? await searchExerciseHistory(ctx.client, q, limit ?? 20) : await fetchExerciseHistoryList(ctx.client)).map((r) => ({
+			id: r.id,
+			title: r.title,
+			isCircuit: r.isCircuit ?? false,
+			units: exerciseUnits(r.param1Type, r.param2Type)
+		})), { hint: "Pass q to search by name, or limit to cap the list." });
+	}));
+	server.registerTool("athlete_exercise_history", {
+		title: "Exercise history + PRs",
+		description: "Per-exercise PRs and the dated session time-series (sets performed, estimated 1RM). Set raw:true for the untouched API object. Get the exercise id from athlete_exercises.",
+		inputSchema: {
+			exerciseId: idParam,
+			raw: z.boolean().optional()
+		},
+		annotations: READ
+	}, ({ exerciseId, raw }) => attempt(async () => {
+		const detail = await fetchExerciseHistoryDetail(ctx.client, toId(exerciseId), await userId());
+		return jsonResult(raw === true ? detail : presentExerciseHistory(detail));
+	}));
+	server.registerTool("athlete_personal_records", {
+		title: "Exercise personal records",
+		description: "Personal records for an exercise (reps/weight, strength-standard filters).",
+		inputSchema: { exerciseId: idParam },
+		annotations: READ
+	}, ({ exerciseId }) => attempt(async () => jsonResult(await fetchPersonalRecords(ctx.client, toId(exerciseId)))));
+	server.registerTool("athlete_exercise_stats", {
+		title: "Exercise stats (last performance + PR)",
+		description: "Last performance and PR for an exercise as of a date (YYYY-MM-DD, required by the API).",
+		inputSchema: {
+			exerciseId: idParam,
+			date: dateString
+		},
+		annotations: READ
+	}, ({ exerciseId, date }) => attempt(async () => jsonResult(await fetchExerciseStats(ctx.client, toId(exerciseId), await userId(), date))));
 }
-/** Read-only coach/athlete queries. Exercise lookups live in the exercise store tools. */
-function registerReadTools(server, ctx) {
-	registerRosterReads(server, ctx);
-	registerEntityReads(server, ctx);
+/** The gated set-logging write. */
+function registerLogTool(server, ctx) {
+	server.registerTool("athlete_log_set", {
+		title: "Log completed set results",
+		description: "Athlete-facing write: record entered results (reps/weight per set) for a saved workout set on a given day, marking the set completed. Writes to the athlete's (coach-visible) training log and shows in exercise history. Get savedWorkoutSetId + savedWorkoutSetExerciseId from athlete_workouts (raw:true). Requires confirmation (elicitation or confirm:true).",
+		inputSchema: {
+			...logSetArgsSchema.shape,
+			confirm: z.boolean().optional()
+		},
+		annotations: DESTRUCTIVE
+	}, ({ date, savedWorkoutSetId, results, confirm }, extra) => attempt(async () => {
+		if (!await confirmGate(server, extra.requestId, `Log results to saved workout set ${toId(savedWorkoutSetId)} on ${date}? This writes to your coach-visible training log.`, confirm)) return errorResult(NOT_CONFIRMED);
+		const mapped = results.map((r) => ({
+			savedWorkoutSetExerciseId: toId(r.savedWorkoutSetExerciseId),
+			sets: r.sets.map((s) => {
+				const slot = {};
+				if (s.param1 !== void 0) slot.param1 = s.param1;
+				if (s.param2 !== void 0) slot.param2 = s.param2;
+				return slot;
+			})
+		}));
+		return jsonResult(await logAthleteSet(ctx.client, {
+			date,
+			savedWorkoutSetId: toId(savedWorkoutSetId),
+			results: mapped
+		}));
+	}));
+}
+/**
+* Live tools over the logged-in user's own training (history, scheduled/completed workouts,
+* PRs, working maxes), plus a gated set-logging write. The athlete user id is
+* resolved once from /user/simple and reused across tools.
+*/
+function registerAthleteTrainingTools(server, ctx) {
+	let whoamiCache = null;
+	const whoami = async () => {
+		if (whoamiCache === null) {
+			const res = await ctx.client.request("GET", "/user/simple");
+			if (!res.ok || !isRecord(res.data)) throw new Error("Could not load /user/simple.");
+			whoamiCache = res.data;
+		}
+		return whoamiCache;
+	};
+	const userId = async () => {
+		const id = coerceInt((await whoami()).id);
+		if (id === null || id <= 0) throw new Error("Could not resolve athlete user id from /user/simple.");
+		return id;
+	};
+	registerProfileTools(server, ctx, whoami, userId);
+	registerExerciseTools$1(server, ctx, userId);
+	registerLogTool(server, ctx);
 }
 //#endregion
 //#region src/tools/athletes.ts
@@ -486,7 +619,6 @@ const METRIC_KEYS = [
 	"readiness-athlete",
 	"lift-1rm-history",
 	"training-summary-athlete",
-	"training-summary-team",
 	"compliance-team",
 	"lift-progress-team",
 	"working-max-history"
@@ -495,58 +627,80 @@ const METRICS = {
 	"readiness-team": {
 		path: "/v5/analytics/readiness/teams",
 		scope: "team",
-		fields: ["date"]
+		inputs: ["date"],
+		requires: ["date"]
 	},
 	"readiness-athlete": {
 		path: "/v5/analytics/readiness/users",
 		scope: "user",
-		fields: ["date"]
+		inputs: ["dateStart", "dateEnd"],
+		requires: ["dateStart", "dateEnd"]
 	},
 	"lift-1rm-history": {
 		path: "/v5/analytics/lift-one-rep-max-history/users",
 		scope: "user",
-		fields: [
-			"date_start",
-			"date_end",
-			"exercise_id",
-			"use_metric"
+		inputs: [
+			"dateStart",
+			"dateEnd",
+			"exerciseId",
+			"useMetric"
+		],
+		requires: [
+			"dateStart",
+			"dateEnd",
+			"exerciseId"
 		]
 	},
 	"training-summary-athlete": {
 		path: "/v5/analytics/training-summary/users",
 		scope: "user",
-		fields: ["date_start", "date_end"]
-	},
-	"training-summary-team": {
-		path: "/v5/analytics/training-summary/teams",
-		scope: "team",
-		fields: ["date_start", "date_end"]
+		inputs: ["dateStart", "dateEnd"],
+		requires: ["dateStart", "dateEnd"]
 	},
 	"compliance-team": {
 		path: "/v5/analytics/compliance",
 		scope: "team",
-		fields: ["date_start", "date_end"]
+		inputs: ["dateStart", "dateEnd"],
+		requires: ["dateStart", "dateEnd"]
 	},
 	"lift-progress-team": {
 		path: "/v5/analytics/lift-progress/teams",
 		scope: "team",
-		fields: [
-			"exercise_id",
-			"date_start",
-			"date_end"
+		inputs: [
+			"exerciseId",
+			"dateStart",
+			"dateEnd"
+		],
+		requires: [
+			"exerciseId",
+			"dateStart",
+			"dateEnd"
 		]
 	},
 	"working-max-history": {
 		path: "/v5/analytics/working-max-history/users",
 		scope: "user",
-		fields: ["date_start", "date_end"]
+		inputs: [
+			"exerciseId",
+			"dateStart",
+			"dateEnd",
+			"useMetric"
+		],
+		requires: ["exerciseId"]
 	}
 };
+const BODY_KEY = {
+	date: "date",
+	dateStart: "date_start",
+	dateEnd: "date_end",
+	exerciseId: "exercise_id",
+	useMetric: "use_metric"
+};
 /** Analytics report pulls. Read-only despite the POST verb, so ungated. */
 function registerAnalyticsTools(server, ctx) {
 	server.registerTool("analytics_query", {
 		title: "Pull an analytics report",
-		description: "Read a TrainHeroic analytics report. `metric` picks the report (run analytics_categories for the catalog). Team metrics need teamId; athlete metrics need userIds. Dates are YYYY-MM-DD: readiness takes a single `date`, history/summary metrics take dateStart/dateEnd. lift-1rm-history and lift-progress-team also take exerciseId.",
+		description: "Read a TrainHeroic analytics report. `metric` picks the report (run analytics_categories for the catalog). Team metrics (readiness-team, compliance-team, lift-progress-team) need teamId; athlete metrics need 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.",
 		inputSchema: {
 			metric: z.enum(METRIC_KEYS),
 			teamId: idParam.optional(),
@@ -560,6 +714,13 @@ function registerAnalyticsTools(server, ctx) {
 		annotations: READ
 	}, async ({ metric, teamId, userIds, exerciseId, date, dateStart, dateEnd, useMetric }) => {
 		const spec = METRICS[metric];
+		const inputs = {
+			date,
+			dateStart,
+			dateEnd,
+			exerciseId,
+			useMetric
+		};
 		const body = {};
 		if (spec.scope === "team") {
 			if (teamId === void 0) return errorResult(`${metric} needs teamId.`);
@@ -568,14 +729,13 @@ function registerAnalyticsTools(server, ctx) {
 			if (userIds === void 0 || userIds.length === 0) return errorResult(`${metric} needs userIds (one or more athlete ids).`);
 			body.user_ids = userIds.map((u) => String(toId(u)));
 		}
-		const provided = {
-			date,
-			date_start: dateStart,
-			date_end: dateEnd,
-			exercise_id: exerciseId === void 0 ? void 0 : String(toId(exerciseId)),
-			use_metric: useMetric
-		};
-		for (const field of spec.fields) if (provided[field] !== void 0) body[field] = provided[field];
+		const missing = spec.requires.filter((k) => inputs[k] === void 0);
+		if (missing.length > 0) return errorResult(`${metric} also needs: ${missing.join(", ")}.`);
+		for (const k of spec.inputs) {
+			const v = inputs[k];
+			if (v === void 0) continue;
+			body[BODY_KEY[k]] = k === "exerciseId" ? String(toId(v)) : v;
+		}
 		return apiCall(ctx, "POST", spec.path, { body }, "Narrow with a tighter date range or fewer athletes.");
 	});
 }
@@ -891,4 +1051,4 @@ function registerMessagingTools(server, ctx) {
 	registerWrites(server, ctx);
 }
 //#endregion
-export { DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SYNC, apiCall, attempt, boundedSerialize, confirmGate, errorResult, idParam, jsonResult, registerAnalyticsTools, registerAthleteTools, registerExerciseTools, registerMessagingTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };
+export { DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SYNC, apiCall, attempt, boundedSerialize, confirmGate, errorResult, idParam, jsonResult, registerAnalyticsTools, registerAthleteTools, registerAthleteTrainingTools, registerExerciseTools, registerMessagingTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trainheroic-unofficial/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,8 +25,8 @@
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@trainheroic-unofficial/dto": "0.3.0",
-    "@trainheroic-unofficial/js": "0.3.0"
+    "@trainheroic-unofficial/dto": "0.4.0",
+    "@trainheroic-unofficial/js": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",