@trainheroic-unofficial/js 4.1.1 → 4.2.0

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.
package/dist/index.d.mts CHANGED
@@ -33,6 +33,23 @@ export declare class TrainHeroicHttpError extends Error {
33
33
  readonly responseBody: unknown;
34
34
  constructor(method: string, url: string, status: number, diagnostics?: TrainHeroicHttpErrorDiagnostics);
35
35
  }
36
+ /**
37
+ * True for statuses that mean TrainHeroic's servers could not be reached or did not answer: a
38
+ * gateway failure (502, 503, 504) or a Cloudflare edge error (520-530). TrainHeroic sits behind
39
+ * Cloudflare, so a 522 means the edge timed out connecting to TrainHeroic's origin. These describe
40
+ * an upstream outage, so the same request can succeed when retried later.
41
+ */
42
+ export declare function isTrainHeroicUnavailableStatus(status: number): boolean;
43
+ /**
44
+ * Thrown when TrainHeroic answers with an outage status (see `isTrainHeroicUnavailableStatus`).
45
+ * The message tells the reader to retry later, so a model relaying it does not ask the user to
46
+ * re-check credentials that are fine.
47
+ */
48
+ export declare class TrainHeroicUnavailableError extends Error {
49
+ readonly name = "TrainHeroicUnavailableError";
50
+ readonly status: number;
51
+ constructor(status: number);
52
+ }
36
53
  type TrainHeroicHttpErrorHandler = (error: TrainHeroicHttpError) => void | PromiseLike<void>;
37
54
  //#endregion
38
55
  //#region src/transport.d.ts
@@ -53,8 +70,10 @@ export type LoginOptions = {
53
70
  transport?: TrainHeroicTransport;
54
71
  };
55
72
  /**
56
- * Authenticate against TrainHeroic. Returns the session bundle, or null on bad
57
- * credentials. TrainHeroic returns only { id, scope, role, session_id } (verified in
73
+ * Authenticate against TrainHeroic. Returns the session bundle, or null when TrainHeroic
74
+ * rejects the login. Throws `TrainHeroicUnavailableError` when TrainHeroic is unreachable (an
75
+ * outage status such as a Cloudflare 522), so callers can tell the user to retry later.
76
+ * TrainHeroic returns only { id, scope, role, session_id } (verified in
58
77
  * the Phase 0 spike: no refresh_token, no api_token, no TTL). The 48-char session_id
59
78
  * is sent as the `session-token` header and works against both API hosts.
60
79
  */
package/dist/index.mjs CHANGED
@@ -243,6 +243,28 @@ var TrainHeroicHttpError = class extends Error {
243
243
  this.responseBody = diagnostics.responseBody === void 0 ? void 0 : safeResponseBodyDiagnostics(diagnostics.responseBody);
244
244
  }
245
245
  };
246
+ /**
247
+ * True for statuses that mean TrainHeroic's servers could not be reached or did not answer: a
248
+ * gateway failure (502, 503, 504) or a Cloudflare edge error (520-530). TrainHeroic sits behind
249
+ * Cloudflare, so a 522 means the edge timed out connecting to TrainHeroic's origin. These describe
250
+ * an upstream outage, so the same request can succeed when retried later.
251
+ */
252
+ function isTrainHeroicUnavailableStatus(status) {
253
+ return status === 502 || status === 503 || status === 504 || status >= 520 && status <= 530;
254
+ }
255
+ /**
256
+ * Thrown when TrainHeroic answers with an outage status (see `isTrainHeroicUnavailableStatus`).
257
+ * The message tells the reader to retry later, so a model relaying it does not ask the user to
258
+ * re-check credentials that are fine.
259
+ */
260
+ var TrainHeroicUnavailableError = class extends Error {
261
+ name = "TrainHeroicUnavailableError";
262
+ status;
263
+ constructor(status) {
264
+ super(`TrainHeroic is not responding right now (HTTP ${status}). Try again in a few minutes.`);
265
+ this.status = status;
266
+ }
267
+ };
246
268
  /** Call observability hooks without allowing them to change SDK behavior. */
