@trainheroic-unofficial/js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alan Cohen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @trainheroic-unofficial/js
+
+An unofficial TypeScript SDK for the TrainHeroic coaching API. It handles auth and session
+renewal, talks to both TrainHeroic hosts, keeps a searchable exercise library, encodes
+workouts into the API's payload format, and wraps messaging. It runs in any modern
+JavaScript runtime, including Cloudflare workerd.
+
+Part of the [trainheroic-unofficial](../../README.md) workspace.
+
+## Two entry points
+
+```ts
+// Runtime-agnostic. Safe in browsers and on workerd.
+import { TrainHeroicClient, ExerciseLibrary, buildSession } from "@trainheroic-unofficial/js";
+
+// Node-only filesystem helpers, kept out of the main entry.
+import { JsonFileLibraryCache, defaultCachePath } from "@trainheroic-unofficial/js/node";
+```
+
+The `.` entry imports no `node:*` modules. Anything that touches the filesystem lives behind
+`./node`, so the SDK stays portable.
+
+## What it covers
+
+- **Client and auth.** `TrainHeroicClient` holds the coach credentials, acquires a session
+  token lazily, and renews it transparently. TrainHeroic issues no refresh token, so on a
+  401/403 the client logs in again with the stored credentials and retries once. A cold
+  client hit by concurrent requests performs a single shared login. `RequestOptions.base`
+  selects the host (`coach` for `api.trainheroic.com`, `apis` for `apis.trainheroic.com`).
+- **Exercises.** `ExerciseIndex` is the interface the rest of the system codes against;
+  `ExerciseLibrary` is the in-memory implementation that resolves names to ids, ranks
+  fuzzy search, and persists through a `LibraryCache` (in-memory by default, JSON file via
+  `./node`). The hosted server supplies a D1-backed implementation of the same interface.
+- **Workouts.** A session builder (create, save blocks and exercises, optionally publish),
+  read-back, instruction editing, and removal, plus the encoder that turns a
+  `WorkoutSpec` into the API's payload.
+- **Messaging.** Listing conversation streams, reading a stream, and building, sending, or
+  deleting a comment.
+
+## The workout encoder
+
+The encoder is the package's hardest-won piece. TrainHeroic's exercise payload expects every
+parameter slot present, so the encoder fills all of them (empty slots included) to avoid an
+HTTP 500. A scalar prescription is broadcast across the set count, RPE is routed into the
+instruction text rather than a numeric slot (the API would otherwise coerce it to load), and
+unit mismatches between a spec and the exercise's fixed parameter types are surfaced as
+advisories instead of silently dropped.
+
+## Develop
+
+```bash
+pnpm build       # tsdown -> dist (separate "." and "./node" outputs)
+pnpm typecheck
+pnpm test
+pnpm exec vitest run test/workout-encode.test.ts          # one file
+pnpm exec vitest run -t "broadcasts a scalar over sets"   # one test
+```

package/dist/index.d.mts

