GithubHelp home page GithubHelp logo

octonode's Introduction

octonode

octonode is a library for nodejs to access the github v3 api

Installation

npm install octonode

Usage

var github = require('octonode');

// Then we instanciate 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 ghgist = client.gist();
var ghteam = client.team(37);

var ghsearch = client.search();

Build a client which accesses any public information

var client = github.client();

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

Build a client from an access token

var client = github.client('someaccesstoken');

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

Build a client from credentials

var client = github.client({
  username: 'pksunkara',
  password: 'password'
});

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

Build a client from client keys

var client = github.client({
  id: 'abcdefghijklmno',
  secret: 'abcdefghijk'
});

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

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

Authentication

Authenticate to github in cli mode (desktop application)

github.auth.config({
  username: 'pksunkara',
  password: 'password'
}).login(['user', 'repo', 'gist'], function (err, id, token) {
  console.log(id, token);
});

Revoke authentication to github in cli mode (desktop application)

github.auth.config({
  username: 'pksunkara',
  password: 'password'
}).revoke(id, function (err) {
  if (err) throw err;
});

Authenticate to github in web mode (web application)

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

// Build the authorization config and url
var auth_url = github.auth.config({
  id: 'mygithubclientid',
  secret: 'mygithubclientsecret'
}).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 github login
  if (uri.pathname=='/login') {
    res.writeHead(301, {'Content-Type': 'text/plain', 'Location': auth_url})
    res.end('Redirecting to ' + auth_url);
  }
  // Callback url from github 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 {
      github.auth.login(values.code, function (err, token) {
        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');

Rate Limiting

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

client.limit(function (err, left, max) {
  console.log(left); // 4999
  console.log(max);  // 5000
});

API Callback Structure

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

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

Github authenticated user api

Token/Credentials required for the following:

Get information about the user (GET /user)

ghme.info(callback); //json

Update user profile (PATCH /user)

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

Get emails of the user (GET /user/emails)

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

Set emails of the user (POST /user/emails)

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

Delete emails of the user (DELETE /user/emails)

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

Get the followers of the user (GET /user/followers)

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

Get users whom the user is following (GET /user/following)

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

Check if the user is following a user (GET /user/following/marak)

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

Follow a user (PUT /user/following/marak)

ghme.follow('marak');

Unfollow a user (DELETE /user/following/marak)

ghme.unfollow('marak');

Get public keys of a user (GET /user/keys)

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

Get a single public key (GET /user/keys/1)

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

Create a public key (POST /user/keys)

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

Update a public key (PATCH /user/keys/1)

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

Delete a public key (DELETE /user/keys/1)

ghme.keys(1);

List your public and private organizations (GET /user/orgs)

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

List your repositories (GET /user/repos)

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

Create a repository (POST /user/repos)

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

Fork a repository (POST /repos/pksunkara/hub/forks)

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

Github users api

No token required for the following

Get information about an user (GET /users/pksunkara)

ghuser.info(callback); //json

Get an user followers (GET /users/pksunkara/followers)

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

Get an user followings (GET /users/pksunkara/following)

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

Github repositories api

Get information about a repository (GET /repos/pksunkara/hub)

ghrepo.info(callback); //json

Get the commits for a repository (GET /repos/pkumar/hub/commits)

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

Get the tags for a repository (GET /repos/pksunkara/hub/tags)

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

Get the languages for a repository (GET /repos/pksunkara/hub/languages)

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

Get the contributors for a repository (GET /repos/pksunkara/hub/contributors)

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

Get the branches for a repository (GET /repos/pksunkara/hub/branches)

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

Get the issues for a repository (GET /repos/pksunkara/hub/issues)

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

Get the README for a repository (GET /repos/pksunkara/hub/readme)

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

Get the contents of a path in repository

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

Get archive link for a repository

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

Get the blob for a repository (GET /repos/pksunkara/hub/git/blobs/SHA)

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

Get users who starred a repository (GET /repos/pksunkara/hub/stargazers)

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

Get the teams for a repository (GET /repos/pksunkara/hub/teams)

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

Get a git tree (GET /repos/pksunkara/hub/git/trees/18293abcd72)

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

Delete the repository (DELETE /repos/pksunkara/hub)

ghrepo.destroy();

List statuses for a specific ref (GET /repos/pksunkara/hub/statuses/master)

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

Create status (POST /repos/pksunkara/hub/statuses/SHA)

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

Github organizations api

Get information about an organization (GET /orgs/flatiron)

ghorg.info(callback); //json

Update an organization (POST /orgs/flatiron)

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

List organization repositories (GET /orgs/flatiron/repos)

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

Create an organization repository (POST /orgs/flatiron/repos)

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

Get an organization's teams (GET /orgs/flatiron/teams)

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

Get an organization's members (GET /orgs/flatiron/members)

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

Check an organization member (GET /orgs/flatiron/members/pksunkara)

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

Github gists api

List authenticated user's gists (GET /gists)

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

List authenticated user's public gists (GET /gists/public)

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

List authenticated user's starred gists (GET /gists/starred)

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

List a user's public gists (GET /users/pksunkara/gists)

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

Get a single gist (GET /gists/37)

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

Create a gist (POST /gists)

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

Edit a gist (PATCH /gists/37)

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

Delete a gist (DELETE /gists/37)

ghgist.delete(37);

Fork a gist (POST /gists/37/forks)

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

Star a gist (PUT /gists/37/star)

ghgist.star(37);

Unstar a gist (DELETE /gists/37/unstar)

ghgist.unstar(37);

Check if a gist is starred (GET /gists/37/star)

ghgist.check(37); //boolean

List comments on a gist (GET /gists/37/comments)

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

Create a comment (POST /gists/37/comments)

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

Get a single comment (GET /gists/comments/1)

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

Edit a comment (POST /gists/comments/1)

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

Delete a comment (DELETE /gists/comments/1)

ghgist.comment(1);

Github teams api

Get a team (GET /team/37)

ghteam.info(callback); //json

Get the team members (GET /team/37/members)

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

Check if a user is part of the team (GET /team/37/members/pksunkara)

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

Github search api

Search issues

ghsearch.issues('pksunkara/hub', 'open', 'git', callback); //array of issues

Search repositories

ghsearch.repos('git', 'javascript', 1, callback); //array of repositories

Search users

ghsearch.users('git', callback); //array of users

Search emails

ghsearch.emails('[email protected]', callback); //user

Testing

npm test

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

Contributors

Here is a list of Contributors

TODO

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);
me.get_issues(params, callback);

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

org.update(dict_with_update_properties, callback);
org.add_member('user', 'team', callback);
org.remove_member('user', 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.has_collaborator('name', callback);
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.create_pull_request_comment('id', {body:'', commit_id:'', path:'', position:''}, callback);
repo.reply_to_pull_request_comment('id', 'body', callback);
repo.edit_pull_request_comment('id', 'body', callback);
repo.delete_pull_request_comment('id', 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_issue_labels('issue', callback);
repo.add_labels_to_issue('issue', ['label1', 'label2'], callback);
repo.remove_label_from_issue('issue', 'labelid', callback);
repo.set_labels_for_issue('issue', ['label1', 'label2'], callback);
repo.remove_all_labels_from_issue('issue', 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.create_reference('ref', 'sha', callback);
repo.update_reference('ref', 'sha', force, callback);

I accept pull requests and guarantee a reply back within a day

License

MIT/X11

Bug Reports

Report here. Guaranteed reply within a day.

Contact

Pavan Kumar Sunkara ([email protected])

Follow me on github, twitter

octonode's People

Contributors

avvs avatar booo avatar edufelipe avatar gregberge avatar iamwilhelm avatar indexzero avatar joefiorini avatar joeframbach avatar ksato9700 avatar mwawrusch avatar naholyr avatar pksunkara avatar podviaznikov avatar swsnr avatar yanghua avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.