TrainingPeaks SDK


A comprehensive TypeScript SDK for TrainingPeaks API integration, built with Clean Architecture principles and designed for modern JavaScript/TypeScript applications.

> 📋 Product Context: For comprehensive business objectives, target market analysis, and feature roadmap, see PRODUCT.md.

Features

- 🏗️ Clean Architecture: Follows hexagonal architecture (ports & adapters) for maintainability
- 🔒 Type-Safe: Full TypeScript support with comprehensive type definitions
- 📦 Dual Package: Supports both ESM and CommonJS module systems
- 🧪 Well Tested: Comprehensive unit, integration, and E2E test coverage
- 🔐 Authentication: Secure session management with cookie support
- 📊 Workout Management: Complete workout CRUD operations
- 🏃 User Management: User profile and settings management
- 📁 File Upload: Support for TCX, GPX, and FIT file formats
- 🚀 Modern Stack: Built with Axios, Zod validation, and Playwright

Requirements

- Node.js: >=20.0.0
- npm: >=9.0.0 (included with Node.js 20+)

Installation

``bash
npm install trainingpeaks-sdk
`

> ⚠️ Node.js Version: This SDK requires Node.js 20.0.0 or higher due to the use of modern APIs like crypto.randomUUID(). Node.js 18 and earlier are not supported.

Quick Start

$3

`typescript
import { createTrainingPeaksSdk } from 'trainingpeaks-sdk';

// Initialize the SDK
const sdk = createTrainingPeaksSdk({
debug: false, // Optional: enable debug logging
timeout: 30000, // Optional: request timeout in ms
});

// Login with credentials
const loginResult = await sdk.login({
username: 'your-username',
password: 'your-password',
});

console.log('Login successful:', loginResult);
// Returns: { token: {...}, user: {...} }
`

$3

`typescript
// Get user's workouts list
const workouts = await sdk.getWorkoutsList({
startDate: '2024-01-01',
endDate: '2024-12-31',
// athleteId is optional - uses current user if not provided
});

console.log('Workouts:', workouts);
// Returns: WorkoutListItem[] with id, name, date, etc.
`

> ⚠️ Current Limitations: This SDK currently supports authentication and workout list retrieval. Additional features like workout creation, updates, and individual workout details are planned for future releases.

$3

`typescript
// Clear authentication and logout
await sdk.logout();
console.log('Logged out successfully');
`

$3

`typescript
try {
const result = await sdk.login({
username: 'invalid-user',
password: 'wrong-password',
});
} catch (error) {
console.error('Login failed:', error.message);
// Handle authentication errors
}
`

API Reference

$3

`typescript
const sdk = createTrainingPeaksSdk(config?: TrainingPeaksClientConfig)
`

Config Options:

- debug?: boolean - Enable debug logging
- timeout?: number - Request timeout in milliseconds
- baseUrl?: string - Custom API base URL

$3

#### login(credentials: LoginCredentials)

Authenticate with username and password.

`typescript
type LoginCredentials = {
username: string;
password: string;
};

type LoginResponse = {
token: {
accessToken: string;
tokenType: string;
expiresAt: string;
refreshToken?: string;
};
user: {
id: string;
name: string;
username: string;
avatar?: string;
};
};
`

#### logout()

Clear authentication and end the current session.

$3

#### getWorkoutsList(command: GetWorkoutsListCommand)

Get user's workouts list with date filtering.

`typescript
type GetWorkoutsListCommand = {
athleteId?: string; // Optional - uses current user if not provided
startDate: string; // YYYY-MM-DD format
endDate: string; // YYYY-MM-DD format
};

type WorkoutListItem = {
id: string;
name: string;
date: string;
duration: number;
distance?: number;
activityType?: string;
// Additional workout metadata...
};
`

Current Features

✅ Available Now:

- User authentication (login/logout)
- Workout list retrieval with date filtering
- Session management with automatic cookie handling
- TypeScript support with full type definitions
- Clean Architecture implementation

🚧 Planned Features:

- Individual workout details retrieval
- Workout file upload (TCX, GPX, FIT formats)
- Workout creation and updates
- User profile management
- Workout statistics and analytics

Configuration

$3

`typescript
import {
createTrainingPeaksSdk,
type TrainingPeaksClientConfig,
} from 'trainingpeaks-sdk';

const config: TrainingPeaksClientConfig = {
baseUrl: 'https://tpapi.trainingpeaks.com', // Optional
timeout: 30000, // Optional: request timeout in ms
debug: true, // Optional: enable debug logging
headers: {
// Optional: custom headers
'User-Agent': 'MyApp/1.0.0',
},
};

const sdk = createTrainingPeaksSdk(config);
`

$3

You can also configure the SDK using environment variables:

`bash


API Base URL (optional)

TRAININGPEAKS_API_BASE_URL=https://tpapi.trainingpeaks.com

Request timeout in milliseconds (optional)

