@trainheroic-unofficial/core 0.2.0 → 0.4.0

package/README.md

@@ -16,7 +16,9 @@ functions:
 ```ts
 import {
   registerReadTools,
-  registerRawTools,
+  registerAthleteTools,
+  registerTeamTools,
+  registerAnalyticsTools,
   registerExerciseTools,
   registerWorkoutTools,
   registerMessagingTools,
@@ -36,15 +38,18 @@ change.
 ## What the tools cover
 
 The tools group into coach reads (profile, athletes, teams, programs, notifications,
-analytics), exercise library operations (resolve, search, get, sync, create, forget,
-stats), the workout lifecycle (build a draft, read it back, publish, remove), messaging
-(list, read, draft, send, delete), and a `th_request` escape hatch for any endpoint the
-dedicated tools do not cover.
+analytics catalog), athlete management (invite, archive, restore), team management (create,
+rename, delete, join codes), analytics report pulls (`analytics_query`: readiness, 1RM and
+working-max history, training summary, compliance, lift progress), exercise library
+operations (resolve, search, get, sync, create,
+forget, stats), the workout/session lifecycle (build a draft, read it back, publish,
+unpublish, copy, save as template, remove), and messaging (list, read, draft, send, delete).
+There is no raw-request escape hatch; every endpoint reaches the model through a typed tool.
 
 Tools return their result in-band. A failure comes back as an error result the model can
 read and correct, not a thrown exception. Reads are marked read-only. Athlete-facing or
-destructive actions (publish, remove, send, delete, and non-GET `th_request`) pass through a
-confirmation gate before they run.
+destructive actions (publish, unpublish, remove, send, delete, archive, team/code delete)
+pass through a confirmation gate before they run.
 
 The D1-backed warehouse sync tools are not here; they live in the `cloudflare` package
 because they depend on its storage.

package/dist/index.d.mts

@@ -63,13 +63,42 @@ 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/raw.d.ts
+//#region src/tools/athlete-training.d.ts
 /**
- * Escape hatch covering every endpoint without a dedicated tool (e.g. the analytics
- * POSTs). GET is ungated; mutating methods go through the same confirmation gate as
- * the dedicated destructive tools so this cannot be used to bypass it.
+ * 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.
  */
-declare function registerRawTools(server: McpServer, ctx: ToolContext): void;
+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
+ * person by email to a team, and the athlete record only exists once they accept and set
+ * their own name. So the create path is the two-step invite from the API reference:
+ * validate the address (POST /v5/emails/validate), then inviteToTeam
+ * (POST /v5/athletes/inviteToTeam). Both act on the live account, so the invite is gated.
+ */
+declare function registerAthleteTools(server: McpServer, ctx: ToolContext): void;
+//#endregion
+//#region src/tools/teams.d.ts
+/**
+ * Team write tools. The team reads (list_teams, get_team, list_team_codes) live in
+ * reads.ts; this module covers create/rename/delete plus the join-code lifecycle.
+ */
+declare function registerTeamTools(server: McpServer, ctx: ToolContext): void;
+//#endregion
+//#region src/tools/analytics.d.ts
+/** Analytics report pulls. Read-only despite the POST verb, so ungated. */
+declare function registerAnalyticsTools(server: McpServer, ctx: ToolContext): void;
 //#endregion
 //#region src/tools/exercises.d.ts
 /**
@@ -80,11 +109,11 @@ declare function registerRawTools(server: McpServer, ctx: ToolContext): void;
 declare function registerExerciseTools(server: McpServer, ctx: ToolContext): void;
 //#endregion
 //#region src/tools/workout.d.ts
-/** Workout building, read-back, publishing, and removal. */
+/** Workout building, read-back, publishing, and the session calendar lifecycle. */
 declare function registerWorkoutTools(server: McpServer, ctx: ToolContext): void;
 //#endregion
 //#region src/tools/messaging.d.ts
 /** 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, registerExerciseTools, registerMessagingTools, registerRawTools, registerReadTools, 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;
@@ -221,12 +221,12 @@ const SIMPLE_GETS = [
 	{
 		name: "analytics_categories",
 		title: "Analytics categories",
-		description: "Lists available analytics types. Pull the data via th_request POST /v5/analytics/*.",
+		description: "Lists available analytics types. Pull a report with analytics_query (pick the matching metric).",
 		path: "/v5/analytics"
 	}
 ];
-/** Read-only coach/athlete queries. Exercise lookups live in the exercise store tools. */
-function registerReadTools(server, ctx) {
+/** Roster-level reads: the fixed GETs plus the filterable athlete and team lists. */
+function registerRosterReads(server, ctx) {
 	for (const t of SIMPLE_GETS) server.registerTool(t.name, {
 		title: t.title,
 		description: t.description,
@@ -279,6 +279,9 @@ function registerReadTools(server, ctx) {
 		const query = qs.toString();
 		return apiCall(ctx, "GET", `/1.0/coach/teams${query ? `?${query}` : ""}`);
 	});
+}
+/** Reads scoped to a single entity (team, program, athlete) plus the activity feed. */
+function registerEntityReads(server, ctx) {
 	server.registerTool("get_team", {
 		title: "Get team",
 		description: "Full team object by team id.",
@@ -298,38 +301,442 @@ function registerReadTools(server, ctx) {
 		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."));
 }
+/** 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/raw.ts
+//#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().max(200).optional(),
+			gender: z.number().int().optional()
+		},
+		annotations: READ
+	}, ({ 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: "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: {
+			startDate: dateString,
+			endDate: dateString,
+			raw: z.boolean().optional()
+		},
+		annotations: READ
+	}, ({ 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))));
+}
+/** 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
+		}));
+	}));
+}
 /**
-* Escape hatch covering every endpoint without a dedicated tool (e.g. the analytics
-* POSTs). GET is ungated; mutating methods go through the same confirmation gate as
-* the dedicated destructive tools so this cannot be used to bypass it.
+* 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 registerRawTools(server, ctx) {
-	server.registerTool("th_request", {
-		title: "Raw TrainHeroic request",
-		description: "Call any TrainHeroic endpoint directly. `path` is everything after the host. `base` selects the host: 'coach' = api.trainheroic.com (default), 'apis' = apis.trainheroic.com. Prefer dedicated tools where they exist. POST/PUT/DELETE act on the live account and require confirmation.",
+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
+const DEFAULT_INVITE_MESSAGE = "Follow these steps and you'll be set up and ready to go!";
+/** Normalize one-or-many emails into a deduped, trimmed list. */
+function asEmailList(emails) {
+	return [...new Set((Array.isArray(emails) ? emails : [emails]).map((e) => e.trim()).filter((e) => e.length > 0))];
+}
+/**
+* Athlete management. TrainHeroic has no "create athlete" primitive: a coach invites a
+* person by email to a team, and the athlete record only exists once they accept and set
+* their own name. So the create path is the two-step invite from the API reference:
+* validate the address (POST /v5/emails/validate), then inviteToTeam
+* (POST /v5/athletes/inviteToTeam). Both act on the live account, so the invite is gated.
+*/
+function registerAthleteTools(server, ctx) {
+	server.registerTool("athlete_invite", {
+		title: "Invite an athlete",
+		description: "Add athletes by emailing them a TrainHeroic team invitation — this is how you 'create' an athlete; there is no other create path, and no name is collected here (the athlete sets their own on accept). Targets a team by id, so list_teams first if you need one. Validates each address, then sends the invite. ATHLETE-FACING and immediate; requires confirmation (elicitation, or confirm:true).",
 		inputSchema: {
-			method: z.enum([
-				"GET",
-				"POST",
-				"PUT",
-				"DELETE"
-			]),
-			path: z.string().min(1),
-			body: z.unknown().optional(),
-			base: z.enum(["coach", "apis"]).optional(),
+			teamId: idParam,
+			emails: z.union([z.string(), z.array(z.string()).min(1)]),
+			message: z.string().optional(),
 			confirm: z.boolean().optional()
 		},
 		annotations: DESTRUCTIVE
-	}, async ({ method, path, body, base, confirm }, extra) => {
-		if (method !== "GET") {
-			if (!await confirmGate(server, extra.requestId, `Run ${method} ${path} against the live TrainHeroic account?`, confirm)) return errorResult(NOT_CONFIRMED);
+	}, ({ teamId, emails, message, confirm }, extra) => attempt(async () => {
+		const list = asEmailList(emails);
+		if (list.length === 0) return errorResult("Provide at least one email address to invite.");
+		const id = toId(teamId);
+		if (!await confirmGate(server, extra.requestId, `Invite ${list.join(", ")} to team ${id}? This emails them a real TrainHeroic invitation.`, confirm)) return errorResult(NOT_CONFIRMED);
+		const validation = await ctx.client.request("POST", "/v5/emails/validate", { body: { emails: list.join(",") } });
+		if (!validation.ok) {
+			const detail = typeof validation.data === "string" ? validation.data : JSON.stringify(validation.data);
+			return errorResult(`Email validation failed (HTTP ${validation.status}): ${detail}`);
+		}
+		const valid = Array.isArray(validation.data) ? validation.data : list;
+		if (valid.length === 0) return errorResult(`No valid addresses among: ${list.join(", ")}. They may be malformed or already on the team.`);
+		const invite = await ctx.client.request("POST", "/v5/athletes/inviteToTeam", { body: {
+			teamType: 0,
+			teamId: id,
+			orgId: null,
+			emails: valid,
+			message: message ?? DEFAULT_INVITE_MESSAGE
+		} });
+		if (!invite.ok) {
+			const detail = typeof invite.data === "string" ? invite.data : JSON.stringify(invite.data);
+			return errorResult(`Invite failed (HTTP ${invite.status}): ${detail}`);
+		}
+		return jsonResult({
+			invited: true,
+			teamId: id,
+			result: invite.data
+		});
+	}));
+	server.registerTool("athlete_archive", {
+		title: "Archive athletes",
+		description: "Remove one or more athletes from the active roster (PUT /v5/athletes/archive). Their data is preserved and they can be restored. Acts on the live account; requires confirmation (elicitation, or confirm:true).",
+		inputSchema: {
+			athleteIds: z.array(idParam).min(1),
+			confirm: z.boolean().optional()
+		},
+		annotations: DESTRUCTIVE
+	}, ({ athleteIds, confirm }, extra) => attempt(async () => {
+		const ids = athleteIds.map(toId);
+		if (!await confirmGate(server, extra.requestId, `Archive athlete(s) ${ids.join(", ")}? They leave the active roster (data is kept and restorable).`, confirm)) return errorResult(NOT_CONFIRMED);
+		return apiCall(ctx, "PUT", "/v5/athletes/archive", { body: { athleteIds: ids } });
+	}));
+	server.registerTool("athlete_restore", {
+		title: "Restore athletes",
+		description: "Restore previously archived athletes to the active roster (PUT /v5/athletes/restore).",
+		inputSchema: { athleteIds: z.array(idParam).min(1) },
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: true,
+			destructiveHint: false,
+			openWorldHint: true
 		}
-		const options = {};
-		if (body !== void 0) options.body = body;
-		if (base !== void 0) options.base = base;
-		return apiCall(ctx, method, path, options, "Large or unfiltered response. Add query params to narrow it, or use a dedicated tool for this endpoint if one exists.");
+	}, ({ athleteIds }) => apiCall(ctx, "PUT", "/v5/athletes/restore", { body: { athleteIds: athleteIds.map(toId) } }));
+}
+//#endregion
+//#region src/tools/teams.ts
+const ADDITIVE = {
+	readOnlyHint: false,
+	destructiveHint: false,
+	openWorldHint: true
+};
+/**
+* Team write tools. The team reads (list_teams, get_team, list_team_codes) live in
+* reads.ts; this module covers create/rename/delete plus the join-code lifecycle.
+*/
+function registerTeamTools(server, ctx) {
+	server.registerTool("team_create", {
+		title: "Create a team",
+		description: "Create a team (POST /1.0/coach/team/createWithTitleAndCode). Also creates the team's calendar/program. Returns the new team including its calendar id. Use the team id with athlete_invite.",
+		inputSchema: { title: z.string().min(1) },
+		annotations: ADDITIVE
+	}, ({ title }) => apiCall(ctx, "POST", "/1.0/coach/team/createWithTitleAndCode", { body: { title } }));
+	server.registerTool("team_update", {
+		title: "Rename a team",
+		description: "Update a team's settings, e.g. its title (PUT /v5/teams/{teamId}).",
+		inputSchema: {
+			teamId: idParam,
+			title: z.string().min(1)
+		},
+		annotations: ADDITIVE
+	}, ({ teamId, title }) => apiCall(ctx, "PUT", `/v5/teams/${toId(teamId)}`, { body: { title } }));
+	server.registerTool("team_delete", {
+		title: "Delete a team",
+		description: "Delete a team (DELETE /v5/teams/{teamId}). Removes the team and its calendar from the live account; hard to undo. Requires confirmation (elicitation, or confirm:true).",
+		inputSchema: {
+			teamId: idParam,
+			confirm: z.boolean().optional()
+		},
+		annotations: DESTRUCTIVE
+	}, ({ teamId, confirm }, extra) => attempt(async () => {
+		const id = toId(teamId);
+		if (!await confirmGate(server, extra.requestId, `Delete team ${id}? This removes the team and its calendar from the live account.`, confirm)) return errorResult(NOT_CONFIRMED);
+		return apiCall(ctx, "DELETE", `/v5/teams/${id}`);
+	}));
+	server.registerTool("team_code_create", {
+		title: "Create a team join code",
+		description: "Create an access code athletes use to self-join a team (POST /v5/teams/{teamId}/teamCodes). `type` defaults to 2, the standard join code.",
+		inputSchema: {
+			teamId: idParam,
+			type: z.number().int().optional()
+		},
+		annotations: ADDITIVE
+	}, ({ teamId, type }) => apiCall(ctx, "POST", `/v5/teams/${toId(teamId)}/teamCodes`, { body: { type: type ?? 2 } }));
+	server.registerTool("team_code_delete", {
+		title: "Delete a team join code",
+		description: "Delete a team access code by its id (DELETE /v5/teamCodes/{codeId}). Athletes can no longer use it to join. Requires confirmation (elicitation, or confirm:true).",
+		inputSchema: {
+			codeId: idParam,
+			confirm: z.boolean().optional()
+		},
+		annotations: DESTRUCTIVE
+	}, ({ codeId, confirm }, extra) => attempt(async () => {
+		const id = toId(codeId);
+		if (!await confirmGate(server, extra.requestId, `Delete team join code ${id}? Athletes can no longer use it to join.`, confirm)) return errorResult(NOT_CONFIRMED);
+		return apiCall(ctx, "DELETE", `/v5/teamCodes/${id}`);
+	}));
+}
+//#endregion
+//#region src/tools/analytics.ts
+const METRIC_KEYS = [
+	"readiness-team",
+	"readiness-athlete",
+	"lift-1rm-history",
+	"training-summary-athlete",
+	"compliance-team",
+	"lift-progress-team",
+	"working-max-history"
+];
+const METRICS = {
+	"readiness-team": {
+		path: "/v5/analytics/readiness/teams",
+		scope: "team",
+		inputs: ["date"],
+		requires: ["date"]
+	},
+	"readiness-athlete": {
+		path: "/v5/analytics/readiness/users",
+		scope: "user",
+		inputs: ["dateStart", "dateEnd"],
+		requires: ["dateStart", "dateEnd"]
+	},
+	"lift-1rm-history": {
+		path: "/v5/analytics/lift-one-rep-max-history/users",
+		scope: "user",
+		inputs: [
+			"dateStart",
+			"dateEnd",
+			"exerciseId",
+			"useMetric"
+		],
+		requires: [
+			"dateStart",
+			"dateEnd",
+			"exerciseId"
+		]
+	},
+	"training-summary-athlete": {
+		path: "/v5/analytics/training-summary/users",
+		scope: "user",
+		inputs: ["dateStart", "dateEnd"],
+		requires: ["dateStart", "dateEnd"]
+	},
+	"compliance-team": {
+		path: "/v5/analytics/compliance",
+		scope: "team",
+		inputs: ["dateStart", "dateEnd"],
+		requires: ["dateStart", "dateEnd"]
+	},
+	"lift-progress-team": {
+		path: "/v5/analytics/lift-progress/teams",
+		scope: "team",
+		inputs: [
+			"exerciseId",
+			"dateStart",
+			"dateEnd"
+		],
+		requires: [
+			"exerciseId",
+			"dateStart",
+			"dateEnd"
+		]
+	},
+	"working-max-history": {
+		path: "/v5/analytics/working-max-history/users",
+		scope: "user",
+		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 (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(),
+			userIds: z.array(idParam).optional(),
+			exerciseId: idParam.optional(),
+			date: z.string().optional(),
+			dateStart: z.string().optional(),
+			dateEnd: z.string().optional(),
+			useMetric: z.boolean().optional()
+		},
+		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.`);
+			body.teamId = toId(teamId);
+		} else {
+			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 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.");
 	});
 }
 //#endregion
