# github-base

> Low-level methods for working with the GitHub API in node.js/JavaScript.

Latest version **1.0.0** (published 2018-08-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install github-base
pnpm add github-base
yarn add github-base
bun add github-base
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2018-08-14 |
| First published | 2015-03-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=8 |
| Dependencies | 6 |
| Unpacked size | 28.5 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 59 |
| Author | Jon Schlinkert |
| Maintainers | doowb, jonschlinkert |
| Keywords | api, base, del, delete, get, github, paginate, paginated, patch, post, put, request |

## Links

- npm: https://www.npmjs.com/package/github-base
- Repository: https://github.com/jonschlinkert/github-base
- Issues: https://github.com/jonschlinkert/github-base/issues
- npm.io page: https://npm.io/package/github-base

## Dependencies (6)

- [qs](https://npm.io/package/qs.md) ^6.5.1
- [use](https://npm.io/package/use.md) ^3.1.0
- [needle](https://npm.io/package/needle.md) ^2.2.2
- [get-value](https://npm.io/package/get-value.md) ^3.0.1
- [paged-request](https://npm.io/package/paged-request.md) ^1.0.2
- [parse-link-header](https://npm.io/package/parse-link-header.md) ^1.0.1

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2018-08-14
- 0.5.4 — 2017-04-20
- 0.5.3 — 2017-04-20
- 0.5.2 — 2017-04-06
- 0.5.1 — 2016-09-11
- 0.5.0 — 2016-09-09
- 0.4.1 — 2016-02-02
- 0.4.0 — 2015-10-17
- 0.3.2 — 2015-10-15
- 0.3.1 — 2015-09-14
- 0.3.0 — 2015-09-14
- 0.2.3 — 2015-08-13
- 0.2.2 — 2015-08-11
- 0.2.1 — 2015-08-09
- 0.2.0 — 2015-08-09
- … 2 more at https://npm.io/package/github-base/versions

## README

# github-base [![NPM version](https://img.shields.io/npm/v/github-base.svg?style=flat)](https://www.npmjs.com/package/github-base) [![NPM monthly downloads](https://img.shields.io/npm/dm/github-base.svg?style=flat)](https://npmjs.org/package/github-base) [![NPM total downloads](https://img.shields.io/npm/dt/github-base.svg?style=flat)](https://npmjs.org/package/github-base) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/github-base.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/github-base) [![Windows Build Status](https://img.shields.io/appveyor/ci/jonschlinkert/github-base.svg?style=flat&label=AppVeyor)](https://ci.appveyor.com/project/jonschlinkert/github-base)

> Low-level methods for working with the GitHub API in node.js/JavaScript.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Table of Contents

<details>
<summary><strong>Details</strong></summary>

- [Install](#install)
- [Heads up!](#heads-up)
- [Why github-base, instead of...?](#why-github-base-instead-of)
- [Usage](#usage)
- [API](#api)
  * [GitHub](#github)
  * [.request](#request)
  * [.get](#get)
  * [.delete](#delete)
  * [.patch](#patch)
  * [.post](#post)
  * [.put](#put)
  * [.paged](#paged)
  * [.use](#use)
- [Authentication](#authentication)
- [Paths and placeholders](#paths-and-placeholders)
- [Options](#options)
  * [options.query](#optionsquery)
- [About](#about)
  * [Related projects](#related-projects)
  * [Contributors](#contributors)
  * [Author](#author)
  * [License](#license)

_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_

</details>

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save github-base
```

## 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('github-base');
```

**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)_.

### [GitHub](index.js#L18)

Create an instance of `GitHub` with the given options.

**Params**

* `options` **{Object}**

**Example**

```js
const GitHub = require('github-base');
const github = new GitHub([options]);
```

### [.request](index.js#L42)

Uses [needle](https://github.com/tomas/needle) to make a request to the GitHub API. Supports the following verbs: `GET`, `PUT`, `POST`, `PATCH`, and `DELETE`. Takes a callback or returns a promise.

**Params**

* `method` **{String}**: The http VERB to use
* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).

**Example**

```js
// list all orgs for the authenticated user
const auth = require('./local-private-auth-info');
const github = new GitHub(auth);
github.request('GET', '/user/orgs')
  .then(res => console.log(res.body));
```

### [.get](index.js#L64)

Make a `GET` request to the GitHub API.

**Params**

* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).

**Example**

```js
// get a list of orgs for the authenticated user
github.get('/user/orgs')
  .then(res => console.log(res.body));

// get gists for the authenticated user
github.get('/gists')
  .then(res => console.log(res.body));
```

### [.delete](index.js#L84)

Make a `DELETE` request to the GitHub API.

**Params**

* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).

**Example**

```js
// un-follow someone
github.delete('/user/following/:some_username', { some_username: 'whatever' })
  .then(res => {
    console.log('RESPONSE:', res);
  });
```

### [.patch](index.js#L106)

Make a `PATCH` request to the GitHub API.

**Params**

* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).

**Example**

```js
// update a gist
const fs = require('fs');
const options = { files: { 'readme.md': { content: fs.readFileSync('README.md', 'utf8') } } };
github.patch('/gists/bd139161a425896f35f8', options)
  .then(res => {
    console.log('RESPONSE:', res);
  });
```

### [.post](index.js#L126)

Make a `POST` request to the GitHub API.

**Params**

* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).

**Example**

```js
// create a new repository
github.post('/user/repos', { name: 'new-repo-name' })
  .then(res => {
    console.log('RESPONSE:', res);
  });
```

### [.put](index.js#L146)

Make a `PUT` request to the GitHub API.

**Params**

* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).

**Example**

```js
// follow someone
github.put('/user/following/jonschlinkert')
  .then(res => {
    console.log('RESPONSE:', res);
  });
```

### [.paged](index.js#L165)

Recursively make GET requests until all pages of records are returned.

**Params**

* `path` **{String}**: The path to append to the base GitHub API URL.
* `options` **{Options}**: Request [options](#options).

**Example**

```js
// get all repos for the authenticated user
github.paged('/user/repos?type=all&per_page=1000&sort=updated')
  .then(res => console.log(res.pages))
  .catch(console.error)
```

### .use

Register plugins with [use](https://github.com/jonschlinkert/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](https://github.com/ljharb/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);
  });
```

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [gists](https://www.npmjs.com/package/gists): Methods for working with the GitHub Gist API. Node.js/JavaScript | [homepage](https://github.com/jonschlinkert/gists "Methods for working with the GitHub Gist API. Node.js/JavaScript")
* [github-contributors](https://www.npmjs.com/package/github-contributors): Generate a markdown or JSON list of contributors for a project using the GitHub API. | [homepage](https://github.com/jonschlinkert/github-contributors "Generate a markdown or JSON list of contributors for a project using the GitHub API.")
* [repos](https://www.npmjs.com/package/repos): List all repositories for one or more users or orgs. | [homepage](https://github.com/jonschlinkert/repos "List all repositories for one or more users or orgs.")
* [topics](https://www.npmjs.com/package/topics): Get and update GitHub repository topics. | [homepage](https://github.com/jonschlinkert/topics "Get and update GitHub repository topics.")

### Contributors

| **Commits** | **Contributor** | 
| --- | --- |
| 40 | [jonschlinkert](https://github.com/jonschlinkert) |
| 10 | [doowb](https://github.com/doowb) |
| 7 | [olstenlarck](https://github.com/olstenlarck) |

### Author

**Jon Schlinkert**

* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

### License

Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on August 14, 2018._

---
_Source: https://npm.io/package/github-base · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._