@trainheroic-unofficial/core 0.2.0 → 0.3.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,26 @@ 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/athletes.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 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 registerRawTools(server: McpServer, ctx: ToolContext): void;
+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 +93,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 { 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 };

package/dist/index.mjs

@@ -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.",
@@ -297,39 +300,283 @@ function registerReadTools(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.",
+		inputSchema: {
+			page: z.number().int().positive().optional(),
+			pageSize: z.number().int().positive().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}` : ""}`);
+	});
+	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.",
+		inputSchema: {
+			athleteId: idParam,
+			startDate: z.string().optional(),
+			endDate: z.string().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.");
+	});
+}
+/** 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/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))];
+}
 /**
-* 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 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 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 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: {
+			teamId: idParam,
+			emails: z.union([z.string(), z.array(z.string()).min(1)]),
+			message: z.string().optional(),
+			confirm: z.boolean().optional()
+		},
+		annotations: DESTRUCTIVE
+	}, ({ 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
+		}
+	}, ({ 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: {
-			method: z.enum([
-				"GET",
-				"POST",
-				"PUT",
-				"DELETE"
-			]),
-			path: z.string().min(1),
-			body: z.unknown().optional(),
-			base: z.enum(["coach", "apis"]).optional(),
+			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
-	}, 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);
+	}, ({ 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",
+	"training-summary-team",
+	"compliance-team",
+	"lift-progress-team",
+	"working-max-history"
+];
+const METRICS = {
+	"readiness-team": {
+		path: "/v5/analytics/readiness/teams",
+		scope: "team",
+		fields: ["date"]
+	},
+	"readiness-athlete": {
+		path: "/v5/analytics/readiness/users",
+		scope: "user",
+		fields: ["date"]
+	},
+	"lift-1rm-history": {
+		path: "/v5/analytics/lift-one-rep-max-history/users",
+		scope: "user",
+		fields: [
+			"date_start",
+			"date_end",
+			"exercise_id",
+			"use_metric"
+		]
+	},
+	"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"]
+	},
+	"compliance-team": {
+		path: "/v5/analytics/compliance",
+		scope: "team",
+		fields: ["date_start", "date_end"]
+	},
+	"lift-progress-team": {
+		path: "/v5/analytics/lift-progress/teams",
+		scope: "team",
+		fields: [
+			"exercise_id",
+			"date_start",
+			"date_end"
+		]
+	},
+	"working-max-history": {
+		path: "/v5/analytics/working-max-history/users",
+		scope: "user",
+		fields: ["date_start", "date_end"]
+	}
+};
+/** 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.",
+		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 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 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.");
+		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];
+		return apiCall(ctx, "POST", spec.path, { body }, "Narrow with a tighter date range or fewer athletes.");
 	});
 }
 //#endregion
@@ -343,7 +590,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 +654,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 +728,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 +749,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 +891,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, registerExerciseTools, registerMessagingTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trainheroic-unofficial/core",
-  "version": "0.2.0",
+  "version": "0.3.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.3.0",
+    "@trainheroic-unofficial/js": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",