hubkit

hubkit

A simple GitHub API library for JavaScript that works in both NodeJS and the browser. Features:

• Takes a request-level approach that naturally covers the entire GitHub v3 API.
• All requests return promises. (You need to include a promise polyfill or run node with --harmony.)
• Responses are (optionally) cached, and requests are conditional to save on bandwidth and request quota. Inspired by simple-github, octo, and octokit.

To enable caching, make sure that LRUCache is loaded. Either npm install lru-cache --save (for NodeJS), or load lru-cache.js into the browser. Or you can pass any other cache instance as an option to the constructor, as long as it has get and set methods.

A simple example:

var gh = new Hubkit({
  token: '123456890ABCDEF',
  owner: 'pkaminski',
  repo: 'hubkit'
});
gh.request('GET /repos/:owner/:repo/commits').then(console.log);
gh.request('GET /repos/:owner/:repo/git/commits/:sha', {sha: '09876abc'}).then(console.log);
gh.request('POST /repose/{owner}/{repo}/pulls', {body: {title: 'foo', head: 'bar', base: 'master'}});

You issue requests exactly as documented in GitHub's API. Path segments of the form :foo or {foo} are interpolated from the options object passed as the second argument and defaulting to the options object passed to the constructor. The method can be specified either together with the path, or as a {method: 'GET'} option (the inline one takes precedence, and GET is the default if nothing else is found).

There are two ways to authenticate: either pass a token to the options, or both a username and password. Unauthenticated requests are fine too, of course.

Every call returns a Promise, which you might need to polyfill if your target environment doesn't support it natively. You can then use the standard then API to specify both success and failure callbacks, or in Node it integrates nicely with co, so you can do something like:

co(function*() {
  var commits = yield gh.request('GET /repose/:owner/:repo/commits');
})();

The returned values are exactly as documented in the GitHub API, except that requests with option {boolean: true} will return true or false instead (sorry, no way to automate it). Note that for paged responses, all pages will be concatenated together into the return value by default (see below).

After every request, you can access Hubkit.rateLimit and Hubkit.rateLimitRemaining for the latest information on your GitHub quotas, and Hubkit.oAuthScopes to see what scopes your authorization entitles you to.

Valid options to pass (to the constructor or to each request) include:

• token: String token to use for authentication; takes precedence over username and password.
• username and password: For basic authentication.
• userAgent: The user-agent to present in requests. Uses the browser's user agent, or Hubkit in NodeJS.
• host: The hostname to prepend to all request paths; defaults to https://api.github.com.
• cache: An object with get and set methods to be used as a cache for responses. The objects inserted into the cache will be of the form {value: {...}, eTag: 'abc123', status: 200, size: 1763}. You can use the (approximate) size field to help your cache determine when to evict items. The default cache is set to hold ~500K.
• method: The HTTP method to use for the request.
• media: A GitHub-specific media type for the response content. Valid values are:
  • for comment bodies: raw+json (default), text+json, html+json, full+json
  • for blobs: json (default), raw
  • for commits, etc.: diff, patch
• body: The contents of the request to send, typically a JSON-friendly object.
• perPage: The number of items to return per page of response. Defaults to 100.
• allPages: Whether to automatically fetch all pages by following the next links and concatenate the results before returning them. Defaults to true. If set to false and a result has more pages, you'll find a next() function on the result that you can call to get a promise with the next page of items.