github-contributions-counter
Version:
A simple Javascript API that will return the public github contributions history for a user based on a universal function
149 lines (114 loc) • 4.73 kB
Markdown
# github-contributions-counter
A simple Javascript API that will return the public Github contributions history for a user based on a universal function
<br>
<br>
#### 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](https://www.npmjs.com/package/github-contributions-counter)
```bash
npm install github-contributions-counter
```
### Demo
[Code Sandbox github-contributions-counter](https://codesandbox.io/s/github-contributions-counter-2x0ev?file=/index.html)
### Usage
```js
// 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
```js
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.
```js
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](https://developer.mozilla.org/en-US/docs/Web/HTTP/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/](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](https://sammyrp.com)\
[Sammy Robens-Paradise | Github](https://github.com/SammyRobensParadise)