@dgpholdings/greatoak-shared 1.2.28 → 1.2.30

package/README.md

@@ -1,93 +1,118 @@
-# Shared
+# @dgpholdings/greatoak-shared
 
+The shared library for the Fitfrix ecosystem. Contains all types, utilities, and the scoring engine used across:
 
+- `v2/fitfrix` — the mobile app (React Native / Expo)
+- `backend/api-service` — the NestJS backend
+- `fitfrix.com` — the web/landing (Vite + React)
 
-## Getting started
+Any type, constant, or utility that is used by more than one package lives here. If you're about to define a type locally in a consuming app — check here first.
 
-To make it easy for you to get started with GitLab, here's a list of recommended next steps.
+---
 
-Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
+## Install / Import
 
-## Add your files
+```ts
+// Types
+import type { TExercise, TRecord, TUserMetric } from '@dgpholdings/greatoak-shared';
 
-- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
-- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:
-
-```
-cd existing_repo
-git remote add origin https://gitlab.com/greatoak/shared.git
-git branch -M main
-git push -uf origin main
+// Utils
+import { calculateExerciseScoreV2, calculateTotalVolume, isDefined, toError } from '@dgpholdings/greatoak-shared';
 ```
 
-## Integrate with your tools
-
-- [ ] [Set up project integrations](https://gitlab.com/greatoak/shared/-/settings/integrations)
-
-## Collaborate with your team
-
-- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
-- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
-- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
-- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
-- [ ] [Set auto-merge](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)
-
-## Test and Deploy
-
-Use the built-in continuous integration in GitLab.
-
-- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)
-- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
-- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
-- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
-- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
-
-***
-
-# Editing this README
-
-When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template.
-
-## Suggestions for a good README
-
-Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
+---
+
+## What's Inside
+
+| Category | Location | Doc |
+|---|---|---|
+| **Types** | `src/types/` | [docs/types.md](docs/types.md) |
+| **Utils** | `src/utils/` | [docs/utils.md](docs/utils.md) |
+| **Scoring Engine** | `src/utils/scoring/` | [docs/scoring.md](docs/scoring.md) |
+
+---
+
+## Types — Quick Reference
+
+| File | What it defines |
+|---|---|
+| `commonTypes.ts` | `TRecord`, `TExerciseConfig`, `TTemplateExercise`, `TGdprData`, `TDayKey` |
+| `TApiExercise.ts` | `TExercise`, `TBodyPart`, `EBodyParts`, `TTrainingType`, `TTimingGuardrails` |
+| `TApiUser.ts` | `TUserMetric`, `TFitnessGoal`, `TUserType`, `TSubscriptionStatus`, `TGender` |
+| `TApiAuth.ts` | `TOnboardingData`, signup/signin request & response types |
+| `TApiExerciseRecord.ts` | Record save/fetch request & response types |
+| `TApiTemplateData.ts` | `TTemplate`, `TTemplateDb`, `TTemplateData`, `TExerciseLatestRecord` |
+| `TApiProPlan.ts` | `TProPlan`, pro plan CRUD request & response types |
+| `TApiTemplateShop.ts` | `TTemplateShopDb`, shop CRUD & shared plan types |
+| `TApiBillingPlan.ts` | `TBillingPlan`, `TBillingCountries`, billing API types |
+| `TApiRevenueCat.ts` | `TApiRevenueCatWebhookReq`, RevenueCat event types |
+| `TApiClientProgress.ts` | `TClientWorkoutHistory`, trainer dashboard types |
+
+---
+
+## Utils — Quick Reference
+
+| Export | What it does |
+|---|---|
+| `calculateExerciseScoreV2` | Full exercise scoring → `{ score, muscleScores }` |
+| `calculateTotalVolume` | Total workout volume for charts |
+| `isDefined` / `isDefinedNumber` | Null/undefined type guards |
+| `toError` | Converts unknown catch values to `Error` |
+| `toNumber` | Safe string/number → `number \| undefined` |
+| `mmssToSecs` | `"MM:SS"` → seconds |
+| `getDaysAndHoursDifference` | Date diff → `{ days, hours }` |
+| `isUserAllowedToUpdate` | Profile update rate-limit guard |
+| `countryToCurrencyCode` | Country code → ISO currency string |
+| `slugifyText` | Text → URL-safe slug |
+| `generatePlanCode` | Generates a unique 9-char Crockford Base32 plan code |
+| `maskEmail` / `isEmail` / `isAnonymousEmail` | Email utilities |
+| `NOOP` | Empty function `() => {}` |
+
+---
+
+## Source Structure
 
-## Name
-Choose a self-explaining name for your project.
-
-## Description
-Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
-
-## Badges
-On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
-
-## Visuals
-Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
-
-## Installation
-Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
-
-## Usage
-Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
-
-## Support
-Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
-
-## Roadmap
-If you have ideas for releases in the future, it is a good idea to list them in the README.
-
-## Contributing
-State if you are open to contributions and what your requirements are for accepting them.
-
-For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
-
-You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
+```
+shared/
+├── src/
+│   ├── types/
+│   │   ├── index.ts               # Re-exports all types
+│   │   ├── commonTypes.ts         # TRecord, TExerciseConfig, TTemplateExercise, TGdprData, TDayKey
+│   │   ├── TApiExercise.ts        # TExercise and related
+│   │   ├── TApiUser.ts            # TUserMetric and related
+│   │   ├── TApiAuth.ts            # Auth flows
+│   │   ├── TApiExerciseRecord.ts  # Workout record save/fetch
+│   │   ├── TApiTemplateData.ts    # User workout templates
+│   │   ├── TApiProPlan.ts         # Pro/trainer plans
+│   │   ├── TApiTemplateShop.ts    # Template shop (legacy, see TApiProPlan)
+│   │   ├── TApiBillingPlan.ts     # Billing plans
+│   │   ├── TApiRevenueCat.ts      # In-app purchase webhooks
+│   │   └── TApiClientProgress.ts  # Trainer client tracking
+│   └── utils/
+│       ├── index.ts               # Re-exports all utils
+│       ├── billing.utils.ts
+│       ├── email.utils.ts
+│       ├── isDefined.utils.ts
+│       ├── noop.utils.ts
+│       ├── number.util.ts
+│       ├── planCode.util.ts
+│       ├── slugify.util.ts
+│       ├── time.util.ts
+│       ├── toError.util.ts
+│       └── scoring/               # Exercise scoring engine
+│           └── README.md          # Full scoring documentation
+├── docs/
+│   ├── types.md                   # All types documented in detail
+│   ├── utils.md                   # All utils documented with examples
+│   └── scoring.md                 # Scoring system overview
+└── README.md                      # This file
+```
 
-## Authors and acknowledgment
-Show your appreciation to those who have contributed to the project.
+---
 
-## License
-For open source projects, say how it is licensed.
+## Key Design Rules
 
-## Project status
-If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
+- **No local duplication** — if a type or utility is needed by ≥2 packages, it belongs here
+- **No framework code** — this package must stay framework-agnostic (no React, no NestJS decorators)
+- **Strict types** — no `any`. Use generics, discriminated unions, or `unknown`
+- **Scoring is the business core** — the scoring engine drives the muscle fatigue diagram and progress charts. Read [docs/scoring.md](docs/scoring.md) before touching it

package/dist/types/TApiExercise.d.ts

@@ -121,6 +121,8 @@ export type TExercise = {
     importantTipsHtml: string;
     popularityIndex: number;
     isFavorite?: boolean;
+    scoringSpecialHandling?: "plyometric" | "stretch-mobility" | "continuous-duration" | "loaded-carry";
+    isFlaggedCorrection?: boolean;
 };
 export type TBodyPartExercises = Record<TBodyPart, TExercise[]>;
 export type TApiCreateOrUpdateExerciseReq = {

package/dist/types/commonTypes.d.ts

@@ -21,13 +21,15 @@ export type TRecord = {
     rir?: string;
 } | {
     type: "cardio-machine";
-    speedMin: string;
-    speedMax: string;
+    speed?: string;
+    inclinePercentage?: string;
+    resistanceLevel?: string;
     durationMmSs: string;
     distance?: string;
 } | {
     type: "cardio-free";
     distance: string;
+    auxWeightKg?: string;
     durationMmSs: string;
 });
 export type TRecordDuration = Extract<TRecord, {
@@ -53,6 +55,8 @@ export type TExerciseConfig = {
     enableSetNote?: boolean;
     enableExerciseNote?: boolean;
     enableTimeIntervalMode?: boolean;
+    enableInclinePercentage?: boolean;
+    enableResistanceLevel?: boolean;
 };
 export type TTemplateExercise = {
     exerciseId: string;

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

@@ -63,5 +63,5 @@ interface IMetabolicData {
  * // → 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 declare function calculateCalories(sets: IParsedSet[], metabolicData: IMetabolicData, user: IUserContext, difficultyLevel: number, scoringSpecialHandling?: "plyometric" | "stretch-mobility" | "continuous-duration" | "loaded-carry"): number;
 export {};

package/dist/utils/scoring/calculateCalories.js

@@ -46,16 +46,21 @@ const helpers_1 = require("./helpers");
  * // → 6.4 (for 3 light bench press sets)
  * // → 142.3 (for a 20-min treadmill run)
  */
-function calculateCalories(sets, metabolicData, user, difficultyLevel) {
+function calculateCalories(sets, metabolicData, user, difficultyLevel, scoringSpecialHandling) {
     if (sets.length === 0)
         return 0;
+    // Stretch/mobility: no meaningful work calories — only passive rest MET applies
+    if (scoringSpecialHandling === "stretch-mobility") {
+        const totalRestSecs = sets.reduce((sum, s) => { var _a; return sum + ((_a = s.restDurationSecs) !== null && _a !== void 0 ? _a : 0); }, 0);
+        return Math.round(constants_1.REST_MET * user.weightKg * (totalRestSecs / 3600) * 10) / 10;
+    }
     // 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);
+        const effectiveMET = calculateEffectiveMET(set, metabolicData, metMin, metMax, user, difficultyLevel, scoringSpecialHandling);
         // 2. Work calories: MET × weight × time
         const workHours = set.activeDurationSecs / 3600;
         totalWorkCalories += effectiveMET * user.weightKg * workHours;
@@ -85,12 +90,19 @@ function calculateCalories(sets, metabolicData, user, difficultyLevel) {
  * 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;
+function calculateEffectiveMET(set, metabolicData, metMin, metMax, user, difficultyLevel, scoringSpecialHandling) {
+    var _a, _b, _c, _d, _e;
     // 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;
+    // Continuous-duration (battle ropes, high knees, jump rope): these behave like
+    // cardio metabolically — bypass the static-hold duration formula entirely
+    if (scoringSpecialHandling === "continuous-duration") {
+        met = metMin + (metMax - metMin) * effortNormalized;
+        met *= metabolicData.compoundMultiplier;
+        return (0, helpers_1.clamp)(met, 1, 25);
+    }
     // Apply type-specific intensity scaling
     switch (set.type) {
         case "weight-reps":
@@ -103,11 +115,17 @@ function calculateEffectiveMET(set, metabolicData, metMin, metMax, user, difficu
             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);
+            // Loaded carry: scale MET up by the weight being carried relative to bodyweight
+            if (scoringSpecialHandling === "loaded-carry") {
+                const auxWeightKg = (_e = set.auxWeightKg) !== null && _e !== void 0 ? _e : 0;
+                if (auxWeightKg > 0) {
+                    met *= 1 + (auxWeightKg / user.weightKg) * constants_1.LOADED_CARRY_WEIGHT_MET_SCALE;
+                }
+            }
             break;
     }
     // Apply compound multiplier (multi-joint exercises have higher energy cost)
@@ -190,11 +208,9 @@ function getDurationMultiplier(durationSecs, auxWeightKg, userWeightKg, metaboli
  * 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;
+    var _a;
     // Average speed from the set data
-    const avgSpeed = (speedMin + speedMax) / 2;
+    const avgSpeed = (_a = set.speed) !== null && _a !== void 0 ? _a : 0;
     if (avgSpeed > 0) {
         // If we have pace factors, use them for more accurate MET lookup
         if (metabolicData.paceFactors) {

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

@@ -48,6 +48,7 @@ interface IFatigueExerciseData {
         compoundMultiplier: number;
         muscleGroupFactor: number;
     };
+    scoringSpecialHandling?: "plyometric" | "stretch-mobility" | "continuous-duration" | "loaded-carry";
 }
 /**
  * Calculate per-muscle fatigue scores for an exercise.

package/dist/utils/scoring/calculateMuscleFatiue.js

@@ -59,9 +59,12 @@ function calculateMuscleFatigue(sets, exercise, user, timingGuardrails) {
     var _a;
     if (sets.length === 0)
         return {};
+    // Stretching/mobility produces zero mechanical fatigue — skip entirely
+    if (exercise.scoringSpecialHandling === "stretch-mobility")
+        return {};
     const fatigueMultiplier = (_a = timingGuardrails === null || timingGuardrails === void 0 ? void 0 : timingGuardrails.fatigueMultiplier) !== null && _a !== void 0 ? _a : constants_1.FALLBACK_FATIGUE_MULTIPLIER;
     // --- Step 1–3: Compute cumulative fatigue stimulus ---
-    const cumulativeFatigue = computeCumulativeFatigue(sets, exercise.difficultyLevel, user, fatigueMultiplier);
+    const cumulativeFatigue = computeCumulativeFatigue(sets, exercise.difficultyLevel, user, fatigueMultiplier, exercise.scoringSpecialHandling);
     // --- Step 4: Distribute to muscles ---
     const rawMuscleFatigue = distributeFatigueToMuscles(cumulativeFatigue, exercise.primaryMuscles, exercise.secondaryMuscles);
     // --- Step 5: Normalize to 0–100 ---
@@ -77,13 +80,16 @@ function calculateMuscleFatigue(sets, exercise, user, timingGuardrails) {
  * Volume load represents the mechanical work experienced by the muscles.
  * Different exercise types produce volume in fundamentally different ways:
  *
- * weight-reps:   Force (kg) × repetitions
- * reps-only:     Effective load (BW fraction + aux) × repetitions
- * duration:      Time under tension × difficulty scaling × aux boost
- * cardio:        Duration × speed factor (represents sustained effort)
+ * weight-reps:        Force (kg) × repetitions
+ * reps-only:          Effective load (BW fraction + aux) × repetitions
+ *   plyometric:       Same + PLYOMETRIC_LOAD_MULTIPLIER for impact/neuromotor demand
+ * duration:           Time under tension × difficulty scaling × aux boost
+ *   continuous-duration: Routed through cardio path with dampener (no static hold)
+ * cardio:             Duration × speed factor (represents sustained effort)
+ *   loaded-carry:     Speed factor boosted by carried weight relative to bodyweight
  */
-function computeVolumeLoad(set, difficultyLevel, user) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+function computeVolumeLoad(set, difficultyLevel, user, scoringSpecialHandling) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
     switch (set.type) {
         case "weight-reps": {
             const kg = (_a = set.kg) !== null && _a !== void 0 ? _a : 0;
@@ -97,11 +103,22 @@ function computeVolumeLoad(set, difficultyLevel, user) {
             // difficulty 0 → 0%, difficulty 2 → ~33%, difficulty 4 → 65%
             const bodyweightLoad = (difficultyLevel / 4) * constants_1.BW_FRACTION_SCALE * user.weightKg;
             const totalLoad = bodyweightLoad + auxWeightKg;
-            return totalLoad * reps;
+            const baseVolume = totalLoad * reps;
+            // Plyometric: impact forces and neuromotor demand exceed simple BW × reps
+            if (scoringSpecialHandling === "plyometric") {
+                return baseVolume * constants_1.PLYOMETRIC_LOAD_MULTIPLIER;
+            }
+            return baseVolume;
         }
         case "duration": {
-            const durationSecs = (_e = set.durationSecs) !== null && _e !== void 0 ? _e : set.activeDurationSecs;
-            const auxWeightKg = (_f = set.auxWeightKg) !== null && _f !== void 0 ? _f : 0;
+            // Continuous-movement duration (battle ropes, high knees, jump rope):
+            // these are not static holds — route through cardio path with dampener
+            if (scoringSpecialHandling === "continuous-duration") {
+                const durationSecs = (_e = set.durationSecs) !== null && _e !== void 0 ? _e : set.activeDurationSecs;
+                return durationSecs * constants_1.CONTINUOUS_DURATION_INTENSITY_FACTOR * constants_1.CARDIO_MUSCLE_FATIGUE_DAMPENER;
+            }
+            const durationSecs = (_f = set.durationSecs) !== null && _f !== void 0 ? _f : set.activeDurationSecs;
+            const auxWeightKg = (_g = set.auxWeightKg) !== null && _g !== void 0 ? _g : 0;
             // Duration exercises: time under tension is the primary driver
             // Scale by (difficultyLevel + 1) so even difficulty-0 produces some fatigue
             // Aux weight adds load (holding a plate during plank, etc.)
@@ -109,13 +126,11 @@ function computeVolumeLoad(set, difficultyLevel, user) {
             return durationSecs * (difficultyLevel + 1) * auxBoost;
         }
         case "cardio-machine": {
-            const durationSecs = (_g = set.cardioDurationSecs) !== null && _g !== void 0 ? _g : set.activeDurationSecs;
-            const speedMin = (_h = set.speedMin) !== null && _h !== void 0 ? _h : 0;
-            const speedMax = (_j = set.speedMax) !== null && _j !== void 0 ? _j : 0;
-            const avgSpeed = (speedMin + speedMax) / 2;
+            const durationSecs = (_h = set.cardioDurationSecs) !== null && _h !== void 0 ? _h : set.activeDurationSecs;
+            const speed = (_j = set.speed) !== null && _j !== void 0 ? _j : 0;
             // Speed factor: faster pace = more muscle engagement per second
             // Normalize against expected speed range (3–20 km/h)
-            const speedFactor = avgSpeed > 0 ? (0, helpers_1.clamp)(avgSpeed / constants_1.CARDIO_SPEED_RANGE.max, 0.1, 1.5) : 0.3; // fallback: light effort
+            const speedFactor = speed > 0 ? (0, helpers_1.clamp)(speed / constants_1.CARDIO_SPEED_RANGE.max, 0.1, 1.5) : 0.3; // fallback: light effort
             // Cardio dampener: running fatigues muscles less than lifting
             // A 30-min jog ≠ 30 min of squats for muscle fatigue
             return durationSecs * speedFactor * constants_1.CARDIO_MUSCLE_FATIGUE_DAMPENER;
@@ -123,16 +138,21 @@ function computeVolumeLoad(set, difficultyLevel, user) {
         case "cardio-free": {
             const durationSecs = (_k = set.cardioDurationSecs) !== null && _k !== void 0 ? _k : set.activeDurationSecs;
             const distance = (_l = set.distance) !== null && _l !== void 0 ? _l : 0;
-            let baseVolume;
+            let speedFactor;
             if (distance > 0 && durationSecs > 0) {
                 const speedKmh = distance / (durationSecs / 3600);
-                const speedFactor = (0, helpers_1.clamp)(speedKmh / constants_1.CARDIO_SPEED_RANGE.max, 0.1, 1.5);
-                baseVolume = durationSecs * speedFactor;
+                speedFactor = (0, helpers_1.clamp)(speedKmh / constants_1.CARDIO_SPEED_RANGE.max, 0.1, 1.5);
             }
             else {
-                baseVolume = durationSecs * 0.3;
+                speedFactor = 0.3;
             }
-            return baseVolume * constants_1.CARDIO_MUSCLE_FATIGUE_DAMPENER;
+            // Loaded carry: the weight being carried increases muscle stress beyond pace alone
+            if (scoringSpecialHandling === "loaded-carry") {
+                const auxWeightKg = (_m = set.auxWeightKg) !== null && _m !== void 0 ? _m : 0;
+                const weightBoost = 1 + (auxWeightKg / user.weightKg) * 0.4;
+                return durationSecs * speedFactor * weightBoost * constants_1.CARDIO_MUSCLE_FATIGUE_DAMPENER;
+            }
+            return durationSecs * speedFactor * constants_1.CARDIO_MUSCLE_FATIGUE_DAMPENER;
         }
         default:
             return 0;
@@ -155,12 +175,12 @@ function computeVolumeLoad(set, difficultyLevel, user) {
  *
  * @returns Single number representing total fatigue stimulus
  */
-function computeCumulativeFatigue(sets, difficultyLevel, user, fatigueMultiplier) {
+function computeCumulativeFatigue(sets, difficultyLevel, user, fatigueMultiplier, scoringSpecialHandling) {
     let cumulative = 0;
     for (let i = 0; i < sets.length; i++) {
         const set = sets[i];
         // Step 1: Raw volume for this set
-        const volumeLoad = computeVolumeLoad(set, difficultyLevel, user);
+        const volumeLoad = computeVolumeLoad(set, difficultyLevel, user, scoringSpecialHandling);
         // Step 2: Scale by effort and exercise fatigue multiplier
         const stimulus = volumeLoad * set.effortFraction * fatigueMultiplier;
         // Step 3: Apply diminishing returns decay

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

@@ -44,8 +44,9 @@ interface IRawRecord {
     reps?: string;
     durationMmSs?: string;
     auxWeightKg?: string;
-    speedMin?: string;
-    speedMax?: string;
+    speed?: string;
+    inclinePercentage?: string;
+    resistanceLevel?: string;
     distance?: string;
     restDurationSecs?: number;
 }

package/dist/utils/scoring/calculateQualityScore.js

@@ -137,7 +137,7 @@ function calculateConsistency(parsedSets) {
  * Extract the consistency metric for a set based on its type.
  */
 function extractConsistencyMetric(set) {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _a, _b, _c, _d, _e, _f, _g;
     switch (set.type) {
         case "weight-reps": {
             // Volume per set: weight × reps
@@ -155,14 +155,13 @@ function extractConsistencyMetric(set) {
         }
         case "cardio-machine": {
             // Average speed
-            const speedMin = (_e = set.speedMin) !== null && _e !== void 0 ? _e : 0;
-            const speedMax = (_f = set.speedMax) !== null && _f !== void 0 ? _f : 0;
-            return (speedMin + speedMax) / 2;
+            const speed = (_e = set.speed) !== null && _e !== void 0 ? _e : 0;
+            return speed;
         }
         case "cardio-free": {
             // Effective speed (km/h)
-            const distance = (_g = set.distance) !== null && _g !== void 0 ? _g : 0;
-            const durationSecs = (_h = set.cardioDurationSecs) !== null && _h !== void 0 ? _h : set.activeDurationSecs;
+            const distance = (_f = set.distance) !== null && _f !== void 0 ? _f : 0;
+            const durationSecs = (_g = set.cardioDurationSecs) !== null && _g !== void 0 ? _g : set.activeDurationSecs;
             if (durationSecs > 0 && distance > 0) {
                 return distance / (durationSecs / 3600);
             }

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

@@ -2,10 +2,14 @@ import { TRecord, TUserMetric } from "../../types";
 /**
  * Calculates total volume for a set of records.
  *
- * - weight-reps: reps * weight
- * - reps-only: reps * (auxWeight || 30% of bodyweight)
- * - duration: durationSecs * 10 * (1 + auxWeight/100)
- * - cardio-machine: distance (m) * (1 + avgSpeed/20)
- * - cardio-free: distance (m) * (1 + speed/20)
+ * - weight-reps:        reps * weight
+ * - reps-only:          reps * (auxWeight || 30% of bodyweight)
+ *   plyometric:         × 1.5 multiplier for impact/explosive demand
+ * - duration:           durationSecs * 10 * (1 + auxWeight/100)
+ *   continuous-duration: durationSecs only (no static-hold multiplier)
+ *   stretch-mobility:   0 (no training volume)
+ * - cardio-machine:     distance (m) * (1 + speed/20) * inclineBoost * resistanceBoost
+ * - cardio-free:        distance (m) * (1 + speed/20)
+ *   loaded-carry:       × carried weight boost
  */
-export declare const calculateTotalVolume: (record: TRecord[], user: TUserMetric) => number;
+export declare const calculateTotalVolume: (record: TRecord[], user: TUserMetric, scoringSpecialHandling?: "plyometric" | "stretch-mobility" | "continuous-duration" | "loaded-carry") => number;

package/dist/utils/scoring/calculateTotalVolume.js

@@ -5,18 +5,25 @@ const time_util_1 = require("../time.util");
 /**
  * Calculates total volume for a set of records.
  *
- * - weight-reps: reps * weight
- * - reps-only: reps * (auxWeight || 30% of bodyweight)
- * - duration: durationSecs * 10 * (1 + auxWeight/100)
- * - cardio-machine: distance (m) * (1 + avgSpeed/20)
- * - cardio-free: distance (m) * (1 + speed/20)
+ * - weight-reps:        reps * weight
+ * - reps-only:          reps * (auxWeight || 30% of bodyweight)
+ *   plyometric:         × 1.5 multiplier for impact/explosive demand
+ * - duration:           durationSecs * 10 * (1 + auxWeight/100)
+ *   continuous-duration: durationSecs only (no static-hold multiplier)
+ *   stretch-mobility:   0 (no training volume)
+ * - cardio-machine:     distance (m) * (1 + speed/20) * inclineBoost * resistanceBoost
+ * - cardio-free:        distance (m) * (1 + speed/20)
+ *   loaded-carry:       × carried weight boost
  */
-const calculateTotalVolume = (record, user) => {
+const calculateTotalVolume = (record, user, scoringSpecialHandling) => {
+    // Stretching/mobility produces no training volume
+    if (scoringSpecialHandling === "stretch-mobility")
+        return 0;
     return record.reduce((total, set) => {
         const weight = parseFloat(set.type === "weight-reps"
             ? set.kg
-            : set.type === "duration" || set.type === "reps-only"
-                ? set.auxWeightKg
+            : set.type === "duration" || set.type === "reps-only" || set.type === "cardio-free"
+                ? set.auxWeightKg || "0"
                 : "0") || 0;
         const reps = parseFloat(set.type === "weight-reps" || set.type === "reps-only" ? set.reps : "0") || 0;
         const duration = set.type === "duration" ||
@@ -30,21 +37,35 @@ const calculateTotalVolume = (record, user) => {
         else if (set.type === "reps-only") {
             const bodyweight = user.weightKg || 70;
             const effectiveWeight = weight > 0 ? weight : bodyweight * 0.3;
-            return total + reps * effectiveWeight;
+            const baseVolume = reps * effectiveWeight;
+            return total + (scoringSpecialHandling === "plyometric" ? baseVolume * 1.5 : baseVolume);
         }
         else if (set.type === "duration") {
+            // Continuous-duration: no static-hold multiplier — just time elapsed
+            if (scoringSpecialHandling === "continuous-duration") {
+                return total + duration;
+            }
             const weightFactor = weight > 0 ? 1 + weight / 100 : 1;
             return total + duration * 10 * weightFactor;
         }
         else if (set.type === "cardio-machine") {
-            const avgSpeed = (parseFloat(set.speedMin) + parseFloat(set.speedMax)) / 2 || 10;
-            const distance = parseFloat(set.distance || "0") || (avgSpeed * duration) / 3600;
-            return total + distance * 1000 * (1 + avgSpeed / 20);
+            const speed = parseFloat(set.speed || "10");
+            const inclineBoost = set.inclinePercentage
+                ? 1 + parseFloat(set.inclinePercentage) * 0.02
+                : 1;
+            const resistanceBoost = set.resistanceLevel
+                ? 1 + parseFloat(set.resistanceLevel) * 0.05
+                : 1;
+            const distance = parseFloat(set.distance || "0") || (speed * duration) / 3600;
+            return total + distance * 1000 * (1 + speed / 20) * inclineBoost * resistanceBoost;
         }
         else if (set.type === "cardio-free") {
             const distance = parseFloat(set.distance) || 0;
             const speed = distance / (duration / 3600);
-            return total + distance * 1000 * (1 + speed / 20);
+            const carryBoost = scoringSpecialHandling === "loaded-carry" && weight > 0
+                ? 1 + weight / (user.weightKg || 70) * 0.5
+                : 1;
+            return total + distance * 1000 * (1 + speed / 20) * carryBoost;
         }
         return total;
     }, 0);

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

@@ -133,6 +133,26 @@ export declare const SET_FATIGUE_DECAY_RATE = 0.15;
  * "volume" of strength work would.
  */
 export declare const CARDIO_MUSCLE_FATIGUE_DAMPENER = 0.3;
+/**
+ * Load multiplier for plyometric / explosive reps-only exercises.
+ * Accounts for impact forces (3–5× BW) and neuromotor demand that
+ * simple BW × reps volume underestimates.
+ * Applied to volume load before fatigue distribution.
+ */
+export declare const PLYOMETRIC_LOAD_MULTIPLIER = 1.5;
+/**
+ * Intensity factor for continuous-movement duration exercises
+ * (battle ropes, high knees, jump rope) when no speed/distance is available.
+ * Represents moderate continuous effort — higher than isometric holds but
+ * routed through the cardio dampener like other cardio types.
+ */
+export declare const CONTINUOUS_DURATION_INTENSITY_FACTOR = 0.5;
+/**
+ * MET scale factor for loaded-carry exercises (farmer's walk, overhead carry).
+ * For every 100% of bodyweight carried, MET is boosted by this fraction.
+ * e.g. carrying 50% BW → MET × (1 + 0.5 × 0.5) = MET × 1.25
+ */
+export declare const LOADED_CARRY_WEIGHT_MET_SCALE = 0.5;
 /**
  * Reference max scaling by difficulty level.
  * Maps difficultyLevel (0–4) → expected max weight as a fraction of bodyweight.

package/dist/utils/scoring/constants.js

@@ -16,7 +16,7 @@
  *   FACTOR_*    = multipliers used in formulas
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REST_NO_DATA_SCORE = exports.REST_OUTSIDE_SCORE = exports.REST_ACCEPTABLE_BASE = exports.REST_OPTIMAL_SCORE = exports.EFFORT_NO_DATA_SCORE = exports.EFFORT_MIN_SCORE = exports.EFFORT_DISTANCE_PENALTY = exports.OPTIMAL_RPE_RANGE = exports.OPTIMAL_RIR_RANGE = exports.PROGRESSIVE_OVERLOAD_FLOOR = exports.CONSISTENCY_MIN_SCORE = exports.CONSISTENCY_CV_PENALTY = exports.QUALITY_WEIGHTS = exports.REFERENCE_MAX_EFFORT = exports.REFERENCE_MAX_REPS = exports.REFERENCE_MAX_SETS = exports.DIFFICULTY_TO_WEIGHT_FRACTION = exports.CARDIO_MUSCLE_FATIGUE_DAMPENER = exports.SET_FATIGUE_DECAY_RATE = exports.SECONDARY_MUSCLE_ALLOCATION = exports.PRIMARY_MUSCLE_ALLOCATION = exports.CARDIO_SPEED_RANGE = exports.BW_FRACTION_SCALE = exports.DURATION_CATEGORY_THRESHOLDS = exports.DEFAULT_DURATION_FACTORS = exports.WEIGHT_CATEGORY_THRESHOLDS = exports.DEFAULT_WEIGHT_FACTORS = exports.REST_MET = exports.EFFORT_FRACTION_RANGE = exports.EFFORT_FRACTION_BASE = exports.EFFORT_CURVE_EXPONENT = exports.DEFAULT_EFFORT_FRACTION = exports.ABSOLUTE_WORK_MAX = exports.ABSOLUTE_WORK_MIN = exports.ABSOLUTE_REST_MAX = exports.ABSOLUTE_REST_MIN = exports.FALLBACK_STRESS_REST_BONUS = exports.FALLBACK_FATIGUE_MULTIPLIER = exports.FALLBACK_REST_SECS = exports.FALLBACK_SET_DURATION_SECS = exports.FALLBACK_SECS_PER_REP = exports.DEFAULT_USER_AGE = exports.DEFAULT_USER_HEIGHT_CM = exports.DEFAULT_USER_WEIGHT_KG = void 0;
+exports.REST_NO_DATA_SCORE = exports.REST_OUTSIDE_SCORE = exports.REST_ACCEPTABLE_BASE = exports.REST_OPTIMAL_SCORE = exports.EFFORT_NO_DATA_SCORE = exports.EFFORT_MIN_SCORE = exports.EFFORT_DISTANCE_PENALTY = exports.OPTIMAL_RPE_RANGE = exports.OPTIMAL_RIR_RANGE = exports.PROGRESSIVE_OVERLOAD_FLOOR = exports.CONSISTENCY_MIN_SCORE = exports.CONSISTENCY_CV_PENALTY = exports.QUALITY_WEIGHTS = exports.REFERENCE_MAX_EFFORT = exports.REFERENCE_MAX_REPS = exports.REFERENCE_MAX_SETS = exports.DIFFICULTY_TO_WEIGHT_FRACTION = exports.LOADED_CARRY_WEIGHT_MET_SCALE = exports.CONTINUOUS_DURATION_INTENSITY_FACTOR = exports.PLYOMETRIC_LOAD_MULTIPLIER = exports.CARDIO_MUSCLE_FATIGUE_DAMPENER = exports.SET_FATIGUE_DECAY_RATE = exports.SECONDARY_MUSCLE_ALLOCATION = exports.PRIMARY_MUSCLE_ALLOCATION = exports.CARDIO_SPEED_RANGE = exports.BW_FRACTION_SCALE = exports.DURATION_CATEGORY_THRESHOLDS = exports.DEFAULT_DURATION_FACTORS = exports.WEIGHT_CATEGORY_THRESHOLDS = exports.DEFAULT_WEIGHT_FACTORS = exports.REST_MET = exports.EFFORT_FRACTION_RANGE = exports.EFFORT_FRACTION_BASE = exports.EFFORT_CURVE_EXPONENT = exports.DEFAULT_EFFORT_FRACTION = exports.ABSOLUTE_WORK_MAX = exports.ABSOLUTE_WORK_MIN = exports.ABSOLUTE_REST_MAX = exports.ABSOLUTE_REST_MIN = exports.FALLBACK_STRESS_REST_BONUS = exports.FALLBACK_FATIGUE_MULTIPLIER = exports.FALLBACK_REST_SECS = exports.FALLBACK_SET_DURATION_SECS = exports.FALLBACK_SECS_PER_REP = exports.DEFAULT_USER_AGE = exports.DEFAULT_USER_HEIGHT_CM = exports.DEFAULT_USER_WEIGHT_KG = void 0;
 // ---------------------------------------------------------------------------
 // User Defaults (when TUserMetric has missing fields)
 // ---------------------------------------------------------------------------
@@ -165,6 +165,26 @@ exports.SET_FATIGUE_DECAY_RATE = 0.15;
  * "volume" of strength work would.
  */
 exports.CARDIO_MUSCLE_FATIGUE_DAMPENER = 0.3;
+/**
+ * Load multiplier for plyometric / explosive reps-only exercises.
+ * Accounts for impact forces (3–5× BW) and neuromotor demand that
+ * simple BW × reps volume underestimates.
+ * Applied to volume load before fatigue distribution.
+ */
+exports.PLYOMETRIC_LOAD_MULTIPLIER = 1.5;
+/**
+ * Intensity factor for continuous-movement duration exercises
+ * (battle ropes, high knees, jump rope) when no speed/distance is available.
+ * Represents moderate continuous effort — higher than isometric holds but
+ * routed through the cardio dampener like other cardio types.
+ */
+exports.CONTINUOUS_DURATION_INTENSITY_FACTOR = 0.5;
+/**
+ * MET scale factor for loaded-carry exercises (farmer's walk, overhead carry).
+ * For every 100% of bodyweight carried, MET is boosted by this fraction.
+ * e.g. carrying 50% BW → MET × (1 + 0.5 × 0.5) = MET × 1.25
+ */
+exports.LOADED_CARRY_WEIGHT_MET_SCALE = 0.5;
 /**
  * Reference max scaling by difficulty level.
  * Maps difficultyLevel (0–4) → expected max weight as a fraction of bodyweight.

package/dist/utils/scoring/index.js

@@ -38,6 +38,7 @@ const calculateExerciseScoreV2 = (param) => {
             compoundMultiplier: exercise.metabolicData.compoundMultiplier,
             muscleGroupFactor: exercise.metabolicData.muscleGroupFactor,
         },
+        scoringSpecialHandling: exercise.scoringSpecialHandling,
     }, userContext, exercise.timingGuardrails);
     // Pillar 3: Quality Score → score
     const { score } = (0, calculateQualityScore_1.calculateQualityScore)(parsedSets, record, exercise.timingGuardrails);

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

@@ -42,8 +42,9 @@ interface IRawRecord {
     reps?: string;
     durationMmSs?: string;
     auxWeightKg?: string;
-    speedMin?: string;
-    speedMax?: string;
+    speed?: string;
+    inclinePercentage?: string;
+    resistanceLevel?: string;
     distance?: string;
 }
 /**

package/dist/utils/scoring/parseRecords.js

@@ -143,8 +143,9 @@ function parseDuration(record, effortFraction, restDurationSecs, guardrails) {
     };
 }
 function parseCardioMachine(record, effortFraction, restDurationSecs) {
-    const speedMin = (0, helpers_1.safeParseFloat)(record.speedMin);
-    const speedMax = (0, helpers_1.safeParseFloat)(record.speedMax);
+    const speed = (0, helpers_1.safeParseFloat)(record.speed);
+    const inclinePercentage = (0, helpers_1.safeParseFloat)(record.inclinePercentage);
+    const resistanceLevel = (0, helpers_1.safeParseFloat)(record.resistanceLevel);
     const distance = (0, helpers_1.safeParseFloat)(record.distance);
     const cardioDurationSecs = (0, helpers_1.parseDurationMmSs)(record.durationMmSs);
     // Need at least duration or distance to be meaningful
@@ -156,14 +157,16 @@ function parseCardioMachine(record, effortFraction, restDurationSecs) {
         activeDurationSecs,
         restDurationSecs,
         effortFraction,
-        speedMin,
-        speedMax,
+        speed,
+        inclinePercentage,
+        resistanceLevel,
         distance,
         cardioDurationSecs,
     };
 }
 function parseCardioFree(record, effortFraction, restDurationSecs) {
     const distance = (0, helpers_1.safeParseFloat)(record.distance);
+    const auxWeightKg = (0, helpers_1.safeParseFloat)(record.auxWeightKg);
     const cardioDurationSecs = (0, helpers_1.parseDurationMmSs)(record.durationMmSs);
     if (cardioDurationSecs === 0 && distance === 0)
         return null;
@@ -174,6 +177,7 @@ function parseCardioFree(record, effortFraction, restDurationSecs) {
         restDurationSecs,
         effortFraction,
         distance,
+        auxWeightKg,
         cardioDurationSecs,
     };
 }

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

@@ -63,10 +63,12 @@ export interface IParsedSet {
     auxWeightKg?: number;
     /** duration: hold time in seconds */
     durationSecs?: number;
-    /** cardio-machine: min speed */
-    speedMin?: number;
-    /** cardio-machine: max speed */
-    speedMax?: number;
+    /** cardio-machine: speed */
+    speed?: number;
+    /** cardio-machine: incline percentage (Treadmill) */
+    inclinePercentage?: number;
+    /** cardio-machine: resistance level (Elliptical, Cycling) */
+    resistanceLevel?: number;
     /** cardio-machine / cardio-free: distance (km) */
     distance?: number;
     /** cardio-free / cardio-machine: session duration in seconds */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dgpholdings/greatoak-shared",
-	"version": "1.2.28",
+	"version": "1.2.30",
 	"description": "Shared TypeScript types and utilities for @dgpholdings projects",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",