@dgpholdings/greatoak-shared 1.2.91 → 1.2.93

package/dist/types/goalFeature/utilGoal.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveGoalContext = resolveGoalContext;
+exports.recommendNextIntent = recommendNextIntent;
+const goalJourney_1 = require("./goalJourney");
+function resolveGoalContext(goalProfile, recentSessions, now = new Date()) {
+    var _a, _b;
+    if (!(goalProfile === null || goalProfile === void 0 ? void 0 : goalProfile.activeGoal) || !(goalProfile === null || goalProfile === void 0 ? void 0 : goalProfile.goalStartDate))
+        return null;
+    const goalStart = new Date(goalProfile.goalStartDate);
+    const msPerDay = 86400000;
+    const daysSince = (now.getTime() - goalStart.getTime()) / msPerDay;
+    const currentWeek = Math.max(1, Math.ceil(daysSince / 7));
+    // Sessions this calendar week (Monday 00:00 UTC)
+    const monday = new Date(now);
+    monday.setUTCDate(now.getUTCDate() - ((now.getUTCDay() + 6) % 7));
+    monday.setUTCHours(0, 0, 0, 0);
+    const last4WeeksCutoff = new Date(now.getTime() - 28 * msPerDay);
+    const goalStartTime = goalStart.getTime();
+    const sessionsSinceGoalStart = recentSessions.filter((s) => new Date(s.createdAt).getTime() >= goalStartTime);
+    const totalSince = sessionsSinceGoalStart.length;
+    const sessionsIn4Weeks = sessionsSinceGoalStart.filter((s) => new Date(s.createdAt) >= last4WeeksCutoff).length;
+    const sessionsThisWeek = sessionsSinceGoalStart.filter((s) => new Date(s.createdAt) >= monday).length;
+    const currentPhase = (0, goalJourney_1.derivePhase)(currentWeek, totalSince, sessionsIn4Weeks);
+    const weeklyStructure = [...goalJourney_1.GOAL_SESSION_INTENTS[goalProfile.activeGoal]];
+    // Edge case: no sessions yet — use first non-rest slot as entry point
+    if (recentSessions.length === 0) {
+        const firstActive = (_a = weeklyStructure.find((s) => s !== "rest")) !== null && _a !== void 0 ? _a : "full-body";
+        return {
+            goal: goalProfile.activeGoal,
+            daysPerWeek: goalProfile.daysPerWeek,
+            currentPhase,
+            currentWeek,
+            weeklyStructure,
+            lastSessionDate: goalProfile.goalStartDate,
+            lastSessionIntent: firstActive,
+            sessionsCompletedThisWeek: 0,
+            totalSessionsSinceGoalStart: 0,
+            sessionsInLast4Weeks: 0,
+        };
+    }
+    const lastSession = recentSessions[0]; // sorted desc by createdAt
+    return {
+        goal: goalProfile.activeGoal,
+        daysPerWeek: goalProfile.daysPerWeek,
+        currentPhase,
+        currentWeek,
+        weeklyStructure,
+        lastSessionDate: lastSession.createdAt,
+        lastSessionIntent: (_b = lastSession.intentId) !== null && _b !== void 0 ? _b : "unstructured",
+        sessionsCompletedThisWeek: sessionsThisWeek,
+        totalSessionsSinceGoalStart: totalSince,
+        sessionsInLast4Weeks: sessionsIn4Weeks,
+    };
+}
+// ---------------------------------------------------------------------------
+// Muscle → intent cluster
+// Keyed by keyof typeof EBodyParts — TypeScript enforces valid muscle keys
+// ---------------------------------------------------------------------------
+const MUSCLE_TO_INTENTS = {
+    "serratus-anterior": ["push", "upper"],
+    "tricep-brachii-long": ["push", "upper"],
+    "tricep-brachii-lateral": ["push", "upper"],
+    "latissimus-dorsi": ["pull", "upper"],
+    rhomboids: ["pull", "upper"],
+    trapezius: ["pull", "upper"],
+    "bicep-long-outer": ["pull", "upper"],
+    "bicep-short-inner": ["pull", "upper"],
+    "deltoids-posterior": ["pull", "upper"],
+    "fore-arm-inner": ["pull", "upper"],
+    "fore-arm-outer": ["pull", "upper"],
+    "lower-back": ["core"],
+    quadriceps: ["legs", "lower", "cardio", "fatburn"],
+    hamstrings: ["legs", "lower", "cardio", "fatburn"],
+    "glutes-maximus": ["legs", "lower", "cardio", "fatburn"], // burpees, jump squats
+    "glutes-medius": ["legs", "lower", "cardio", "fatburn"],
+    "medius-upper": ["legs", "lower", "cardio", "fatburn"],
+    "maximus-lower": ["legs", "lower", "cardio", "fatburn"],
+    adductors: ["legs", "lower", "cardio", "fatburn"],
+    "calf-inner": ["legs", "lower", "cardio"],
+    "calf-outer": ["legs", "lower", "cardio"],
+    calves: ["legs", "lower", "cardio"],
+    "pectoralis-major": ["push", "upper", "fatburn"],
+    "deltoids-anterior": ["push", "upper", "fatburn"],
+    "deltoids-middle": ["push", "upper", "fatburn"],
+    "abs-upper": ["core", "fatburn"],
+    "abs-lower": ["core", "fatburn"],
+    obliques: ["core", "fatburn"],
+};
+const MUSCLE_SCORED_INTENTS = [
+    "push",
+    "pull",
+    "legs",
+    "lower",
+    "upper",
+    "core",
+    "cardio",
+    "fatburn",
+];
+// ---------------------------------------------------------------------------
+// Goal → intent readiness bias
+// Modest nudge — never overrides the structural decision in steps 1-3
+// ---------------------------------------------------------------------------
+const GOAL_INTENT_BIAS = {
+    strength: { push: 10, pull: 10, legs: 8 },
+    hypertrophy: { push: 10, pull: 10, legs: 10 },
+    fat_loss: { cardio: 20, fatburn: 18, "full-body": 10 },
+    endurance: { cardio: 25, lower: 8 },
+    mobility: { mobility: 30, core: 8 },
+    rehabilitation: { mobility: 25, core: 12 },
+    sport_performance: { legs: 12, core: 10, cardio: 8 },
+    general_fitness: { "full-body": 15, cardio: 8 },
+    core_strength: { core: 25, pull: 6, legs: 6 },
+};
+const INTENT_RATIONALE = {
+    push: "intentRationale.push",
+    pull: "intentRationale.pull",
+    legs: "intentRationale.legs",
+    lower: "intentRationale.lower",
+    upper: "intentRationale.upper",
+    core: "intentRationale.core",
+    cardio: "intentRationale.cardio",
+    strength: "intentRationale.strength",
+    fatburn: "intentRationale.fatburn",
+    mobility: "intentRationale.mobility",
+    "full-body": "intentRationale.fullBody",
+};
+const GLOBAL_RECOVERY_THRESHOLD = 72;
+const CLUSTER_FATIGUE_HARD_CAP = 65;
+const RETURNING_USER_GAP_DAYS = 7;
+const GAP_BRIDGE_THRESHOLD_DAYS = 3;
+const HIGH_CONFIDENCE_GAP = 15;
+function daysSince(isoDate, now = new Date()) {
+    return (now.getTime() - new Date(isoDate).getTime()) / 86400000;
+}
+function globalAvgFatigue(fatigue) {
+    const values = Object.values(fatigue).map((v) => v.fatigue);
+    if (values.length === 0)
+        return 0;
+    return values.reduce((a, b) => a + b, 0) / values.length;
+}
+function clusterAvgFatigue(intent, fatigue) {
+    const muscles = Object.entries(MUSCLE_TO_INTENTS)
+        .filter(([, intents]) => intents.includes(intent))
+        .map(([muscle]) => muscle);
+    if (muscles.length === 0)
+        return 0;
+    const scores = muscles.map((m) => { var _a, _b; return (_b = (_a = fatigue[m]) === null || _a === void 0 ? void 0 : _a.fatigue) !== null && _b !== void 0 ? _b : 0; });
+    return scores.reduce((a, b) => a + b, 0) / scores.length;
+}
+function buildReadinessScores(fatigue, goalContext) {
+    var _a, _b, _c, _d, _e, _f;
+    const bias = (_a = GOAL_INTENT_BIAS[goalJourney_1.GOAL_TO_AI_FITNESS_GOAL[goalContext.goal]]) !== null && _a !== void 0 ? _a : {};
+    const scores = {};
+    for (const intent of MUSCLE_SCORED_INTENTS) {
+        scores[intent] =
+            100 - clusterAvgFatigue(intent, fatigue) + ((_b = bias[intent]) !== null && _b !== void 0 ? _b : 0);
+    }
+    scores["full-body"] = 50 + ((_c = bias["full-body"]) !== null && _c !== void 0 ? _c : 0);
+    scores["strength"] = 50 + ((_d = bias["strength"]) !== null && _d !== void 0 ? _d : 0);
+    scores["fatburn"] = 50 + ((_e = bias["fatburn"]) !== null && _e !== void 0 ? _e : 0);
+    scores["mobility"] = 60 + ((_f = bias["mobility"]) !== null && _f !== void 0 ? _f : 0);
+    return scores;
+}
+function topByScore(scores) {
+    return Object.entries(scores).sort(([, a], [, b]) => b - a)[0][0];
+}
+function computeConfidence(scores) {
+    var _a;
+    const sorted = Object.values(scores).sort((a, b) => b - a);
+    const gap = sorted[0] - ((_a = sorted[1]) !== null && _a !== void 0 ? _a : 0);
+    if (gap >= HIGH_CONFIDENCE_GAP)
+        return Math.min(0.95, 0.7 + gap / 100);
+    return Math.max(0.4, 0.5 + gap / 100);
+}
+function validateOrFallback(desired, scores, fatigue) {
+    if (desired === "rest") {
+        return { intent: topByScore(scores), wasOverridden: true };
+    }
+    const desiredRec = desired;
+    if (MUSCLE_SCORED_INTENTS.includes(desiredRec)) {
+        if (clusterAvgFatigue(desiredRec, fatigue) <= CLUSTER_FATIGUE_HARD_CAP) {
+            return { intent: desiredRec, wasOverridden: false };
+        }
+        return { intent: topByScore(scores), wasOverridden: true };
+    }
+    return { intent: desiredRec, wasOverridden: false };
+}
+/**
+ * Find the next non-rest slot in weeklyStructure after afterIntent.
+ * Circular — wraps around. Used by both gap bridge and structure follow.
+ * Returns "full-body" if structure is entirely rest days (defensive).
+ */
+function nextNonRestSlot(weeklyStructure, afterIntent) {
+    const lastIdx = weeklyStructure.findIndex((s) => s === afterIntent && s !== "rest");
+    const start = lastIdx === -1 ? 0 : (lastIdx + 1) % weeklyStructure.length;
+    for (let i = 0; i < weeklyStructure.length; i++) {
+        const slot = weeklyStructure[(start + i) % weeklyStructure.length];
+        if (slot !== "rest")
+            return slot;
+    }
+    return "full-body";
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Recommend the next session intent.
+ *
+ * Decision pipeline (strict priority):
+ *   1. GLOBAL RECOVERY   avgFatigue > 72              → "mobility"
+ *   2. RETURNING USER    gap >= 7 days                → first non-rest slot
+ *   3. GAP BRIDGE        gap 3-7 days                 → most overdue slot
+ *   4. STRUCTURE FOLLOW  gap < 3 days                 → next slot (circular)
+ *   5. MUSCLE OVERRIDE   cluster fatigue > 65         → highest-readiness alt
+ *
+ * Output is always a valid TWorkoutIntent.
+ * Never outputs: "rest", "arms", "back", "unstructured".
+ * rationale is an i18n key — resolve via t() on the FE.
+ */
+function recommendNextIntent(fatigue, goalContext) {
+    var _a;
+    const { weeklyStructure, lastSessionDate, lastSessionIntent } = goalContext;
+    const gap = daysSince(lastSessionDate);
+    const avgFat = globalAvgFatigue(fatigue);
+    const scores = buildReadinessScores(fatigue, goalContext);
+    // ── 1. GLOBAL RECOVERY ───────────────────────────────────────────────────
+    if (avgFat >= GLOBAL_RECOVERY_THRESHOLD) {
+        return {
+            intent: "mobility",
+            confidence: 0.92,
+            rationale: INTENT_RATIONALE["mobility"],
+            decisionPath: "global_recovery",
+            intentScores: scores,
+        };
+    }
+    // ── 2. RETURNING USER ────────────────────────────────────────────────────
+    if (gap >= RETURNING_USER_GAP_DAYS) {
+        const reEntry = (_a = weeklyStructure.find((s) => s !== "rest")) !== null && _a !== void 0 ? _a : "full-body";
+        const { intent } = validateOrFallback(reEntry, scores, fatigue);
+        return {
+            intent,
+            confidence: 0.82,
+            rationale: INTENT_RATIONALE[intent],
+            decisionPath: "returning_user",
+            intentScores: scores,
+        };
+    }
+    // ── 3. GAP BRIDGE ────────────────────────────────────────────────────────
+    if (gap >= GAP_BRIDGE_THRESHOLD_DAYS) {
+        const missed = nextNonRestSlot(weeklyStructure, lastSessionIntent);
+        const { intent, wasOverridden } = validateOrFallback(missed, scores, fatigue);
+        return {
+            intent,
+            confidence: computeConfidence(scores),
+            rationale: INTENT_RATIONALE[intent],
+            decisionPath: wasOverridden ? "muscle_override" : "gap_bridge",
+            intentScores: scores,
+        };
+    }
+    // ── 4. STRUCTURE FOLLOW + 5. MUSCLE OVERRIDE ─────────────────────────────
+    const next = nextNonRestSlot(weeklyStructure, lastSessionIntent);
+    const { intent, wasOverridden } = validateOrFallback(next, scores, fatigue);
+    return {
+        intent,
+        confidence: computeConfidence(scores),
+        rationale: INTENT_RATIONALE[intent],
+        decisionPath: wasOverridden ? "muscle_override" : "structure_follow",
+        intentScores: scores,
+    };
+}

package/dist/types/index.d.ts

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

package/dist/types/index.js

@@ -1,2 +1,18 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+// Features
+__exportStar(require("./goalFeature"), exports);

package/dist/utils/scoringWorkout/helpers.d.ts

@@ -1,18 +1,4 @@
-/**
- * ============================================================================
- * FITFRIX EXERCISE SCORING SYSTEM — Helpers
- * ============================================================================
- *
- * Pure utility functions with no business logic. These handle:
- * - Safe parsing of string values from TRecord
- * - Duration parsing ("MM:SS" → seconds)
- * - Clamping and validation
- * - Effort fraction conversion (RPE/RIR → 0–1)
- * - User context extraction with fallbacks
- *
- * All functions are deterministic and side-effect free.
- */
-import { TGender } from "../../types";
+import { TActivityLevel, TGender } from "../../types";
 import type { IUserContext } from "./types";
 /**
  * Safely parse a string to a float.
@@ -112,12 +98,11 @@ export declare function getEffortFraction(record: {
  * @param user - The raw TUserMetric object
  */
 export declare function extractUserContext(user: {
-    weightKg?: number;
-    heightCm?: number;
-    gender?: TGender;
-    dob?: Date | string;
-    fitnessLevel?: import("../../types").TActivityLevel;
-    fitnessGoals?: import("../../constants/AiExerciseVocabulary").TAiFitnessGoal[];
+    weightKg: number;
+    heightCm: number;
+    gender: TGender;
+    dob: Date | string;
+    fitnessLevel: TActivityLevel;
     bodyFatPercentage?: number;
 }): IUserContext;
 /**

package/dist/utils/scoringWorkout/helpers.js

@@ -199,7 +199,7 @@ function getEffortFraction(record) {
  * @param user - The raw TUserMetric object
  */
 function extractUserContext(user) {
-    var _a, _b, _c;
+    var _a, _b;
     const weightKg = user.weightKg && user.weightKg > 20 && user.weightKg < 300
         ? user.weightKg
         : constants_1.DEFAULT_USER_WEIGHT_KG;
@@ -213,8 +213,7 @@ function extractUserContext(user) {
         gender: user.gender || "unmentioned",
         age,
         fitnessLevel: (_a = user.fitnessLevel) !== null && _a !== void 0 ? _a : "moderately-active",
-        fitnessGoals: (_b = user.fitnessGoals) !== null && _b !== void 0 ? _b : ["general_fitness"],
-        bodyFatPercentage: (_c = user.bodyFatPercentage) !== null && _c !== void 0 ? _c : 20,
+        bodyFatPercentage: (_b = user.bodyFatPercentage) !== null && _b !== void 0 ? _b : 20,
     };
 }
 /**

package/dist/utils/scoringWorkout/index.js

@@ -39,7 +39,6 @@ const calculateExerciseScoreV2 = (param) => {
     const { exercise, record, user, historicalContext } = param;
     const userContext = (0, helpers_1.extractUserContext)(user);
     const parsedSets = (0, parseRecords_1.parseRecords)(record, exercise.timingGuardrails, historicalContext);
-    // ── Pillar 2: Muscle Fatigue ─────────────────────────────────────────────
     const muscleScores = (0, calculateMuscleFatigue_1.calculateMuscleFatigue)(parsedSets, {
         primaryMuscles: exercise.primaryMuscles,
         secondaryMuscles: exercise.secondaryMuscles,
@@ -51,11 +50,9 @@ const calculateExerciseScoreV2 = (param) => {
         scoringSpecialHandling: exercise.scoringSpecialHandling,
         isUnilateral: exercise.isUnilateral,
     }, userContext, exercise.timingGuardrails, historicalContext);
-    // ── Pillar 3: Quality Score ──────────────────────────────────────────────
     // userContext is intentionally not passed — quality scoring is goal-agnostic.
     // Goal-specific logic lives in the gate system and quick plan generator.
     const { score, qualityBreakdown, restDisciplineActive } = (0, calculateQualityScore_1.calculateQualityScore)(parsedSets, record, exercise.timingGuardrails, historicalContext);
-    // ── Result (Option A flat shape) ─────────────────────────────────────────
     return {
         score,
         qualityBreakdown,

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

@@ -8,7 +8,6 @@
  * scoring pillars (Calories, Muscle Fatigue, Quality).
  */
 import { TActivityLevel, TGender, TRecord } from "../../types";
-import type { TAiFitnessGoal } from "../../constants/AiExerciseVocabulary";
 /**
  * A single scored session with real per-muscle fatigue values.
  * muscleScores = {} for pre-P3-1 sessions (backward compat fallback).
@@ -141,6 +140,5 @@ export interface IUserContext {
     gender: TGender;
     age: number;
     fitnessLevel: TActivityLevel;
-    fitnessGoals: TAiFitnessGoal[];
     bodyFatPercentage: number;
 }

package/package.json

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