hevy-shared 1.0.954 → 1.0.956

package/built/hevyTrainer.d.ts

@@ -38,18 +38,46 @@ export interface ExerciseSelectionParams<T extends HevyTrainerLibraryExercise> {
     criteria: ExerciseSelectionCriteria;
     context: ExerciseSelectionContext;
 }
+export interface ExerciseSelectionTraceEntry {
+    pass: 1 | 2 | 3 | 4 | 5 | 6;
+    label: string;
+    candidatePoolSize: number;
+    selectedExerciseId?: string;
+}
+export interface ExerciseSelectionTrace {
+    entries: ExerciseSelectionTraceEntry[];
+    selectedPass?: 1 | 2 | 3 | 4 | 5 | 6;
+}
 export interface ProgramGenerationParams<T extends HevyTrainerLibraryExercise> {
     trainerAlgorithmSettings: TrainerAlgorithmSettings;
-    selectedDays: WeeklyTrainingFrequency;
-    selectedGoal: TrainingGoal;
-    selectedLevel: TrainingLevel;
-    selectedEquipments: GranularEquipment[];
-    selectedWorkoutDurationMinutes?: WorkoutDurationMinutes;
-    selectedRestTimerLength: RestTimerLength;
+    frequency: WeeklyTrainingFrequency;
+    goal: TrainingGoal;
+    level: TrainingLevel;
+    equipments: GranularEquipment[];
+    workoutDurationMinutes: WorkoutDurationMinutes;
+    restTimerLength: RestTimerLength;
     exerciseStore: T[];
     focusMuscle?: SimplifiedMuscleGroup;
     excludedExerciseIds?: Set<string>;
+    /**
+     * When enabled, includes exercise selection trace breadcrumbs in the result
+     * for debugging. Intended for troubleshooting on backoffice; keep off in
+     * normal usage on the app.
+     */
+    debugExerciseSelectionTrace?: boolean;
+}
+export interface ProgramExerciseSelectionTraceRecord {
+    routine: HevyTrainerRoutineName;
+    prescriptionIndex: number;
+    prescription: ExercisePrescription;
+    resolvedMuscleGroup: MuscleGroup;
+    criteria: ExerciseSelectionCriteria;
+    selectedExerciseId?: string;
+    trace: ExerciseSelectionTrace;
 }
+export type TrainerProgramAttemptWithTraces = TrainerProgramAttempt & {
+    exerciseSelectionTraces: ProgramExerciseSelectionTraceRecord[];
+};
 export type FrequencyString = 'one_day' | 'two_days' | 'three_days' | 'four_days' | 'five_days' | 'six_days';
 export declare const frequencyMap: Record<WeeklyTrainingFrequency, FrequencyString>;
 export declare const programSplits: Record<WeeklyTrainingFrequency, HevyTrainerRoutineName[]>;
@@ -171,7 +199,14 @@ export declare const getPrioritySortedExercises: <T extends HevyTrainerLibraryEx
 /**
  * Selects the best exercise for a given prescription using a multi-pass strategy
  */
-export declare const pickExerciseForPrescription: <T extends HevyTrainerLibraryExercise>(params: ExerciseSelectionParams<T>) => T | undefined;
+type PickExerciseResult<T extends HevyTrainerLibraryExercise> = {
+    exercise?: T;
+    trace: ExerciseSelectionTrace;
+};
+export declare function pickExerciseForPrescription<T extends HevyTrainerLibraryExercise>(params: ExerciseSelectionParams<T> & {
+    withTrace: true;
+}): PickExerciseResult<T>;
+export declare function pickExerciseForPrescription<T extends HevyTrainerLibraryExercise>(params: ExerciseSelectionParams<T>): T | undefined;
 export type HevyTrainerLibraryExercise = Pick<LibraryExercise, 'id' | 'title' | 'priority' | 'muscle_group' | 'other_muscles' | 'exercise_type' | 'equipment_category' | 'category' | 'level' | 'goal' | 'granular_equipments'>;
 export interface ExercisePrescriptionError {
     type: 'exercise_not_found';
@@ -205,5 +240,11 @@ export interface TrainerProgramError {
 export type TrainerProgramAttempt = TrainerProgramResult | TrainerProgramError;
 /**
  * Generates a complete training program based on the provided parameters
+ * - debugExerciseSelectionTrace: true -> includes exercise selection trace breadcrumbs in the result for debugging.
+ * - debugExerciseSelectionTrace: false -> no exercise selection trace breadcrumbs in the result.
  */
-export declare const generateProgram: <T extends HevyTrainerLibraryExercise>(params: ProgramGenerationParams<T>) => TrainerProgramAttempt;
+export declare function generateProgram<T extends HevyTrainerLibraryExercise>(params: ProgramGenerationParams<T> & {
+    debugExerciseSelectionTrace: true;
+}): TrainerProgramAttemptWithTraces;
+export declare function generateProgram<T extends HevyTrainerLibraryExercise>(params: ProgramGenerationParams<T>): TrainerProgramAttempt;
+export {};

package/built/hevyTrainer.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateProgram = exports.pickExerciseForPrescription = exports.getPrioritySortedExercises = exports.isEquipmentCompatible = exports.normalizeExerciseCategory = exports.getTrainerRestTimerSeconds = exports.getTrainerRepRange = exports.getTrainerSetCount = exports.programSplits = exports.frequencyMap = exports.routineNames = exports.defaultDurationPerFrequency = exports.hevyTrainerExerciseCategories = exports.granularEquipmentsToTrainerEquipments = exports.trainerEquipmentToGranularEquipments = exports.granularEquipmentDefaults = exports.trainerGymTypes = exports.workoutDurationOptions = void 0;
+exports.getPrioritySortedExercises = exports.isEquipmentCompatible = exports.normalizeExerciseCategory = exports.getTrainerRestTimerSeconds = exports.getTrainerRepRange = exports.getTrainerSetCount = exports.programSplits = exports.frequencyMap = exports.routineNames = exports.defaultDurationPerFrequency = exports.hevyTrainerExerciseCategories = exports.granularEquipmentsToTrainerEquipments = exports.trainerEquipmentToGranularEquipments = exports.granularEquipmentDefaults = exports.trainerGymTypes = exports.workoutDurationOptions = void 0;
+exports.pickExerciseForPrescription = pickExerciseForPrescription;
+exports.generateProgram = generateProgram;
 const _1 = require(".");
 exports.workoutDurationOptions = [40, 60, 80];
 exports.trainerGymTypes = [
@@ -448,60 +450,98 @@ const findAlternativeIsolationExercise = (exercises, criteria, context) => {
         return matchesCriteria && isNotUsed;
     });
 };
-/**
- * Selects the best exercise for a given prescription using a multi-pass strategy
- */
-const pickExerciseForPrescription = (params) => {
+const pickExerciseForPrescriptionWithTrace = (params) => {
     const { sortedExercises, handPickedExercises, criteria, context } = params;
+    const trace = { entries: [] };
     const exercises = handPickedExercises
         ? [...handPickedExercises, ...sortedExercises[criteria.muscleGroup]]
         : sortedExercises[criteria.muscleGroup];
-    // Pass 1: Find exact match not used in program
     const programContext = {
         programUsedExerciseIds: context.programUsedExerciseIds,
         excludedExerciseIds: context.excludedExerciseIds,
     };
-    let exercise = findMatchingExercise(exercises, criteria, programContext);
-    if (exercise)
-        return exercise;
-    // Pass 2: Find exact match not used in routine (allow reuse in program)
     const routineContext = {
         routineUsedExerciseIds: context.routineUsedExerciseIds,
         excludedExerciseIds: context.excludedExerciseIds,
     };
+    // Pass 1
+    let exercise = findMatchingExercise(exercises, criteria, programContext);
+    trace.entries.push({
+        pass: 1,
+        label: 'exact match; not used in program',
+        candidatePoolSize: exercises.length,
+        selectedExerciseId: exercise === null || exercise === void 0 ? void 0 : exercise.id,
+    });
+    if (exercise)
+        return { exercise, trace: Object.assign(Object.assign({}, trace), { selectedPass: 1 }) };
+    // Pass 2
     exercise = findMatchingExercise(exercises, criteria, routineContext);
+    trace.entries.push({
+        pass: 2,
+        label: 'exact match; not used in routine (reuse allowed in program)',
+        candidatePoolSize: exercises.length,
+        selectedExerciseId: exercise === null || exercise === void 0 ? void 0 : exercise.id,
+    });
     if (exercise)
-        return exercise;
-    // Pass 3: Find alternative isolation exercise not used in program
+        return { exercise, trace: Object.assign(Object.assign({}, trace), { selectedPass: 2 }) };
+    // Pass 3
     exercise = findAlternativeIsolationExercise(exercises, criteria, programContext);
+    trace.entries.push({
+        pass: 3,
+        label: 'handpicked alternative isolation; not used in program',
+        candidatePoolSize: exercises.length,
+        selectedExerciseId: exercise === null || exercise === void 0 ? void 0 : exercise.id,
+    });
     if (exercise)
-        return exercise;
-    // Pass 4: Find alternative isolation exercise not used in routine
+        return { exercise, trace: Object.assign(Object.assign({}, trace), { selectedPass: 3 }) };
+    // Pass 4
     exercise = findAlternativeIsolationExercise(exercises, criteria, routineContext);
+    trace.entries.push({
+        pass: 4,
+        label: 'handpicked alternative isolation; not used in routine (reuse allowed in program)',
+        candidatePoolSize: exercises.length,
+        selectedExerciseId: exercise === null || exercise === void 0 ? void 0 : exercise.id,
+    });
     if (exercise)
-        return exercise;
-    // Pass 5: Find exercise regardless of exercise category (isolation or compound)
+        return { exercise, trace: Object.assign(Object.assign({}, trace), { selectedPass: 4 }) };
+    // Pass 5
     exercise = findMatchingExercise(exercises, Object.assign(Object.assign({}, criteria), { exerciseCategory: 'all' }), routineContext);
+    trace.entries.push({
+        pass: 5,
+        label: 'match regardless of isolation or compound; not used in routine (reuse allowed in program)',
+        candidatePoolSize: exercises.length,
+        selectedExerciseId: exercise === null || exercise === void 0 ? void 0 : exercise.id,
+    });
     if (exercise)
-        return exercise;
-    // Pass 6: Find exercises where the prescription muscle group
-    // is in the exercise's other muscles, also ignores exercise category
+        return { exercise, trace: Object.assign(Object.assign({}, trace), { selectedPass: 5 }) };
+    // Pass 6
     const secondaryMuscleExercises = Object.values(sortedExercises)
         .flat()
         .filter((e) => e.other_muscles.includes(criteria.muscleGroup));
     exercise = findMatchingExercise(secondaryMuscleExercises, Object.assign(Object.assign({}, criteria), { exerciseCategory: 'all' }), routineContext);
-    return exercise;
+    trace.entries.push({
+        pass: 6,
+        label: 'secondary muscle match; regardless of isolation or compound; not used in routine (reuse allowed in program)',
+        candidatePoolSize: secondaryMuscleExercises.length,
+        selectedExerciseId: exercise === null || exercise === void 0 ? void 0 : exercise.id,
+    });
+    return exercise
+        ? { exercise, trace: Object.assign(Object.assign({}, trace), { selectedPass: 6 }) }
+        : { exercise: undefined, trace };
 };
-exports.pickExerciseForPrescription = pickExerciseForPrescription;
-/**
- * Generates a complete training program based on the provided parameters
- */
-const generateProgram = (params) => {
-    var _a;
-    const { trainerAlgorithmSettings, selectedDays, selectedGoal, selectedLevel, selectedEquipments, selectedWorkoutDurationMinutes, selectedRestTimerLength, exerciseStore, focusMuscle, excludedExerciseIds, } = params;
-    const routines = exports.programSplits[selectedDays];
+function pickExerciseForPrescription(params) {
+    if (params.withTrace) {
+        return pickExerciseForPrescriptionWithTrace(params);
+    }
+    return pickExerciseForPrescriptionWithTrace(params).exercise;
+}
+function generateProgram(params) {
+    var _a, _b;
+    const { trainerAlgorithmSettings, frequency, goal, level, equipments, workoutDurationMinutes, restTimerLength, exerciseStore, focusMuscle, excludedExerciseIds, debugExerciseSelectionTrace, } = params;
+    const exerciseSelectionTraces = [];
+    const routines = exports.programSplits[frequency];
     const program = {
-        name: selectedDays,
+        name: frequency,
         routines: [],
     };
     const sortedExercises = (0, exports.getPrioritySortedExercises)(trainerAlgorithmSettings.exercise_priorities, exerciseStore);
@@ -513,7 +553,8 @@ const generateProgram = (params) => {
         let routineBarbellExerciseCount = 0;
         const routineUsedExerciseIds = new Set();
         const routineExercises = [];
-        for (const exercisePrescription of routineTemplate.exercises) {
+        for (let prescriptionIndex = 0; prescriptionIndex < routineTemplate.exercises.length; prescriptionIndex++) {
+            const exercisePrescription = routineTemplate.exercises[prescriptionIndex];
             const muscleGroup = getMuscleGroup({
                 muscleGroupPrescription: exercisePrescription.muscle_group,
                 programFocusMuscleExerciseCount,
@@ -525,31 +566,56 @@ const generateProgram = (params) => {
                 continue;
             }
             // If the exercise does not meet the min workout duration limit, skip the exercise
-            const execiseDoesNotMeetMinWorkoutDurationLimit = selectedWorkoutDurationMinutes &&
-                exercisePrescription.min_workout_duration_limit
+            const execiseDoesNotMeetMinWorkoutDurationLimit = exercisePrescription.min_workout_duration_limit
                 ? exercisePrescription.min_workout_duration_limit >
-                    selectedWorkoutDurationMinutes
+                    workoutDurationMinutes
                 : false;
             if (execiseDoesNotMeetMinWorkoutDurationLimit) {
                 continue;
             }
-            const exercise = (0, exports.pickExerciseForPrescription)({
-                sortedExercises,
-                criteria: {
-                    frequency: selectedDays,
-                    exerciseCategory: exercisePrescription.category,
-                    equipments: selectedEquipments,
-                    muscleGroup,
-                    routineBarbellExerciseCount,
-                    level: selectedLevel,
-                    goal: selectedGoal,
-                },
-                context: {
-                    programUsedExerciseIds,
-                    routineUsedExerciseIds,
-                    excludedExerciseIds,
-                },
-            });
+            const criteria = {
+                frequency,
+                exerciseCategory: exercisePrescription.category,
+                equipments,
+                muscleGroup,
+                routineBarbellExerciseCount,
+                level,
+                goal,
+            };
+            let exercise;
+            if (debugExerciseSelectionTrace) {
+                const selection = pickExerciseForPrescription({
+                    sortedExercises,
+                    criteria,
+                    context: {
+                        programUsedExerciseIds,
+                        routineUsedExerciseIds,
+                        excludedExerciseIds,
+                    },
+                    withTrace: true,
+                });
+                exercise = selection.exercise;
+                exerciseSelectionTraces.push({
+                    routine,
+                    prescriptionIndex,
+                    prescription: exercisePrescription,
+                    resolvedMuscleGroup: muscleGroup,
+                    criteria,
+                    selectedExerciseId: (_a = selection.exercise) === null || _a === void 0 ? void 0 : _a.id,
+                    trace: selection.trace,
+                });
+            }
+            else {
+                exercise = pickExerciseForPrescription({
+                    sortedExercises,
+                    criteria,
+                    context: {
+                        programUsedExerciseIds,
+                        routineUsedExerciseIds,
+                        excludedExerciseIds,
+                    },
+                });
+            }
             if (!!exercise) {
                 programUsedExerciseIds.add(exercise.id);
                 routineUsedExerciseIds.add(exercise.id);
@@ -557,17 +623,17 @@ const generateProgram = (params) => {
                     routineBarbellExerciseCount++;
                 if (exercisePrescription.muscle_group === 'focus_muscle')
                     programFocusMuscleExerciseCount++;
-                const repRange = (0, exports.getTrainerRepRange)(trainerAlgorithmSettings, selectedGoal, exercisePrescription.category);
+                const repRange = (0, exports.getTrainerRepRange)(trainerAlgorithmSettings, goal, exercisePrescription.category);
                 routineExercises.push({
                     exerciseTemplate: exercise,
                     muscleGroup: exercisePrescription.muscle_group,
                     category: exercisePrescription.category,
-                    sets: (0, exports.getTrainerSetCount)(trainerAlgorithmSettings, selectedGoal, selectedDays),
+                    sets: (0, exports.getTrainerSetCount)(trainerAlgorithmSettings, goal, frequency),
                     repRangeStart: repRange.rep_range_start,
                     repRangeEnd: repRange.rep_range_end,
-                    restTimerSeconds: (0, exports.getTrainerRestTimerSeconds)(trainerAlgorithmSettings, selectedGoal, selectedRestTimerLength, exercisePrescription.category),
+                    restTimerSeconds: (0, exports.getTrainerRestTimerSeconds)(trainerAlgorithmSettings, goal, restTimerLength, exercisePrescription.category),
                     warmupSetCount: exercisePrescription.warmup_set_count,
-                    notes: (_a = trainerAlgorithmSettings.exercise_notes[exercise.id]) !== null && _a !== void 0 ? _a : '',
+                    notes: (_b = trainerAlgorithmSettings.exercise_notes[exercise.id]) !== null && _b !== void 0 ? _b : '',
                 });
             }
             else {
@@ -577,9 +643,9 @@ const generateProgram = (params) => {
                     prescription: exercisePrescription,
                     muscleGroup,
                     context: {
-                        goal: selectedGoal,
-                        level: selectedLevel,
-                        equipments: selectedEquipments,
+                        goal,
+                        level,
+                        equipments,
                         focusMuscle,
                     },
                 });
@@ -593,15 +659,18 @@ const generateProgram = (params) => {
     }
     // Return result based on whether there were errors
     if (allErrors.length > 0) {
-        return {
+        const result = {
             success: false,
             errors: allErrors,
             partialProgram: program,
         };
+        return debugExerciseSelectionTrace
+            ? Object.assign(Object.assign({}, result), { exerciseSelectionTraces }) : result;
     }
-    return {
+    const result = {
         success: true,
         program,
     };
-};
-exports.generateProgram = generateProgram;
+    return debugExerciseSelectionTrace
+        ? Object.assign(Object.assign({}, result), { exerciseSelectionTraces }) : result;
+}

package/built/index.d.ts

@@ -1,8 +1,6 @@
 import { WorkoutDurationMinutes } from './hevyTrainer';
-import { postEmailBackofficeSchema } from './schemas';
 import { Language } from './translations';
 import { Lookup } from './typeUtils';
-import z from 'zod';
 export * from './constants';
 export * from './utils';
 export * from './units';
@@ -1989,4 +1987,3 @@ export interface GetAccountsByEmailResponse {
         wellhub_email: string | null;
     }[];
 }
-export type PostEmailBackofficeRequest = z.infer<typeof postEmailBackofficeSchema>;