octocat.js
Modified from SamyPesse octocat to fix npm audit issues. Test coverage is low on this, recommend using the original octocat.
Javascript library to access the GitHub API.
-
✨ Promise based -
✨ Support GitHub Enterprise -
✨ Easy handling of paginated results
Installation
$ npm install octocat --save
Usage
Create an API client
const GitHub = require('octocat');
// Using an access token
const client = new GitHub({
token: 'my-access-token'
});
// Using an username/password
const client = new GitHub({
username: 'SamyPesse',
password: 'my-password'
});
// Connecting to an enterprise version
const client = new GitHub({
endpoint: 'https:///github.mycompany.com'
});
HTTP API access
All of these methods return promises.
client.request('GET', '/repos/SamyPesse/octocat.js', { /* query/body parameters */})
client.get('/repos/SamyPesse/octocat.js', { /* query parameters */})
client.post('/repos/SamyPesse/octocat.js', { /* body parameters */})
client.patch('/repos/SamyPesse/octocat.js', { /* body parameters */})
client.put('/repos/SamyPesse/octocat.js', { /* body parameters */})
client.del('/repos/SamyPesse/octocat.js', { /* body parameters */})
These methods return a response
object that looks like:
{
// HTTP Status code
statusCode: 200,
// Type of status: 2XX, 3XX, 4xx
statusType: '2XX',
// Headers returned by the server
headers: { ... },
// Body of the request
body: { ... }
}
In case of error, the response can also be accessible using as a response
property.
Pagination
Some methods of Octonode return paginated results. Check on GitHub which API methods are paginated.
These methods return a Page
object:
-
page.list
contains the list of results in the current page -
page.next()
update with the results of the next page (Promised) -
page.prev()
update with the results of the previous page (Promised) -
page.hasNext()
andpage.hasPrev()
-
page.all()
return all the results by recursively calling the API
Users
// Get a single user
const user = client.user('SamyPesse');
user.info().then(function(infos) { ... });
// Get the authenticated user
const user = client.me();
// Edit the authenticated user
user.edit({
name: "New Name"
})
Repositories
// Create a new repository
client.createRepo({ ... }).then(function() { });
// Get public repositories (paginated)
client.repos().then(function(page) { ... });
// List user repositories
user.repos().then(function(page) { ... });
// Get a single repository
const repo = client.repo('SamyPesse/octocat.js');
repo.info().then(function(infos) { ... });
// Compare two commits
repo.compare('master', 'dev').then(function(infos) { ... });
// Perform a merge
repo.merge({ base: 'master', head: 'dev' }).then(function() { ... });
// Delete the repository
repo.destroy()
Issues
// List issues for a repository
repo.issues().then(function(page) { ... });
// Create an issue in a repository
repo.createIssue({
title: "An awesome issue"
});
// Get a single issue in a repository
const issue = repo.issue(200);
issue.info().then(function(infos) { ... });
// Edit an issue
issue.edit({
title: "New Title"
})
Organization
// List organizations of an user
user.orgs().then(function(orgs) { ... });
// Check an user's membership to an organization
user.getOrgMembership('organization').then(function(membership) { ... });
// List an user's memberships to all of his organizations
user.getOrgsMemberships({ state: 'active' }).then(function(page) { ... });
// Get a single organization
const org = client.org('GitbookIO');
org.info().then(function(infos) { ... });
// Edit the organization
org.edit({
name: "The new name"
})
// List members of the organization
org.members().then(function(page) { ... });
// Create a new repository
org.createRepo({ ... }).then(function() { });
Commits
// List commits for a repository
repo.commits().then(function(commits) { ... });
// Get a single commit
const commit = repo.commit('6dcb09b5b57875f334f61aebed695e2e4193db5e');
commit.info().then(function(infos) { ... });
Statuses
// Create a Status
repo.createStatus('sha', { ... }).then(function() { ... });
// List Statuses for a specific Ref
commit.statuses().then(function(statuses) { ... });
Branches
// List branches for a repository
repo.branches().then(function(branches) { ... });
// Get a single branch
const branch = repo.branch('master');
branch.info().then(function(infos) { ... });
Tags
// List tags for a repository
repo.tags().then(function(tags) { ... });
Webhooks
// List hooks for a repository
repo.hooks().then(function(hooks) { ... });
// Get a single hook
const hook = repo.hook('1');
hook.info().then(function(infos) { ... });
// Edit a hook
hook.edit({
name: "Test"
})
// Delete the hook
hook.destroy()
Releases
// List releases of a repository
repo.releases().then(function(assets) { ... });
// Get details about the release
const release = repo.release('1');
release.info().then(function(infos) { ... });
// Edit a release
release.edit({
name: "Test"
})
// Delete the release
release.destroy()
Uploading assets
// Upload a new asset as file/stream
release.upload('./myfile.zip').then(function() { ... });
release.upload(stream, { name: "myfile.zip" }).then(function() { ... });
release.upload
will also notify with progress:
release.upload('./myfile.zip')
.progress((p) => {
/*
{ percentage: 96.61881065572815,
transferred: 45088768,
length: 46666656,
remaining: 1577888,
eta: 0,
runtime: 11,
delta: 196608,
speed: 3920762.434782609 }
*/
})
.then(() => {
});
Releases Assets
// List assets of a release
release.assets().then(function(assets) { ... });
// Get details about the release
const asset = release.asset('1');
asset.info().then(function(infos) { ... });
// Download the asset to a file
asset.download('./myfile.zip').then(function() { ... });
// Download the asset to a stream
asset.download(stream).then(function() { ... });
// Delete the asset
asset.destroy()
Emails
// List email addresses
client.userEmails().then(function(emails) { ... });
// Add email address(es)
client.addUserEmails([ 'octocat@github.com' ]).then(function() { ... });
// Delete email address(es)
client.deleteUserEmails([ 'octocat@github.com' ]).then(function() { ... });
Authorization for a specific app
const app = client.application('clientId');
const token = app.token('access_token');
// Check an authorization
token.info().then(function(infos) { ... });
// Reset an authorization
token.reset().then(function() { ... });
// Delete an authorization
token.destroy().then(function() { ... });
Git Data
Reference
const ref = repo.gitRef('heads/master');
// Get a reference
ref.info().then(function(infos) { ... });
// Edit / Delete
ref.edit({ ... }).then(function() { ... });
ref.destroy().then(function() { ... });
Commit
const commit = repo.gitCommit('<sha>');
// Get a commit
commit.info().then(function(infos) { ... });
Rate Limiting
You can also check your rate limit status by calling the following.
client.limit().then(function(rate) { ... })