Kilometrikisa-client NPM

Kilometrikisa client

A client library to scrape data from Kilometrikisa.fi website and post data to user's contest logs. Supports scraping team statistics as well as team member data of user's team. Inspired by the original implementation of Strava2Kilometrikisa.

API Reference

Features

Login to Kilometrikisa by username and password
Scrape info about contests (id, name, dates etc.). Either latest contest or by contest page url
Scrape public team statistics from Kilometrikisa site
Scrape team member statistics from Kilometrikisa site (requires Kilometrikisa credentials and being part of the scraped team)
Update/add distance and time entries for logged in user
Fetch team data from Kilometrikisa results. Supports sorting and pagination.

Installation

npm install kilometrikisa-client --save

Usage

A quick example of usage for updating contest log of the user for the latest contest:

import { getTeamStatistics, kilometrikisaSession } from 'kilometrikisa-client';

// Log in to get session
const session = await kilometrikisaSession({username: 'username', password: 'password'});

// Fetch latest contest
const contest = await getLatestContest();

// Fetch member statistics of your team
const memberData = await session.getTeamMemberStatistics('team-slug', contest.slug);

// Update user's contest log for latest contest
await client.updateContestLog(contest.contestId, '2022-05-01', 10);

// Fetch public team statistics for current contest
const teamData = await getTeamStatistics('team-slug');

Team and contest slugs can be found from the kilometrikisa.fi site urls. For example team slug can be found from public team page's url: https://www.kilometrikisa.fi/teams/<this-is-team-slug>/ Contest slug can be found from the team page url when logged in. Usually it is in form of kilometrikisa-2022 etc. For more check API Reference

Development

To run production tests you'll need Kilometrikisa credentials. Copy .env.template to .env and fill in credentials:

# Run local tests
npm test

cp .env.template .env
# Fill in kilometrikisa credentials to the .env file
# Run tests against the kilometrikisa production (credentials required)
npm run test:production

How to release

Bump up the package version with npm version major|minor|patch and push the commit to main
Create Github release
Let Github Actions to deploy the release automatically to the NPM.

Contributing

Please open an issue about the bug, feature request etc. first to open a discussion
For bug reports, be specific about the issue and provide steps to reproduce the bug if possible

Code quality

Add tests for the new feature or bug fix if possible
Make sure test suite and linter pass

Pull requests and commits

If possible pull requests should conform the following guidelines:

Use rebase work flow. Do not merge main branch to your feature branch. Use git rebase main instead
Commit names should be descriptive and in imperative format. E.g. "Add support for X"