## Heads up!

As of v1.0, the API is 100% promise based, callbacks are no longer supported. Please see the [API documentation](#API) and [release history](changelog.md) for more details.

## Why github-base, instead of...?

Every other GitHub API library we found either had a [huge dependency tree](https://github.com/sindresorhus/gh-got), tries to be [everything to everyone](https://github.com/michael/github/blob/master/package.json#L45-L56), was [too bloated with boilerplace code](https://github.com/mikedeboer/node-github/tree/master/templates), was too opinionated, or was not maintained.  

We created github-base to provide low-level support for a handful of HTTP verbs for creating higher-level libraries:

- [.request](#request): the base handler all of the GitHub HTTP verbs: `GET`, `PUT`, `POST`, `DELETE`, `PATCH`
- [.get](#get): proxy for `.request('GET', path, options, cb)`
- [.delete](#delete): proxy for `.request('DELETE', path, options, cb)`
- [.patch](#patch): proxy for `.request('PATCH', path, options, cb)`
- [.post](#post): proxy for `.request('POST', path, options, cb)`
- [.put](#put): proxy for `.request('PUT', path, options, cb)`
- [.paged](#paged): recursively makes `GET` requests until all pages have been retrieved.

Jump to the [API section](#API) for more details.

## Usage

Add github-base to your node.js/JavaScript project with the following line of code:

```js
const GitHub = require('{%= name %}');
```

**Example usage**

Recursively `GET` all pages of gists for a user:

```js
const github = new GitHub({ /* options */ });
const owner = 'jonschlinkert';

github.paged(`/users/${owner}/gists`)
  .then(res => console.log(res))
  .catch(console.error);
```

## API

_(All request methods take a callback, or return a promise if a callback isn't passed as the last argument)_.

{%= apidocs("index.js") %}


### .use

Register plugins with [use][].

```js
const github = new GitHub();

github.use(function() {
  // do stuff with the github-base instance
});
```

## Authentication

There are a few ways to authenticate, all of them require info to be passed on the [options](#options).

```js
const github = new GitHub({
  username: YOUR_USERNAME,
  password: YOUR_PASSWORD,
});

// or 
const github = new GitHub({
  token: YOUR_TOKEN
});

// or 
const github = new GitHub({
  bearer: YOUR_JSON_WEB_TOKEN
});
```

## Paths and placeholders

**Deprecated**: Since es2015 templates make this feature less useful, we plan to remove it in a future release. 

Paths are similar to router paths, where placeholders in the given string are replaced with values from the options. For instance, the path in the following example:

```js
const github = new GitHub();
const options = { user: 'jonschlinkert', repo: 'github-base', subscribed: true };

github.put('/repos/:user/:repo/subscription', options);
```

Expands to:

```js
'/repos/jonschlinkert/github-base/subscription'
```

Placeholder names are also arbitrary, you can make them whatever you want as long as all placeholder names can be resolved using values defined on the options.

## Options

Options may be passed to the constructor when instantiating, and/or set on the instance directly, and/or passed to any of the methods. 

**Examples**

```js
// pass to constructor
const github = new GitHub({ user: 'doowb' });

// and/or directly set on instance options
github.options.user = 'doowb';

// and/or pass to a method
github.get('/users/:user/gists', { user: 'doowb' })
```

### options.query

**Type**: `object`

**Default**: `{ per_page: 100 }` for [get](#get) and [paged](#paged) requests, `undefined` for all other requests.

Pass an object to stringify and append to the URL using the `.stringify` method from [qs][].

**Examples**

```js
github.paged('/users/:user/gists', { user: 'doowb', query: { per_page: 30 } })
  .then(res => {
    console.log(res.pages);
  });
```

You can also manually append the query string:

```js
github.paged('/users/:user/gists?per_page=30', { user: 'doowb' })
  .then(res => {
    console.log(res.pages);
  });
```