A lightweight TypeScript client library for the Intervals.icu API. Supports all major endpoints including athletes, events, wellness, workouts, and activities.
- 🚀 Lightweight - Zero dependencies beyond axios
- 📘 Fully Typed - Written in TypeScript with comprehensive type definitions
- 🌳 Tree-shakeable - ESM exports for optimal bundle size
- 🔐 Authentication - Built-in support for API key authentication
- ⚡ Rate Limiting Awareness - Tracks and exposes rate limit information
- 🛡️ Error Handling - Robust error handling with custom error types
- 📖 Well Documented - JSDoc comments on all public methods
npm install intervals-icuimport { IntervalsClient } from 'intervals-icu';
// Initialize the client
const client = new IntervalsClient({
apiKey: 'your-api-key-here',
athleteId: 'i12345' // optional, defaults to 'me'
});
// Get athlete information
const athlete = await client.getAthlete();
console.log(`Athlete: ${athlete.name}, FTP: ${athlete.ftp}`);
// Get events
const events = await client.getEvents({
oldest: '2024-01-01',
newest: '2024-12-31'
});
// Create a wellness entry
await client.createWellness({
date: '2024-01-15',
weight: 70,
restingHR: 50,
sleepSecs: 28800
});interface IntervalsConfig {
apiKey: string; // Required: Your Intervals.icu API key
athleteId?: string; // Optional: Athlete ID (defaults to 'me')
baseURL?: string; // Optional: API base URL
timeout?: number; // Optional: Request timeout in ms (default: 10000)
}Get athlete information.
const athlete = await client.getAthlete();
console.log(athlete.name, athlete.ftp, athlete.weight);Update athlete information.
const updated = await client.updateAthlete({
ftp: 250,
weight: 70
});Get calendar events.
const events = await client.getEvents({
oldest: '2024-01-01',
newest: '2024-12-31'
});Get a specific event by ID.
const event = await client.getEvent(12345);Create a new calendar event.
const event = await client.createEvent({
start_date_local: '2024-01-15',
name: 'Race Day',
category: 'RACE',
description: 'Important race'
});Update an existing event.
await client.updateEvent(12345, {
name: 'Updated Race Day'
});Delete an event.
await client.deleteEvent(12345);Events now include a type field that allows you to reliably differentiate between different event types (Run, Ride, Swim, Strength, etc.) without relying on name patterns:
// Get all events
const allEvents = await client.getEvents({
oldest: '2024-01-01',
newest: '2024-12-31'
});
// Filter only running events
const runEvents = allEvents.filter(event => event.type === 'Run');
// Filter only cycling events
const rideEvents = allEvents.filter(event => event.type === 'Ride');
// Filter only swimming events
const swimEvents = allEvents.filter(event => event.type === 'Swim');
// Filter only strength training events
const strengthEvents = allEvents.filter(event => event.type === 'Strength');
// Find a specific running workout
const runWorkout = allEvents.find(e =>
e.category === 'WORKOUT' && e.type === 'Run'
);This approach is:
- ✅ Reliable and type-safe
- ✅ Language-agnostic (works with any language/locale)
- ✅ More maintainable than name-based pattern matching
Get wellness data.
const wellness = await client.getWellness({
oldest: '2024-01-01',
newest: '2024-01-31'
});Create a new wellness entry.
const wellness = await client.createWellness({
date: '2024-01-15',
weight: 70,
restingHR: 50,
hrv: 65,
sleepSecs: 28800,
sleepQuality: 8
});Update a wellness entry for a specific date.
await client.updateWellness('2024-01-15', {
weight: 69.5,
mood: 8
});Delete a wellness entry.
await client.deleteWellness('2024-01-15');Get planned workouts.
const workouts = await client.getWorkouts({
oldest: '2024-01-01',
newest: '2024-01-31'
});Get a specific workout by ID.
const workout = await client.getWorkout(12345);Create a new workout.
const workout = await client.createWorkout({
start_date_local: '2024-01-15',
name: 'Tempo Run',
description: '45 min tempo at threshold',
duration_secs: 2700,
tss: 65
});Update an existing workout.
await client.updateWorkout(12345, {
name: 'Updated Tempo Run',
tss: 70
});Delete a workout.
await client.deleteWorkout(12345);Get recorded activities.
const activities = await client.getActivities({
oldest: '2024-01-01',
newest: '2024-01-31'
});Get a specific activity by ID.
const activity = await client.getActivity(12345);Update an existing activity.
await client.updateActivity(12345, {
name: 'Morning Run',
description: 'Easy recovery run',
feel: 8
});Delete an activity.
await client.deleteActivity(12345);The client automatically tracks rate limit information from the API responses:
// Make some API calls
await client.getAthlete();
// Check rate limit status
const remaining = client.getRateLimitRemaining();
const resetTime = client.getRateLimitReset();
console.log(`Remaining: ${remaining}, Resets at: ${resetTime}`);The client throws IntervalsAPIError for all API-related errors:
import { IntervalsClient, IntervalsAPIError } from 'intervals-icu';
try {
const athlete = await client.getAthlete();
} catch (error) {
if (error instanceof IntervalsAPIError) {
console.error(`API Error: ${error.message}`);
console.error(`Status: ${error.status}`);
console.error(`Code: ${error.code}`);
// Handle specific error types
if (error.code === 'RATE_LIMIT_EXCEEDED') {
console.error('Rate limit exceeded, try again later');
} else if (error.code === 'AUTH_FAILED') {
console.error('Invalid API key');
}
}
}All methods and responses are fully typed. Import types as needed:
import type {
Athlete,
Event,
Wellness,
Workout,
Activity,
PaginationOptions,
IntervalsConfig
} from 'node-intervals-icu';To get your API key:
- Log in to Intervals.icu
- Go to Settings → API Key
- Copy your API key
Your athlete ID can be found in the URL when viewing your profile (e.g., i12345), or you can use 'me' to refer to the authenticated athlete.
MIT License - Copyright (c) 2025 Fernando Paladini
See the LICENSE file for details.
Special thanks to Filipe for the inspiration and the initial idea that led to the creation of this library. Your project was the spark that made this happen! 🙏
Contributions are welcome! Please read our Contributing Guide to learn how you can help make this project better.
For maintainers: See the Publishing Guide for detailed instructions on publishing this library to NPM.