- pksunkara/octonode: api v3 in nodejs

octonode is a library for nodejs to access the v3 api

npm install octonode

var  = require('octonode');

// Then we instantiate a client with or without a token (as show in a later section)

var ghme           = client.me();
var ghuser         = client.user('pksunkara');
var ghrepo         = client.repo('pksunkara/hub');
var ghorg          = client.org('flatiron');
var ghissue        = client.issue('pksunkara/hub', 37);
var ghmilestone    = client.milestone('pksunkara/hub', 37);
var ghlabel        = client.label('pksunkara/hub', 'todo');
var ghpr           = client.pr('pksunkara/hub', 37);
var ghrelease      = client.release('pksunkara/hub', 37);
var ghgist         = client.gist();
var ghteam         = client.team(37);
var ghproject      = client.project(37);
var ghnotification = client.notification(37);

var ghsearch = client.search();

var client = .client();

client.get('/users/pksunkara', {}, function (err, status, body, headers) {
  console.log(body); //json object
});

var client = .client('some_access_token');

client.get('/user', {}, function (err, status, body, headers) {
  console.log(body); //json object
});

You can configure the protocol, hostname and port to use. For example to connect to a Enterprise instance.

var client = .client('some_access_token', {
  hostname: 'mydomain.com/api/v3'
});

client.get('/user', {}, function (err, status, body, headers) {
  console.log(body); //json object
});

Request options can be set by setting defaults on the client. (e.g. Proxies)

var client = .client();

client.requestDefaults['proxy'] = 'https://myproxy.com:1085'

These options are passed through to request, see their API here: https://.com/request/request#requestoptions-callback

You can set proxies dynamically by using the example above, but Octonode will respect environment proxies by default. Just set this using: export HTTP_PROXY='https://myproxy.com:1085' if you are using the command line

Many of the below use cases use parts of the above code

The client supports conditional requests and helps you respecting rate limits by caching information that hasn't changed. You can add the If-None-Match header to each request calling the conditional method.

var client = .client();

// This add If-None-Match header to the request
.repo().conditional('ETAG').issues();

More info about conditional requests can be founded here.

Note: Ensure that the scopes argument is an object containing the required note property. For two-factor authentication add the One Time Password otp key with its corresponding code to the configuration object.

var scopes = {
  'scopes': ['user', 'repo', 'gist'],
  'note': 'admin script'
};

.auth.config({
  username: 'pksunkara',
  password: 'password'
}).login(scopes, function (err, id, token, headers) {
  console.log(id, token);
});

// Web application which authenticates to 
var http = require('http')
  , url = require('url')
  , qs = require('querystring')
  ,  = require('octonode');

// Build the authorization config and url
var auth_url = .auth.config({
  id: 'myclientid',
  secret: 'myclientsecret',
  apiUrl: 'https://optional-internal--enterprise/api/v3',
  webUrl: 'https://optional-internal--enterprise'
}).login(['user', 'repo', 'gist']);

// Store info to verify against CSRF
var state = auth_url.match(/&state=([0-9a-z]{32})/i);

// Web server
http.createServer(function (req, res) {
  uri = url.parse(req.url);
  // Redirect to  login
  if (uri.pathname=='/login') {
    res.writeHead(302, {'Content-Type': 'text/plain', 'Location': auth_url})
    res.end('Redirecting to ' + auth_url);
  }
  // Callback url from  login
  else if (uri.pathname=='/auth') {
    var values = qs.parse(uri.query);
    // Check against CSRF attacks
    if (!state || state[1] != values.state) {
      res.writeHead(403, {'Content-Type': 'text/plain'});
      res.end('');
    } else {
      .auth.login(values.code, function (err, token, headers) {
        res.writeHead(200, {'Content-Type': 'text/plain'});
        res.end(token);
      });
    }
  } else {
    res.writeHead(200, {'Content-Type': 'text/plain'})
    res.end('');
  }
}).listen(3000);

