@trainheroic-unofficial/dto 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,47 @@
+# @trainheroic-unofficial/dto
+
+Domain DTOs and zod schemas for the TrainHeroic API. This package is the single source of
+truth for request and response shapes; the SDK, the MCP tool layer, and the CLI all import
+their types from here instead of redefining them.
+
+Part of the [trainheroic-unofficial](../../README.md) workspace.
+
+## Install
+
+Internal to the workspace (consumed as `workspace:*`). Published builds expose a single ESM
+entry with type declarations.
+
+```ts
+import { workoutSpecSchema, type WorkoutSpec, idSchema } from "@trainheroic-unofficial/dto";
+
+const spec: WorkoutSpec = workoutSpecSchema.parse(input);
+```
+
+## What's inside
+
+Schemas come in two flavors. Input schemas are strict enough to validate user-supplied
+data such as workout specs, exercise-create bodies, and message drafts. Response schemas
+are deliberately tolerant: they use loose objects and accept a number or a numeric string
+for ids, so upstream API drift adds fields without breaking parsing.
+
+`src/` is organized by domain (`common`, `exercise`, `workout`, `messaging`, `responses`),
+re-exported through `index.ts`. The central pieces:
+
+- `idSchema` normalizes the API's number-or-string ids.
+- `workoutSpecSchema` / `WorkoutSpec` is the protocol used to build a session: an optional
+  top-level instruction plus an array of blocks, where each block carries an exercises
+  array and each exercise references a library id. `blockSpecSchema` and
+  `exerciseSpecSchema` are its parts; `leaderboardSpecSchema` covers red-zone leaderboards.
+- The read-back types (`ReadResult` and friends) describe a decoded session, and `Advisory`
+  carries the unit notes and warnings the encoder produces.
+- The `responses` module holds the tolerant schemas used to validate API payloads at
+  checkpoints without rejecting unknown fields.
+
+## Develop
+
+```bash
+pnpm build       # tsdown -> dist (ESM + .d.mts)
+pnpm typecheck
+pnpm test                                  # vitest
+pnpm exec vitest run test/workout.test.ts  # one file
+```

package/dist/index.d.mts

