@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

// 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 | | Utils | src/utils/ | docs/utils.md | | Scoring Engine | src/utils/scoring/ | 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

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 before touching it