console.log('Server started on 3000');

You can also check your rate limit status by calling the following.

client.limit(function (err, left, max, reset) {
  console.log(left); // 4999
  console.log(max);  // 5000
  console.log(reset);  // 1372700873 (UTC epoch seconds)
});

All the callbacks for the following will take first an error argument, then a data argument, like this:

ghme.info(function(err, data, headers) {
  console.log("error: " + err);
  console.log("data: " + data);
  console.log("headers:" + headers);
});

If you would like to work with promises rather than callbacks, you can call the promise based version of any of the api calls by appending Async to the function call.

For example prs() becomes prsAsync() like this:

async function getPullRequests () {
  const client = .client(config.AccessToken)
  const repo = client.repo('pksunkara/octonode')

  const result = await repo.prsAsync({ per_page: 100 })
  return result[0]
}

If a function is said to be supporting pagination, then that function can be used in many ways as shown below. Results from the function are arranged in pages.

The page argument is optional and is used to specify which page of issues to retrieve. The perPage argument is also optional and is used to specify how many issues per page.

// Normal usage of function
ghrepo.issues(callback); //array of first 30 issues

// Using pagination parameters
ghrepo.issues(2, 100, callback); //array of second 100 issues
ghrepo.issues(10, callback); //array of 30 issues from page 10

// Pagination parameters can be set with query object too
ghrepo.issues({
  page: 2,
  per_page: 100, //maximum is 100
  state: 'closed'
}, callback); //array of second 100 issues which are closed

Token/Credentials required for the following:

ghme.info(callback); //json

ghme.update({
  "name": "monalisa octocat",
  "email": "[email protected]",
}, callback);

ghme.emails(callback); //array of emails

ghme.emails(['[email protected]', '[email protected]'], callback); //array of emails
ghme.emails('[email protected]', callback); //array of emails

ghme.emails(['[email protected]', '[email protected]']);
ghme.emails('[email protected]');

ghme.followers(callback); //array of  users

This query supports pagination.

ghme.following(callback); //array of  users

ghme.following('marak', callback); //boolean

ghme.follow('marak');

ghme.unfollow('marak');

ghme.keys(callback); //array of keys

ghme.keys(1, callback); //key

ghme.keys({"title":"laptop", "key":"ssh-rsa AAA..."}, callback); //key

ghme.keys(1, {"title":"desktop", "key":"ssh-rsa AAA..."}, callback); //key

ghme.keys(1);

This query supports pagination.

ghme.starred(callback); //array of repos

ghme.checkStarred('flatiron/flatiron', callback); //boolean

ghme.star('flatiron/flatiron');

ghme.unstar('flatiron/flatiron');

This query supports pagination.

ghme.watched(callback); //array of repos

This query supports pagination.

ghme.orgs(callback); //array of orgs

This query supports pagination.

ghme.repos(callback); //array of repos

ghme.repo({
  "name": "Hello-World",
  "description": "This is your first repo",
}, callback); //repo

ghme.fork('pksunkara/hub', callback); //forked repo

This query supports pagination.

ghme.issues({
  page: 2,
  per_page: 100,
  filter: 'assigned',
  state: 'open',
  sort: 'created'
}, callback); //array of issues

This query supports pagination.

ghme.teams({
  page: 1,
  per_page: 50
}, callback); //array of team memberships

Options based on http://git.io/vYYOx

ghme.notifications({}, callback); //array of notifications

No token required for the following

ghuser.info(callback); //json

This query supports pagination.

ghuser.followers(callback); //array of  users

This query supports pagination.

ghuser.following(callback); //array of  users

This query supports pagination.

ghuser.repos(callback); //array of public  repos

This query supports pagination.

Optionally, supply an array of Event Types to filter by.

ghuser.events(['PushEvent'], callback); //array of PushEvent events

Or leave it out to get all Event Types.

ghuser.events(callback); //array of events

This query supports pagination.

