@trainheroic-unofficial/js 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +30 -30
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,9 +1,9 @@
1
1
  # @trainheroic-unofficial/js
2
2
 
3
- An unofficial TypeScript SDK for the TrainHeroic coaching API. It handles auth and session
4
- renewal, talks to both TrainHeroic hosts, keeps a searchable exercise library, encodes
5
- workouts into the API's payload format, and wraps messaging. It runs in any modern
6
- JavaScript runtime, including Cloudflare workerd.
3
+ An unofficial TypeScript SDK for the TrainHeroic coaching API. The client covers auth and
4
+ session renewal across both TrainHeroic hosts, a searchable exercise library, workout
5
+ encoding, and messaging. It runs in any modern JavaScript runtime, including Cloudflare
6
+ workerd.
7
7
 
8
8
  Part of the [trainheroic-unofficial](../../README.md) workspace.
9
9
 
@@ -73,7 +73,7 @@ const created = await client.request("POST", "/2.0/coach/exercise/create", {
73
73
  });
74
74
  ```
75
75
 
76
- There is no enumerated endpoint catalog; the paths are the ones the TrainHeroic web app calls.
76
+ The paths are the ones the TrainHeroic web app calls.
77
77
  Most are reachable through the typed helpers below, so you rarely call `request` directly. The
78
78
  request and response shapes those helpers use live in
79
79
  [`@trainheroic-unofficial/dto`](../dto) as zod schemas and types.
@@ -86,7 +86,7 @@ life of the process, so a fresh process logs in again. To skip that login, read
86
86
  one client and hand it to the next via the third constructor argument.
87
87
 
88
88
  After a request has run, `client.sessionId` holds the active token, typed `string | null` (it
89
- is `null` only before the first login). Persist it with your own storage — `saveToken` and
89
+ is `null` only before the first login). Persist it with your own storage; `saveToken` and
90
90
  `loadToken` below stand in for whatever you use (a file, a KV store, an env var):
91
91
 
92
92
  ```ts
@@ -130,16 +130,17 @@ The `.` entry imports no `node:*` modules. Anything that touches the filesystem
130
130
  client hit by concurrent requests performs a single shared login. `RequestOptions.base`
131
131
  selects the host (`coach` for `api.trainheroic.com`, `apis` for `apis.trainheroic.com`).
132
132
  - **Exercises.** `ExerciseIndex` is the interface the rest of the system codes against;
133
- `ExerciseLibrary` is the in-memory implementation that resolves names to ids, ranks
134
- fuzzy search, and persists through a `LibraryCache` (in-memory by default, JSON file via
135
- `./node`). The hosted server supplies a D1-backed implementation of the same interface.
136
- - **Workouts.** A session builder (create, save blocks and exercises, optionally publish),
137
- read-back, instruction editing, and removal, plus the encoder that turns a
138
- `WorkoutSpec` into the API's payload.
139
- - **Athlete training.** Functions for the logged-in account's own training: scheduled and
140
- completed workouts, per-exercise history, personal records, and working maxes.
141
- - **Messaging.** Listing conversation streams, reading a stream, and building, sending, or
142
- deleting a comment.
133
+ `ExerciseLibrary` is the in-memory implementation, handling name-to-id resolution,
134
+ fuzzy search ranking, and persistence through a `LibraryCache` (in-memory by default,
135
+ JSON file via `./node`). The hosted server supplies a D1-backed implementation of the
136
+ same interface.
137
+ - **Workouts.** A session builder that creates a session, saves blocks and exercises,
138
+ and optionally publishes, along with read-back, instruction editing, and removal.
139
+ Includes the encoder that turns a `WorkoutSpec` into the API's payload.
140
+ - **Athlete training.** Functions for the logged-in account's own training, covering
141
+ scheduled and completed workouts, per-exercise history, personal records, and working maxes.
142
+ - **Messaging.** Tools for conversation streams: listing them, reading a stream, and
143
+ building or sending or deleting a comment.
143
144
 