@@ -343,7 +750,7 @@ function registerExerciseTools(server, ctx) {
 	const index = ctx.index;
 	server.registerTool("exercise_resolve", {
 		title: "Resolve exercise name",
-		description: "Map a name to an exercise id via the local mirror. Returns the match plus ranked candidates; when ambiguous, match is null and you should pick from candidates. Units (param_1_unit/param_2_unit) are fixed per exercise — check them before prescribing.",
+		description: "Map a name to an exercise id via the local mirror. Returns the match plus ranked candidates; when ambiguous, match is null and you should pick from candidates. Each result's `units` array lists the fixed measurement units by entry slot; they are fixed per exercise — check them before prescribing.",
 		inputSchema: { name: z.string().min(1) },
 		annotations: READ
 	}, ({ name }) => attempt(async () => jsonResult(await index.resolve(name))));
@@ -407,8 +814,8 @@ function registerExerciseTools(server, ctx) {
 }
 //#endregion
 //#region src/tools/workout.ts
-/** Workout building, read-back, publishing, and removal. */
-function registerWorkoutTools(server, ctx) {
+/** Build a draft, read it back, and publish it. */
+function registerBuild(server, ctx) {
 	server.registerTool("workout_build", {
 		title: "Build a workout session (draft)",
 		description: "Build an UNPUBLISHED session from a spec (program -> session -> blocks -> exercises). Two exercises in one block become a superset. Add a block 'leaderboard' for a Red-Zone score, or a top-level 'instruction' for the session note (Coach Instructions). Returns the draft ids, a read-back, and unit advisories. Review, then workout_publish.",
@@ -481,6 +888,9 @@ function registerWorkoutTools(server, ctx) {
 			readback: await readSession(ctx.client, programId, parseWorkoutDate(date), pwId)
 		});
 	}));
+}
+/** Calendar lifecycle for an existing session: remove, unpublish, copy, save to library. */
+function registerLifecycle(server, ctx) {
 	server.registerTool("session_remove", {
 		title: "Remove a session",
 		description: "Delete a session from the live calendar (also the way to replace a date: remove then build). Hard to undo. Requires confirmation (elicitation, or confirm:true).",
@@ -499,6 +909,66 @@ function registerWorkoutTools(server, ctx) {
 		await removeSession(ctx.client, programId, pwId);
 		return jsonResult({ removed: pwId });
 	}));
+	server.registerTool("session_unpublish", {
+		title: "Unpublish a session",
+		description: "Unpublish a previously published session (POST .../programWorkout/unPublish/{pwId}). It is no longer athlete-facing. Requires confirmation (elicitation, or confirm:true).",
+		inputSchema: {
+			pwId: z.number(),
+			confirm: z.boolean().optional()
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			openWorldHint: true
+		}
+	}, ({ pwId, confirm }, extra) => attempt(async () => {
+		if (!await confirmGate(server, extra.requestId, `Unpublish session ${pwId}? Athletes will no longer see it.`, confirm)) return errorResult(NOT_CONFIRMED);
+		return apiCall(ctx, "POST", `/2.0/coach/calendar/programWorkout/unPublish/${pwId}`);
+	}));
+	server.registerTool("session_copy", {
+		title: "Copy a session to a date",
+		description: "Copy/repeat a session to a target date on a program (POST .../copyProgramWorkout). toDate is YYYY-M-D. Creates a new session; review and publish it separately.",
+		inputSchema: {
+			toProgramId: z.number(),
+			pwId: z.number(),
+			toDate: z.string()
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			openWorldHint: true
+		}
+	}, ({ toProgramId, pwId, toDate }) => attempt(async () => {
+		const [year, month, day] = parseWorkoutDate(toDate);
+		const dayOfWeek = new Date(Date.UTC(year, month - 1, day)).getUTCDay();
+		return apiCall(ctx, "POST", "/2.0/coach/calendar/copyProgramWorkout", { body: {
+			toProgramId,
+			pwId,
+			toDate: {
+				date: `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`,
+				day,
+				month,
+				year,
+				dayOfWeek,
+				isToday: false
+			}
+		} });
+	}));
+	server.registerTool("session_save_as_template", {
+		title: "Save a session to the library",
+		description: "Save an existing session as a reusable template in the session library (POST .../programWorkout/saveWorkoutAsTemplate/{workoutId}). Pass the workout_id.",
+		inputSchema: { workoutId: z.number() },
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			openWorldHint: true
+		}
+	}, ({ workoutId }) => apiCall(ctx, "POST", `/2.0/coach/calendar/programWorkout/saveWorkoutAsTemplate/${workoutId}`));
+}
+/** Workout building, read-back, publishing, and the session calendar lifecycle. */
+function registerWorkoutTools(server, ctx) {
+	registerBuild(server, ctx);
+	registerLifecycle(server, ctx);
 }
 //#endregion
 //#region src/tools/messaging.ts
@@ -581,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, registerExerciseTools, registerMessagingTools, registerRawTools, registerReadTools, 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.2.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.2.0",
-    "@trainheroic-unofficial/js": "0.2.0"
+    "@trainheroic-unofficial/dto": "0.4.0",
+    "@trainheroic-unofficial/js": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",