@dimrev4/fitness-v3-backend SDK

TypeScript SDK for Fitness V3 Backend API - Comprehensive client for body measurements, meal tracking, workout management, and fitness data.

🚀 Features

• 📏 Body Measurements — track weight, BMI, and BMR over time
• 🍽️ Meal Management — save meal templates, log ingredients, record consumption
• 🏋️ Workout Management — exercise library, workout templates, completion tracking
• 🔐 Authentication — integrates with Users Core (JWT-based)
• 📊 Date-range filtering — query data by date ranges with pagination
• 👥 Group support — access group-shared measurements with permissions
• 💪 100% TypeScript with full type safety
• ⚡ Axios-based with interceptors support

📦 Installation

npm install @dimrev4/fitness-v3-backend
# or
yarn add @dimrev4/fitness-v3-backend
# or
pnpm add @dimrev4/fitness-v3-backend

🔑 Authentication Requirements

All API requests require an x-api-key header. Protected endpoints additionally require Authorization: Bearer <jwt-token>.

🔧 Quick Start

1. Setup

import {
  Configuration,
  AuthV1Api,
  MeasurementsV1Api,
  SavedMealsV1Api,
  UserMealConsumptionV1Api,
  IngredientsV1Api,
  ExercisesV1Api,
  SavedWorkoutsV1Api,
  UserWorkoutCompletedV1Api,
  FilesV1Api,
} from '@dimrev4/fitness-v3-backend';

const config = new Configuration({
  basePath: 'https://fitness-api.yourdomain.com',
  apiKey: process.env.FITNESS_API_KEY,
});

const authApi = new AuthV1Api(config);
const measurementsApi = new MeasurementsV1Api(config);

2. Authentication

// Login
const loginResponse = await authApi.authV1ControllerLogin({
  email: '[email protected]',
  password: 'securePassword123!',
});

const { user, accessToken } = loginResponse.data;

// Create authenticated client
const authConfig = new Configuration({
  basePath: 'https://fitness-api.yourdomain.com',
  apiKey: process.env.FITNESS_API_KEY,
  accessToken,
});

const authenticatedMeasurementsApi = new MeasurementsV1Api(authConfig);

3. Body Measurements

// Get current user's measurements with date filtering
const measurements = await authenticatedMeasurementsApi.getAllByUserId({
  limit: 10,
  offset: 0,
  fromDate: '2025-01-01',
  toDate: '2025-01-31',
});

console.log('Recent measurements:', measurements.data.measurements);

// Create a new measurement
const newMeasurement = await authenticatedMeasurementsApi.createMeasurement({
  date: new Date().toISOString(),
  weightKG: 75.5,
  bmi: 24.6,
  bmr: 1800,
});

// Update measurement
const updatedMeasurement = await authenticatedMeasurementsApi.updateMeasurement(
  'measurement-id',
  {
    weightKG: 75.8,
    bmi: 24.7,
  },
);

// Delete measurement (soft delete)
await authenticatedMeasurementsApi.deleteMeasurement('measurement-id');

4. Group-Based Measurements

// Get measurements for a group (requires isRoot permission in the group)
const groupMeasurements =
  await authenticatedMeasurementsApi.getAllByUserIdAdmin('group-id', {
    limit: 20,
    offset: 0,
    fromDate: '2025-01-01',
    toDate: '2025-01-31',
  });

5. Saved Meals

import { SavedMealsV1Api } from '@dimrev4/fitness-v3-backend';

const mealsApi = new SavedMealsV1Api(authConfig);

// Create a saved meal template
const meal = await mealsApi.savedMealsV1ControllerCreate({
  name: 'Post-workout protein shake',
  mealType: 'SNACK',
  foodCategory: 'PROTEIN',
  calories: 350,
  proteinGrams: 30,
  // ... other nutritional fields
});

// List saved meals (paginated)
const meals = await mealsApi.savedMealsV1ControllerFindAll({
  limit: 20,
  offset: 0,
});

6. Log Meal Consumption

import { UserMealConsumptionV1Api } from '@dimrev4/fitness-v3-backend';

const consumptionApi = new UserMealConsumptionV1Api(authConfig);

