Octo.js is a simple, flexible, functional JavaScript library for interacting with GitHub's v3 API. It runs in node.js apps and the browser. It supports Basic Auth, OAuth 2, pagination and more.
Requires superagent — A lightweight library for supporting Ajax in the browser and HTTP in node.js.
All examples are written in CoffeeScript, but Octo.js itself is written in JavaScript.
api = octo.api()
do api.get('/events').on 'success', (res) ->
pubevents = res.bodyapi.get sets up a closure, so you'll need to invoke it before the request is sent.
events = api.get('/events').perpage(50)
.on 'end', (res) ->
console.log api.limit()
console.log events.page() #1
do eventsDownload both superagent and octo.js and include them in the <head> of your document.
<script src="superagent.js"></script>
<script src="octo.js"></script>Install using npm.
npm install octoRequire octo in your node.js script
octo = require 'octo'One goal of octo.js was to make paging very simple. Paging is built right into the library.
events = api.get('/events').on 'success', (res) ->
# the current page
events.page()
# requests the next page
events.next()
# requests the previous page
events.prev()
do eventsWhat if you want to start on a different page and limit the number of results per page?
# Start on page 5 only returning 10 results per page
do api.get('/events').page(5).perpage(10)Octo.js supports three events: "success", "error" and "end". These callbacks are registered per pager. This makes it easy to use the same callbacks for each page you request.
success- Response status was in the 200 rangeerror- Response wasn't in the 200 rangeend- Fired at the end of every request, regarldess of status.
do api.get('/events')
.on('success', (res) -> console.log(res.body))
.on('error', (res) -> console.log(res.body))
.on('end', (res) -> console.log(res.body))api = octo.api().username('foo').password('bar')
do api.get('/user').on 'success', (res) -> console.log res.bodyIf you've registered your script or app as an OAuth app, you can use your token to authenticate with the api.
api = octo.api().token('MY APP TOKEN')
do api.get('/user').on 'success', (res) -> console.log res.bodyThis will work with any registered OAuth application, but will return unauthorized if you've not registered your application with GitHub.
GitHub APIv3 allows you to programmatically fetch a token for use in scripts that might not be websites. Grabbing an OAuth token requires a username and password. Once you have a token, you can use it without a need for your username and password.
api = octo.api().username('foo').password('bar')
do api.post('/authorizations', {note: 'my script', scopes: ['public_repo']})
.on 'success', (res) -> console.log res.bodyThe GitHub API has a rate limit that's returned with the headers of every request. You can easily access this info to see your limit and how many requests you have left
do api.get('/users/caged/repos').on 'success', ->
# Your limit per hour
console.log api.limit()
# Amount you have remaining in that hour
console.log api.remaining()There are some interactive examples in ./examples. You can fire up the server to play with these:
node examples.js
Examples available at http://localhost:9292