strava

# Strava Skill

Interact with Strava to load activities, analyze workouts, and track fitness data.

## Setup

### 1. Create a Strava API Application

1. Go to https://www.strava.com/settings/api
2. Create an app (use `http://localhost` as callback for testing)
3. Note your **Client ID** and **Client Secret**

### 2. Get Initial OAuth Tokens

Visit this URL in your browser (replace CLIENT_ID):
```
https://www.strava.com/oauth/authorize?client_id=CLIENT_ID&response_type=code&redirect_uri=http://localhost&approval_prompt=force&scope=activity:read_all
```

After authorizing, you'll be redirected to `http://localhost/?code=AUTHORIZATION_CODE`

Exchange the code for tokens:
```bash
curl -X POST https://www.strava.com/oauth/token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=AUTHORIZATION_CODE \
  -d grant_type=authorization_code
```

This returns `access_token` and `refresh_token`.

### 3. Configure Credentials

Add to `~/.clawdbot/clawdbot.json`:
```json
{
  "skills": {
    "entries": {
      "strava": {
        "enabled": true,
        "env": {
          "STRAVA_ACCESS_TOKEN": "your-access-token",
          "STRAVA_REFRESH_TOKEN": "your-refresh-token",
          "STRAVA_CLIENT_ID": "your-client-id",
          "STRAVA_CLIENT_SECRET": "your-client-secret"
        }
      }
    }
  }
}
```

Or use environment variables:
```bash
export STRAVA_ACCESS_TOKEN="your-access-token"
export STRAVA_REFRESH_TOKEN="your-refresh-token"
export STRAVA_CLIENT_ID="your-client-id"
export STRAVA_CLIENT_SECRET="your-client-secret"
```

## Usage

### List Recent Activities

Get the last 30 activities:
```bash
curl -s -H "Authorization: Bearer ${STRAVA_ACCESS_TOKEN}" \
  "https://www.strava.com/api/v3/athlete/activities?per_page=30"
```

Get the last 10 activities:
```bash
curl -s -H "Authorization: Bearer ${STRAVA_ACCESS_TOKEN}" \
  "https://www.strava.com/api/v3/athlete/activities?per_page=10"
```

### Filter Activities by Date

Get activities after a specific date (Unix timestamp):
```bash
# Activities after Jan 1, 2024
curl -s -H "Authorization: Bearer ${STRAVA_ACCESS_TOKEN}" \
  "https://www.strava.com/api/v3/athlete/activities?after=1704067200"
```

Get activities in a date range:
```bash
# Activities between Jan 1 - Jan 31, 2024
curl -s -H "Authorization: Bearer ${STRAVA_ACCESS_TOKEN}" \
  "https://www.strava.com/api/v3/athlete/activities?after=1704067200&before=1706745600"
```

### Get Activity Details

Get full details for a specific activity (replace ACTIVITY_ID):
```bash
curl -s -H "Authorization: Bearer ${STRAVA_ACCESS_TOKEN}" \
  "https://www.strava.com/api/v3/activities/ACTIVITY_ID"
```

### Get Athlete Profile

Get the authenticated athlete's profile:
```bash
curl -s -H "Authorization: Bearer ${STRAVA_ACCESS_TOKEN}" \
  "https://www.strava.com/api/v3/athlete"
```

### Get Athlete Stats

Get athlete statistics (replace ATHLETE_ID):
```bash
curl -s -H "Authorization: Bearer ${STRAVA_ACCESS_TOKEN}" \
  "https://www.strava.com/api/v3/athletes/ATHLETE_ID/stats"
```

### Pagination

Navigate through pages:
```bash
# Page 1 (default)
curl -s -H "Authorization: Bearer ${STRAVA_ACCESS_TOKEN}" \
  "https://www.strava.com/api/v3/athlete/activities?page=1&per_page=30"

# Page 2
curl -s -H "Authorization: Bearer ${STRAVA_ACCESS_TOKEN}" \
  "https://www.strava.com/api/v3/athlete/activities?page=2&per_page=30"
```

## Token Refresh

Access tokens expire every 6 hours. Refresh using the helper script:
```bash
bash {baseDir}/scripts/refresh_token.sh
```

Or manually:
```bash
curl -s -X POST https://www.strava.com/oauth/token \
  -d client_id="${STRAVA_CLIENT_ID}" \
  -d client_secret="${STRAVA_CLIENT_SECRET}" \
  -d grant_type=refresh_token \
  -d refresh_token="${STRAVA_REFRESH_TOKEN}"
```

The response includes a new `access_token` and `refresh_token`. Update your configuration with both tokens.

## Common Data Fields

Activity objects include:
- `name` — Activity title
- `distance` — Distance in meters
- `moving_time` — Moving time in seconds
- `elapsed_time` — Total time in seconds
- `total_elevation_gain` — Elevation gain in meters
- `type` — Activity type (Run, Ride, Swim, etc.)
- `sport_type` — Specific sport type
- `start_date` — Start time (ISO 8601)
- `average_speed` — Average speed in m/s
- `max_speed` — Max speed in m/s
- `average_heartrate` — Average heart rate (if available)
- `max_heartrate` — Max heart rate (if available)
- `kudos_count` — Number of kudos received

## Rate Limits

- **200 requests** per 15 minutes
- **2,000 requests** per day

If you hit rate limits, responses will include `X-RateLimit-*` headers.

## Tips

- Convert Unix timestamps: `date -d @TIMESTAMP` (Linux) or `date -r TIMESTAMP` (macOS)
- Convert meters to km: divide by 1000
- Convert meters to miles: divide by 1609.34
- Convert m/s to km/h: multiply by 3.6
- Convert m/s to mph: multiply by 2.237
- Convert seconds to hours: divide by 3600
- Parse JSON with `jq` if available, or use `grep`/`sed` for basic extraction

## Examples

Get running activities from last week with distances:
```bash
LAST_WEEK=$(date -d '7 days ago' +%s 2>/dev/null || date -v-7d +%s)
curl -s -H "Authorization: Bearer ${STRAVA_ACCESS_TOKEN}" \
  "https://www.strava.com/api/v3/athlete/activities?after=${LAST_WEEK}&per_page=50" \
  | grep -E '"name"|"distance"|"type"'
```

Get total distance from recent activities:
```bash
curl -s -H "Authorization: Bearer ${STRAVA_ACCESS_TOKEN}" \
  "https://www.strava.com/api/v3/athlete/activities?per_page=10" \
  | grep -o '"distance":[0-9.]*' | cut -d: -f2 | awk '{sum+=$1} END {print sum/1000 " km"}'
```

## Error Handling

If you get a 401 Unauthorized error, your access token has expired. Run the token refresh command.

If you get rate limit errors, wait until the limit window resets (check `X-RateLimit-Usage` header).