ghuser.orgs(callback); //array of organizations

ghrepo.info(callback); //json

ghrepo.update({
  private: false
}, callback); // repo

ghrepo.collaborators(callback); //array of  users

ghrepo.collaborators('marak', callback); //boolean

ghrepo.commits(callback); //array of commits

ghrepo.commit('18293abcd72', callback); //commit

ghrepo.compare('master', 'develop', callback); //compare develop to master

ghrepo.tags(callback); //array of tags

ghrepo.releases(callback); //array of releases

ghrepo.languages(callback); //array of languages

ghrepo.contributors(callback); //array of  users

This query supports pagination.

ghrepo.branches(callback); //array of branches

ghrepo.branch('master', callback); //branch

ghrepo.createReference('master', '18293abcd72', callback);

This query supports pagination.

ghrepo.issues(callback); //array of issues

ghrepo.issue({
  "title": "Found a bug",
  "body": "I'm having a problem with this.",
  "assignee": "octocat",
  "milestone": 1,
  "labels": ["Label1", "Label2"]
}, callback); //issue

This query supports pagination.

ghrepo.milestones(callback); //array of milestones

ghrepo.milestone({
  "title": "Sprint 345",
  "description": "The sprint where we fix all the things!",
  "due_on": new Date(2014, 7, 1)
}, callback); //milestone

This query supports pagination.

ghrepo.projects(callback); //array of projects

ghrepo.project({
  "name": "Sprint 345",
  "body": "The sprint where we fix all the things!"
}, callback); //project

This query supports pagination.

ghrepo.labels(callback); //array of labels

ghrepo.label({
  "name": "Priority",
  "color": "ff0000",
}, callback); //label

This query supports pagination.

ghrepo.prs(callback); //array of pull requests

ghrepo.pr({
  "title": "Amazing new feature",
  "body": "Please pull this in!",
  "head": "octocat:new-feature",
  "base": "master"
}, callback); //pull request

This query supports pagination.

ghrepo.hooks(callback); //array of hooks

ghrepo.hook({
  "name": "web",
  "active": true,
  "events": ["push", "pull_request"],
  "config": {
    "url": "http://myawesomesite.com//events"
  }
}, callback); // hook

ghrepo.deleteHook(37, callback);

ghrepo.readme(callback); //file
ghrepo.readme('v0.1.0', callback); //file

ghrepo.contents('', "myBranch", callback);

ghrepo.contents('lib/index.js', callback); //path
ghrepo.contents('lib/index.js', 'v0.1.0', callback); //path

ghrepo.createContents('lib/index.js', 'commit message', 'content', callback); //path
ghrepo.createContents('lib/index.js', 'commit message', 'content', 'v0.1.0', callback); //path

ghrepo.updateContents('lib/index.js', 'commit message', 'content', 'put-sha-here', callback); //path
ghrepo.updateContents('lib/index.js', 'commit message', 'content', 'put-sha-here', 'master', callback); //path
ghrepo.updateContents('lib/index.js', 'commit message', 'content', 'put-sha-here', 'v0.1.0', callback); //path

ghrepo.deleteContents('lib/index.js', 'commit message', 'put-sha-here', callback); //path
ghrepo.deleteContents('lib/index.js', 'commit message', 'put-sha-here', 'v0.1.0', callback); //path

ghrepo.archive('tarball', callback); //link to archive
ghrepo.archive('zipball', 'v0.1.0', callback); //link to archive

ghrepo.blob('18293abcd72', callback); //blob

ghrepo.stargazers(1, 100, callback); //array of users
ghrepo.stargazers(10, callback);     //array of users
ghrepo.stargazers(callback);         //array of users

ghrepo.teams(callback); //array of teams

ghrepo.tree('18293abcd72', callback); //tree
ghrepo.tree('18293abcd72', true, callback); //recursive tree

ghrepo.destroy();

ghrepo.statuses('master', callback); //array of statuses

