@dgpholdings/greatoak-shared 1.2.16 → 1.2.17

package/dist/utils/index.d.ts

@@ -8,3 +8,4 @@ export { toError } from "./toError.util";
 export { generatePlanCode } from "./planCode.util";
 export { maskEmail, isAnonymousEmail, isEmail } from "./email.utils";
 export { NOOP } from "./noop.utils";
+export { calculateExerciseScoreV2 } from "./scoring";

package/dist/utils/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NOOP = exports.isEmail = exports.isAnonymousEmail = exports.maskEmail = exports.generatePlanCode = exports.toError = exports.slugifyText = exports.isDefinedNumber = exports.isDefined = exports.calculateExerciseScore = exports.countryToCurrencyCode = exports.getDaysAndHoursDifference = exports.isUserAllowedToUpdate = exports.mmssToSecs = exports.toNumber = void 0;
+exports.calculateExerciseScoreV2 = exports.NOOP = exports.isEmail = exports.isAnonymousEmail = exports.maskEmail = exports.generatePlanCode = exports.toError = exports.slugifyText = exports.isDefinedNumber = exports.isDefined = exports.calculateExerciseScore = exports.countryToCurrencyCode = exports.getDaysAndHoursDifference = exports.isUserAllowedToUpdate = exports.mmssToSecs = exports.toNumber = void 0;
 var number_util_1 = require("./number.util");
 Object.defineProperty(exports, "toNumber", { enumerable: true, get: function () { return number_util_1.toNumber; } });
 var time_util_1 = require("./time.util");
@@ -26,3 +26,5 @@ Object.defineProperty(exports, "isAnonymousEmail", { enumerable: true, get: func
 Object.defineProperty(exports, "isEmail", { enumerable: true, get: function () { return email_utils_1.isEmail; } });
 var noop_utils_1 = require("./noop.utils");
 Object.defineProperty(exports, "NOOP", { enumerable: true, get: function () { return noop_utils_1.NOOP; } });
+var scoring_1 = require("./scoring");
+Object.defineProperty(exports, "calculateExerciseScoreV2", { enumerable: true, get: function () { return scoring_1.calculateExerciseScoreV2; } });

package/dist/utils/scoring/calculateCalories.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Pillar 1: Calorie Burn
+ * ============================================================================
+ *
+ * Estimates energy expenditure (kcal) for an exercise using the MET system.
+ *
+ * Formula (per set):
+ *   calories = effectiveMET × userWeightKg × (activeDurationSecs / 3600)
+ *
+ * Where effectiveMET is the exercise's baseMET adjusted for:
+ *   - Effort level (RPE/RIR → scales within metRange)
+ *   - Weight intensity (for weight-reps: how heavy relative to bodyweight)
+ *   - Duration category (for duration: short/medium/long multiplier)
+ *   - Speed (for cardio: interpolated from pace or speed range)
+ *   - Compound multiplier (multi-joint exercises burn more)
+ *
+ * After summing all sets:
+ *   - Rest calories are added (elevated MET during rest periods)
+ *   - EPOC (afterburn) is added as a percentage of work calories
+ *
+ * References:
+ *   - Ainsworth BE et al. "Compendium of Physical Activities" (2011)
+ *   - Katch, McArdle & Katch, "Exercise Physiology" (8th ed.)
+ */
+import type { IParsedSet, IUserContext } from "./types";
+interface IMetabolicData {
+    baseMET: number;
+    metRange: [number, number];
+    compoundMultiplier: number;
+    muscleGroupFactor: number;
+    intensityScaling: "linear" | "exponential" | "plateau";
+    epocFactor: number;
+    weightFactors?: {
+        lightWeight: number;
+        moderateWeight: number;
+        heavyWeight: number;
+    };
+    durationFactors?: {
+        shortDuration: number;
+        mediumDuration: number;
+        longDuration: number;
+    };
+    paceFactors?: Record<string, number>;
+    lightWeight?: number;
+    moderateWeight?: number;
+    heavyWeight?: number;
+    shortDuration?: number;
+    mediumDuration?: number;
+    longDuration?: number;
+}
+/**
+ * Calculate total calorie burn for an exercise.
+ *
+ * @param sets           Parsed & validated sets (from parseRecords)
+ * @param metabolicData  Exercise's metabolic configuration
+ * @param user           Validated user context
+ * @param difficultyLevel Exercise difficulty (0–4), used for bodyweight estimation
+ * @returns              Total calories burned (kcal), rounded to 1 decimal
+ *
+ * @example
+ * const calories = calculateCalories(parsedSets, exercise.metabolicData, userCtx, exercise.difficultyLevel);
+ * // → 6.4 (for 3 light bench press sets)
+ * // → 142.3 (for a 20-min treadmill run)
+ */
+export declare function calculateCalories(sets: IParsedSet[], metabolicData: IMetabolicData, user: IUserContext, difficultyLevel: number): number;
+export {};

package/dist/utils/scoring/calculateCalories.js

@@ -0,0 +1,329 @@
+"use strict";
+// calculateCalories.ts
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Pillar 1: Calorie Burn
+ * ============================================================================
+ *
+ * Estimates energy expenditure (kcal) for an exercise using the MET system.
+ *
+ * Formula (per set):
+ *   calories = effectiveMET × userWeightKg × (activeDurationSecs / 3600)
+ *
+ * Where effectiveMET is the exercise's baseMET adjusted for:
+ *   - Effort level (RPE/RIR → scales within metRange)
+ *   - Weight intensity (for weight-reps: how heavy relative to bodyweight)
+ *   - Duration category (for duration: short/medium/long multiplier)
+ *   - Speed (for cardio: interpolated from pace or speed range)
+ *   - Compound multiplier (multi-joint exercises burn more)
+ *
+ * After summing all sets:
+ *   - Rest calories are added (elevated MET during rest periods)
+ *   - EPOC (afterburn) is added as a percentage of work calories
+ *
+ * References:
+ *   - Ainsworth BE et al. "Compendium of Physical Activities" (2011)
+ *   - Katch, McArdle & Katch, "Exercise Physiology" (8th ed.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateCalories = calculateCalories;
+const constants_1 = require("./constants");
+const helpers_1 = require("./helpers");
+// ---------------------------------------------------------------------------
+// Main Calorie Calculation
+// ---------------------------------------------------------------------------
+/**
+ * Calculate total calorie burn for an exercise.
+ *
+ * @param sets           Parsed & validated sets (from parseRecords)
+ * @param metabolicData  Exercise's metabolic configuration
+ * @param user           Validated user context
+ * @param difficultyLevel Exercise difficulty (0–4), used for bodyweight estimation
+ * @returns              Total calories burned (kcal), rounded to 1 decimal
+ *
+ * @example
+ * const calories = calculateCalories(parsedSets, exercise.metabolicData, userCtx, exercise.difficultyLevel);
+ * // → 6.4 (for 3 light bench press sets)
+ * // → 142.3 (for a 20-min treadmill run)
+ */
+function calculateCalories(sets, metabolicData, user, difficultyLevel) {
+    if (sets.length === 0)
+        return 0;
+    // Normalize metRange so [0] = min, [1] = max (sample data has them reversed)
+    const [metMin, metMax] = normalizeMetRange(metabolicData.metRange, metabolicData.baseMET);
+    let totalWorkCalories = 0;
+    let totalRestCalories = 0;
+    for (const set of sets) {
+        // 1. Calculate effective MET for this set
+        const effectiveMET = calculateEffectiveMET(set, metabolicData, metMin, metMax, user, difficultyLevel);
+        // 2. Work calories: MET × weight × time
+        const workHours = set.activeDurationSecs / 3600;
+        totalWorkCalories += effectiveMET * user.weightKg * workHours;
+        // 3. Rest calories: elevated resting MET during recovery
+        if (set.restDurationSecs !== null && set.restDurationSecs > 0) {
+            const restHours = set.restDurationSecs / 3600;
+            totalRestCalories += constants_1.REST_MET * user.weightKg * restHours;
+        }
+    }
+    // 4. EPOC (Excess Post-exercise Oxygen Consumption) — afterburn effect
+    const epocCalories = totalWorkCalories * metabolicData.epocFactor;
+    // 5. Total = work + rest + afterburn
+    const total = totalWorkCalories + totalRestCalories + epocCalories;
+    return Math.round(total * 10) / 10; // Round to 1 decimal place
+}
+// ---------------------------------------------------------------------------
+// Effective MET Calculation (per set)
+// ---------------------------------------------------------------------------
+/**
+ * Calculate the effective MET for a single set based on its type and intensity.
+ *
+ * The general approach:
+ *   1. Interpolate base MET within [metMin, metMax] using effort fraction
+ *   2. Apply type-specific intensity multiplier
+ *   3. Apply compound multiplier
+ *
+ * The effort fraction (from RPE/RIR) determines WHERE in the MET range
+ * this set falls. Low effort → closer to metMin, high effort → closer to metMax.
+ */
+function calculateEffectiveMET(set, metabolicData, metMin, metMax, user, difficultyLevel) {
+    var _a, _b, _c, _d;
+    // Start with effort-scaled MET
+    // effortFraction is 0.5–1.3 (from helpers), we normalize to 0–1 for interpolation
+    const effortNormalized = (0, helpers_1.clamp)((set.effortFraction - 0.5) / 0.8, 0, 1);
+    let met = metMin + (metMax - metMin) * effortNormalized;
+    // Apply type-specific intensity scaling
+    switch (set.type) {
+        case "weight-reps":
+            met *= getWeightMultiplier((_a = set.kg) !== null && _a !== void 0 ? _a : 0, user.weightKg, metabolicData);
+            break;
+        case "reps-only":
+            met *= getRepsOnlyMultiplier((_b = set.auxWeightKg) !== null && _b !== void 0 ? _b : 0, user.weightKg, difficultyLevel);
+            break;
+        case "duration":
+            met *= getDurationMultiplier((_c = set.durationSecs) !== null && _c !== void 0 ? _c : 0, (_d = set.auxWeightKg) !== null && _d !== void 0 ? _d : 0, user.weightKg, metabolicData);
+            break;
+        case "cardio-machine":
+            // For cardio, we override the effort-based MET with speed-based MET
+            met = getCardioMachineMET(set, metabolicData, metMin, metMax, effortNormalized);
+            break;
+        case "cardio-free":
+            met = getCardioFreeMET(set, metabolicData, metMin, metMax, effortNormalized);
+            break;
+    }
+    // Apply compound multiplier (multi-joint exercises have higher energy cost)
+    met *= metabolicData.compoundMultiplier;
+    // Safety clamp: MET should never go below 1 or above 25
+    return (0, helpers_1.clamp)(met, 1, 25);
+}
+// ---------------------------------------------------------------------------
+// Type-Specific Multipliers
+// ---------------------------------------------------------------------------
+/**
+ * Weight multiplier for weight-reps exercises.
+ *
+ * Classifies the weight as light/moderate/heavy relative to bodyweight
+ * and returns the corresponding multiplier.
+ *
+ * Example: 10kg at 75kg bodyweight → ratio 0.13 → "light" → 0.8 multiplier
+ */
+function getWeightMultiplier(kg, userWeightKg, metabolicData) {
+    const ratio = kg / userWeightKg;
+    // Resolve weight factors (handle both nested and flat shapes)
+    const factors = resolveWeightFactors(metabolicData);
+    if (ratio < constants_1.WEIGHT_CATEGORY_THRESHOLDS.lightMax) {
+        return factors.light;
+    }
+    else if (ratio < constants_1.WEIGHT_CATEGORY_THRESHOLDS.moderateMax) {
+        return factors.moderate;
+    }
+    else {
+        return factors.heavy;
+    }
+}
+/**
+ * Multiplier for reps-only (bodyweight) exercises.
+ *
+ * The "load" is the user's bodyweight (scaled by difficulty) + any aux weight.
+ * We return a gentle multiplier that boosts MET slightly for added weight.
+ *
+ * Example: Push-up (difficulty 1) with 2.5kg vest at 75kg bodyweight
+ *   bodyweightLoad = (1/4) × 0.65 × 75 = 12.19 kg equivalent
+ *   totalLoad = 12.19 + 2.5 = 14.69
+ *   ratio = 14.69 / 75 = 0.196
+ *   multiplier = 1.0 + 0.196 × 0.5 = 1.098
+ */
+function getRepsOnlyMultiplier(auxWeightKg, userWeightKg, difficultyLevel) {
+    const bodyweightLoad = (difficultyLevel / 4) * constants_1.BW_FRACTION_SCALE * userWeightKg;
+    const totalLoad = bodyweightLoad + auxWeightKg;
+    const ratio = totalLoad / userWeightKg;
+    // Gentle scaling: aux weight adds intensity but not dramatically
+    return 1.0 + ratio * 0.5;
+}
+/**
+ * Multiplier for duration (isometric/hold) exercises.
+ *
+ * Two factors:
+ * 1. Duration category (short/medium/long) — longer holds are metabolically harder
+ * 2. Aux weight boost — holding weight during a plank increases energy cost
+ */
+function getDurationMultiplier(durationSecs, auxWeightKg, userWeightKg, metabolicData) {
+    // Resolve duration factors (handle both nested and flat shapes)
+    const factors = resolveDurationFactors(metabolicData);
+    let durationMultiplier;
+    if (durationSecs < constants_1.DURATION_CATEGORY_THRESHOLDS.shortMax) {
+        durationMultiplier = factors.short;
+    }
+    else if (durationSecs <= constants_1.DURATION_CATEGORY_THRESHOLDS.mediumMax) {
+        durationMultiplier = factors.medium;
+    }
+    else {
+        durationMultiplier = factors.long;
+    }
+    // Aux weight boosts MET (holding a plate during plank, weighted vest, etc.)
+    const auxBoost = 1.0 + (auxWeightKg / userWeightKg) * 0.3;
+    return durationMultiplier * auxBoost;
+}
+/**
+ * MET calculation for cardio-machine exercises (treadmill, stationary bike, etc.)
+ *
+ * Uses average speed to interpolate within the MET range.
+ * If paceFactors are available, we interpolate from the pace table instead.
+ */
+function getCardioMachineMET(set, metabolicData, metMin, metMax, effortNormalized) {
+    var _a, _b;
+    const speedMin = (_a = set.speedMin) !== null && _a !== void 0 ? _a : 0;
+    const speedMax = (_b = set.speedMax) !== null && _b !== void 0 ? _b : 0;
+    // Average speed from the set data
+    const avgSpeed = (speedMin + speedMax) / 2;
+    if (avgSpeed > 0) {
+        // If we have pace factors, use them for more accurate MET lookup
+        if (metabolicData.paceFactors) {
+            return interpolatePaceFactors(avgSpeed, metabolicData.paceFactors);
+        }
+        // Otherwise, interpolate linearly within metRange based on speed
+        const speedFraction = (0, helpers_1.clamp)((avgSpeed - constants_1.CARDIO_SPEED_RANGE.min) /
+            (constants_1.CARDIO_SPEED_RANGE.max - constants_1.CARDIO_SPEED_RANGE.min), 0, 1);
+        return metMin + (metMax - metMin) * speedFraction;
+    }
+    // No speed data: fall back to effort-based interpolation
+    return metMin + (metMax - metMin) * effortNormalized;
+}
+/**
+ * MET calculation for cardio-free exercises (outdoor running, cycling, etc.)
+ *
+ * Derives speed from distance ÷ time, then interpolates MET.
+ */
+function getCardioFreeMET(set, metabolicData, metMin, metMax, effortNormalized) {
+    var _a, _b;
+    const distance = (_a = set.distance) !== null && _a !== void 0 ? _a : 0;
+    const durationSecs = (_b = set.cardioDurationSecs) !== null && _b !== void 0 ? _b : 0;
+    if (distance > 0 && durationSecs > 0) {
+        // Speed in km/h
+        const speed = distance / (durationSecs / 3600);
+        if (metabolicData.paceFactors) {
+            return interpolatePaceFactors(speed, metabolicData.paceFactors);
+        }
+        const speedFraction = (0, helpers_1.clamp)((speed - constants_1.CARDIO_SPEED_RANGE.min) /
+            (constants_1.CARDIO_SPEED_RANGE.max - constants_1.CARDIO_SPEED_RANGE.min), 0, 1);
+        return metMin + (metMax - metMin) * speedFraction;
+    }
+    // No distance/time data: fall back to effort-based
+    return metMin + (metMax - metMin) * effortNormalized;
+}
+// ---------------------------------------------------------------------------
+// Resolution Helpers (handle flat vs nested metabolicData shapes)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve weight factors from metabolicData.
+ * Sample data sometimes has them nested under `weightFactors`, sometimes flat.
+ */
+function resolveWeightFactors(metabolicData) {
+    var _a, _b;
+    if (metabolicData.weightFactors) {
+        return {
+            light: metabolicData.weightFactors.lightWeight,
+            moderate: metabolicData.weightFactors.moderateWeight,
+            heavy: metabolicData.weightFactors.heavyWeight,
+        };
+    }
+    // Check flat shape
+    if (metabolicData.lightWeight !== undefined) {
+        return {
+            light: metabolicData.lightWeight,
+            moderate: (_a = metabolicData.moderateWeight) !== null && _a !== void 0 ? _a : constants_1.DEFAULT_WEIGHT_FACTORS.moderate,
+            heavy: (_b = metabolicData.heavyWeight) !== null && _b !== void 0 ? _b : constants_1.DEFAULT_WEIGHT_FACTORS.heavy,
+        };
+    }
+    return constants_1.DEFAULT_WEIGHT_FACTORS;
+}
+/**
+ * Resolve duration factors from metabolicData.
+ * Same flat-vs-nested handling as weight factors.
+ */
+function resolveDurationFactors(metabolicData) {
+    var _a, _b;
+    if (metabolicData.durationFactors) {
+        return {
+            short: metabolicData.durationFactors.shortDuration,
+            medium: metabolicData.durationFactors.mediumDuration,
+            long: metabolicData.durationFactors.longDuration,
+        };
+    }
+    // Check flat shape
+    if (metabolicData.shortDuration !== undefined) {
+        return {
+            short: metabolicData.shortDuration,
+            medium: (_a = metabolicData.mediumDuration) !== null && _a !== void 0 ? _a : constants_1.DEFAULT_DURATION_FACTORS.medium,
+            long: (_b = metabolicData.longDuration) !== null && _b !== void 0 ? _b : constants_1.DEFAULT_DURATION_FACTORS.long,
+        };
+    }
+    return constants_1.DEFAULT_DURATION_FACTORS;
+}
+/**
+ * Interpolate MET from a pace factors table.
+ *
+ * paceFactors is a map of speed (km/h) → MET value.
+ * We find the two closest speeds and linearly interpolate between them.
+ *
+ * Example:
+ *   paceFactors = { "5.0": 4.3, "8.0": 8.3, "12.0": 11.0, "16.0": 15.0 }
+ *   speed = 10 km/h → interpolate between 8.0 (8.3 MET) and 12.0 (11.0 MET)
+ *   result ≈ 9.65 MET
+ */
+function interpolatePaceFactors(speed, paceFactors) {
+    const entries = Object.keys(paceFactors)
+        .map((k) => [parseFloat(k), paceFactors[k]])
+        .filter(([k]) => !isNaN(k))
+        .sort((a, b) => a[0] - b[0]);
+    if (entries.length === 0)
+        return 3; // fallback moderate MET
+    // Below minimum pace
+    if (speed <= entries[0][0])
+        return entries[0][1];
+    // Above maximum pace
+    if (speed >= entries[entries.length - 1][0])
+        return entries[entries.length - 1][1];
+    // Find surrounding entries and interpolate
+    for (let i = 0; i < entries.length - 1; i++) {
+        const [speedLow, metLow] = entries[i];
+        const [speedHigh, metHigh] = entries[i + 1];
+        if (speed >= speedLow && speed <= speedHigh) {
+            const fraction = (speed - speedLow) / (speedHigh - speedLow);
+            return metLow + (metHigh - metLow) * fraction;
+        }
+    }
+    return entries[entries.length - 1][1]; // shouldn't reach here
+}
+/**
+ * Normalize metRange so [0] is always min and [1] is always max.
+ * Sample data has metRange as [5, 2] (max first) for some exercises.
+ */
+function normalizeMetRange(metRange, baseMET) {
+    const min = Math.min(metRange[0], metRange[1]);
+    const max = Math.max(metRange[0], metRange[1]);
+    // If range seems invalid, create one around baseMET
+    if (min === max || max === 0) {
+        return [baseMET * 0.7, baseMET * 1.5];
+    }
+    return [min, max];
+}

package/dist/utils/scoring/calculateMuscleFatiue.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Pillar 2: Muscle Fatigue
+ * ============================================================================
+ *
+ * Calculates per-muscle fatigue scores (0–100) for a single exercise.
+ *
+ * HOW IT WORKS:
+ *
+ * 1. For each set, compute a "fatigue stimulus" — how much mechanical work
+ *    the muscles experienced. This is type-specific:
+ *      weight-reps:   kg × reps
+ *      reps-only:     (bodyweightLoad + auxWeight) × reps
+ *      duration:      durationSecs × (difficultyLevel + 1) × auxBoost
+ *      cardio:        durationSecs × speedFactor
+ *
+ * 2. Multiply by effort (RPE/RIR → 0.5–1.3) and the exercise's
+ *    fatigueMultiplier from timingGuardrails.
+ *
+ * 3. Accumulate across sets with DIMINISHING RETURNS — later sets contribute
+ *    less because the muscle is pre-fatigued and can't generate as much force.
+ *    Decay: setDecay = 1 / (1 + 0.15 × setIndex)
+ *
+ * 4. Distribute the accumulated fatigue to muscles:
+ *      Primary muscles   → 100% of stimulus
+ *      Secondary muscles → 35% of stimulus
+ *
+ * 5. Normalize to 0–100 using an EXERCISE-AWARE reference maximum.
+ *    The reference max is what "5 hard sets of THIS exercise" would produce,
+ *    scaled by the exercise's difficultyLevel so bicep curls and squats
+ *    get fair scores.
+ *
+ * IMPORTANT: This function scores ONE exercise. The caller aggregates
+ * across exercises for full-workout muscle fatigue maps.
+ */
+import type { IParsedSet, IUserContext } from "./types";
+import type { ITimingGuardrails } from "./parseRecords";
+/** Muscle key from EBodyParts (e.g., "pectoralis-major", "quadriceps") */
+type MuscleKey = string;
+/**
+ * Minimal exercise metadata needed for fatigue calculation.
+ */
+interface IFatigueExerciseData {
+    primaryMuscles: MuscleKey[];
+    secondaryMuscles: MuscleKey[];
+    difficultyLevel: number;
+    metabolicData: {
+        compoundMultiplier: number;
+        muscleGroupFactor: number;
+    };
+}
+/**
+ * Calculate per-muscle fatigue scores for an exercise.
+ *
+ * @param sets              Parsed & validated sets (from parseRecords)
+ * @param exercise          Exercise metadata (muscles, difficulty, metabolic)
+ * @param user              Validated user context
+ * @param timingGuardrails  For fatigueMultiplier
+ * @returns                 Map of muscle key → fatigue score (0–100)
+ *
+ * @example
+ * const fatigue = calculateMuscleFatigue(parsedSets, exercise, userCtx, exercise.timingGuardrails);
+ * // → { "pectoralis-major": 24, "pectoralis-minor": 24, "deltoids-anterior": 8, ... }
+ */
+export declare function calculateMuscleFatigue(sets: IParsedSet[], exercise: IFatigueExerciseData, user: IUserContext, timingGuardrails?: ITimingGuardrails): Record<string, number>;
+export {};