await consumptionApi.userMealConsumptionV1ControllerCreate({
  mealId: 'saved-meal-id',
  date: new Date().toISOString(),
});

// Get consumption history with date filter
const history = await consumptionApi.userMealConsumptionV1ControllerFindAll({
  fromDate: '2025-01-01',
  toDate: '2025-01-31',
});

🏗️ API Overview

Authentication (AuthV1Api) — /api/auth/v1

• POST /api/auth/v1/login - Authenticate user (proxies to Users Core)
• POST /api/auth/v1/register - Register step 1 (creates pending OTP record)
• POST /api/auth/v1/confirm-otp - Register step 2 (validates OTP, issues tokens)
• POST /api/auth/v1/logout - Invalidate session
• POST /api/auth/v1/refresh - Validate refresh token, issue new access token
• POST /api/auth/v1/get-me - Return current user details
• POST /api/auth/v1/meta/create - Create user meta profile (DOB, height, gender)
• POST /api/auth/v1/meta/update - Update user meta profile

Body Measurements (MeasurementsV1Api) — /api/measurements/v1

• GET /api/measurements/v1 - Get user's measurements (paginated, date filter)
• GET /api/measurements/v1/all - Get all user's measurements (no pagination)
• POST /api/measurements/v1 - Create measurement
• GET /api/measurements/v1/:measurementId - Get specific measurement
• PATCH /api/measurements/v1/:measurementId - Update measurement
• DELETE /api/measurements/v1/:measurementId - Soft delete measurement
• GET /api/measurements/v1/group/:groupId - Get group measurements (requires isRoot)
• GET /api/measurements/v1/group/:groupId/:measurementId - Get specific group measurement

Saved Meals (SavedMealsV1Api) — /api/meals/v1

• POST /api/meals/v1 - Create saved meal template
• GET /api/meals/v1 - List saved meals (paginated)
• GET /api/meals/v1/all - List all saved meals
• GET /api/meals/v1/:id - Get saved meal by ID
• PUT /api/meals/v1/:id - Update saved meal
• DELETE /api/meals/v1/:id - Soft delete saved meal

User Meal Consumption (UserMealConsumptionV1Api) — /api/meals/user-meals-consumption/v1

• POST /api/meals/user-meals-consumption/v1 - Log meal consumption
• GET /api/meals/user-meals-consumption/v1/all - Get consumption history (date filter)

Ingredients (IngredientsV1Api) — /api/ingredients/v1

Public read endpoints; privileged write endpoints.

• POST /api/ingredients/v1 - Create ingredient (privileged)
• GET /api/ingredients/v1 - List ingredients (paginated, search)
• GET /api/ingredients/v1/all - List all ingredients
• GET /api/ingredients/v1/:id - Get ingredient by ID
• PUT /api/ingredients/v1/:id - Update ingredient (privileged)
• DELETE /api/ingredients/v1/:id - Soft delete ingredient (privileged)

Exercises (ExercisesV1Api) — /api/exercises/v1

Public read endpoints; privileged write endpoints.

• POST /api/exercises/v1 - Create exercise (privileged)
• GET /api/exercises/v1 - List exercises (paginated, search)
• GET /api/exercises/v1/all - List all exercises
• GET /api/exercises/v1/:id - Get exercise by ID
• PUT /api/exercises/v1/:id - Update exercise (privileged)
• DELETE /api/exercises/v1/:id - Soft delete exercise (privileged)

Saved Workouts (SavedWorkoutsV1Api) — /api/workouts/v1

• POST /api/workouts/v1 - Create workout template
• GET /api/workouts/v1 - List workouts (paginated)
• GET /api/workouts/v1/all - List all workouts
• GET /api/workouts/v1/:id - Get workout by ID
• PUT /api/workouts/v1/:id - Update workout
• DELETE /api/workouts/v1/:id - Soft delete workout

User Workout Completed (UserWorkoutCompletedV1Api) — /api/workouts/user-workout-completed/v1

• POST /api/workouts/user-workout-completed/v1 - Record completed workout
• GET /api/workouts/user-workout-completed/v1/all - Get completion history (date filter)

Files (FilesV1Api) — /api/files/v1

Proxy to Files Core presigned URLs.

