https://github.com/caged/octo
octo.js - A small JavaScript library for GitHub's API that works in nodejs and the browser.
https://github.com/caged/octo
Last synced: about 1 year ago
JSON representation
octo.js - A small JavaScript library for GitHub's API that works in nodejs and the browser.
- Host: GitHub
- URL: https://github.com/caged/octo
- Owner: caged
- Created: 2012-04-09T20:43:44.000Z (about 14 years ago)
- Default Branch: master
- Last Pushed: 2015-11-26T22:10:42.000Z (over 10 years ago)
- Last Synced: 2025-04-19T17:10:57.600Z (about 1 year ago)
- Language: JavaScript
- Homepage: http://labratrevenge.com/octo
- Size: 215 KB
- Stars: 20
- Watchers: 2
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: Readme.md
Awesome Lists containing this project
README
# Octo.js
Octo.js is a simple, flexible, functional JavaScript library for interacting with [GitHub's v3 API](http://developer.github.com/v3). It runs in node.js apps and the browser. It supports Basic Auth, OAuth 2, pagination and more.
**Requires [superagent](https://github.com/visionmedia/superagent)** — A lightweight library for supporting Ajax in the browser and HTTP in node.js.
All examples are written in [CoffeeScript](http://coffeescript.org), but Octo.js itself is written in JavaScript.
## Quick Example
```coffeescript
api = octo.api()
do api.get('/events').on 'success', (res) ->
pubevents = res.body
```
`api.get` sets up a closure, so you'll need to invoke it before the request is sent.
```coffeescript
events = api.get('/events').perpage(50)
.on 'end', (res) ->
console.log api.limit()
console.log events.page() #1
do events
```
## Using in the browser
Download both [superagent](https://github.com/visionmedia/superagent) and octo.js and include them in the `` of your document.
```html
```
## Using in node.js
Install using `npm`.
```shell
npm install octo
```
Require octo in your node.js script
```coffeescript
octo = require 'octo'
```
## Paging
One goal of octo.js was to make paging very simple. Paging is built right into the library.
```coffeescript
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 events
```
What if you want to start on a different page and limit the number of results per page?
```coffeescript
# Start on page 5 only returning 10 results per page
do api.get('/events').page(5).perpage(10)
```
## Events
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 range
* *`error`* - Response wasn't in the 200 range
* *`end`* - Fired at the end of every request, regarldess of status.
```coffeescript
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))
```
## Basic Auth
``` coffeescript
api = octo.api().username('foo').password('bar')
do api.get('/user').on 'success', (res) -> console.log res.body
```
## OAuth2
If you've [registered your script or app](https://github.com/settings/applications/new) as an OAuth app, you can use your token to authenticate with the api.
```coffeescript
api = octo.api().token('MY APP TOKEN')
do api.get('/user').on 'success', (res) -> console.log res.body
```
This will work with any registered OAuth application, but will return *unauthorized* if you've not registered your application with GitHub.
### Getting an OAuth 2 token from the API
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.
```coffeescript
api = octo.api().username('foo').password('bar')
do api.post('/authorizations', {note: 'my script', scopes: ['public_repo']})
.on 'success', (res) -> console.log res.body
```
## Checking Rate limits
The 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
```coffeescript
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()
```
### More examples
There are some interactive examples in ./examples. You can fire up the server to play with these:
```shell
node examples.js
Examples available at http://localhost:9292
```