247
269
  function notifyHttpError(handler, method, url, status, diagnostics = {}) {
248
270
  if (!handler) return;
@@ -270,8 +292,10 @@ function authUrl() {
270
292
  return DEFAULT_AUTH_URL;
271
293
  }
272
294
  /**
273
- * Authenticate against TrainHeroic. Returns the session bundle, or null on bad
274
- * credentials. TrainHeroic returns only { id, scope, role, session_id } (verified in
295
+ * Authenticate against TrainHeroic. Returns the session bundle, or null when TrainHeroic
296
+ * rejects the login. Throws `TrainHeroicUnavailableError` when TrainHeroic is unreachable (an
297
+ * outage status such as a Cloudflare 522), so callers can tell the user to retry later.
298
+ * TrainHeroic returns only { id, scope, role, session_id } (verified in
275
299
  * the Phase 0 spike: no refresh_token, no api_token, no TTL). The 48-char session_id
276
300
  * is sent as the `session-token` header and works against both API hosts.
277
301
  */
@@ -291,6 +315,7 @@ async function loginTrainHeroic(email, password, options = {}) {
291
315
  if (!res.ok) {
292
316
  await res.body?.cancel().catch(() => {});
293
317
  notifyHttpError(options.onHttpError, "POST", url, res.status);
318
+ if (isTrainHeroicUnavailableStatus(res.status)) throw new TrainHeroicUnavailableError(res.status);
294
319
  return null;
295
320
  }
296
321
  const data = await res.json().catch(() => null);
@@ -3904,4 +3929,4 @@ var ExerciseLibrary = class {
3904
3929
  }
3905
3930
  };
3906
3931
  //#endregion
3907
- export { ANALYTICS_METRIC_KEYS, BLOCK_TYPE_CONDITIONING, BLOCK_TYPE_HYPERTROPHY, DEFAULT_INVITE_MESSAGE, ExerciseLibrary, LEADERBOARD_LABEL, LEADERBOARD_TYPE, MAIN_LIFT_FAMILIES, MAX_PARAM_SLOTS, MemoryLibraryCache, PARAM_NONE, PARAM_PCT_MAX, PARAM_REPS, PARAM_RPE, PARAM_UNIT, PARAM_WEIGHT, PROGRAM_KINDS, SESSION_TEMPLATES_LIST_PATH, TrainHeroicAuthError, TrainHeroicClient, TrainHeroicHttpError, addExercisesToWorkout, analyticsMetricCatalog, asExerciseList, buildBlockPayload, buildCommentPayload, buildExerciseSetPayload, buildSearchText, buildSession, buildSetCompletePayload, calendarWriteError, checkResponse, chunk, classifyMainLift, coerceInt, coerceNum, collectAdvisories, copySession, createLimiter, createPersonalWorkout, createProgram, createSessionTemplate, dateWindows, defaultBlockType, definedProps, deleteComment, deleteProgram, exerciseSetCount, exerciseTitle, exerciseUnits, fetchAthleteCircuits, fetchAthleteMainLiftPRs, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteProgrammingPrograms, fetchAthleteUser, fetchAthleteWorkouts, fetchAthleteWorkoutsChunked, fetchCoachAthleteCalendar, fetchCoachAthleteCalendarSummary, fetchCoachAthleteWorkouts, fetchCoachRoster, fetchCurrentExerciseDefaults, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchRecentExercises, fetchRosterActivity, fetchRosterMainLiftPRs, fetchStreams, fetchTeamAthleteIds, fetchWorkingMaxes, findSavedWorkoutSet, findSetSplits, historyInRange, inviteAthletes, isPersonalSession, isRecord, logAdHocSession, logAthleteSet, logForAthlete, logSessionForAthlete, loginTrainHeroic, makeExercise, mapPool, mergeWorkoutsById, performedExercises, prescribeAthleteSet, prescribeForAthlete, presentAthleteWorkout, presentAthleteWorkoutExport, presentAthleteWorkouts, presentAthleteWorkoutsExport, presentCoachAthleteTraining, presentExercise, presentExerciseHistory, presentLogTargets, programWorkoutOnDate, publishSession, queryAnalytics, rankSearch, readLive, readSession, removePersonalWorkout, removeSession, repsList, resolveAthleteMainLifts, resolveAthleteUserId, resolveBuildProgramId, resolveLeaderboard, savedWorkoutOf, searchExerciseHistory, selectWorkouts, selectWorkoutsByProgram, sendComment, serializeWorkoutHistory, setAthleteExerciseNote, setAthleteWorkoutNote, setSessionInstruction, setSplitSummary, sortRosterByRecency, splitOversizedBlocks, str, summarizeAthleteWorkouts, swapAthleteExercise, teamPublishTarget, teamVolume, toSetResults, trainHeroicApiErrorMessage, unitAdvisory, unitLabel, unwrapEnvelope, updateTeam, updateTeamPublishSettings, withUnits, workoutsToCsv, workoutsToJson, workoutsToText };
3932
+ export { ANALYTICS_METRIC_KEYS, BLOCK_TYPE_CONDITIONING, BLOCK_TYPE_HYPERTROPHY, DEFAULT_INVITE_MESSAGE, ExerciseLibrary, LEADERBOARD_LABEL, LEADERBOARD_TYPE, MAIN_LIFT_FAMILIES, MAX_PARAM_SLOTS, MemoryLibraryCache, PARAM_NONE, PARAM_PCT_MAX, PARAM_REPS, PARAM_RPE, PARAM_UNIT, PARAM_WEIGHT, PROGRAM_KINDS, SESSION_TEMPLATES_LIST_PATH, TrainHeroicAuthError, TrainHeroicClient, TrainHeroicHttpError, TrainHeroicUnavailableError, addExercisesToWorkout, analyticsMetricCatalog, asExerciseList, buildBlockPayload, buildCommentPayload, buildExerciseSetPayload, buildSearchText, buildSession, buildSetCompletePayload, calendarWriteError, checkResponse, chunk, classifyMainLift, coerceInt, coerceNum, collectAdvisories, copySession, createLimiter, createPersonalWorkout, createProgram, createSessionTemplate, dateWindows, defaultBlockType, definedProps, deleteComment, deleteProgram, exerciseSetCount, exerciseTitle, exerciseUnits, fetchAthleteCircuits, fetchAthleteMainLiftPRs, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteProgrammingPrograms, fetchAthleteUser, fetchAthleteWorkouts, fetchAthleteWorkoutsChunked, fetchCoachAthleteCalendar, fetchCoachAthleteCalendarSummary, fetchCoachAthleteWorkouts, fetchCoachRoster, fetchCurrentExerciseDefaults, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchRecentExercises, fetchRosterActivity, fetchRosterMainLiftPRs, fetchStreams, fetchTeamAthleteIds, fetchWorkingMaxes, findSavedWorkoutSet, findSetSplits, historyInRange, inviteAthletes, isPersonalSession, isRecord, isTrainHeroicUnavailableStatus, logAdHocSession, logAthleteSet, logForAthlete, logSessionForAthlete, loginTrainHeroic, makeExercise, mapPool, mergeWorkoutsById, performedExercises, prescribeAthleteSet, prescribeForAthlete, presentAthleteWorkout, presentAthleteWorkoutExport, presentAthleteWorkouts, presentAthleteWorkoutsExport, presentCoachAthleteTraining, presentExercise, presentExerciseHistory, presentLogTargets, programWorkoutOnDate, publishSession, queryAnalytics, rankSearch, readLive, readSession, removePersonalWorkout, removeSession, repsList, resolveAthleteMainLifts, resolveAthleteUserId, resolveBuildProgramId, resolveLeaderboard, savedWorkoutOf, searchExerciseHistory, selectWorkouts, selectWorkoutsByProgram, sendComment, serializeWorkoutHistory, setAthleteExerciseNote, setAthleteWorkoutNote, setSessionInstruction, setSplitSummary, sortRosterByRecency, splitOversizedBlocks, str, summarizeAthleteWorkouts, swapAthleteExercise, teamPublishTarget, teamVolume, toSetResults, trainHeroicApiErrorMessage, unitAdvisory, unitLabel, unwrapEnvelope, updateTeam, updateTeamPublishSettings, withUnits, workoutsToCsv, workoutsToJson, workoutsToText };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/js",
3
- "version": "4.1.1",
3
+ "version": "4.2.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -28,7 +28,7 @@
28
28
  "dependencies": {
29
29
  "es-toolkit": "^1.52.0",
30
30
  "zod": "^4.6.5",
31
- "@trainheroic-unofficial/dto": "4.1.1"
31
+ "@trainheroic-unofficial/dto": "4.2.0"
32
32
  },
33
33
  "devDependencies": {
34
34
  "@types/node": "^26.6.4",