@@ -0,0 +1,197 @@
+import { z } from "zod";
+
+//#region src/common.d.ts
+/** An entity id as it arrives over the wire — a number or a numeric string. */
+declare const idSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+type Id = z.infer<typeof idSchema>;
+/**
+ * An id as a tool argument: a number, or a string of digits. Unlike idSchema (which
+ * tolerates whatever the API sends back), this rejects non-numeric strings up front so
+ * a bad argument fails validation instead of becoming NaN in a URL or a query.
+ */
+declare const idArgSchema: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+//#endregion
+//#region src/exercise.d.ts
+/** A library exercise row as the index stores it. */
+type ExerciseRow = {
+  id: number;
+  title: string;
+  param_1_type: number | null;
+  param_2_type: number | null;
+  can_edit: number;
+  user_id: number | null;
+  use_count: number;
+};
+/** A row annotated with human-readable unit labels for display. */
+type ExerciseView = ExerciseRow & {
+  param_1_unit: string | null;
+  param_2_unit: string | null;
+};
+/** The outcome of resolving a name: a single match (or null) plus ranked candidates. */
+type ResolveResult = {
+  match: ExerciseView | null;
+  candidates: ExerciseView[];
+};
+/** Body for creating a custom exercise; extra fields the API accepts are preserved. */
+declare const exerciseCreateSchema: z.ZodObject<{
+  title: z.ZodString;
+  param_1_type: z.ZodOptional<z.ZodNumber>;
+  param_2_type: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+type ExerciseCreate = z.infer<typeof exerciseCreateSchema>;
+//#endregion
+//#region src/messaging.d.ts
+/** A chat comment to draft or send: target stream, body text, optional threaded reply. */
+declare const commentDraftSchema: z.ZodObject<{
+  streamId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+  text: z.ZodString;
+  replyTo: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>;
+type CommentDraft = z.infer<typeof commentDraftSchema>;
+//#endregion
+//#region src/responses.d.ts
+/** An exercise as the library + create endpoints return it (only the fields we read). */
+declare const exerciseResponseSchema: z.ZodObject<{
+  id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+  title: z.ZodString;
+  param_1_type: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodNull]>>;
+  param_2_type: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodNull]>>;
+}, z.core.$loose>;
+/** The exercise library list (envelope already unwrapped). */
+declare const exerciseLibraryResponseSchema: z.ZodArray<z.ZodObject<{
+  id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+  title: z.ZodString;
+  param_1_type: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodNull]>>;
+  param_2_type: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodNull]>>;
+}, z.core.$loose>>;
+/** The create-session response (a programWorkout): we read workout_id + id. */
+declare const sessionCreateResponseSchema: z.ZodObject<{
+  workout_id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+  id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+}, z.core.$loose>;
+/** A programWorkout from the calendar edit view (we match by id and walk sets). */
+declare const programWorkoutResponseSchema: z.ZodObject<{
+  id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+  sets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+/** The calendar edit-view response we read sessions back from. */
+declare const programsEditResponseSchema: z.ZodObject<{
+  programWorkouts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+    sets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$loose>>>;
+}, z.core.$loose>;
+//#endregion
+//#region src/workout.d.ts
+/** A single exercise prescription inside a block. */
+declare const exerciseSpecSchema: z.ZodObject<{
+  id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+  title: z.ZodOptional<z.ZodString>;
+  reps: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>]>>;
+  sets: z.ZodOptional<z.ZodNumber>;
+  weight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>]>>;
+  rpe: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+  instr: z.ZodOptional<z.ZodString>;
+  param_1_type: z.ZodOptional<z.ZodNumber>;
+  param_2_type: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type ExerciseSpec = z.infer<typeof exerciseSpecSchema>;
+/** A block's Red-Zone leaderboard: a unit string/number, or an object with options. */
+declare const leaderboardSpecSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodObject<{
+  unit: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+  type: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+  lowest_wins: z.ZodOptional<z.ZodBoolean>;
+  instruction: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>;
+type LeaderboardSpec = z.infer<typeof leaderboardSpecSchema>;
+/** A block (group of exercises); two exercises render as a superset. */
+declare const blockSpecSchema: z.ZodObject<{
+  title: z.ZodString;
+  type: z.ZodOptional<z.ZodNumber>;
+  instruction: z.ZodOptional<z.ZodString>;
+  leaderboard: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodObject<{
+    unit: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    type: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    lowest_wins: z.ZodOptional<z.ZodBoolean>;
+    instruction: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>]>>;
+  exercises: z.ZodArray<z.ZodObject<{
+    id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+    title: z.ZodOptional<z.ZodString>;
+    reps: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>]>>;
+    sets: z.ZodOptional<z.ZodNumber>;
+    weight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>]>>;
+    rpe: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    instr: z.ZodOptional<z.ZodString>;
+    param_1_type: z.ZodOptional<z.ZodNumber>;
+    param_2_type: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type BlockSpec = z.infer<typeof blockSpecSchema>;
+/** A full session spec: the blocks plus an optional session note (Coach Instructions). */
+declare const workoutSpecSchema: z.ZodObject<{
+  blocks: z.ZodArray<z.ZodObject<{
+    title: z.ZodString;
+    type: z.ZodOptional<z.ZodNumber>;
+    instruction: z.ZodOptional<z.ZodString>;
+    leaderboard: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodObject<{
+      unit: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+      type: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+      lowest_wins: z.ZodOptional<z.ZodBoolean>;
+      instruction: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    exercises: z.ZodArray<z.ZodObject<{
+      id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+      title: z.ZodOptional<z.ZodString>;
+      reps: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>]>>;
+      sets: z.ZodOptional<z.ZodNumber>;
+      weight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>]>>;
+      rpe: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+      instr: z.ZodOptional<z.ZodString>;
+      param_1_type: z.ZodOptional<z.ZodNumber>;
+      param_2_type: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+  instruction: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type WorkoutSpec = z.infer<typeof workoutSpecSchema>;
+/** A calendar date as the workout API expects it: [year, month, day]. */
+type WorkoutDate = readonly [number, number, number];
+/**
+ * Parse a `YYYY-M-D` string into the `WorkoutDate` tuple. The single home for this
+ * conversion, shared by the MCP tools and the CLI so they cannot drift on what counts
+ * as a valid date. Each part must be an integer.
+ */
+declare function parseWorkoutDate(s: string): WorkoutDate;
+/** Unit advisories surfaced when building: informational notes and override warnings. */
+type Advisory = {
+  notes: string[];
+  warnings: string[];
+};
+/** A single exercise as read back from a built session. */
+type ReadExercise = {
+  order: number;
+  title: string;
+  reps: string[];
+  primaryUnit: string | null;
+  load: string[];
+  loadUnit: string | null;
+  instruction: string;
+};
+/** A block as read back from a built session. */
+type ReadBlock = {
+  order: number;
+  title: string;
+  leaderboard: string | null;
+  exercises: ReadExercise[];
+};
+/** A whole session read back from the calendar. */
+type ReadResult = {
+  pwId: number;
+  date: string;
+  published: unknown;
+  instruction: string;
+  blocks: ReadBlock[];
+};
+//#endregion
+export { Advisory, BlockSpec, CommentDraft, ExerciseCreate, ExerciseRow, ExerciseSpec, ExerciseView, Id, LeaderboardSpec, ReadBlock, ReadExercise, ReadResult, ResolveResult, WorkoutDate, WorkoutSpec, blockSpecSchema, commentDraftSchema, exerciseCreateSchema, exerciseLibraryResponseSchema, exerciseResponseSchema, exerciseSpecSchema, idArgSchema, idSchema, leaderboardSpecSchema, parseWorkoutDate, programWorkoutResponseSchema, programsEditResponseSchema, sessionCreateResponseSchema, workoutSpecSchema };

package/dist/index.mjs

@@ -0,0 +1,113 @@
+import { z } from "zod";
+//#region src/common.ts
+/** An entity id as it arrives over the wire — a number or a numeric string. */
+const idSchema = z.union([z.string(), z.number()]);
+/**
+* An id as a tool argument: a number, or a string of digits. Unlike idSchema (which
+* tolerates whatever the API sends back), this rejects non-numeric strings up front so
+* a bad argument fails validation instead of becoming NaN in a URL or a query.
+*/
+const idArgSchema = z.union([z.number().int(), z.string().regex(/^\d+$/u)]);
+//#endregion
+//#region src/exercise.ts
+/** Body for creating a custom exercise; extra fields the API accepts are preserved. */
+const exerciseCreateSchema = z.looseObject({
+	title: z.string().min(1),
+	param_1_type: z.number().optional(),
+	param_2_type: z.number().optional()
+});
+//#endregion
+//#region src/messaging.ts
+/** A chat comment to draft or send: target stream, body text, optional threaded reply. */
+const commentDraftSchema = z.object({
+	streamId: idSchema,
+	text: z.string().min(1),
+	replyTo: idSchema.optional()
+});
+//#endregion
+//#region src/responses.ts
+const intLike = z.union([z.number(), z.string()]);
+const intLikeOrNull = z.union([
+	z.number(),
+	z.string(),
+	z.null()
+]);
+/** An exercise as the library + create endpoints return it (only the fields we read). */
+const exerciseResponseSchema = z.looseObject({
+	id: intLike,
+	title: z.string(),
+	param_1_type: intLikeOrNull.optional(),
+	param_2_type: intLikeOrNull.optional()
+});
+/** The exercise library list (envelope already unwrapped). */
+const exerciseLibraryResponseSchema = z.array(exerciseResponseSchema);
+/** The create-session response (a programWorkout): we read workout_id + id. */
+const sessionCreateResponseSchema = z.looseObject({
+	workout_id: intLike,
+	id: intLike
+});
+/** A programWorkout from the calendar edit view (we match by id and walk sets). */
+const programWorkoutResponseSchema = z.looseObject({
+	id: intLike,
+	sets: z.record(z.string(), z.unknown()).optional()
+});
+/** The calendar edit-view response we read sessions back from. */
+const programsEditResponseSchema = z.looseObject({ programWorkouts: z.array(programWorkoutResponseSchema).optional() });
+//#endregion
+//#region src/workout.ts
+/** A single exercise prescription inside a block. */
+const exerciseSpecSchema = z.object({
+	id: z.union([z.number(), z.string()]),
+	title: z.string().optional(),
+	reps: z.union([
+		z.number(),
+		z.string(),
+		z.array(z.union([z.number(), z.string()]))
+	]).optional(),
+	sets: z.number().optional(),
+	weight: z.union([z.number(), z.array(z.number())]).optional(),
+	rpe: z.union([z.number(), z.string()]).optional(),
+	instr: z.string().optional(),
+	param_1_type: z.number().optional(),
+	param_2_type: z.number().optional()
+});
+/** A block's Red-Zone leaderboard: a unit string/number, or an object with options. */
+const leaderboardSpecSchema = z.union([
+	z.string(),
+	z.number(),
+	z.object({
+		unit: z.union([z.string(), z.number()]).optional(),
+		type: z.union([z.string(), z.number()]).optional(),
+		lowest_wins: z.boolean().optional(),
+		instruction: z.string().optional()
+	})
+]);
+/** A block (group of exercises); two exercises render as a superset. */
+const blockSpecSchema = z.object({
+	title: z.string(),
+	type: z.number().optional(),
+	instruction: z.string().optional(),
+	leaderboard: leaderboardSpecSchema.optional(),
+	exercises: z.array(exerciseSpecSchema)
+});
+/** A full session spec: the blocks plus an optional session note (Coach Instructions). */
+const workoutSpecSchema = z.object({
+	blocks: z.array(blockSpecSchema),
+	instruction: z.string().optional()
+});
+/**
+* Parse a `YYYY-M-D` string into the `WorkoutDate` tuple. The single home for this
+* conversion, shared by the MCP tools and the CLI so they cannot drift on what counts
+* as a valid date. Each part must be an integer.
+*/
+function parseWorkoutDate(s) {
+	const parts = s.split("-").map((p) => Number(p));
+	if (parts.length !== 3 || parts.some((n) => !Number.isInteger(n))) throw new Error(`date must be YYYY-M-D, got "${s}".`);
+	return [
+		parts[0],
+		parts[1],
+		parts[2]
+	];
+}
+//#endregion
+export { blockSpecSchema, commentDraftSchema, exerciseCreateSchema, exerciseLibraryResponseSchema, exerciseResponseSchema, exerciseSpecSchema, idArgSchema, idSchema, leaderboardSpecSchema, parseWorkoutDate, programWorkoutResponseSchema, programsEditResponseSchema, sessionCreateResponseSchema, workoutSpecSchema };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@trainheroic-unofficial/dto",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alandotcom/trainheroic-skill.git",
+    "directory": "packages/dto"
+  },
+  "description": "Domain DTOs and zod schemas for TrainHeroic — the single source of truth for shapes.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.3",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}