Contribution

GitHub contribution graph parser calculates contribution streak and commit statistics from a user's GitHub contribution graph page


Motivation

The GitHub API does not provide contribution streak data; this package scrapes and parses the contribution graph from a user's GitHub contribution graph at https://github.com/users/USERNAME/contributions to provide contribution streak and commit statistics.

Install

Install from npm with your favourite package manager:

``sh


npm

npm install contribution

yarn

yarn add contribution

pnpm

pnpm add contribution

bun

bun add contribution
`

Usage

Import the function and call it with a GitHub username:

`typescript
import { fetchGitHubStats } from 'contribution';

const stats = await fetchGitHubStats('jamieweavis');
console.log(stats);
`

The returned GitHubStats object has the following structure:

`typescript
interface GitHubStats {
// Streak
bestStreak: number;
previousStreak: number;
currentStreak: number;
isStreakAtRisk: boolean;

// Contributions
mostContributions: number;
todaysContributions: number;
totalContributions: number;
contributions: Contributions;
}

interface Contributions {
[date: string]: Day; // [YYYY-MM-DD]
}

interface Day {
contributions: number;
gitHubLegendLevel: number;
}
`

Development

$3

- Node.js (v20+)
- pnpm (v10+)

$3

Clone the repository and install dependencies:

`sh
git clone https://github.com/jamieweavis/contribution.git

cd contribution

pnpm install
`

Run all tests with Vitest:

`sh
pnpm test
`

Check the code for linting and formatting issues with Biome:

`sh
pnpm check
`

Build the package with Parcel:

`sh
pnpm build
``

Related

- Streaker - Cross-platform GitHub contribution streak & statistic tracking menu bar application with reminder notification
- Streaker CLI - GitHub contribution streak & statistic tracking command line application with ASCII contribution graph