@@ -0,0 +1,198 @@
+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 { ZodType } from "zod";
+export * from "@trainheroic-unofficial/dto";
+
+//#region src/auth.d.ts
+type TrainHeroicSession = {
+  thUserId: number;
+  sessionId: string;
+  scope: string;
+  role: string;
+};
+/**
+ * Authenticate against TrainHeroic. Returns the session bundle, or null on bad
+ * credentials. TrainHeroic returns only { id, scope, role, session_id } (verified in
+ * the Phase 0 spike: no refresh_token, no api_token, no TTL). The 48-char session_id
+ * is sent as the `session-token` header and works against both API hosts.
+ */
+declare function loginTrainHeroic(email: string, password: string): Promise<TrainHeroicSession | null>;
+//#endregion
+//#region src/client.d.ts
+declare class TrainHeroicAuthError extends Error {
+  name: string;
+}
+type ApiBase = "coach" | "apis";
+type RequestOptions = {
+  body?: unknown;
+  base?: ApiBase;
+};
+type ClientResult<T = unknown> = {
+  status: number;
+  ok: boolean;
+  data: T;
+};
+/**
+ * Authenticated TrainHeroic API client. Holds the coach credentials (from the grant's
+ * encrypted props) and a lazily-acquired session token cached in memory for the life
+ * of the Durable Object instance. On a 401/403 it re-logs in once and retries, since
+ * TrainHeroic has no refresh token and sessions expire after ~1-2h.
+ */
+declare class TrainHeroicClient {
+  #private;
+  constructor(email: string, password: string, sessionId?: string | null);
+  get sessionId(): string | null;
+  request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<ClientResult<T>>;
+}
+//#endregion
+//#region src/response-check.d.ts
+/**
+ * Validate an API response against its (loose) expected shape and warn once on drift.
+ * Never throws: callers keep working via defensive coercion. This only surfaces a signal
+ * when TrainHeroic renames or drops a field we read.
+ */
+declare function checkResponse(schema: ZodType, data: unknown, label: string): void;
+//#endregion
+//#region src/exercise-util.d.ts
+/**
+ * Display labels for TrainHeroic parameter types. The unit is FIXED PER EXERCISE
+ * (the API forces param_1_type/param_2_type back to the library default on save), so
+ * resolve/search surface it to stop callers picking, say, the miles "Run" for a
+ * metric workout. Keep in sync with the workout builder's unit table.
+ */
+declare const PARAM_UNIT: Readonly<Record<number, string | null>>;
+declare const PARAM_NONE = 0;
+declare const PARAM_WEIGHT = 1;
+declare const PARAM_PCT_MAX = 2;
+declare const PARAM_REPS = 3;
+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. */
+declare function withUnits(row: ExerciseRow): ExerciseView;
+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;
+/** Pull the exercise array out of whatever shape the bulk endpoint returns. */
+declare function asExerciseList(body: unknown): Array<Record<string, unknown>>;
+declare function isRecord(x: unknown): x is Record<string, unknown>;
+/**
+ * Rank candidate rows for a free-text query (FTS5 replacement). Higher is better:
+ * exact title, then prefix, then count of matched tokens, with shorter titles and
+ * standard (non-custom) exercises preferred on ties.
+ */
+declare function rankSearch<T extends {
+  title: string;
+  can_edit: number;
+}>(rows: readonly T[], query: string, limit: number): T[];
+declare function chunk<T>(items: readonly T[], size: number): T[][];
+/**
+ * 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).
+ */
+interface ExerciseIndex {
+  ensureFresh(): Promise<void>;
+  refresh(): Promise<Record<string, unknown>>;
+  resolve(name: string): Promise<ResolveResult>;
+  search(query: string, limit?: number): Promise<ExerciseView[]>;
+  get(id: number): Promise<Record<string, unknown> | null>;
+  defaults(id: number): Promise<{
+    param1: number | null;
+    param2: number | null;
+  } | null>;
+  create(body: Record<string, unknown>): Promise<Record<string, unknown>>;
+  recordDelete(id: number): Promise<void>;
+  stats(): Promise<Record<string, unknown>>;
+}
+//#endregion
+//#region src/workout-encode.d.ts
+declare const LEADERBOARD_TYPE: Readonly<Record<string, number>>;
+declare const LEADERBOARD_LABEL: Readonly<Record<number, string>>;
+type Leaderboard = {
+  isRedzone: number | null;
+  redzoneType: number;
+  smallerIsBetter: number | null;
+  redzoneInstruction: string;
+};
+declare function resolveLeaderboard(block: BlockSpec): Leaderboard;
+declare function repsList(ex: ExerciseSpec): string[];
+/** Build one saveWorkoutSetExercises payload entry with all ten param slots filled. */
+declare function makeExercise(ex: ExerciseSpec, workoutSetId: number, order: number, key: string): Record<string, unknown>;
+declare function buildBlockPayload(blocks: readonly BlockSpec[], workoutId: number): Array<Record<string, unknown>>;
+/** Flag spec params the API will silently override to the exercise's fixed units. */
+declare function unitAdvisory(blockTitle: string, ex: ExerciseSpec, defaults: {
+  param1: number | null;
+  param2: number | null;
+}): Advisory;
+/**
+ * Run unit advisories across a whole block list against an exercise index. Shared by the
+ * MCP workout_build tool and the CLI so both surface the same notes/warnings. Ensures the
+ * index is loaded first, otherwise `defaults` returns null on a cold index and every
+ * advisory is silently dropped.
+ */
+declare function collectAdvisories(blocks: readonly BlockSpec[], index: ExerciseIndex): Promise<Advisory>;
+//#endregion
+//#region src/workout-session.d.ts
+type BuildOptions = {
+  programId: number;
+  blocks: BlockSpec[];
+  date?: WorkoutDate;
+  timelineDay?: number;
+  publish?: boolean; /** Optional session-level note ("Coach Instructions"), set after the blocks save. */
+  instruction?: string;
+};
+declare function buildSession(client: TrainHeroicClient, opts: BuildOptions): Promise<{
+  pwId: number;
+  workoutId: number;
+}>;
+/**
+ * Set a session's Coach Instructions (the day-note at the top of a session). `pw` is the
+ * programWorkout object (the create-time response or a day's edit-GET entry). The PUT wants
+ * the whole object back with `instruction` set and `sets`/`setKeys` as a flat list of block
+ * ids. This does NOT change publish state: `published` is sent exactly as it is on `pw`.
+ */
+declare function setSessionInstruction(client: TrainHeroicClient, workoutId: number, pw: Record<string, unknown>, instruction: string, blockIds: number[]): Promise<void>;
+declare function removeSession(client: TrainHeroicClient, programId: number, pwId: number): Promise<void>;
+declare function publishSession(client: TrainHeroicClient, pwId: number): Promise<void>;
+declare function readSession(client: TrainHeroicClient, programId: number, date: WorkoutDate, pwId: number): Promise<ReadResult>;
+//#endregion
+//#region src/messaging.d.ts
+/** Live list of chat streams, flattened to (stream, kind) tuples. */
+declare function fetchStreams(client: TrainHeroicClient): Promise<Array<{
+  stream: Record<string, unknown>;
+  kind: string;
+}>>;
+/**
+ * The exact chat comment body the web app sends. The non-obvious required field is
+ * `feed_id` (the stream id repeated in the body); omitting it returns 400.
+ */
+declare function buildCommentPayload(streamId: number, text: string, replyTo?: number | null): Record<string, unknown>;
+declare function sendComment(client: TrainHeroicClient, streamId: number, text: string, replyTo?: number | null): Promise<Record<string, unknown>>;
+declare function deleteComment(client: TrainHeroicClient, streamId: number, commentId: number): Promise<unknown>;
+declare function readLive(client: TrainHeroicClient, streamId: number, limit?: number): Promise<unknown[]>;
+//#endregion
+//#region src/exercise-index.d.ts
+/**
+ * The exercise library held in memory for fast queries and persisted through a
+ * LibraryCache (JSON file for a CLI/local server, in-memory by default). Same
+ * resolve/search/unit behavior as the D1-backed store, with no database.
+ */
+declare class ExerciseLibrary implements ExerciseIndex {
+  #private;
+  constructor(client: TrainHeroicClient, cache?: LibraryCache);
+  ensureFresh(): Promise<void>;
+  refresh(): Promise<Record<string, unknown>>;
+  get(id: number): Promise<Record<string, unknown> | null>;
+  defaults(id: number): Promise<{
+    param1: number | null;
+    param2: number | null;
+  } | null>;
+  search(query: string, limit?: number): Promise<ExerciseView[]>;
+  resolve(name: string): Promise<ResolveResult>;
+  create(body: Record<string, unknown>): Promise<Record<string, unknown>>;
+  recordDelete(id: number): Promise<void>;
+  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 };

