@kgryte/github-get NPM

Github Get

Retrieves resources from a Github API endpoint.

Installation

$ npm install @kgryte/github-get

Usage

var request = require( '@kgryte/github-get' );

request( options, clbk )

Retrieves resources from a Github API endpoint.

request( onResponse );

function onResponse( error, data, info ) {
	// Check for rate limit info...
	if ( info ) {
		console.error( 'Limit: %d', info.limit );
		console.error( 'Remaining: %d', info.remaining );
		console.error( 'Reset: %s', (new Date( info.reset*1000 )).toISOString() );
	}
	if ( error ) {
		throw error;
	}
	console.log( JSON.stringify( data ) );
	// returns <response_data>
}

The function accepts the following options:

protocol: request protocol. Default: 'https'.
hostname: endpoint hostname. Default: 'api.github.com'.
port: endpoint port. Default: 443 (https) or 80 (http).
pathname: resource pathname; e.g., /user/repos. Default: '/'.
page: resource page. Default: 1.
last_page: last resource page. If provided, the function will use link headers to resolve all pages starting from page. Default: 1.
per_page: page size. Default: 100.
query: params portion of a query string; e.g., beep=boop&a=b. This should not include page or per_page query params. Default: ''.
token: Github access token.
accept: media type. Default: 'application/vnd.github.moondragon+json'.
useragent: user agent string.

To specify a particular resource endpoint, set the pathname option.

var opts = {
	'pathname': '/user/repos'
};

request( opts, onResponse );

To authenticate with an endpoint, set the token option.

var opts = {
	'token': 'tkjorjk34ek3nj4!'
};

request( opts, onResponse );

By default, the function only requests a single page of results. To resolve multiple pages, set the last_page option.

// Resolves pages 2-5...
var opts = {
	'page': 2,
	'last_page': 5
};

request( opts, onResponse );

To specify that all pages beginning from page be resolved, set the last_page option to 'last'.

// Resolve all pages...
var opts = {
	'last_page': 'last'
};

request( opts, onResponse );

To specify a user agent, set the useragent option.

var opts = {
	'useragent': 'hello-github!'
};

request( opts, onResponse );

request.factory( options, clbk )

Creates a reusable function.

var opts = {
	'pathname': '/user/repos',
	'last_page': 'last',
	'token': 'tkjorjk34ek3nj4!'
};

var get = request.factory( opts, onResponse );

get();
get();
get();
// ...

The factory method accepts the same options as request().

Notes

If the module encounters an application-level error while initially querying an endpoint (e.g., no network connection, malformed request, etc), that error is returned immediately to the provided callback.
Response data will either be an object or an object array. If multiple pages are resolved, response data is always an object array.

The `function` will honor the `last_page` option as long as the option value does __not__ exceed the maximum number of available [pages][github-pagination].

Rate limit information includes the following:
- limit: maximum number of requests a consumer is permitted to make per hour.
- remaining: number of remaining requests.
- reset: time at which the current rate limit window resets in UTC seconds.

Examples

var request = require( '@kgryte/github-get' );

var opts = {
	'hostname': 'api.github.com',
	'pathname': '/user/repos',
	'useragent': 'my-unique-agent',
	'accept': 'application/vnd.github.moondragon+json',
	'token': 'tkjorjk34ek3nj4!',
	'last_page': 'last'
};

request( opts, onResponse );

function onResponse( error, data, info ) {
	if ( info ) {
		console.error( info );
	}
	if ( error ) {
		throw error;
	}
	console.log( data );
}

To run the example code from the top-level application directory,

$ DEBUG=* node ./examples/index.js

Note: in order to run the example, you will need to obtain an access token and modify the token option accordingly.

CLI

Installation

To use the module as a general utility, install the module globally

$ npm install -g @kgryte/github-get

Usage

Usage: ghget [options] 

Options:

  -h,  --help               Print this message.
  -V,  --version            Print the package version.
       --protocol protocol  Request protocol. Default: https.
       --hostname host      Hostname. Default: api.github.com.
  -p,  --port port          Port. Default: 443 (https) or 80 (http).
       --pathname pathname  Resource pathname. Default: '/'.
       --token token        Github access token.
       --accept media_type  Media type. Default: application/vnd.github.v3+json.
  -ua, --useragent ua       User agent.
       --page page          Resource page. Default: 1.
       --last_page page     Last resource page to resolve. Default: 1.
       --per_page size      Page size. Default: 100.
  -qs, --query querystring  Params portion of a query string.

Notes

In addition to the token option, the token may also be specified by a GITHUB_TOKEN environment variable. The command-line option always takes precedence.
Request resources are written to stdout.
Rate limit information is written to stderr.

Examples

Setting the access token using the command-line option:

$ DEBUG=* ghget --token <token> --pathname '/user/repos'
# => '[{...},{...},...]'

Setting the access token using an environment variable:

$ DEBUG=* GITHUB_TOKEN=<token> ghget --pathname '/user/repos'
# => '[{...},{...},...]'

For local installations, modify the command to point to the local installation directory; e.g.,

$ DEBUG=* ./node_modules/.bin/ghget --token <token> --pathname '/user/repos'
# => '[{...},{...},...]'

Or, if you have cloned this repository and run npm install, modify the command to point to the executable; e.g.,

$ DEBUG=* node ./bin/cli --token <token> --pathname '/user/repos'
# => '[{...},{...},...]'

Tests

Unit

This repository uses tape for unit tests. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

Browser Support

This repository uses Testling for browser testing. To run the tests in a (headless) local web browser, execute the following command in the top-level application directory: