@trainheroic-unofficial/js 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { n as LibrarySnapshot, r as MemoryLibraryCache, t as LibraryCache } from "./library-cache-CDABOdIN.mjs";
-import { Advisory, BlockSpec, ExerciseRow, ExerciseSpec, ExerciseView, ReadResult, ResolveResult, WorkoutDate } from "@trainheroic-unofficial/dto";
+import { Advisory, AthletePrefs, AthleteProfileSummary, AthleteUser, AthleteWorkingMax, AthleteWorkoutView, BlockSpec, ExerciseHistoryDetail, ExerciseHistoryListItem, ExerciseRow, ExerciseSpec, ExerciseStats, ExerciseView, PersonalRecord, PresentedExerciseHistory, ProgramWorkout, ReadResult, ResolveResult, WorkoutDate } from "@trainheroic-unofficial/dto";
 import { ZodType } from "zod";
 export * from "@trainheroic-unofficial/dto";
 
@@ -69,8 +69,19 @@ declare const PARAM_RPE = 14;
 declare function coerceInt(value: unknown): number | null;
 declare function coerceNum(value: unknown): number | null;
 declare function unitLabel(paramType: unknown): string | null;
-/** Annotate a row with human-readable units for display. */
+/**
+ * Fixed measurement units for an exercise, ordered by entry slot (param 1, then param 2).
+ * Positional, not semantic: some exercises reverse the slots, so the array is not labelled
+ * by role. A null entry is an unset slot.
+ */
+declare function exerciseUnits(param1: unknown, param2: unknown): Array<string | null>;
+/** Present a row for display: drop the raw param-type codes, surface units positionally. */
 declare function withUnits(row: ExerciseRow): ExerciseView;
+/**
+ * Present a full raw exercise object for display: drop the raw param-type codes and add the
+ * positional `units` array. Keeps every other field of the raw object intact.
+ */
+declare function presentExercise(raw: Record<string, unknown>): Record<string, unknown>;
 declare function buildSearchText(title: string): string;
 /** Strip the {"success":1,"data":X} envelope some 2.0/coach endpoints use. */
 declare function unwrapEnvelope(body: unknown): unknown;
@@ -84,9 +95,15 @@ declare function isRecord(x: unknown): x is Record<string, unknown>;
  */
 declare function rankSearch<T extends {
   title: string;
-  can_edit: number;
+  can_edit?: number;
 }>(rows: readonly T[], query: string, limit: number): T[];
 declare function chunk<T>(items: readonly T[], size: number): T[][];
+/**
+ * Map over items with a bounded number of concurrent workers. Used to fan out upstream
+ * fetches (per-exercise history, the CLI export) without bursting the host all at once or,
+ * on workerd, blowing the subrequest budget.
+ */
+declare function mapPool<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
 /**
  * The exercise-library surface the tools depend on, so the tools work over either a
  * D1-backed mirror (hosted, multi-tenant) or an in-memory cache (local, single-user).
@@ -106,6 +123,117 @@ interface ExerciseIndex {
   stats(): Promise<Record<string, unknown>>;
 }
 //#endregion
+//#region src/athlete.d.ts
+/**
+ * The logged-in account's numeric user id (the athlete warehouse's tenant key, and a required
+ * query arg for several athlete endpoints). Works from any session — coach or athlete — and
+ * even from a cached session that never went through login.
+ */
+declare function resolveAthleteUserId(client: TrainHeroicClient): Promise<number>;
+/** Lifetime training totals. `use_metric` is required by the API (omitting it 400s). */
+declare function fetchAthleteProfileSummary(client: TrainHeroicClient, userId: number, useMetric?: boolean): Promise<AthleteProfileSummary>;
+declare function fetchAthleteUser(client: TrainHeroicClient, userId: number): Promise<AthleteUser>;
+declare function fetchAthletePrefs(client: TrainHeroicClient): Promise<AthletePrefs>;
+declare function fetchWorkingMaxes(client: TrainHeroicClient): Promise<AthleteWorkingMax[]>;
+declare function fetchExerciseHistoryList(client: TrainHeroicClient): Promise<ExerciseHistoryListItem[]>;
+/** Free-text search over the athlete's logged exercises (FTS replacement via rankSearch). */
+declare function searchExerciseHistory(client: TrainHeroicClient, query: string, limit?: number): Promise<ExerciseHistoryListItem[]>;
+declare function fetchExerciseHistoryDetail(client: TrainHeroicClient, exerciseId: number, userId: number): Promise<ExerciseHistoryDetail>;
+declare function fetchPersonalRecords(client: TrainHeroicClient, exerciseId: number): Promise<PersonalRecord[]>;
+/** Last performance + PR for an exercise. `date` (YYYY-MM-DD) is required by the API. */
+declare function fetchExerciseStats(client: TrainHeroicClient, exerciseId: number, userId: number, date: string): Promise<ExerciseStats>;
+/** Scheduled + completed workouts in an inclusive YYYY-MM-DD window. */
+declare function fetchAthleteWorkouts(client: TrainHeroicClient, startDate: string, endDate: string): Promise<ProgramWorkout[]>;
+declare function fetchLeaderboard(client: TrainHeroicClient, workoutId: number, opts?: {
+  page?: number;
+  pageSize?: number;
+  gender?: number;
+}): Promise<unknown>;
+/** Flatten one `/3.0/athlete/programworkout/range` item into a readable workout. */
+declare function presentAthleteWorkout(raw: ProgramWorkout): AthleteWorkoutView;
+declare function presentAthleteWorkouts(list: readonly ProgramWorkout[]): AthleteWorkoutView[];
+/**
+ * One set of entered values for a single exercise within a saved workout set.
+ * `param1` and `param2` correspond to the exercise's first and second parameter types
+ * (e.g. reps and weight). At most 10 sets are supported.
+ */
+type SetResult = {
+  savedWorkoutSetExerciseId: number;
+  sets: Array<{
+    param1?: number | string;
+    param2?: number | string;
+  }>;
+};
+/**
+ * Build the body for `PUT /1.0/athlete/savedworkoutsetexercise/{id}`. The body uses
+ * snake_case keys matching the live API response shape. Each set slot (1-10) gets a
+ * `param_N_made` flag (1 if data is present, 0 otherwise) and `param_1_data_N` /
+ * `param_2_data_N` string values.
+ *
+ * Only `savedWorkoutSetExerciseId`, `savedWorkoutSetId`, and `workoutSetExerciseId` are
+ * required from the live exercise record; everything else is derived from `results`.
+ *
+ * Exported for unit testing — callers should use `logAthleteSet` instead.
+ */
+declare function buildExerciseLogPayload(savedWorkoutSetExerciseId: number, savedWorkoutSetId: number, workoutSetExerciseId: number, results: readonly {
+  param1?: number | string;
+  param2?: number | string;
+}[]): Record<string, unknown>;
+/**
+ * Locate the target saved workout set across all program workouts on the given day.
+ * Returns the `savedWorkoutId`, the matching set's `workoutSetExercises` array so callers
+ * can look up `workout_set_exercise_id` by `savedWorkoutSetExerciseId`, and the raw set
+ * record so callers can build the set-completion PUT body via `buildSetCompletePayload`.
+ */
+declare function findSavedWorkoutSet(workouts: readonly ProgramWorkout[], savedWorkoutSetId: number): {
+  savedWorkoutId: number;
+  exercises: Record<string, unknown>[];
+  rawSet: Record<string, unknown>;
+};
+/**
+ * Build the body for `PUT /1.0/athlete/savedworkoutset/{id}` that marks the set completed.
+ *
+ * The API requires the **app's camelCase in-memory model**, not the snake_case shape the
+ * GET endpoints return. Key field mappings from the raw set record:
+ *   saved_workout_id   → sessionId
+ *   workout_set_id     → workoutSetId
+ *   is_super_set (0/1) → isSuperSet (boolean)
+ *   plain_text (0/1)   → isPlainText (boolean)
+ *   unit ("lb"/"kg")   → isMetric (boolean)
+ *   workoutSetExercises[].id → exercises (array of IDs)
+ *
+ * `exerciseIds` must be the savedWorkoutSetExercise IDs (not workout_set_exercise_ids).
+ *
+ * Exported for unit testing — callers should use `logAthleteSet` instead.
+ */
+declare function buildSetCompletePayload(rawSet: Record<string, unknown>, exerciseIds: readonly number[], complete: boolean): Record<string, unknown>;
+/**
+ * Record entered set results for one saved workout set.
+ *
+ * **Two-step write (both required for data to persist):**
+ * 1. For each exercise in `results`:
+ *    `PUT /1.0/athlete/savedworkoutsetexercise/{savedWorkoutSetExerciseId}` with the
+ *    per-slot `param_N_data_M` values. This is the only path that actually stores reps
+ *    and weight — the `savedworkoutset` PUT accepts the same fields but silently discards
+ *    them.
+ * 2. `PUT /1.0/athlete/savedworkoutset/{savedWorkoutSetId}` with `completed:"1"` to
+ *    mark the block done and make the entry visible as a logged set in history.
+ *
+ * The date is used to locate the saved workout (via the range endpoint) so we can resolve
+ * `saved_workout_id` and `workout_set_exercise_id` for each exercise. Both are required
+ * by the respective PUT bodies.
+ */
+declare function logAthleteSet(client: TrainHeroicClient, args: {
+  date: string;
+  savedWorkoutSetId: number;
+  results: readonly SetResult[];
+}): Promise<{
+  savedWorkoutSetId: number;
+  exercisesLogged: number;
+}>;
+/** Flatten `/v5/exercises/{id}/history` into PRs + a session time-series. */
+declare function presentExerciseHistory(detail: ExerciseHistoryDetail): PresentedExerciseHistory;
+//#endregion
 //#region src/workout-encode.d.ts
 declare const LEADERBOARD_TYPE: Readonly<Record<string, number>>;
 declare const LEADERBOARD_LABEL: Readonly<Record<number, string>>;
