@dgpholdings/greatoak-shared 1.2.86 → 1.2.88

package/README.md

@@ -1,149 +1,149 @@
-# @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)
-
-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.
-
----
-
-## Install / Import
-
-```ts
-// Types
-import type { TExercise, TRecord, TUserMetric } from '@dgpholdings/greatoak-shared';
-
-// Utils
-import { calculateExerciseScoreV2, calculateTotalVolume, isDefined, toError } from '@dgpholdings/greatoak-shared';
-```
-
----
-
-## 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` | Signup/signin request & response types (`TApiSignupAnonymousReq`, `TSignInRes`, etc.) |
-| `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
-
-```
-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
-```
-
----
-
-## Key Design Rules
-
-- **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
-
-
-## Renewing token 
-
-1. Login using the token (recommended way)
-
-In your Git Bash, run:
-
-`npm login`
-
-It will prompt:
-
-Username:
-Password:
-Email:
-
-Use this:
-
-Username → your npm username
-
-Password → paste the granular token (NOT your npm password)
-
-Email → your npm email
-
-After that, npm stores the token in:
-
-`shared\.npmrc`
-
-Then publishing works normally:
-
+# @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)
+
+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.
+
+---
+
+## Install / Import
+
+```ts
+// Types
+import type { TExercise, TRecord, TUserMetric } from '@dgpholdings/greatoak-shared';
+
+// Utils
+import { calculateExerciseScoreV2, calculateTotalVolume, isDefined, toError } from '@dgpholdings/greatoak-shared';
+```
+
+---
+
+## 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` | Signup/signin request & response types (`TApiSignupAnonymousReq`, `TSignInRes`, etc.) |
+| `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
+
+```
+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
+```
+
+---
+
+## Key Design Rules
+
+- **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
+
+
+## Renewing token 
+
+1. Login using the token (recommended way)
+
+In your Git Bash, run:
+
+`npm login`
+
+It will prompt:
+
+Username:
+Password:
+Email:
+
+Use this:
+
+Username → your npm username
+
+Password → paste the granular token (NOT your npm password)
+
+Email → your npm email
+
+After that, npm stores the token in:
+
+`shared\.npmrc`
+
+Then publishing works normally:
+
 `npm publish`

package/dist/__mocks__/catalog.fixture.d.ts

@@ -0,0 +1,2 @@
+import { TExercise } from "../types";
+export declare const testCatalog: Record<string, TExercise>;

package/dist/__mocks__/catalog.fixture.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testCatalog = void 0;
+exports.testCatalog = {
+    "-SR_ogujWtdkH6EtCe2OQ": {
+        exerciseId: "-SR_ogujWtdkH6EtCe2OQ",
+        name: "Diamond Push Up",
+        primaryMuscles: ["tricep-brachii-long", "tricep-brachii-lateral"],
+        secondaryMuscles: [
+            "pectoralis-major",
+            "pectoralis-minor",
+            "deltoids-anterior",
+            "serratus-anterior",
+            "abs-upper",
+        ],
+        difficultyLevel: 3,
+        movementPattern: "push_horizontal",
+        exerciseType: "bodyweight",
+        isUnilateral: false,
+        bodyweightDependency: null,
+        weightMultiplier: null,
+        status: "active",
+    },
+    "2tprDDd4_BsnK6gbMVWTQ": {
+        exerciseId: "2tprDDd4_BsnK6gbMVWTQ",
+        name: "Arm Circles Backward",
+        primaryMuscles: ["deltoids-middle", "deltoids-anterior"],
+        secondaryMuscles: ["trapezius", "rhomboids", "serratus-anterior"],
+        difficultyLevel: 1,
+        movementPattern: "mobility",
+        exerciseType: "mobility",
+        isUnilateral: false,
+        bodyweightDependency: null,
+        weightMultiplier: null,
+        status: "active",
+    },
+    "3CkW5o5VQbCodRFmByeMc": {
+        exerciseId: "3CkW5o5VQbCodRFmByeMc",
+        name: "Jump Squats",
+        primaryMuscles: ["quadriceps", "glutes-maximus", "calves"],
+        secondaryMuscles: ["hamstrings", "abs-lower", "hip-flexors"],
+        difficultyLevel: 3,
+        movementPattern: "plyo",
+        exerciseType: "plyometric",
+        isUnilateral: false,
+        bodyweightDependency: "high",
+        weightMultiplier: null,
+        status: "active",
+    },
+    "5LyI0el3TUJta6xLYdoua": {
+        exerciseId: "5LyI0el3TUJta6xLYdoua",
+        name: "Arnold Press",
+        primaryMuscles: ["deltoids-anterior", "deltoids-middle"],
+        secondaryMuscles: [
+            "deltoids-anterior",
+            "tricep-brachii-long",
+            "serratus-anterior",
+        ],
+        difficultyLevel: 3,
+        movementPattern: "push_vertical",
+        exerciseType: "compound",
+        isUnilateral: false,
+        bodyweightDependency: null,
+        weightMultiplier: null,
+        status: "active",
+    },
+    "9W7Yon0FWh1Eqd52yjHV9": {
+        exerciseId: "9W7Yon0FWh1Eqd52yjHV9",
+        name: "Child Pose",
+        primaryMuscles: ["lower-back", "latissimus-dorsi"],
+        secondaryMuscles: ["deltoids-middle", "rhomboids", "abs-upper"],
+        difficultyLevel: 0,
+        movementPattern: "mobility",
+        exerciseType: "mobility",
+        isUnilateral: false,
+        bodyweightDependency: null,
+        weightMultiplier: null,
+        status: "active",
+    },
+    "D3XVV-ypHfraYO52eH9ur": {
+        exerciseId: "D3XVV-ypHfraYO52eH9ur",
+        name: "Bulgarian Split Squat",
+        primaryMuscles: ["quadriceps", "glutes-maximus"],
+        secondaryMuscles: ["hamstrings", "glutes-medius", "calves", "abs-lower"],
+        difficultyLevel: 2,
+        movementPattern: "lunge",
+        exerciseType: "bodyweight",
+        isUnilateral: false,
+        bodyweightDependency: "high",
+        weightMultiplier: null,
+        status: "active",
+    },
+    EA9B8p_H60pQPRBevjRj6: {
+        exerciseId: "EA9B8p_H60pQPRBevjRj6",
+        name: "Close Grip Push Up",
+        primaryMuscles: ["tricep-brachii-long", "tricep-brachii-lateral"],
+        secondaryMuscles: [
+            "pectoralis-major",
+            "pectoralis-minor",
+            "deltoids-anterior",
+            "serratus-anterior",
+            "abs-upper",
+        ],
+        difficultyLevel: 3,
+        movementPattern: "push_horizontal",
+        exerciseType: "bodyweight",
+        isUnilateral: false,
+        bodyweightDependency: "high",
+        weightMultiplier: null,
+        status: "active",
+    },
+    RQCNQi0sw8icSqyhzytyS: {
+        exerciseId: "RQCNQi0sw8icSqyhzytyS",
+        name: "Machine Fly (Pec Deck)",
+        primaryMuscles: ["pectoralis-major", "pectoralis-minor"],
+        secondaryMuscles: ["deltoids-anterior", "serratus-anterior"],
+        difficultyLevel: 1,
+        movementPattern: "push_horizontal",
+        exerciseType: "isolation",
+        isUnilateral: false,
+        bodyweightDependency: "none",
+        weightMultiplier: {
+            female: 0.18,
+            male: 0.3,
+            default: 0.24,
+        },
+        status: "active",
+    },
+    "S7Edj-DnCvOgYNv_0SlzP": {
+        exerciseId: "S7Edj-DnCvOgYNv_0SlzP",
+        name: "Plank Up-Downs",
+        primaryMuscles: ["abs-upper", "abs-lower"],
+        secondaryMuscles: [
+            "deltoids-anterior",
+            "tricep-brachii-long",
+            "obliques",
+            "serratus-anterior",
+        ],
+        difficultyLevel: 3,
+        movementPattern: "core_stability",
+        exerciseType: "bodyweight",
+        isUnilateral: false,
+        bodyweightDependency: null,
+        weightMultiplier: null,
+        status: "active",
+    },
+    _pz6syBDTeH36DFmg2VRy: {
+        exerciseId: "_pz6syBDTeH36DFmg2VRy",
+        name: "Treadmill Running",
+        primaryMuscles: ["quadriceps", "hamstrings", "calf-inner", "calf-outer"],
+        secondaryMuscles: [
+            "maximus-lower",
+            "medius-upper",
+            "abs-upper",
+            "abs-lower",
+        ],
+        difficultyLevel: 1,
+        movementPattern: "cardio",
+        exerciseType: "cardio",
+        isUnilateral: false,
+        bodyweightDependency: "high",
+        weightMultiplier: null,
+        status: "active",
+    },
+    cICiD8ldTl3TVKl_SZV4y: {
+        exerciseId: "cICiD8ldTl3TVKl_SZV4y",
+        name: "Tricep Extension Machine",
+        primaryMuscles: ["tricep-brachii-long", "tricep-brachii-lateral"],
+        secondaryMuscles: ["fore-arm-inner"],
+        difficultyLevel: 1,
+        movementPattern: "push_horizontal",
+        exerciseType: "isolation",
+        isUnilateral: false,
+        bodyweightDependency: "none",
+        weightMultiplier: {
+            female: 0.15,
+            male: 0.25,
+            default: 0.2,
+        },
+        status: "active",
+    },
+    cXExEzqEAF8YrFN2kAnIq: {
+        exerciseId: "cXExEzqEAF8YrFN2kAnIq",
+        name: "Alternating Lunges with Pause",
+        primaryMuscles: ["quadriceps", "glutes-maximus"],
+        secondaryMuscles: ["hamstrings", "calves", "glutes-medius", "abs-lower"],
+        difficultyLevel: 2,
+        movementPattern: "lunge",
+        exerciseType: "bodyweight",
+        isUnilateral: false,
+        bodyweightDependency: "high",
+        weightMultiplier: null,
+        status: "active",
+    },
+    "xNvol6-lFnHQUMCfxFMBD": {
+        exerciseId: "xNvol6-lFnHQUMCfxFMBD",
+        name: "Bodyweight Squat",
+        primaryMuscles: ["quadriceps", "glutes-maximus"],
+        secondaryMuscles: ["hamstrings", "calves", "abs-lower"],
+        difficultyLevel: 1,
+        movementPattern: "squat",
+        exerciseType: "bodyweight",
+        isUnilateral: false,
+        bodyweightDependency: null,
+        weightMultiplier: null,
+        status: "active",
+    },
+};

package/dist/__mocks__/exercises.mock.d.ts

@@ -5,31 +5,24 @@ import { TExercise } from "../types";
  */
 export declare const mockExerciseWeightReps: TExercise;
 /**
- * MOCK EXERCISE: Reps-Only
- * Simulates a bodyweight movement (e.g., Push-up).
+ * MOCK EXERCISE: Reps-Only (bodyweight push)
  */
 export declare const mockExerciseRepsOnly: TExercise;
 /**
- * MOCK EXERCISE: Duration
- * Simulates an isometric hold (e.g., Plank).
+ * MOCK EXERCISE: Duration (isometric hold)
  */
 export declare const mockExerciseDuration: TExercise;
 /**
  * MOCK EXERCISE: Cardio-Machine
- * Simulates a machine cardio session (e.g., Treadmill).
  */
 export declare const mockExerciseCardioMachine: TExercise;
 /**
  * MOCK EXERCISE: Cardio-Free
- * Simulates an outdoor/untracked cardio session (e.g., Outdoor Run).
  */
 export declare const mockExerciseCardioFree: TExercise;
 /**
- * MOCK EXERCISE: No Guardrails
- * Simulates an older DB entry or custom exercise missing guardrails.
+ * MOCK EXERCISE: No Guardrails (legacy/custom entry)
  */
 export declare const mockExerciseNoGuardrails: TExercise;
-/**
- * Helper dictionary containing all mock exercises mapped by their ID.
- */
+/** All mock exercises mapped by id. */
 export declare const mockExercisesDictionary: Record<string, TExercise>;