TRAININGPEAKS_TIMEOUT=30000

Enable debug logging (optional)

TRAININGPEAKS_DEBUG=true
`

Error Handling

The SDK provides structured error handling with HTTP-specific error information:

`typescript
import { createTrainingPeaksSdk } from 'trainingpeaks-sdk';

const sdk = createTrainingPeaksSdk();

try {
await sdk.login({ username: 'user', password: 'pass' });
} catch (error) {
// HTTP errors include status, statusText, and response data
if (error.status) {
console.error(HTTP ${error.status}: ${error.statusText});
console.error('Response:', error.data);
} else {
console.error('Network or other error:', error.message);
}
}
`

TypeScript Support

The SDK is written in TypeScript and provides comprehensive type definitions:

`typescript
import { createTrainingPeaksSdk } from 'trainingpeaks-sdk';
import type {
TrainingPeaksClientConfig,
LoginCredentials,
GetWorkoutsListCommand,
WorkoutListItem,
} from 'trainingpeaks-sdk';

// All types are fully typed
const config: TrainingPeaksClientConfig = {
debug: true,
timeout: 30000,
};

const credentials: LoginCredentials = {
username: 'myuser',
password: 'mypass',
};

const workoutsQuery: GetWorkoutsListCommand = {
startDate: '2024-01-01',
endDate: '2024-12-31',
};
`

Module Exports

The SDK supports multiple import patterns for different use cases:

`typescript
// Main SDK factory function
import { createTrainingPeaksSdk } from 'trainingpeaks-sdk';

// Type imports
import type {
TrainingPeaksClientConfig,
LoginCredentials,
GetWorkoutsListCommand,
WorkoutListItem,
} from 'trainingpeaks-sdk';

// ⚠️ UNSTABLE: Internal modules - No SemVer guarantees
// These imports may introduce breaking changes in any version
// Use at your own risk - prefer public API documentation when possible
import { User } from 'trainingpeaks-sdk/domain';
import { Logger } from 'trainingpeaks-sdk/adapters';
import type { WorkoutType } from 'trainingpeaks-sdk/types';
`

Development

$3

- Node.js >= 18.0.0
- npm >= 8.0.0
- GitHub CLI (gh) - for project setup automation

GitHub CLI Authentication:
`bash


Authenticate with GitHub using web browser (recommended for security)

gh auth login --web

For GitHub Enterprise Server users, specify your hostname

gh auth login --web --hostname your-enterprise-hostname.com

Or set GH_HOST environment variable:

Linux/macOS: export GH_HOST=your-enterprise-hostname.com

Windows CMD: set GH_HOST=your-enterprise-hostname.com

Windows PowerShell: $env:GH_HOST="your-enterprise-hostname.com"

Verify authentication

gh auth status
`

$3

This repository includes automated setup scripts for GitHub project management:

`bash


Run the automated GitHub project setup

./scripts/github/setup/setup-github-project.sh

Test the setup script functionality

./scripts/github/setup/test-setup.sh

Get help and options

./scripts/github/setup/setup-github-project.sh --help
`

The setup script automatically creates:

- 🎯 GitHub project board with views and columns
- 🏷️ Comprehensive label system for issue categorization
- 📋 Issue templates for different types of requests
- 🔧 Initial project setup issues and epics
- ⚡ Dependabot and security automation

For detailed setup instructions, see scripts/github/setup/README.md.

$3

`bash


Install dependencies

npm install

Build the project

npm run build

Build specific targets

npm run build:esm # ES modules
npm run build:cjs # CommonJS
`

$3

`bash


Run unit tests

npm test

Run integration tests

npm run test:integration

Run E2E tests

npm run test:e2e

Run tests with coverage

npm run test:coverage
`

$3

`bash


Lint code

npm run lint

Format code

npm run format

Type check

npm run type-check

Validate imports

npm run check-imports
`

Architecture

This SDK follows Clean Architecture principles with a hexagonal architecture approach:

- Domain Layer: Core business entities and rules
- Application Layer: Business logic orchestration and contracts
- Adapters Layer: External integrations and concrete implementations (formerly Infrastructure) - see migration guide for infrastructure → adapters transition details

Key Benefits:

- 🧪 Highly Testable: Each layer can be tested independently
- 🔄 Maintainable: Clear separation of concerns and dependencies
- 🔧 Extensible: Easy to add new features or swap implementations
- 📦 Modular: Use individual components or the complete SDK

Documentation:

- Clean Architecture Guide - Detailed implementation patterns
- PRODUCT.md - Product vision and business context

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the existing code style
4. Add tests for your changes
5. Run the full test suite (npm run pre-release)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature`)
8. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

- 📖 Documentation
- 🐛 Bug Reports
- 💬 Discussions

Changelog

See CHANGELOG.md for a list of changes and version history.

---

Made with ❤️ for the TrainingPeaks community