@0x3639/intervals-icu

@0x3639/intervals-icu

Maintained fork of paladini/node-intervals-icu with a vendored spec snapshot and CI-enforced coverage — all 149 spec operations covered, 0 phantom routes; 3 verified-but-undocumented routes allowlisted (see spec/undocumented-routes.json and AUDIT.md). See CHANGELOG for what changed in v3.

The most comprehensive TypeScript client for the Intervals.icu API — the training platform used by cyclists, runners, triathletes, and coaches worldwide.

130+ typed methods across 16 service groups. Dual auth (API key + OAuth), file uploads, auto-retry with jitter, and rate-limit tracking. One dependency (axios), ~27 KB minified.

Documentation: 0x3639.github.io/node-intervals-icu — guides, every method, and live-verified API behaviour.

Installation

npm install @0x3639/intervals-icu

Quick start

export INTERVALS_API_KEY=your-api-key   # Settings → Developer settings on intervals.icu

import { IntervalsClient } from '@0x3639/intervals-icu';

const client = new IntervalsClient({ apiKey: process.env.INTERVALS_API_KEY! });

const athlete = await client.athletes.getAthlete();
console.log(`${athlete.name} — FTP: ${athlete.ftp}`);

const activities = await client.activities.listActivities({ oldest: '2024-01-01', newest: '2024-01-31' });
console.log(`${activities.length} activities in January`);

Services Reference

Learn more

• Getting started
• Authentication
• Errors and retries
• Dates, pagination and arrays
• Files: FIT, GPX, CSV and zip
• API behaviour
• Migrating to v3

Related Projects

The TypeScript/Node.js ecosystem has a few Intervals.icu API clients worth knowing about:

When to use @0x3639/intervals-icu (this library):

• You need the broadest API coverage (16 service groups including routes, gear, weather, custom items, performance, analytics, and search)
• You prefer familiar try/catch error handling
• You're comfortable tracking an actively-developed fork (see AUDIT.md for known gaps and CHANGELOG for breaking changes)

When to use @kuranov/intervals-client:

• You want runtime validation of API responses via Valibot (catches unexpected API changes at runtime)
• You prefer the Result<T, E> pattern (no exceptions thrown)
• You want lifecycle hooks for observability (onRequest, onResponse, onRetry)
• You target browsers or edge runtimes (uses ky which is runtime-agnostic)

Both libraries serve the same core purpose and share similar design goals (TypeScript-first, dual ESM+CJS output, auto-retry, OAuth + API key auth). They differ mainly in HTTP client choice, error-handling philosophy, validation strategy, and endpoint coverage.

License

MIT © 0x3639. Original library © Fernando Paladini.

Acknowledgments

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!

Links

• Documentation site
• Intervals.icu API Documentation
• Intervals.icu Website
• GitHub Repository
• npm Package
• Changelog