Strava

This library is a fully typed JavaScript wrapper of the Strava JSON API.

Installation

To install the package, run:

npm install strava

or

yarn add strava

Usage

The library can be initialized with a refresh token and optionally an access token. If these are not available, see below (Token exchange).

import { Strava } from 'strava'

const strava = new Strava({
  client_id: '123',
  client_secret: 'abc',
  refresh_token: 'def',
})

try {
  const activities = await strava.activities.getLoggedInAthleteActivities()
  console.log(activities)
} catch (error) {
  console.log(error)
}

Refreshing the access token

This library will automatically refresh the access token when needed. In order to store the token, you can use the on_token_refresh callback. This received an AccessToken object (consisting of access_token, expires_at, and refresh_token). Note that the refresh token as returned by this call can sometimes change, at which point the old token becomes invalid.

An AccessToken object can also be passed as a second argument to the Strava constructor. This can save an initial token refresh. As AccessToken contains a refresh token, the first argument does not need to contain a refresh token.

import { Strava } from 'strava'

const strava = new Strava(
  {
    client_id: '123',
    client_secret: 'abc',

    on_token_refresh: (response) => {
      cache.accessToken = response
    },
  },
  cache.accessToken,
)

Token exchange

When a user logs in for the first time, you will need to perform authorization with OAuth. This involves sending the user to https://www.strava.com/oauth/authorize, and receiving the auth code as a query parameter.

This can be used as follows:

import { Strava } from 'strava'

try {
  const strava = await Strava.createFromTokenExchange(
    {
      client_id: '123',
      client_secret: 'abc',
    },
    token,
  )

  const activities = await strava.activities.getLoggedInAthleteActivities()
  console.log(activities)
} catch (error) {
  console.log(error)
}

Getting athlete info

When a user logs in for the first time, the Strava API returns information about the newly logged-in user. This can be read using the on_token_refresh callback. Note that this will only ever be provided on the initial token exchange, before the promise returned from Strava.createFromTokenExchange returns. When the on_token_refresh callback is called again after the token expires, response.athlete will always be undefined.

import { Strava } from 'strava'

try {
  const strava = await Strava.createFromTokenExchange(
    {
      client_id: '123',
      client_secret: 'abc',
      on_token_refresh: (response) => {
        if (response.athlete) {
          console.log(response.athlete)
        }

        db.set('refresh_token', response.refresh_token)
      },
    },
    token,
  )

  const activities = await strava.activities.getLoggedInAthleteActivities()
  console.log(activities)
} catch (error) {
  console.log(error)
}

API Rate Limits

The Strava API has rate limits: 200 requests per 15 minutes and 2,000 requests per day. This library automatically tracks rate limit information from API responses.

You can access rate limit information in two ways:

1. Using the getRateLimit() method:

const strava = new Strava({
  client_id: '123',
  client_secret: 'abc',
  refresh_token: 'def',
})

await strava.activities.getLoggedInAthleteActivities()

const rateLimit = strava.getRateLimit()
if (rateLimit) {
  console.log(`Short term: ${rateLimit.shortTermUsage}/${rateLimit.shortTermLimit}`)
  console.log(`Daily: ${rateLimit.longTermUsage}/${rateLimit.longTermLimit}`)
}

2. Using the on_rate_limit_update callback:

const strava = new Strava({
  client_id: '123',
  client_secret: 'abc',
  refresh_token: 'def',
  on_rate_limit_update: (rateLimit) => {
    console.log('Rate limit updated:', rateLimit)

    // Check if approaching limits
    if (rateLimit.shortTermUsage > rateLimit.shortTermLimit * 0.9) {
      console.warn('Approaching 15-minute rate limit!')
    }
  },
})

The RateLimit object contains:

• shortTermLimit - 15-minute request limit
• shortTermUsage - Current 15-minute usage
• longTermLimit - Daily request limit
• longTermUsage - Current daily usage
• timestamp - When the rate limit was last updated

Contributing

Issues and pull requests are welcome.

License

MIT