@@ -195,4 +323,4 @@ declare class ExerciseLibrary implements ExerciseIndex {
   stats(): Promise<Record<string, unknown>>;
 }
 //#endregion
-export { ApiBase, BuildOptions, ClientResult, ExerciseIndex, ExerciseLibrary, LEADERBOARD_LABEL, LEADERBOARD_TYPE, Leaderboard, LibraryCache, LibrarySnapshot, MemoryLibraryCache, PARAM_NONE, PARAM_PCT_MAX, PARAM_REPS, PARAM_RPE, PARAM_UNIT, PARAM_WEIGHT, RequestOptions, TrainHeroicAuthError, TrainHeroicClient, TrainHeroicSession, asExerciseList, buildBlockPayload, buildCommentPayload, buildSearchText, buildSession, checkResponse, chunk, coerceInt, coerceNum, collectAdvisories, deleteComment, fetchStreams, isRecord, loginTrainHeroic, makeExercise, publishSession, rankSearch, readLive, readSession, removeSession, repsList, resolveLeaderboard, sendComment, setSessionInstruction, unitAdvisory, unitLabel, unwrapEnvelope, withUnits };
+export { ApiBase, BuildOptions, ClientResult, ExerciseIndex, ExerciseLibrary, LEADERBOARD_LABEL, LEADERBOARD_TYPE, Leaderboard, LibraryCache, LibrarySnapshot, MemoryLibraryCache, PARAM_NONE, PARAM_PCT_MAX, PARAM_REPS, PARAM_RPE, PARAM_UNIT, PARAM_WEIGHT, RequestOptions, SetResult, TrainHeroicAuthError, TrainHeroicClient, TrainHeroicSession, asExerciseList, buildBlockPayload, buildCommentPayload, buildExerciseLogPayload, buildSearchText, buildSession, buildSetCompletePayload, checkResponse, chunk, coerceInt, coerceNum, collectAdvisories, deleteComment, exerciseUnits, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteUser, fetchAthleteWorkouts, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchStreams, fetchWorkingMaxes, findSavedWorkoutSet, isRecord, logAthleteSet, loginTrainHeroic, makeExercise, mapPool, presentAthleteWorkout, presentAthleteWorkouts, presentExercise, presentExerciseHistory, publishSession, rankSearch, readLive, readSession, removeSession, repsList, resolveAthleteUserId, resolveLeaderboard, searchExerciseHistory, sendComment, setSessionInstruction, unitAdvisory, unitLabel, unwrapEnvelope, withUnits };