ghrepo.combinedStatus('master', callback); //array of statuses

ghrepo.status('18e129c213848c7f239b93fe5c67971a64f183ff', {
  "state": "success",
  "target_url": "http://ci.mycompany.com/job/hub/3",
  "description": "Build success."
}, callback); // created status

ghnotification.markAsRead(callback);

ghnotification.subscribe(callback);

ghnotification.unsubscribe(callback);

ghnotification.mute(callback);

ghorg.info(callback); //json

ghorg.update({
  blog: 'https://blog.com'
}, callback); // org

This query supports pagination.

ghorg.repos(callback); //array of repos

ghorg.repo({
  name: 'Hello-world',
  description: 'My first world program'
}, callback); //repo

This query supports pagination.

ghorg.teams(callback); //array of teams

This query supports pagination.

ghorg.members(callback); //array of  users

ghorg.member('pksunkara', callback); //boolean

ghorg.publicMember('pksunkara', callback); //boolean

ghorg.publicizeMembership('pksunkara', callback);

ghorg.concealMembership('pksunkara', callback);

ghorg.membership('pksunkara', callback); //membership status object indicating state, role, etc.

ghorg.createTeam({
  "name": "new team name",
  "permission": "push",
  "repo_names": [
    "flatiron/utile"
   ]
}, callback);

This query supports pagination.

ghorg.hooks(callback); //array of hooks

ghorg.hook({
  "name": "web",
  "active": true,
  "events": ["push", "pull_request"],
  "config": {
    "url": "http://myawesomesite.com//events"
  }
}, callback); // hook

ghorg.deleteHook(37, callback);

ghissue.info(callback); //issue

ghissue.update({
  "title": "Found a bug and I am serious",
}, callback); //issue

This query supports pagination.

ghissue.comments(callback); //array of comments

ghissue.createComment({
  body: 'Me too.'
}, callback);

ghissue.updateComment(3, {
  body: 'The updated body of the comment.'
}, callback);

ghissue.deleteComment(3, callback);

ghissue.labels(callback);

ghissue.addLabels(['label-name'], callback);

ghissue.replaceAllLabels(['label-name'], callback);

ghissue.removeLabel('label-name', callback);

ghissue.removeAllLabels(callback);

ghmilestone.info(callback); //milestone

ghmilestone.update({
  "title": "Updated milestone title",
}, callback); //milestone

ghmilestone.delete(callback); //milestone

ghproject.info(callback); //project

ghproject.update({
  "name": "Updated project name",
}, callback); //project

ghproject.delete(callback); //project

ghlabel.info(callback); //label

ghlabel.update({
  "color": "000000",
}, callback); //label

ghlabel.delete(callback); //label

ghrepo.merge({ base: baseBranch, head: destinationBranch }, callback);

ghpr.info(callback); //pull request

ghpr.update({
  'title': 'Wow this pr'
}, callback); //pull request

ghpr.close(callback); //pull request

ghpr.merged(callback); //boolean

ghpr.commits(callback); //array of commits

ghpr.comments(callback); //array of comments

ghpr.createComment({
  body: 'my comment',
  commit_id: '8cde3b6c5be2c3067cd87ee4117c0f65e30f3e1f', // needed to comment on current time in PR
  path: 'file.txt', // optional
  position: 4 // optional
}, callback);

ghpr.removecomment(104, callback);

ghpr.files(callback); //array of files

ghpr.reviews(callback); //array of pull request reviews

ghpr.review(104, callback); //pull request review

ghpr.removeReview(104, callback); //pull request review

ghpr.reviewComments(104, callback); //array of review comments

ghpr.createReview({
  body: 'review message', // optional
  comments: [ // optional
    {
      body: 'comment message', // required for each optional comment
      path: 'file.txt', // required for each optional comment
      position: 4 // required for each optional comment
    }
  ],
  event: 'APPROVE || COMMENT || REQUEST_CHANGES' // optional
}, callback); //pull request review

