@dgpholdings/greatoak-shared 1.2.85 → 1.2.87

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__/exercises.mock.js

@@ -5,6 +5,7 @@ exports.mockExercisesDictionary = exports.mockExerciseNoGuardrails = exports.moc
  * MOCK EXERCISE: Weight-Reps
  * Simulates a standard compound lift (e.g., Barbell Squat).
  */
+// @ts-ignore
 exports.mockExerciseWeightReps = {
     exerciseId: "mock-exercise-weight-reps-123",
     name: "Generic Barbell Squat",

package/dist/constants/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./BodyCategories";
 export * from "./AiExerciseVocabulary";
+export * from "./quickStartIntents";

package/dist/constants/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./BodyCategories"), exports);
 __exportStar(require("./AiExerciseVocabulary"), exports);
+__exportStar(require("./quickStartIntents"), exports);

package/dist/constants/quickStartIntents.d.ts

@@ -0,0 +1,19 @@
+export declare const QUICK_START_CLEAR_INTENTS: {
+    readonly push: "push";
+    readonly pull: "pull";
+    readonly core: "core";
+    readonly legs: "legs";
+    readonly upper: "upper";
+    readonly lower: "lower";
+    readonly cardio: "cardio";
+    readonly strength: "strength";
+    readonly fatburn: "fatburn";
+    readonly mobility: "mobility";
+    readonly fullBody: "full-body";
+};
+export declare const QUICK_START_INTENT_PREFIX_SEPARATOR = ": ";
+/**
+ * Inverse map: chip-key strings ("full-body", "push") → TWorkoutType[].
+ * Order in the array matters when an intent maps to multiple types.
+ */
+export declare const QUICK_START_INTENT_TO_WORKOUT_TYPE: Record<(typeof QUICK_START_CLEAR_INTENTS)[keyof typeof QUICK_START_CLEAR_INTENTS], string[]>;

package/dist/constants/quickStartIntents.js

@@ -0,0 +1,39 @@
+"use strict";
+// shared/src/constants/quickStartIntents.ts
+//
+// Shared between Quick Plan frontend (IntentInput chips) and backend (worker).
+// When the frontend prefixes intentText with one of these keys followed by ":",
+// the backend skips intent classification (Haiku) and uses the prefix directly.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUICK_START_INTENT_TO_WORKOUT_TYPE = exports.QUICK_START_INTENT_PREFIX_SEPARATOR = exports.QUICK_START_CLEAR_INTENTS = void 0;
+exports.QUICK_START_CLEAR_INTENTS = {
+    push: "push",
+    pull: "pull",
+    core: "core",
+    legs: "legs",
+    upper: "upper",
+    lower: "lower",
+    cardio: "cardio",
+    strength: "strength",
+    fatburn: "fatburn",
+    mobility: "mobility",
+    fullBody: "full-body",
+};
+exports.QUICK_START_INTENT_PREFIX_SEPARATOR = ": ";
+/**
+ * Inverse map: chip-key strings ("full-body", "push") → TWorkoutType[].
+ * Order in the array matters when an intent maps to multiple types.
+ */
+exports.QUICK_START_INTENT_TO_WORKOUT_TYPE = {
+    push: ["push"],
+    pull: ["pull"],
+    core: ["core"],
+    legs: ["legs"],
+    upper: ["upper"],
+    lower: ["lower"],
+    cardio: ["cardio"],
+    strength: ["strength"],
+    fatburn: ["fatburn"],
+    mobility: ["mobility"],
+    "full-body": ["full-body"],
+};

package/dist/types/TApiAiExerciseAnalysis.d.ts

@@ -1,3 +1,4 @@
+import { TAiMovementPattern } from "../constants";
 export type TConfidence = "high" | "medium" | null;
 export type TNameReviewStatus = "pending" | "approved";
 export type TQdrantSyncStatus = "pending" | "synced" | "failed";
@@ -66,7 +67,7 @@ export type TApiAiExerciseAnalysis = {
     exercise_name: string;
     alternative_names: string[];
     movement_description: string;
-    movement_pattern: string;
+    movement_pattern: TAiMovementPattern;
     exercise_type: string;
     contraction_type: string;
     plane_of_motion: string[];

package/dist/types/TApiClientConstellation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ============================================================================
+ * API CONTRACT — Client Constellation
+ * ============================================================================
+ *
+ * Request/response types for GET /api/constellation. The response is the
+ * render-ready TConstellationState produced by the constellation util; these
+ * types are re-exported here so the backend (and app) consume one stable
+ * contract from the published package.
+ */
+import type { TConstellationState } from "../utils/constellation/types";
+export type { TConstellationState };
+/**
+ * Request: no body. The user is resolved from the JWT. `level` is optional and
+ * may be supplied as a query param to preview a specific level; it defaults to
+ * the user's current level (1) and is clamped to a valid level server-side.
+ */
+export type TApiClientConstellationReq = {
+    level?: number;
+};
+/**
+ * Response envelope, matching the shape your other controllers return
+ * (status + state + message) with the constellation payload under `data`.
+ */
+export type TApiClientConstellationRes = {
+    status: 200;
+    state: "success";
+    data: TConstellationState;
+} | {
+    status: 401 | 500;
+    state: "failed";
+    message: string;
+};

package/dist/types/TApiClientConstellation.js

@@ -0,0 +1,13 @@
+"use strict";
+// shared/src/types/TApiClientConstellation.ts
+/**
+ * ============================================================================
+ * API CONTRACT — Client Constellation
+ * ============================================================================
+ *
+ * Request/response types for GET /api/constellation. The response is the
+ * render-ready TConstellationState produced by the constellation util; these
+ * types are re-exported here so the backend (and app) consume one stable
+ * contract from the published package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/TApiExercise.d.ts

@@ -1,3 +1,4 @@
+import { TAiMovementPattern } from "../constants";
 import { TRecord } from "./commonTypes";
 export type TBodyPart = "Chest" | "Core" | "Shoulders" | "Back" | "Biceps" | "Triceps" | "Forearms" | "Legs" | "Glutes" | "Calves" | "Hamstrings" | "Quadriceps" | "Lower Back" | "Trapezius";
 export declare enum EBodyParts {
@@ -141,9 +142,10 @@ export type TExercise = {
         female: number;
         default: number;
     };
-    movementPattern?: "push" | "pull" | "hinge" | "squat" | "lunge" | "rotation" | "carry" | "isolation";
-    stabilityDemand?: "low" | "moderate" | "high";
-    progressionTier?: "beginner" | "intermediate" | "advanced" | "elite";
+    movementPattern: TAiMovementPattern;
+    exerciseType: "isolation" | "compound" | "bodyweight" | "mobility" | "plyometric" | "isometric" | "cardio";
+    stabilityDemand: "low" | "moderate" | "high";
+    progressionTier: "beginner" | "intermediate" | "advanced" | "elite";
 };
 export type TBodyPartExercises = Record<TBodyPart, TExercise[]>;
 export type TApiCreateOrUpdateExerciseReq = {

package/dist/types/index.d.ts

@@ -15,3 +15,4 @@ export type * from "./TApiSales";
 export type * from "./TApiAiExerciseAnalysis";
 export type * from "./TApiAdminAiHelp";
 export type * from "./TApiAiQuickStartWorkout";
+export type * from "./TApiClientConstellation";

package/dist/utils/constellation/computeNormalisedLoad.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ============================================================================
+ * FITFRIX CONSTELLATION — Normalised Load (strength-star helper)
+ * ============================================================================
+ *
+ * Turns a user's sessions into a single strength number for a movement pattern:
+ * the best estimated-1RM achieved on any matching exercise in the rolling
+ * window, expressed as a ratio of bodyweight.
+ *
+ * Estimated-1RM (Epley, rep-capped at 12) is used instead of raw top weight so
+ * that 60kg x5 ~ 70kg x1 — it rewards productive training over ego-lifting.
+ *
+ * Bodyweight loading (the home-user path): a bodyweight exercise's effective
+ * load is the REAL fraction of bodyweight it moves, taken from the exercise's
+ * own `weightMultiplier` (per-sex), falling back to a coarse map keyed off
+ * `bodyweightDependency`. This is what lets a home user honestly reach a
+ * strength threshold with pull-ups / pistol squats etc., instead of being
+ * capped by a flat guess.
+ *
+ * Returns a bodyweight ratio (e.g. 0.78 = "0.78x bodyweight"). 0 = no data.
+ */
+import type { TExercise } from "../../types";
+import type { TSessionRecord } from "./types";
+/** Epley reps cap: reps beyond this don't increase the 1RM estimate. */
+export declare const EPLEY_REP_CAP = 12;
+/** Estimated 1RM via Epley, with reps capped to avoid endurance-range inflation. */
+export declare function estimateOneRepMax(weightKg: number, reps: number): number;
+export interface INormalisedLoadResult {
+    /** Best estimated-1RM in the window as a ratio of bodyweight. 0 if none. */
+    ratio: number;
+    /** The raw best estimated-1RM in kg (pre-normalisation), for detail display. */
+    bestOneRepMaxKg: number;
+    /** Exercise id that produced the best load (for "your best: Bench Press"). */
+    bestExerciseId?: string;
+}
+/**
+ * Compute the best normalised load for a set of matching exercises within the
+ * window.
+ *
+ * @param matchingExerciseIds  Exercise ids belonging to the target pattern.
+ * @param sessions             All sessions.
+ * @param exerciseCatalog      Full catalog (unfiltered).
+ * @param bodyweightKg         User bodyweight (falls back to default).
+ * @param gender               User sex (selects the weightMultiplier column).
+ * @param windowStartMs        Only sessions on/after this count.
+ * @param now                  Upper bound (sessions after `now` ignored).
+ */
+export declare function computeNormalisedLoad(matchingExerciseIds: Set<string>, sessions: TSessionRecord[], exerciseCatalog: Record<string, TExercise>, bodyweightKg: number, gender: string | undefined, windowStartMs: number, now: number): INormalisedLoadResult;