package/dist/index.mjs

@@ -175,12 +175,31 @@ function unitLabel(paramType) {
 	if (t === null) return null;
 	return PARAM_UNIT[t] ?? null;
 }
-/** Annotate a row with human-readable units for display. */
+/**
+* Fixed measurement units for an exercise, ordered by entry slot (param 1, then param 2).
+* Positional, not semantic: some exercises reverse the slots, so the array is not labelled
+* by role. A null entry is an unset slot.
+*/
+function exerciseUnits(param1, param2) {
+	return [unitLabel(param1), unitLabel(param2)];
+}
+/** Present a row for display: drop the raw param-type codes, surface units positionally. */
 function withUnits(row) {
+	const { param_1_type, param_2_type, ...rest } = row;
+	return {
+		...rest,
+		units: exerciseUnits(param_1_type, param_2_type)
+	};
+}
+/**
+* Present a full raw exercise object for display: drop the raw param-type codes and add the
+* positional `units` array. Keeps every other field of the raw object intact.
+*/
+function presentExercise(raw) {
+	const { param_1_type, param_2_type, ...rest } = raw;
 	return {
-		...row,
-		param_1_unit: unitLabel(row.param_1_type),
-		param_2_unit: unitLabel(row.param_2_type)
+		...rest,
+		units: exerciseUnits(param_1_type, param_2_type)
 	};
 }
 function buildSearchText(title) {
@@ -242,7 +261,7 @@ function rankSearch(rows, query, limit) {
 		if (title.startsWith(q)) score += 100;
 		for (const tok of tokens) if (title.includes(tok)) score += 10;
 		score -= title.length * .05;
-		if (row.can_edit === 0) score += 1;
+		if ((row.can_edit ?? 0) === 0) score += 1;
 		return {
 			row,
 			score
@@ -254,6 +273,307 @@ function chunk(items, size) {
 	for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
 	return out;
 }
+/**
+* Map over items with a bounded number of concurrent workers. Used to fan out upstream
+* fetches (per-exercise history, the CLI export) without bursting the host all at once or,
+* on workerd, blowing the subrequest budget.
+*/
+async function mapPool(items, limit, fn) {
+	const out = Array.from({ length: items.length });
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) {
+			const i = next;
+			next += 1;
+			out[i] = await fn(items[i], i);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()));
+	return out;
+}
+//#endregion
+//#region src/athlete.ts
+async function getJson(client, path, label) {
+	const res = await client.request("GET", path);
+	if (!res.ok) throw new Error(`${label} failed (HTTP ${res.status}).`);
+	return res.data;
+}
+async function getArray(client, path, label) {
+	const res = await client.request("GET", path);
+	if (!res.ok || !Array.isArray(res.data)) throw new Error(`${label} failed (HTTP ${res.status}).`);
+	return res.data;
+}
+/**
+* The logged-in account's numeric user id (the athlete warehouse's tenant key, and a required
+* query arg for several athlete endpoints). Works from any session — coach or athlete — and
+* even from a cached session that never went through login.
+*/
+async function resolveAthleteUserId(client) {
+	const res = await client.request("GET", "/user/simple");
+	const id = isRecord(res.data) ? coerceInt(res.data.id) : null;
+	if (!res.ok || id === null || id <= 0) throw new Error("Could not resolve athlete user id from /user/simple.");
+	return id;
+}
+/** Lifetime training totals. `use_metric` is required by the API (omitting it 400s). */
+function fetchAthleteProfileSummary(client, userId, useMetric = false) {
+	return getJson(client, `/v5/athleteProfile/summary?user_id=${userId}&use_metric=${useMetric ? 1 : 0}`, "athlete profile summary");
+}
+function fetchAthleteUser(client, userId) {
+	return getJson(client, `/v5/users/${userId}`, "athlete user");
+}
+function fetchAthletePrefs(client) {
+	return getJson(client, "/1.0/athlete/prefs", "athlete prefs");
+}
+function fetchWorkingMaxes(client) {
+	return getArray(client, "/2.0/athlete/workingMax", "athlete working maxes");
+}
+function fetchExerciseHistoryList(client) {
+	return getArray(client, "/v5/users/exercises/history", "athlete exercise history list");
+}
+/** Free-text search over the athlete's logged exercises (FTS replacement via rankSearch). */
+async function searchExerciseHistory(client, query, limit = 20) {
+	return rankSearch(await fetchExerciseHistoryList(client), query, limit);
+}
+function fetchExerciseHistoryDetail(client, exerciseId, userId) {
+	return getJson(client, `/v5/exercises/${exerciseId}/history?userId=${userId}`, "athlete exercise history");
+}
+function fetchPersonalRecords(client, exerciseId) {
+	return getArray(client, `/v5/exercises/${exerciseId}/personalRecords`, "athlete personal records");
+}
+/** Last performance + PR for an exercise. `date` (YYYY-MM-DD) is required by the API. */
+function fetchExerciseStats(client, exerciseId, userId, date) {
+	return getJson(client, `/v5/exercises/${exerciseId}/stats?userId=${userId}&date=${date}`, "athlete exercise stats");
+}
+/** Scheduled + completed workouts in an inclusive YYYY-MM-DD window. */
+function fetchAthleteWorkouts(client, startDate, endDate) {
+	return getArray(client, `/3.0/athlete/programworkout/range?startDate=${startDate}&endDate=${endDate}`, "athlete workouts");
+}
+function fetchLeaderboard(client, workoutId, opts = {}) {
+	const qs = new URLSearchParams();
+	if (opts.page !== void 0) qs.set("page", String(opts.page));
+	if (opts.pageSize !== void 0) qs.set("pageSize", String(opts.pageSize));
+	if (opts.gender !== void 0) qs.set("gender", String(opts.gender));
+	const query = qs.toString();
+	return getJson(client, `/3.0/athlete/leaderboard/${workoutId}${query ? `?${query}` : ""}`, "athlete leaderboard");
+}
+const SLOTS = 10;
+function nonEmpty(value) {
+	return value !== void 0 && value !== null && String(value).trim() !== "";
+}
+/**
+* Per-set prescriptions from the param_N_data slots, e.g. ["5 @ 225", "3 @ 245"] or ["AMRAP"].
+* Values are kept raw (a non-numeric prescription like "AMRAP" or "8-12" must survive); the
+* positional units come from the exercise's param types, mirroring the coach presenter.
+*/
+function prescribedSets(ex) {
+	const out = [];
+	for (let i = 1; i <= SLOTS; i += 1) {
+		const p1 = ex[`param_1_data_${i}`];
+		const p2 = ex[`param_2_data_${i}`];
+		const has1 = nonEmpty(p1);
+		const has2 = nonEmpty(p2);
+		if (!has1 && !has2) continue;
+		if (has1 && has2) out.push(`${p1} @ ${p2}`);
+		else if (has1) out.push(String(p1));
+		else out.push(`@ ${p2}`);
+	}
+	return out;
+}
+function presentExercise$1(ex) {
+	const instruction = typeof ex.instruction === "string" && ex.instruction !== "" ? ex.instruction : null;
+	return {
+		exerciseId: coerceInt(ex.exercise_id),
+		title: typeof ex.title === "string" ? ex.title : "",
+		instruction,
+		units: exerciseUnits(ex.param_1_type, ex.param_2_type),
+		prescribed: prescribedSets(ex)
+	};
+}
+function presentBlock(set) {
+	const exercises = Array.isArray(set.workoutSetExercises) ? set.workoutSetExercises : [];
+	return {
+		order: coerceInt(set.order) ?? 0,
+		title: typeof set.title === "string" && set.title !== "" ? set.title : null,
+		instruction: typeof set.instruction === "string" && set.instruction !== "" ? set.instruction : null,
+		isTest: coerceInt(set.is_test) === 1,
+		exercises: exercises.filter(isRecord).map(presentExercise$1)
+	};
+}
+function str$1(v) {
+	return typeof v === "string" && v !== "" ? v : null;
+}
+/** Flatten one `/3.0/athlete/programworkout/range` item into a readable workout. */
+function presentAthleteWorkout(raw) {
+	const rec = raw;
+	const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
+	const workout = isRecord(ssw.workout) ? ssw.workout : {};
+	const sets = Array.isArray(workout.workoutSets) ? workout.workoutSets : [];
+	return {
+		id: coerceInt(rec.id),
+		date: str$1(rec.date) ?? "",
+		title: str$1(rec.workout_title) ?? "",
+		program: str$1(rec.program_title),
+		team: str$1(rec.team_title),
+		instruction: str$1(workout.instruction),
+		blocks: sets.filter(isRecord).map(presentBlock).sort((a, b) => a.order - b.order)
+	};
+}
+function presentAthleteWorkouts(list) {
+	return list.map(presentAthleteWorkout);
+}
+const MAX_PARAM_SLOTS = 10;
+/**
+* Build the body for `PUT /1.0/athlete/savedworkoutsetexercise/{id}`. The body uses
+* snake_case keys matching the live API response shape. Each set slot (1-10) gets a
+* `param_N_made` flag (1 if data is present, 0 otherwise) and `param_1_data_N` /
+* `param_2_data_N` string values.
+*
+* Only `savedWorkoutSetExerciseId`, `savedWorkoutSetId`, and `workoutSetExerciseId` are
+* required from the live exercise record; everything else is derived from `results`.
+*
+* Exported for unit testing — callers should use `logAthleteSet` instead.
+*/
+function buildExerciseLogPayload(savedWorkoutSetExerciseId, savedWorkoutSetId, workoutSetExerciseId, results) {
+	if (results.length > MAX_PARAM_SLOTS) throw new Error(`At most ${MAX_PARAM_SLOTS} sets are supported per exercise; got ${results.length}.`);
+	const body = {
+		id: savedWorkoutSetExerciseId,
+		saved_workout_set_id: savedWorkoutSetId,
+		workout_set_exercise_id: workoutSetExerciseId,
+		completed: results.some((s) => s.param1 !== void 0 || s.param2 !== void 0) ? 1 : 0
+	};
+	for (let i = 1; i <= MAX_PARAM_SLOTS; i += 1) {
+		const slot = results[i - 1];
+		const p1 = slot?.param1 !== void 0 ? String(slot.param1) : "";
+		const p2 = slot?.param2 !== void 0 ? String(slot.param2) : "";
+		body[`param_${i}_made`] = p1 !== "" || p2 !== "" ? 1 : 0;
+		body[`param_1_data_${i}`] = p1;
+		body[`param_2_data_${i}`] = p2;
+	}
+	return body;
+}
+/**
+* Locate the target saved workout set across all program workouts on the given day.
+* Returns the `savedWorkoutId`, the matching set's `workoutSetExercises` array so callers
+* can look up `workout_set_exercise_id` by `savedWorkoutSetExerciseId`, and the raw set
+* record so callers can build the set-completion PUT body via `buildSetCompletePayload`.
+*/
+function findSavedWorkoutSet(workouts, savedWorkoutSetId) {
+	for (const pw of workouts) {
+		const rec = pw;
+		const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
+		const sw = isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
+		if (!sw) continue;
+		const sets = Array.isArray(sw.workoutSets) ? sw.workoutSets : [];
+		for (const s of sets) {
+			if (!isRecord(s)) continue;
+			if (coerceInt(s.id) === savedWorkoutSetId) {
+				const savedWorkoutId = coerceInt(sw.id);
+				if (!savedWorkoutId) continue;
+				return {
+					savedWorkoutId,
+					exercises: Array.isArray(s.workoutSetExercises) ? s.workoutSetExercises.filter(isRecord) : [],
+					rawSet: s
+				};
+			}
+		}
+	}
+	throw new Error(`Saved workout set ${savedWorkoutSetId} not found on this date.`);
+}
+/**
+* Build the body for `PUT /1.0/athlete/savedworkoutset/{id}` that marks the set completed.
+*
+* The API requires the **app's camelCase in-memory model**, not the snake_case shape the
+* GET endpoints return. Key field mappings from the raw set record:
+*   saved_workout_id   → sessionId
+*   workout_set_id     → workoutSetId
+*   is_super_set (0/1) → isSuperSet (boolean)
+*   plain_text (0/1)   → isPlainText (boolean)
+*   unit ("lb"/"kg")   → isMetric (boolean)
+*   workoutSetExercises[].id → exercises (array of IDs)
+*
+* `exerciseIds` must be the savedWorkoutSetExercise IDs (not workout_set_exercise_ids).
+*
+* Exported for unit testing — callers should use `logAthleteSet` instead.
+*/
+function buildSetCompletePayload(rawSet, exerciseIds, complete) {
+	const id = coerceInt(rawSet.id);
+	const sessionId = coerceInt(rawSet.saved_workout_id);
+	const workoutSetId = coerceInt(rawSet.workout_set_id);
+	if (!id || !sessionId || !workoutSetId) throw new Error("Raw set is missing required id / saved_workout_id / workout_set_id.");
+	const unit = typeof rawSet.unit === "string" ? rawSet.unit : "";
+	return {
+		id,
+		sessionId,
+		workoutSetId,
+		completed: complete ? "1" : "0",
+		rx: coerceInt(rawSet.rx) ?? 0,
+		version: coerceInt(rawSet.version) ?? 0,
+		isMetric: unit.toLowerCase() === "kg",
+		isSuperSet: rawSet.is_super_set === 1 || rawSet.is_super_set === true,
+		isPlainText: rawSet.plain_text === 1 || rawSet.plain_text === true,
+		title: typeof rawSet.title === "string" ? rawSet.title : "",
+		instruction: typeof rawSet.instruction === "string" ? rawSet.instruction : "",
+		notes: rawSet.notes ?? null,
+		exercises: [...exerciseIds]
+	};
+}
+/**
+* Record entered set results for one saved workout set.
+*
+* **Two-step write (both required for data to persist):**
+* 1. For each exercise in `results`:
+*    `PUT /1.0/athlete/savedworkoutsetexercise/{savedWorkoutSetExerciseId}` with the
+*    per-slot `param_N_data_M` values. This is the only path that actually stores reps
+*    and weight — the `savedworkoutset` PUT accepts the same fields but silently discards
+*    them.
+* 2. `PUT /1.0/athlete/savedworkoutset/{savedWorkoutSetId}` with `completed:"1"` to
+*    mark the block done and make the entry visible as a logged set in history.
+*
+* The date is used to locate the saved workout (via the range endpoint) so we can resolve
+* `saved_workout_id` and `workout_set_exercise_id` for each exercise. Both are required
+* by the respective PUT bodies.
+*/
+async function logAthleteSet(client, args) {
+	const { exercises, rawSet } = findSavedWorkoutSet(await fetchAthleteWorkouts(client, args.date, args.date), args.savedWorkoutSetId);
+	let exercisesLogged = 0;
+	for (const result of args.results) {
+		const ex = exercises.find((e) => coerceInt(e.id) === result.savedWorkoutSetExerciseId);
+		if (!ex) throw new Error(`savedWorkoutSetExerciseId ${result.savedWorkoutSetExerciseId} not found in saved workout set ${args.savedWorkoutSetId}.`);
+		const workoutSetExerciseId = coerceInt(ex.workout_set_exercise_id);
+		if (!workoutSetExerciseId) throw new Error(`Could not resolve workout_set_exercise_id for exercise ${result.savedWorkoutSetExerciseId}.`);
+		const body = buildExerciseLogPayload(result.savedWorkoutSetExerciseId, args.savedWorkoutSetId, workoutSetExerciseId, result.sets);
+		const res = await client.request("PUT", `/1.0/athlete/savedworkoutsetexercise/${result.savedWorkoutSetExerciseId}`, { body });
+		if (!res.ok) throw new Error(`Failed to log exercise ${result.savedWorkoutSetExerciseId} (HTTP ${res.status}).`);
+		exercisesLogged += 1;
+	}
+	const setBody = buildSetCompletePayload(rawSet, exercises.map((e) => coerceInt(e.id)).filter((n) => n !== null), true);
+	const setRes = await client.request("PUT", `/1.0/athlete/savedworkoutset/${args.savedWorkoutSetId}`, { body: setBody });
+	if (!setRes.ok) throw new Error(`Failed to mark workout set ${args.savedWorkoutSetId} completed (HTTP ${setRes.status}).`);
+	return {
+		savedWorkoutSetId: args.savedWorkoutSetId,
+		exercisesLogged
+	};
+}
+/** Flatten `/v5/exercises/{id}/history` into PRs + a session time-series. */
+function presentExerciseHistory(detail) {
+	return {
+		liftPRs: (detail.liftPRs ?? []).map((p) => ({
+			description: p.description ?? null,
+			reps: p.reps ?? null,
+			weight: p.weight ?? null,
+			date: p.dateCompleted ?? null
+		})),
+		sessions: (detail.history ?? []).map((h) => ({
+			date: h.dateCompleted,
+			abr: h.abr ?? null,
+			estimated1RM: h.bestEstimated1RM ?? null,
+			sets: (h.sets ?? []).map((s) => ({
+				setNumber: s.setNumber,
+				value: s.formattedValue ?? null
+			}))
+		}))
+	};
+}
 //#endregion
 //#region src/workout-encode.ts
 const LEADERBOARD_TYPE = {
@@ -741,10 +1061,7 @@ var ExerciseLibrary = class {
 		await this.ensureFresh();
 		const s = this.#byId.get(id);
 		if (!s) return null;
-		const full = { ...s.raw };
-		full.param_1_unit = unitLabel(full.param_1_type);
-		full.param_2_unit = unitLabel(full.param_2_type);
-		return full;
+		return presentExercise(s.raw);
 	}
 	async defaults(id) {
 		const s = this.#byId.get(id);
@@ -824,4 +1141,4 @@ var ExerciseLibrary = class {
 	}
 };
 //#endregion
-export { ExerciseLibrary, LEADERBOARD_LABEL, LEADERBOARD_TYPE, MemoryLibraryCache, PARAM_NONE, PARAM_PCT_MAX, PARAM_REPS, PARAM_RPE, PARAM_UNIT, PARAM_WEIGHT, TrainHeroicAuthError, TrainHeroicClient, asExerciseList, buildBlockPayload, buildCommentPayload, buildSearchText, buildSession, checkResponse, chunk, coerceInt, coerceNum, collectAdvisories, deleteComment, fetchStreams, isRecord, loginTrainHeroic, makeExercise, publishSession, rankSearch, readLive, readSession, removeSession, repsList, resolveLeaderboard, sendComment, setSessionInstruction, unitAdvisory, unitLabel, unwrapEnvelope, withUnits };
+export { ExerciseLibrary, LEADERBOARD_LABEL, LEADERBOARD_TYPE, MemoryLibraryCache, PARAM_NONE, PARAM_PCT_MAX, PARAM_REPS, PARAM_RPE, PARAM_UNIT, PARAM_WEIGHT, TrainHeroicAuthError, TrainHeroicClient, asExerciseList, buildBlockPayload, buildCommentPayload, buildExerciseLogPayload, buildSearchText, buildSession, buildSetCompletePayload, checkResponse, chunk, coerceInt, coerceNum, collectAdvisories, deleteComment, exerciseUnits, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteUser, fetchAthleteWorkouts, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchStreams, fetchWorkingMaxes, findSavedWorkoutSet, isRecord, logAthleteSet, loginTrainHeroic, makeExercise, mapPool, presentAthleteWorkout, presentAthleteWorkouts, presentExercise, presentExerciseHistory, publishSession, rankSearch, readLive, readSession, removeSession, repsList, resolveAthleteUserId, resolveLeaderboard, searchExerciseHistory, sendComment, setSessionInstruction, unitAdvisory, unitLabel, unwrapEnvelope, withUnits };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trainheroic-unofficial/js",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
   ],
   "dependencies": {
     "zod": "^4.4.3",
-    "@trainheroic-unofficial/dto": "0.2.0"
+    "@trainheroic-unofficial/dto": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",