package/dist/index.mjs

@@ -0,0 +1,827 @@
+import { exerciseLibraryResponseSchema, exerciseResponseSchema, programsEditResponseSchema, sessionCreateResponseSchema } from "@trainheroic-unofficial/dto";
+export * from "@trainheroic-unofficial/dto";
+//#region src/auth.ts
+const AUTH_URL = "https://apis.trainheroic.com/auth";
+/**
+* Authenticate against TrainHeroic. Returns the session bundle, or null on bad
+* credentials. TrainHeroic returns only { id, scope, role, session_id } (verified in
+* the Phase 0 spike: no refresh_token, no api_token, no TTL). The 48-char session_id
+* is sent as the `session-token` header and works against both API hosts.
+*/
+async function loginTrainHeroic(email, password) {
+	const res = await fetch(AUTH_URL, {
+		method: "POST",
+		headers: {
+			"content-type": "application/x-www-form-urlencoded",
+			accept: "application/json"
+		},
+		body: new URLSearchParams({
+			email,
+			password
+		}).toString()
+	});
+	if (!res.ok) return null;
+	const data = await res.json().catch(() => null);
+	if (!data || typeof data.id !== "number" || !data.session_id) return null;
+	return {
+		thUserId: data.id,
+		sessionId: data.session_id,
+		scope: data.scope ?? "",
+		role: data.role ?? ""
+	};
+}
+//#endregion
+//#region src/client.ts
+const COACH_BASE = "https://api.trainheroic.com";
+const APIS_BASE = "https://apis.trainheroic.com";
+var TrainHeroicAuthError = class extends Error {
+	name = "TrainHeroicAuthError";
+};
+/**
+* Authenticated TrainHeroic API client. Holds the coach credentials (from the grant's
+* encrypted props) and a lazily-acquired session token cached in memory for the life
+* of the Durable Object instance. On a 401/403 it re-logs in once and retries, since
+* TrainHeroic has no refresh token and sessions expire after ~1-2h.
+*/
+var TrainHeroicClient = class {
+	#email;
+	#password;
+	#sessionId;
+	#loginInFlight = null;
+	constructor(email, password, sessionId = null) {
+		this.#email = email;
+		this.#password = password;
+		this.#sessionId = sessionId;
+	}
+	get sessionId() {
+		return this.#sessionId;
+	}
+	async #ensureSession() {
+		if (this.#sessionId) return this.#sessionId;
+		this.#loginInFlight ??= this.#login();
+		try {
+			return await this.#loginInFlight;
+		} finally {
+			this.#loginInFlight = null;
+		}
+	}
+	async #login() {
+		const session = await loginTrainHeroic(this.#email, this.#password);
+		if (!session) throw new TrainHeroicAuthError("TrainHeroic login failed");
+		this.#sessionId = session.sessionId;
+		return this.#sessionId;
+	}
+	async request(method, path, options = {}) {
+		const url = `${options.base === "apis" ? APIS_BASE : COACH_BASE}/${path.replace(/^\//, "")}`;
+		let session = await this.#ensureSession();
+		let res = await this.#send(method, url, session, options.body);
+		if (res.status === 401 || res.status === 403) {
+			if (this.#sessionId === session) this.#sessionId = null;
+			session = await this.#ensureSession();
+			res = await this.#send(method, url, session, options.body);
+		}
+		const text = await res.text();
+		let data = text;
+		if (text.length > 0) try {
+			data = JSON.parse(text);
+		} catch {
+			data = text;
+		}
+		return {
+			status: res.status,
+			ok: res.ok,
+			data
+		};
+	}
+	#send(method, url, session, body) {
+		const upper = method.toUpperCase();
+		const headers = {
+			accept: "application/json",
+			"session-token": session
+		};
+		const init = {
+			method: upper,
+			headers
+		};
+		if (body !== void 0 && upper !== "GET" && upper !== "DELETE") {
+			headers["content-type"] = "application/json";
+			init.body = JSON.stringify(body);
+		}
+		return fetch(url, init);
+	}
+};
+//#endregion
+//#region src/response-check.ts
+/**
+* Validate an API response against its (loose) expected shape and warn once on drift.
+* Never throws: callers keep working via defensive coercion. This only surfaces a signal
+* when TrainHeroic renames or drops a field we read.
+*/
+function checkResponse(schema, data, label) {
+	const result = schema.safeParse(data);
+	if (result.success) return;
+	const issue = result.error.issues[0];
+	const where = issue && issue.path.length > 0 ? issue.path.join(".") : "(root)";
+	console.warn(`[trainheroic] response drift in ${label} at ${where}: ${issue?.message ?? "shape mismatch"}`);
+}
+//#endregion
+//#region src/exercise-util.ts
+/**
+* Display labels for TrainHeroic parameter types. The unit is FIXED PER EXERCISE
+* (the API forces param_1_type/param_2_type back to the library default on save), so
+* resolve/search surface it to stop callers picking, say, the miles "Run" for a
+* metric workout. Keep in sync with the workout builder's unit table.
+*/
+const PARAM_UNIT = {
+	0: null,
+	1: "lb",
+	2: "%max",
+	3: "reps",
+	4: "sec",
+	5: "yd",
+	6: "m",
+	7: "in",
+	10: "mi",
+	11: "ft",
+	12: "in",
+	13: "bpm",
+	14: "RPE",
+	18: "sec"
+};
+const PARAM_NONE = 0;
+const PARAM_WEIGHT = 1;
+const PARAM_PCT_MAX = 2;
+const PARAM_REPS = 3;
+const PARAM_RPE = 14;
+function coerceInt(value) {
+	if (typeof value === "boolean") return value ? 1 : 0;
+	if (typeof value === "number") return Number.isFinite(value) ? Math.trunc(value) : null;
+	if (typeof value === "string" && value.trim() !== "") {
+		const n = Number(value);
+		return Number.isFinite(n) ? Math.trunc(n) : null;
+	}
+	return null;
+}
+function coerceNum(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "string" && value.trim() !== "") {
+		const n = Number(value);
+		return Number.isFinite(n) ? n : null;
+	}
+	return null;
+}
+function unitLabel(paramType) {
+	const t = coerceInt(paramType);
+	if (t === null) return null;
+	return PARAM_UNIT[t] ?? null;
+}
+/** Annotate a row with human-readable units for display. */
+function withUnits(row) {
+	return {
+		...row,
+		param_1_unit: unitLabel(row.param_1_type),
+		param_2_unit: unitLabel(row.param_2_type)
+	};
+}
+function buildSearchText(title) {
+	return title.trim().toLowerCase();
+}
+/** Strip the {"success":1,"data":X} envelope some 2.0/coach endpoints use. */
+function unwrapEnvelope(body) {
+	if (body && typeof body === "object" && !Array.isArray(body)) {
+		const obj = body;
+		const keys = new Set(Object.keys(obj));
+		const envelope = /* @__PURE__ */ new Set([
+			"success",
+			"data",
+			"message",
+			"error"
+		]);
+		if ("data" in obj && [...keys].every((k) => envelope.has(k))) return obj.data;
+	}
+	return body;
+}
+/** Pull the exercise array out of whatever shape the bulk endpoint returns. */
+function asExerciseList(body) {
+	const unwrapped = unwrapEnvelope(body);
+	if (Array.isArray(unwrapped)) return unwrapped.filter((x) => isRecord(x));
+	if (isRecord(unwrapped)) {
+		const items = [];
+		for (const key of [
+			"exercises",
+			"circuits",
+			"workoutCircuits",
+			"library",
+			"items",
+			"results"
+		]) {
+			const value = unwrapped[key];
+			if (Array.isArray(value)) items.push(...value.filter((x) => isRecord(x)));
+		}
+		if (items.length > 0) return items;
+		const values = Object.values(unwrapped);
+		if (values.length > 0 && values.every(isRecord)) return values;
+	}
+	return [];
+}
+function isRecord(x) {
+	return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+/**
+* Rank candidate rows for a free-text query (FTS5 replacement). Higher is better:
+* exact title, then prefix, then count of matched tokens, with shorter titles and
+* standard (non-custom) exercises preferred on ties.
+*/
+function rankSearch(rows, query, limit) {
+	const q = query.trim().toLowerCase();
+	const tokens = q.split(/\s+/u).filter((t) => t.length > 0);
+	return rows.map((row) => {
+		const title = row.title.toLowerCase();
+		let score = 0;
+		if (title === q) score += 1e3;
+		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;
+		return {
+			row,
+			score
+		};
+	}).sort((a, b) => b.score - a.score).slice(0, limit).map((s) => s.row);
+}
+function chunk(items, size) {
+	const out = [];
+	for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+	return out;
+}
+//#endregion
+//#region src/workout-encode.ts
+const LEADERBOARD_TYPE = {
+	completion: 0,
+	"for completion": 0,
+	weight: 1,
+	lb: 1,
+	load: 1,
+	reps: 2,
+	rep: 2,
+	rounds: 3,
+	round: 3,
+	time: 4,
+	yards: 5,
+	yd: 5,
+	meters: 6,
+	m: 6,
+	feet: 7,
+	ft: 7,
+	calories: 8,
+	cal: 8,
+	cals: 8,
+	miles: 10,
+	mi: 10,
+	inches: 12,
+	in: 12,
+	watts: 15,
+	w: 15,
+	velocity: 17,
+	"m/s": 17,
+	seconds: 18,
+	sec: 18,
+	s: 18
+};
+const LEADERBOARD_LABEL = {
+	0: "For Completion",
+	1: "Weight",
+	2: "Reps",
+	3: "Rounds",
+	4: "Time",
+	5: "Yards",
+	6: "Meters",
+	7: "Feet",
+	8: "Calories",
+	10: "Miles",
+	12: "Inches",
+	13: "Other",
+	15: "Watts",
+	16: "Percent",
+	17: "Velocity",
+	18: "Seconds"
+};
+function resolveLeaderboard(block) {
+	const lb = block.leaderboard;
+	if (lb === void 0 || lb === null) return {
+		isRedzone: null,
+		redzoneType: 0,
+		smallerIsBetter: null,
+		redzoneInstruction: ""
+	};
+	let unit;
+	let instruction = "";
+	let lowest;
+	if (typeof lb === "object") {
+		unit = lb.unit ?? lb.type;
+		instruction = lb.instruction ?? "";
+		lowest = lb.lowest_wins;
+	} else unit = lb;
+	let rz;
+	if (typeof unit === "string") {
+		const found = LEADERBOARD_TYPE[unit.trim().toLowerCase()];
+		if (found === void 0) throw new Error(`Unknown leaderboard unit '${unit}'. Use one of: ${Object.keys(LEADERBOARD_TYPE).join(", ")}.`);
+		rz = found;
+	} else if (typeof unit === "number") rz = Math.trunc(unit);
+	else throw new Error("Leaderboard requires a unit.");
+	if (lowest === void 0) lowest = rz === 4 || rz === 18;
+	return {
+		isRedzone: 1,
+		redzoneType: rz,
+		smallerIsBetter: lowest ? 1 : 0,
+		redzoneInstruction: instruction
+	};
+}
+function slots(values, n = 10) {
+	const out = [];
+	for (let i = 0; i < n; i += 1) out.push(values && i < values.length ? values[i] ?? "" : "");
+	return out;
+}
+function repsList(ex) {
+	const reps = ex.reps;
+	if (Array.isArray(reps)) return reps.map((r) => String(r));
+	if (reps === void 0 || reps === null) return [];
+	const sets = Math.max(1, Math.trunc(Number(ex.sets ?? 1)) || 1);
+	return Array.from({ length: sets }, () => String(reps));
+}
+/** Build one saveWorkoutSetExercises payload entry with all ten param slots filled. */
+function makeExercise(ex, workoutSetId, order, key) {
+	const reps = repsList(ex);
+	let instruction = ex.instr ?? "";
+	if (instruction === "" && ex.rpe !== void 0 && ex.rpe !== null) instruction = `RPE ${ex.rpe}`;
+	const hasWeight = ex.weight !== void 0 && ex.weight !== null;
+	const weightArr = Array.isArray(ex.weight) ? ex.weight : null;
+	let count = reps.length;
+	if (count === 0 && hasWeight) count = weightArr ? weightArr.length : Math.max(1, Math.trunc(Number(ex.sets ?? 1)) || 1);
+	let param2Type;
+	let param2Values;
+	if (hasWeight) {
+		param2Type = ex.param_2_type ?? 1;
+		param2Values = (weightArr ?? Array.from({ length: count }, () => ex.weight)).map((v) => String(v));
+	} else {
+		param2Type = 0;
+		param2Values = null;
+	}
+	const entry = {
+		exercise_id: ex.id,
+		workout_set_id: workoutSetId,
+		set_id: workoutSetId,
+		setKey: workoutSetId,
+		title: ex.title ?? "",
+		instruction,
+		order,
+		param_1_type: ex.param_1_type ?? 3,
+		param_2_type: param2Type,
+		workout_set_exercise_template_id: null,
+		no_sets: 0,
+		param_count: count,
+		set_num: count,
+		key,
+		video_url: "",
+		thumbnail_url: "",
+		tags: [],
+		eType: "e",
+		use_count: 0
+	};
+	const p1 = slots(reps);
+	const p2 = slots(param2Values);
+	for (let i = 0; i < 10; i += 1) {
+		entry[`param_1_data_${i + 1}`] = p1[i] ?? "";
+		entry[`param_2_data_${i + 1}`] = p2[i] ?? "";
+	}
+	return entry;
+}
+function buildBlockPayload(blocks, workoutId) {
+	return blocks.map((b, i) => {
+		const lb = resolveLeaderboard(b);
+		return {
+			workout_id: workoutId,
+			order: i + 1,
+			type: b.type ?? 2,
+			instruction: b.instruction ?? "",
+			is_redzone: lb.isRedzone,
+			redzone_type: lb.redzoneType,
+			smaller_is_better: lb.smallerIsBetter,
+			redzone_instruction: lb.redzoneInstruction,
+			exercises: [],
+			exerciseKeys: [],
+			key: `k::${workoutId}${i + 1}`,
+			title: b.title
+		};
+	});
+}
+function unitOr(t) {
+	return unitLabel(t) ?? "?";
+}
+/** Flag spec params the API will silently override to the exercise's fixed units. */
+function unitAdvisory(blockTitle, ex, defaults) {
+	const notes = [];
+	const warnings = [];
+	const u = unitOr;
+	const label = `${blockTitle} / ${ex.title ?? ex.id}`;
+	if (Array.isArray(ex.reps) && ex.sets !== void 0 && ex.reps.length !== ex.sets) warnings.push(`${label}: reps array has ${ex.reps.length} entr${ex.reps.length === 1 ? "y" : "ies"}; sets:${ex.sets} is ignored — building ${ex.reps.length} set(s).`);
+	const sentP1 = ex.param_1_type;
+	if (sentP1 !== void 0 && sentP1 !== null && Math.trunc(Number(sentP1)) !== defaults.param1) {
+		const sp1 = Math.trunc(Number(sentP1));
+		warnings.push(`${label}: param_1_type ${sentP1} (${u(sp1)}) is ignored — this exercise is fixed to ${u(defaults.param1)}; values render as ${u(defaults.param1)}.`);
+	} else if (defaults.param1 !== 3 && defaults.param1 !== null) notes.push(`${label}: values are in ${u(defaults.param1)} (the exercise's fixed primary unit).`);
+	if (ex.weight !== void 0 && ex.weight !== null) {
+		const sentP2 = Math.trunc(Number(ex.param_2_type ?? 1));
+		const effP2 = defaults.param2 === 0 || defaults.param2 === null ? 1 : defaults.param2;
+		if (sentP2 !== effP2) if (sentP2 === 2 || sentP2 === 14) warnings.push(`${label}: ${u(sentP2)} does not stick on this exercise — it renders as ${u(effP2)}. Put it in the exercise 'instr' text and leave load blank.`);
+		else warnings.push(`${label}: load renders as ${u(effP2)}, not ${u(sentP2)} (this exercise's secondary unit is fixed).`);
+	}
+	return {
+		notes,
+		warnings
+	};
+}
+/**
+* Run unit advisories across a whole block list against an exercise index. Shared by the
+* MCP workout_build tool and the CLI so both surface the same notes/warnings. Ensures the
+* index is loaded first, otherwise `defaults` returns null on a cold index and every
+* advisory is silently dropped.
+*/
+async function collectAdvisories(blocks, index) {
+	await index.ensureFresh();
+	const pairs = blocks.flatMap((b) => b.exercises.map((ex) => ({
+		block: b,
+		ex
+	})));
+	const defaults = await Promise.all(pairs.map((p) => {
+		const id = Number(p.ex.id);
+		return Number.isFinite(id) ? index.defaults(id) : Promise.resolve(null);
+	}));
+	const notes = [];
+	const warnings = [];
+	pairs.forEach((p, i) => {
+		const def = defaults[i];
+		if (!def) return;
+		const advisory = unitAdvisory(p.block.title, p.ex, def);
+		notes.push(...advisory.notes);
+		warnings.push(...advisory.warnings);
+	});
+	return {
+		notes,
+		warnings
+	};
+}
+//#endregion
+//#region src/workout-session.ts
+async function req(client, method, path, body) {
+	const res = await client.request(method, path, body === void 0 ? void 0 : { body });
+	if (!res.ok) {
+		const detail = typeof res.data === "string" ? res.data : JSON.stringify(res.data);
+		throw new Error(`${method} ${path} failed (HTTP ${res.status}): ${detail}`);
+	}
+	return res.data;
+}
+function createPath(opts) {
+	if (opts.timelineDay !== void 0) return `/2.0/coach/calendar/workout/createWorkoutForTimelineDay/${opts.programId}/${opts.timelineDay}/null`;
+	if (!opts.date) throw new Error("workout build requires either date or timelineDay");
+	const [y, m, d] = opts.date;
+	return `/2.0/coach/calendar/workout/createWorkoutForDay/${opts.programId}/${y}/${m}/${d}/0`;
+}
+async function buildSession(client, opts) {
+	const sess = await req(client, "POST", createPath(opts), {});
+	checkResponse(sessionCreateResponseSchema, sess, "session create");
+	const workoutId = Number(sess.workout_id);
+	const pwId = Number(sess.id);
+	const created = await req(client, "POST", "/2.0/coach/calendar/saveProgramWorkoutSets", buildBlockPayload(opts.blocks, workoutId));
+	const byOrder = new Map(created.map((b) => [b.order, b.id]));
+	let counter = 0;
+	const payloads = opts.blocks.map((block, i) => {
+		const wsid = byOrder.get(i + 1);
+		if (wsid === void 0) throw new Error(`No saved block for order ${i + 1}.`);
+		return block.exercises.map((ex, j) => {
+			counter += 1;
+			return makeExercise(ex, wsid, j + 1, `k::${workoutId}${String(counter).padStart(3, "0")}`);
+		});
+	});
+	await Promise.all(payloads.map((p) => req(client, "POST", "/2.0/coach/calendar/saveWorkoutSetExercises", p)));
+	if (opts.instruction !== void 0 && opts.instruction !== "") {
+		const blockIds = [...byOrder.entries()].sort((a, b) => a[0] - b[0]).map(([, id]) => id);
+		await setSessionInstruction(client, workoutId, sess, opts.instruction, blockIds);
+	}
+	if (opts.publish ?? false) await req(client, "POST", "/2.0/coach/calendar/programWorkout/publish", [pwId]);
+	return {
+		pwId,
+		workoutId
+	};
+}
+/**
+* Set a session's Coach Instructions (the day-note at the top of a session). `pw` is the
+* programWorkout object (the create-time response or a day's edit-GET entry). The PUT wants
+* the whole object back with `instruction` set and `sets`/`setKeys` as a flat list of block
+* ids. This does NOT change publish state: `published` is sent exactly as it is on `pw`.
+*/
+async function setSessionInstruction(client, workoutId, pw, instruction, blockIds) {
+	const body = {
+		...pw,
+		instruction,
+		sets: blockIds,
+		setKeys: blockIds
+	};
+	await req(client, "PUT", `/3.0/coach/workout/${workoutId}`, body);
+}
+async function removeSession(client, programId, pwId) {
+	await req(client, "POST", "/2.0/coach/calendar/removeProgramWorkout", {
+		programId,
+		pwId
+	});
+}
+async function publishSession(client, pwId) {
+	await req(client, "POST", "/2.0/coach/calendar/programWorkout/publish", [pwId]);
+}
+function str(value) {
+	return value === void 0 || value === null ? "" : String(value);
+}
+async function readSession(client, programId, date, pwId) {
+	const [y, m, d] = date;
+	const data = await req(client, "GET", `/1.0/coach/programs/edit/${programId}/${y}/${m}/${d}`);
+	checkResponse(programsEditResponseSchema, data, "programs edit");
+	const pw = (data.programWorkouts ?? []).find((p) => coerceInt(p.id) === pwId);
+	if (!pw) throw new Error(`programWorkout ${pwId} not found on ${y}-${m}-${d}.`);
+	const setsObj = pw.sets ?? {};
+	const blocks = Object.values(setsObj).sort((a, b) => Number(a.order) - Number(b.order)).map((b) => readBlock(b));
+	return {
+		pwId,
+		date: `${str(pw.year)}-${str(pw.month)}-${str(pw.day)}`,
+		published: pw.published,
+		instruction: str(pw.instruction),
+		blocks
+	};
+}
+function readBlock(b) {
+	const rz = coerceInt(b.redzone_type);
+	let leaderboard = null;
+	if (rz && rz > 0) leaderboard = `FOR ${(LEADERBOARD_LABEL[rz] ?? `type ${rz}`).toUpperCase()}${b.smaller_is_better ? " (lowest wins)" : ""}`;
+	const exercises = (Array.isArray(b.exercises) ? b.exercises : []).sort((a, e) => Number(a.order) - Number(e.order)).map((ex) => readExercise(ex));
+	return {
+		order: Number(b.order),
+		title: str(b.title),
+		leaderboard,
+		exercises
+	};
+}
+function readExercise(ex) {
+	const reps = [];
+	const load = [];
+	for (let i = 1; i <= 10; i += 1) {
+		const r = str(ex[`param_1_data_${i}`]);
+		if (r !== "") reps.push(r);
+		const w = str(ex[`param_2_data_${i}`]);
+		if (w !== "") load.push(w);
+	}
+	return {
+		order: Number(ex.order),
+		title: str(ex.title),
+		reps,
+		primaryUnit: unitLabel(coerceInt(ex.param_1_type)),
+		load,
+		loadUnit: unitLabel(coerceInt(ex.param_2_type)),
+		instruction: str(ex.instruction)
+	};
+}
+//#endregion
+//#region src/messaging.ts
+const BUCKETS = [
+	["team", "teams"],
+	["athlete", "athletes"],
+	["program", "programs"],
+	["coach", "coaches"]
+];
+/** Live list of chat streams, flattened to (stream, kind) tuples. */
+async function fetchStreams(client) {
+	const res = await client.request("GET", "/v5/messaging/streams");
+	if (!res.ok || !isRecord(res.data)) throw new Error(`GET /v5/messaging/streams failed (HTTP ${res.status}).`);
+	const out = [];
+	for (const [kind, key] of BUCKETS) {
+		const bucket = res.data[key];
+		if (Array.isArray(bucket)) {
+			for (const s of bucket) if (isRecord(s) && coerceInt(s.id) !== null) out.push({
+				stream: s,
+				kind
+			});
+		}
+	}
+	return out;
+}
+/**
+* The exact chat comment body the web app sends. The non-obvious required field is
+* `feed_id` (the stream id repeated in the body); omitting it returns 400.
+*/
+function buildCommentPayload(streamId, text, replyTo = null) {
+	return {
+		type: 0,
+		content: text,
+		photo_url: "",
+		photoUrl: "",
+		access_level: 0,
+		parent_feed_item_id: replyTo,
+		feed_id: streamId
+	};
+}
+async function sendComment(client, streamId, text, replyTo = null) {
+	const res = await client.request("POST", `/v5/messaging/streams/${streamId}/comments`, { body: buildCommentPayload(streamId, text, replyTo) });
+	if (!res.ok || typeof res.data !== "object" || res.data === null || res.data.id === void 0) throw new Error(`Message send failed (HTTP ${res.status}).`);
+	return res.data;
+}
+async function deleteComment(client, streamId, commentId) {
+	const res = await client.request("DELETE", `/v5/messaging/streams/${streamId}/comments/${commentId}`);
+	if (!res.ok) throw new Error(`Message delete failed (HTTP ${res.status}).`);
+	return res.data;
+}
+async function readLive(client, streamId, limit) {
+	const res = await client.request("GET", `/v5/messaging/streams/${streamId}/comments?lastCommentId=`);
+	if (!res.ok || !Array.isArray(res.data)) throw new Error(`Message read failed (HTTP ${res.status}).`);
+	return limit !== void 0 && limit > 0 ? res.data.slice(-limit) : res.data;
+}
+//#endregion
+//#region src/library-cache.ts
+/** In-memory cache (no persistence). The default when none is supplied. */
+var MemoryLibraryCache = class {
+	#snapshot = null;
+	async load() {
+		return this.#snapshot;
+	}
+	async save(snapshot) {
+		this.#snapshot = snapshot;
+	}
+};
+//#endregion
+//#region src/exercise-index.ts
+const LIBRARY_PATH = "/v5/exerciseLibrary/all";
+const CREATE_PATH = "/2.0/coach/exercise/create";
+const TTL_MS = 168 * 3600 * 1e3;
+function toStored(ex) {
+	const id = coerceInt(ex.id);
+	if (id === null) return null;
+	const title = String(ex.title ?? "");
+	return {
+		id,
+		title,
+		search: buildSearchText(title),
+		param_1_type: coerceInt(ex.param_1_type),
+		param_2_type: coerceInt(ex.param_2_type),
+		can_edit: coerceInt(ex.can_edit) ?? 0,
+		user_id: coerceInt(ex.user_id),
+		use_count: coerceInt(ex.use_count) ?? 0,
+		raw: ex
+	};
+}
+function toRow(s) {
+	return {
+		id: s.id,
+		title: s.title,
+		param_1_type: s.param_1_type,
+		param_2_type: s.param_2_type,
+		can_edit: s.can_edit,
+		user_id: s.user_id,
+		use_count: s.use_count
+	};
+}
+/**
+* The exercise library held in memory for fast queries and persisted through a
+* LibraryCache (JSON file for a CLI/local server, in-memory by default). Same
+* resolve/search/unit behavior as the D1-backed store, with no database.
+*/
+var ExerciseLibrary = class {
+	#client;
+	#cache;
+	#byId = /* @__PURE__ */ new Map();
+	#loaded = false;
+	#fetchedAt = 0;
+	constructor(client, cache = new MemoryLibraryCache()) {
+		this.#client = client;
+		this.#cache = cache;
+	}
+	#hydrate(list, fetchedAt) {
+		const next = /* @__PURE__ */ new Map();
+		for (const ex of list) {
+			const s = toStored(ex);
+			if (s) next.set(s.id, s);
+		}
+		this.#byId = next;
+		this.#fetchedAt = fetchedAt;
+		this.#loaded = true;
+	}
+	async #ensureLoaded() {
+		if (this.#loaded) return;
+		const snap = await this.#cache.load();
+		if (snap && snap.exercises.length > 0 && Date.now() - snap.fetchedAt <= TTL_MS) this.#hydrate(snap.exercises, snap.fetchedAt);
+		else await this.refresh();
+	}
+	async #persist() {
+		await this.#cache.save({
+			fetchedAt: this.#fetchedAt,
+			exercises: [...this.#byId.values()].map((s) => s.raw)
+		});
+	}
+	async ensureFresh() {
+		if (!this.#loaded) await this.#ensureLoaded();
+		else if (Date.now() - this.#fetchedAt > TTL_MS) await this.refresh();
+	}
+	async refresh() {
+		const res = await this.#client.request("GET", LIBRARY_PATH);
+		if (!res.ok) throw new Error(`Exercise library fetch failed (HTTP ${res.status}).`);
+		const list = asExerciseList(res.data);
+		if (list.length === 0) throw new Error("Exercise library returned no rows; keeping the cache.");
+		checkResponse(exerciseLibraryResponseSchema, list, "exercise library");
+		this.#hydrate(list, Date.now());
+		await this.#persist();
+		return { synced: this.#byId.size };
+	}
+	async get(id) {
+		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;
+	}
+	async defaults(id) {
+		const s = this.#byId.get(id);
+		return s ? {
+			param1: s.param_1_type,
+			param2: s.param_2_type
+		} : null;
+	}
+	async search(query, limit = 20) {
+		await this.ensureFresh();
+		return this.#searchOnly(query, limit);
+	}
+	#searchOnly(query, limit) {
+		const tokens = query.toLowerCase().split(/\s+/u).filter((t) => t.length > 0);
+		if (tokens.length === 0) return [];
+		return rankSearch([...this.#byId.values()].filter((s) => tokens.every((t) => s.search.includes(t))).map((s) => toRow(s)), query, limit).map(withUnits);
+	}
+	#exact(name) {
+		const q = name.trim().toLowerCase();
+		const first = [...this.#byId.values()].filter((s) => s.search === q).sort((a, b) => a.can_edit - b.can_edit)[0];
+		return first ? withUnits(toRow(first)) : null;
+	}
+	async resolve(name) {
+		await this.ensureFresh();
+		let hit = this.#exact(name);
+		if (hit) return {
+			match: hit,
+			candidates: [hit]
+		};
+		let candidates = this.#searchOnly(name, 20);
+		if (candidates.length === 0) {
+			await this.refresh();
+			hit = this.#exact(name);
+			if (hit) return {
+				match: hit,
+				candidates: [hit]
+			};
+			candidates = this.#searchOnly(name, 20);
+		}
+		if (candidates.length === 1) return {
+			match: candidates[0] ?? null,
+			candidates
+		};
+		return {
+			match: null,
+			candidates
+		};
+	}
+	async create(body) {
+		await this.ensureFresh();
+		const res = await this.#client.request("POST", CREATE_PATH, { body });
+		if (!res.ok) throw new Error(`Exercise create failed (HTTP ${res.status}).`);
+		const ex = unwrapEnvelope(res.data);
+		if (ex && typeof ex === "object") {
+			checkResponse(exerciseResponseSchema, ex, "exercise create");
+			const s = toStored(ex);
+			if (s) {
+				this.#byId.set(s.id, s);
+				await this.#persist();
+			}
+		}
+		return ex;
+	}
+	async recordDelete(id) {
+		await this.ensureFresh();
+		if (this.#byId.delete(id)) await this.#persist();
+	}
+	async stats() {
+		let custom = 0;
+		for (const s of this.#byId.values()) if (s.can_edit === 1) custom += 1;
+		return {
+			exercises: this.#byId.size,
+			custom,
+			loaded: this.#loaded,
+			fetchedAt: this.#fetchedAt
+		};
+	}
+};
+//#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 };

package/dist/library-cache-CDABOdIN.d.mts

@@ -0,0 +1,22 @@
+//#region src/library-cache.d.ts
+/** A persisted snapshot of the exercise library: the raw rows plus when they were fetched. */
+type LibrarySnapshot = {
+  fetchedAt: number;
+  exercises: Array<Record<string, unknown>>;
+};
+/**
+ * Where ExerciseLibrary persists the library between runs. Abstracted so the library
+ * logic stays runtime-agnostic; the Node JSON-file backend is in the "./node" subpath.
+ */
+interface LibraryCache {
+  load(): Promise<LibrarySnapshot | null>;
+  save(snapshot: LibrarySnapshot): Promise<void>;
+}
+/** In-memory cache (no persistence). The default when none is supplied. */
+declare class MemoryLibraryCache implements LibraryCache {
+  #private;
+  load(): Promise<LibrarySnapshot | null>;
+  save(snapshot: LibrarySnapshot): Promise<void>;
+}
+//#endregion
+export { LibrarySnapshot as n, MemoryLibraryCache as r, LibraryCache as t };

package/dist/node.d.mts

@@ -0,0 +1,14 @@
+import { n as LibrarySnapshot, t as LibraryCache } from "./library-cache-CDABOdIN.mjs";
+
+//#region src/node.d.ts
+/** Default exercise-cache path, overridable with TRAINHEROIC_CACHE_FILE. */
+declare function defaultCachePath(): string;
+/** Persists the exercise library to a JSON file. */
+declare class JsonFileLibraryCache implements LibraryCache {
+  #private;
+  constructor(path?: string);
+  load(): Promise<LibrarySnapshot | null>;
+  save(snapshot: LibrarySnapshot): Promise<void>;
+}
+//#endregion
+export { JsonFileLibraryCache, defaultCachePath };

package/dist/node.mjs

@@ -0,0 +1,29 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import process from "node:process";
+//#region src/node.ts
+/** Default exercise-cache path, overridable with TRAINHEROIC_CACHE_FILE. */
+function defaultCachePath() {
+	return process.env.TRAINHEROIC_CACHE_FILE ?? join(homedir(), ".trainheroic", "library.json");
+}
+/** Persists the exercise library to a JSON file. */
+var JsonFileLibraryCache = class {
+	#path;
+	constructor(path = defaultCachePath()) {
+		this.#path = path;
+	}
+	async load() {
+		try {
+			const parsed = JSON.parse(await readFile(this.#path, "utf8"));
+			if (typeof parsed.fetchedAt === "number" && Array.isArray(parsed.exercises)) return parsed;
+		} catch {}
+		return null;
+	}
+	async save(snapshot) {
+		await mkdir(dirname(this.#path), { recursive: true });
+		await writeFile(this.#path, JSON.stringify(snapshot), { mode: 384 });
+	}
+};
+//#endregion
+export { JsonFileLibraryCache, defaultCachePath };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@trainheroic-unofficial/js",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alandotcom/trainheroic-skill.git",
+    "directory": "packages/js"
+  },
+  "description": "Unofficial TypeScript SDK for the TrainHeroic coaching API.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./node": {
+      "types": "./dist/node.d.mts",
+      "import": "./dist/node.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@trainheroic-unofficial/dto": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "tsdown": "^0.22.3",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}