github-contributions-counter

github-contributions-counter

A simple Javascript API that will return the public Github contributions history for a user based on a universal function

A Quick Note 👀

This was not designed in affiliation with Github, Getting contribution history is not part of their API as of the creation of this package.

Getting Started

Install via npm github-contributions-counter

npm install github-contributions-counter

Demo

Code Sandbox github-contributions-counter

Usage

// normal js require
const API = require('github-contributions-counter')

API.getGitHubContributionsHistory('your_username_here', {}).then((response) => {
  console.log(response)
})
/**
 * The expected response is an array of objects of the following:
 *
 * response = [{ annualContributions: "1699" }]
 *
 * */

API.getGitHubContributionsHistory('your_username_here', { total: 'total' }).then((response) => {
  console.log(response)
})
/**
 * The expected response is an array of objects of the following:
 * This is the all time contributions for a user
 * response = [{ totalContributions: '2027' }]
 *
 * */

API.getGitHubContributionsHistory('your_username_here', { total: 'total', byYear: 'byYear' }).then(
  (response) => {
    console.log(response)
  },
)
/**
 * The expected response is an array of objects of the following:
 * This is all the contributions by year for a user
 * response = [
 *       { contributions: '768', year: '2020' },
 *       { contributions: '1090', year: '2019' },
 *        { contributions: '167', year: '2018' },
 *       { contributions: '2', year: '2017' }
 *      ]
 *
 * */

API.getGitHubContributionsHistory('your_username_here', {
  total: 'total',
  byYear: 'byYear',
  proxy: 'https://your_proxy_url',
}).then((response) => {
  console.log(response)
})
/**
 * The expected response is an array of objects of the following:
 * This is all the contributions by year for a user
 * response = [
 *       { contributions: '768', year: '2020' },
 *       { contributions: '1090', year: '2019' },
 *        { contributions: '167', year: '2018' },
 *       { contributions: '2', year: '2017' }
 *      ]
 *
 * */

Show off your contributions 🤟💻🦾

API

getGitHubContributionsHistory((username: String), (confg: Object)).then((res) => console.log(res))

The API takes two params. The fist is the users username as a string. The second is a config object. The config object has 3 elements.

config = {
  total: 'total',
  byYear: 'byYear',
  proxy: 'https://cors-anywhere.herokuapp.com/',
}

1. total
   pass total: 'total' to get the total contributions for a user
2. byYear
   pass byYear: 'byYear' to get the total contributions for a user sorted by year
3. proxy
   the proxy arg would likely be required if you are using this node package in the browser because of CORS. proxy can have 3 possible configurations. If you do not include proxy in the config object passed to the function then no proxy will be used. If you pass proxy: true in the config object, then the proxy https://cors-anywhere.herokuapp.com/ will be used. As a third option, you can also pass your your own proxy as a string such as proxy: 'https://your-cors-bypass-url.com/'.

Error Handling

1. 429: The API should return 429 if there are too many requests
2. 200: 200 Okay
3. 400: 400 Bad request
4. {error: javascript error}
5. No more than 50 redirects allowed

If you are getting CORS errors such as

You probably need to pass a proxy. This can be done by setting proxy: true in the config object passed a s second argument to getGitHubContributionsHistory

Issues

Given that this API is scraping Github webpages for the desired data, it is a) not the fastest; and b) dependent on the DOM nodes for Github user profiles not changing to a large extent. If it stops working, open an issue on Github and i'll fit it asap! :)

Contributing

1. Fork
2. Open Pull request with a detailed note about the changes you have made
3. It will be reviewed and (hopefully) merged!

Contact

Sammy Robens-Paradise | Website
Sammy Robens-Paradise | Github