ghpr.submitReview(104, {
  body: 'review message', // optional
  event: 'APPROVE || COMMENT || REQUEST_CHANGES' // required
}, callback); //pull request review

ghpr.dismissReview(104, 'dismissal message', callback); //pull request review

ghpr.reviewRequests(callback); //array of review requests

ghpr.createReviewRequests(['user1', 'user2'], callback); //pull request

ghpr.removeReviewRequests(['user1', 'user2'], callback); //pull request

ghrepo.release({
  tag_name: 'v1.0.0',
  draft: true
}, callback);

var archive = fs.readFileSync(__dirname, 'archive-v0.0.1.zip');
// Will upload a file with the default options
/*
{
  name: 'archive.zip',
  contentType: 'application/zip',
  uploadHost: 'uploads..com'
}
*/
ghrelease.uploadAssets(archive, callback);

// Will upload a file with your custom options
var image = fs.readFileSync(__dirname, 'octonode.png');
var options = {
  name: 'octonode.png',
  contentType: 'image/png',
  uploadHost: 'uploads..com'
};
ghrelease.uploadAssets(image, options, callback)

This query supports pagination.

ghgist.list(callback); //array of gists

This query supports pagination.

ghgist.public(callback); //array of gists

This query supports pagination.

ghgist.starred(callback); //array of gists

This query supports pagination.

ghgist.user('pksunkara', callback); //array of gists

ghgist.get(37, callback); //gist

ghgist.create({
  description: "the description",
  files: { ... }
}), callback); //gist

ghgist.edit(37, {
  description: "hello gist"
}, callback); //gist

ghgist.delete(37);

ghgist.fork(37, callback); //gist

ghgist.star(37);

ghgist.unstar(37);

ghgist.check(37); //boolean

ghgist.comments(37, callback); //array of comments

ghgist.comments(37, {
  body: "Just commenting"
}, callback); //comment

ghgist.comment(1, callback); //comment

ghgist.comment(1, {
  body: "lol at commenting"
}, callback); //comment

ghgist.comment(1);

ghteam.info(callback); //json

ghteam.members(callback); //array of  users

ghteam.member('pksunkara', callback); //boolean

ghteam.addUser("pksunkara", callback); //boolean

ghteam.removeUser("pksunkara", callback); //boolean

ghteam.membership("pksunkara", callback); //boolean

ghteam.addMembership("pksunkara", callback); //boolean

ghteam.removeMembership("pksunkara", callback); //boolean

ghteam.repos(callback); //array of repos

ghteam.removeRepo("flatiron/hub", callback);

ghteam.destroy(callback);

ghsearch.issues({
  q: 'windows+state:open+repo:pksunkara/hub',
  sort: 'created',
  order: 'asc'
}, callback); //array of search results

ghsearch.repos({
  q: 'hub+language:go',
  sort: 'created',
  order: 'asc'
}, callback); //array of search results

ghsearch.users({
  q: 'tom+followers:>100',
  sort: 'created',
  order: 'asc'
}, callback); //array of search results

ghsearch.code({
  q: 'auth+in:file+repo:pksunkara/hub',
  sort: 'created',
  order: 'asc'
}, callback); //array of search results

This query supports pagination.

Note: For listing all Organizations / Users pagination is powered exclusively by the since parameter ( APIs ) . since denotes the login ID of last org / user you encountered. Also, note that it's important to pass true as third param when using pagination.

Organizations

  var client = .client();
  client.get('/organizations', callback);
  // OR
  client.get('/organizations', since, per_page, true, callback);

Users

  var client = .client();
  client.get('/users', callback);
  // OR
  client.get('/users', since, per_page, true, callback);

Before run test copy the config.example.json file in test folder to config.json and populate it with your information.

Is suggested to fork https://.com/octocat/Spoon-Knife repo and run test on your copy.

npm test

If you like this project, please watch this and follow me.

Here is a list of Contributors