• POST /api/files/v1/public/presigned-url - Get public upload URL
• GET /api/files/v1/public/presigned-url/*filepath - Get public download URL
• POST /api/files/v1/group/:groupId/presigned-url - Get group upload URL
• GET /api/files/v1/group/:groupId/presigned-url/*filepath - Get group download URL
• POST /api/files/v1/user/:userId/presigned-url - Get user upload URL
• GET /api/files/v1/user/:userId/presigned-url/*filepath - Get user download URL
• GET /api/files/v1/buckets - List buckets

📋 Data Models

Measurement

{
  "id": "e9c83a87-37ac-4938-8d88-379c4ac81c5c",
  "date": "2025-01-15T10:30:00.000Z",
  "weightKG": 75.5,
  "bmi": 24.6,
  "bmr": 1800.0,
  "userId": "user-id",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "deletedAt": null
}

Note: heightCM is not a measurement field. Height is part of the user's meta profile — see POST /api/auth/v1/meta/create.

User Meta Profile

{
  "id": "meta-id",
  "userId": "user-id",
  "dateOfBirth": "1990-05-20",
  "heightCM": 175.0,
  "gender": "MALE",
  "imageUrl": "https://example.com/avatar.jpg",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Saved Meal

{
  "id": "meal-id",
  "name": "Protein Shake",
  "description": "Post-workout protein shake",
  "recipe": "1 scoop protein powder, 1 banana, 200ml milk",
  "imgUrl": "https://example.com/protein-shake.jpg",
  "mealType": "SNACK",
  "foodCategory": "PROTEIN",
  "resourceType": "user",
  "userId": "user-id",
  "groupId": null,
  "calories": 350.5,
  "totalFatGrams": 8.2,
  "proteinGrams": 30.0,
  "totalCarbohydrateGrams": 35.0,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "deletedAt": null
}

User Meal Consumption

{
  "id": "consumption-id",
  "userId": "user-id",
  "mealId": "meal-id",
  "date": "2025-01-15T14:00:00.000Z",
  "createdAt": "2025-01-15T14:00:00.000Z",
  "updatedAt": "2025-01-15T14:00:00.000Z",
  "deletedAt": null
}

🔐 Group Permissions

For group-based measurement endpoints, users must have isRoot in the target group:

{
  "isRoot": true,
  "canCreate": true,
  "canRead": true,
  "canUpdate": true,
  "canDelete": true
}

For privileged write endpoints (ingredients, exercises), users must belong to the configured privileged group.

🧪 Error Handling

import { AxiosError } from 'axios';

try {
  const measurements = await authenticatedMeasurementsApi.getAllByUserId();
} catch (error) {
  if (error instanceof AxiosError) {
    switch (error.response?.status) {
      case 400:
        console.error('Validation failed:', error.response.data.message);
        break;
      case 401:
        console.error('Unauthorized — check JWT token');
        break;
      case 403:
        console.error('Forbidden: Insufficient permissions');
        break;
      case 404:
        console.error('Resource not found');
        break;
      case 409:
        console.error('Conflict:', error.response.data.message);
        break;
      default:
        console.error('API Error:', error.message);
    }
  }
}

⚙️ Advanced Configuration

Custom Axios Instance

import axios from 'axios';
import { Configuration, MeasurementsV1Api } from '@dimrev4/fitness-v3-backend';

const axiosInstance = axios.create({
  timeout: 15000,
});

// Inject auth headers automatically
axiosInstance.interceptors.request.use((config) => {
  const token = getStoredToken();
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  config.headers['x-api-key'] = process.env.FITNESS_API_KEY;
  return config;
});

const config = new Configuration({});
const measurementsApi = new MeasurementsV1Api(config, undefined, axiosInstance);

Environment Setup

const config = new Configuration({
  basePath:
    process.env.NODE_ENV === 'production'
      ? 'https://fitness-api.yourdomain.com'
      : 'http://localhost:42070',
  apiKey: process.env.FITNESS_API_KEY,
  accessToken: process.env.ACCESS_TOKEN,
});

🌍 Pagination & Filtering

const measurements = await authenticatedMeasurementsApi.getAllByUserId({
  offset: 0,
  limit: 25,
  fromDate: '2025-01-01',
  toDate: '2025-01-31',
});

console.log(`${measurements.data.totalItems} measurements found`);
console.log(
  `Page ${measurements.data.currentPage} of ${measurements.data.totalPages}`,
);

🚨 Common Issues

| Issue | Solution | | ---------------------- | --------------------------------------------------- | | 401 Unauthorized | Set accessToken in Configuration | | 403 Forbidden | Check group permissions for group endpoints | | 400 Missing API key | Set apiKey in Configuration (sent as x-api-key) | | CORS Error | Configure API CORS or use proxy in dev | | Validation Error (400) | Check request body against DTO schema | | 404 Resource Not Found | Verify ID and that the resource belongs to the user |

📊 TypeScript Types

Key interfaces for type safety:

interface CreateMeasurementRequestDto {
  date: string; // ISO date string
  weightKG: number;
  bmi: number;
  bmr: number;
}

interface MeasurementDto {
  id: string;
  date: string;
  weightKG: number;
  bmi: number;
  bmr: number;
  userId: string;
  createdAt: string;
  updatedAt: string;
  deletedAt: string | null;
}

interface UpdateMeasurementRequestDto {
  date?: string;
  weightKG?: number;
  bmi?: number;
  bmr?: number;
}

interface GetMeasurementsResponseDto {
  measurements: MeasurementDto[];
  totalItems: number;
  currentPage: number;
  totalPages: number;
}

interface SavedMealDto {
  id: string;
  name: string;
  description: string;
  recipe: string;
  imgUrl: string;
  mealType: 'BREAKFAST' | 'LUNCH' | 'DINNER' | 'SNACK' | 'DESSERT';
  foodCategory:
    | 'DAIRY'
    | 'PROTEIN'
    | 'CARBOHYDRATES'
    | 'FRUITS'
    | 'VEGETABLES'
    | 'FATS'
    | 'GRAINS'
    | 'BEVERAGES'
    | 'SWEETS';
  resourceType: 'user' | 'group' | 'global';
  userId: string | null;
  groupId: string | null;
  calories: number;
  totalFatGrams: number;
  saturatedFatGrams: number;
  transFatGrams: number;
  cholesterolMg: number;
  sodiumMg: number;
  totalCarbohydrateGrams: number;
  dietaryFiberGrams: number;
  totalSugarGrams: number;
  addedSugarGrams: number;
  proteinGrams: number;
  vitaminDGrams: number;
  calciumGrams: number;
  ironGrams: number;
  potassiumGrams: number;
  createdAt: string;
  updatedAt: string;
  deletedAt: string | null;
}

interface UserMealConsumptionDto {
  id: string;
  userId: string;
  mealId: string;
  date: string;
  createdAt: string;
  updatedAt: string;
  deletedAt: string | null;
}

interface ExerciseDto {
  id: string;
  name: string;
  description: string;
  type:
    | 'CARDIO'
    | 'STRENGTH'
    | 'FLEXIBILITY'
    | 'BODY_WEIGHT'
    | 'COMPOUND'
    | 'ISOLATION';
  bodyParts: (
    | 'SHOULDERS'
    | 'UPPER_ARMS'
    | 'FOREARMS'
    | 'BACK'
    | 'CHEST'
    | 'WAIST'
    | 'HIPS'
    | 'THIGHS'
    | 'CALVES'
  )[];
  difficulty: 'EASY' | 'MEDIUM' | 'HARD';
  createdAt: string;
  updatedAt: string;
  deletedAt: string | null;
}

interface UserMetaDto {
  id: string;
  userId: string;
  dateOfBirth: string | null;
  heightCM: number | null;
  gender: string | null;
  imageUrl: string | null;
  createdAt: string;
  updatedAt: string;
}

🔗 Resources

• API Docs: Available at http://localhost:42070/api (Swagger UI)
• Repository: GitHub
• Issues: GitHub Issues
• License: Unlicense

🤝 Contributing

1. Fork the repository
2. Update OpenAPI spec for new features
3. Run pnpm run sdk:generate to rebuild SDK
4. Submit pull request with tests

Auto-generated from Fitness V3 Backend API v0.0.52 | Last Updated: Mar 2026