144
145
  ## Working with exercises
145
146
 
@@ -171,8 +172,8 @@ if (!match) {
171
172
 
172
173
  `buildSession` writes one session into a program on a given day: it creates the session, saves
173
174
  the blocks and exercises, and optionally publishes. `programId` identifies one of your
174
- TrainHeroic programs — find it in the program's URL in the web app, or from a programs read
175
- (`client.request("GET", ...)`). Exercise ids come from the library.
175
+ TrainHeroic programs (find it in the program's URL in the web app, or from a programs read
176
+ via `client.request("GET", ...)`). Exercise ids come from the library.
176
177
 
177
178
  ```ts
178
179
  import { buildSession, type BlockSpec } from "@trainheroic-unofficial/js";
@@ -203,13 +204,13 @@ Each exercise needs an `id`; `sets`, `reps`, `weight`, `rpe`, and a per-exercise
203
204
  optional. `reps` and `weight` take a scalar (broadcast across every set) or a per-set array
204
205
  like `reps: [5, 5, 3]`. The full field list is `ExerciseSpec` / `BlockSpec` in
205
206
  [`@trainheroic-unofficial/dto`](../dto). Loads are in whatever unit the exercise is configured
206
- for in TrainHeroic; a mismatch becomes an advisory rather than a silent change (below).
207
+ for in TrainHeroic; a mismatch becomes an advisory collected separately (see below).
207
208
 
208
- `buildSession` returns `{ pwId, workoutId }`: `pwId` is the program-workout id (the placement
209
- of the session in the program — this is the handle the other calls take), and `workoutId` is
210
- the underlying workout id. Read it back with `readSession(client, programId, date, pwId)`,
211
- publish later with `publishSession(client, pwId)`, or remove it with
212
- `removeSession(client, programId, pwId)`.
209
+ `buildSession` returns `{ pwId, workoutId }`: `pwId` is the program-workout id (the
210
+ placement of the session in the program, which is the handle subsequent calls take), and
211
+ `workoutId` is the underlying workout id. Use `pwId` with `readSession(client, programId, date, pwId)`
212
+ to read the session back. `publishSession(client, pwId)` publishes it later;
213
+ `removeSession(client, programId, pwId)` deletes it.
213
214
 
214
215
  ## Reading athlete training
215
216
 
@@ -228,13 +229,12 @@ scope.
228
229
  `buildSession` calls the encoder for you; you only deal with it directly to preview warnings.
229
230
  TrainHeroic's exercise payload expects every parameter slot present, so the encoder fills all
230
231
  of them (empty slots included) to avoid an HTTP 500. A scalar prescription is broadcast across
231
- the set count, RPE is routed into the instruction text rather than a numeric slot (the API
232
- would otherwise coerce it to load), and unit mismatches between a spec and the exercise's fixed
233
- parameter types are collected as advisories rather than silently dropped.
232
+ the set count. RPE goes into the instruction text because the API coerces a numeric slot to
233
+ load. Unit mismatches between a spec and the exercise's fixed parameter types surface as
234
+ advisories preserved in the return value of `collectAdvisories`.
234
235
 
235
- Those advisories are not part of the `buildSession` result; read them before building by
236
- calling `collectAdvisories(blocks, index)` (the `index` is an `ExerciseLibrary`), which returns
237
- the unit notes and warnings for a set of blocks.
236
+ Call `collectAdvisories(blocks, index)` before building (the `index` is an `ExerciseLibrary`)
237
+ to get the unit notes and warnings for a set of blocks.
238
238
 
239
239
  ## Develop
240
240
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/js",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -27,7 +27,7 @@
27
27
  ],
28
28
  "dependencies": {
29
29
  "zod": "^4.4.3",
30
- "@trainheroic-unofficial/dto": "1.1.0"
30
+ "@trainheroic-unofficial/dto": "1.1.1"
31
31
  },
32
32
  "devDependencies": {
33
33
  "@types/node": "^26.0.0",