The following method names use underscore as an example. The library contains camel cased method names.

// public repos for unauthenticated, private and public for authenticated
me.get_watched_repositories(callback);
me.is_watching('repo', callback);
me.start_watching('repo', callback);
me.stop_watching('repo', callback);

// organization data
var org = octonode.Organization('bulletjs');

org.update(dict_with_update_properties, callback);
org.get_public_members(callback);
org.is_public_member('user', callback);
org.make_member_public('user', callback);
org.conceal_member('user', callback);

org.get_team('team', callback);
org.create_team({name:'', repo_names:'', permission:''}, callback);
org.edit_team({name:'', permission:''}, callback);
org.delete_team('name', callback);
org.get_team_members('team', callback);
org.get_team_member('team', 'user', callback);
org.remove_member_from_team('user', 'team', callback);
org.get_repositories(callback);
org.create_repository({name: ''}, callback);
org.get_team_repositories('team', callback);
org.get_team_repository('team', 'name', callback);
org.add_team_repository('team', 'name', callback);
org.remove_team_repository('team', 'name', callback);

var repo = octonode.Repository('pksunkara/octonode');

repo.update({name: ''}, callback);

// collaborator information
repo.add_collaborator('name', callback);
repo.remove_collaborator('name', callback);

// commit data
repo.get_commit('sha-id', callback);
repo.get_all_comments(callback);
repo.get_commit_comments('SHA ID', callback);
repo.comment_on_commit({body: '', commit_id: '', line: '', path: '', position: ''}, callback);
repo.get_single_comment('comment id', callback);
repo.edit_single_comment('comment id', callback);
repo.delete_single_comment('comment id', callback);

// downloads
repo.get_downloads(callback);
repo.get_download(callback);
repo.create_download({name: ''}, 'filepath', callback);
repo.delete_download(callback);

// keys
repo.get_deploy_keys(callback);
repo.get_deploy_key('id', callback);
repo.create_deploy_key({title: '', key: ''}, callback);
repo.edit_deploy_key({title: '', key: ''}, callback);
repo.delete_deploy_key('id', callback);

// watcher data
repo.get_watchers(callback);

// pull requests
repo.get_all_pull_request_comments(callback);
repo.get_pull_request_comment('id', callback);
repo.reply_to_pull_request_comment('id', 'body', callback);
repo.edit_pull_request_comment('id', 'body', callback);
repo.get_issues(params, callback);
repo.get_issue('id', callback);
repo.create_issue({title: ''}, callback);
repo.edit_issue({title: ''}, callback);
repo.get_issue_comments('issue', callback);
repo.get_issue_comment('id', callback);
repo.create_issue_comment('id', 'comment', callback);
repo.edit_issue_comment('id', 'comment', callback);
repo.delete_issue_comment('id', callback);
repo.get_issue_events('id', callback);
repo.get_events(callback);
repo.get_event('id', callback);
repo.get_labels(callback);
repo.get_label('id', callback);
repo.create_label('name', 'color', callback);
repo.edit_label('name', 'color', callback);
repo.delete_label('id', callback);
repo.get_labels_for_milestone_issues('milestone', callback);
repo.get_milestones(callback);
repo.get_milestone('id', callback);
repo.create_milestone('title', callback);
repo.edit_milestone('title', callback);
repo.delete_milestone('id', callback);

// raw git access
repo.create_blob('content', 'encoding', callback);
repo.get_commit('sha-id', callback);
repo.create_commit('message', 'tree', [parents], callback);
repo.get_reference('ref', callback);
repo.get_all_references(callback);
repo.update_reference('ref', 'sha', force, callback);

Name		Name	Last commit message	Last commit date
Latest commit History 586 Commits
./workflows		./workflows
lib		lib
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json

Repository files navigation

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors 99

Uh oh!

Languages

pksunkara/octonode

Folders and files

Latest commit

History

Repository files navigation

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors 99

Uh oh!

Languages

Packages