Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Octokat.js provides a minimal higher-level wrapper around GitHub's API. It is being developed in the context of github-bookeditor, an EPUB3 Textbook editor for GitHub.
This package can also be used in nodejs
or in the browser as an AMD module or using browserify.
nodejs
, an AMD module in the browser, and as a bower libraryETag
cachingFor the full list of supported methods see the Travis tests, the ./test directory, or ./src/grammar.coffee.
All asynchronous methods accept a Node.js-style callback and return a Common-JS Promise.
Create an Octokat instance.
var octo = new Octokat({
username: "USER_NAME",
password: "PASSWORD"
});
var cb = function (err, val) { console.log(val); };
octo.zen.read(cb);
octo.repos('philschatz', 'octokat.js').fetch(cb); // Fetch repo info
octo.me.starred('philschatz', 'octokat.js').add(cb); // Star a repo
Or if you prefer OAuth:
var octo = new Octokat({
token: "OAUTH_TOKEN"
});
define(['octokat'], function(Octokat) {
var octo = new Octokat({
username: "YOU_USER",
password: "YOUR_PASSWORD"
});
});
Install instructions:
npm install octokat --save
var Octokat = require('octokat');
var octo = new Octokat({
username: "YOU_USER",
password: "YOUR_PASSWORD"
});
var cb = function (err, val) { console.log(val); };
octo.zen.read(cb);
octo.repos('philschatz', 'octokat.js').fetch(cb); // Fetch repo info
octo.me.starred('philschatz', 'octokat.js').add(cb); // Star a repo
This requires Node.js 0.11 with the --harmony-generators
flag:
var co = require('co');
var Octokat = require('octokat');
var octo = new Octokat();
var fn = function *() {
var zen = yield octo.zen.read();
var info = yield octo.repos('philschatz', 'octokat.js').fetch();
console.log(zen);
console.log(info);
};
co(fn)();
This file can be included using the bower package manager:
bower install octokat --save
This is all you need to get up and running:
<script src="../dist/octokat.js"></script>
<script>
var octo = new Octokat();
octo.zen.read(function(err, message) {
if (err) { throw new Error(err); }
alert(message);
});
</script>
octokat.js
has the following optional dependencies when used in a browser:
If you are already using jQuery or AngularJS in your project just be sure to include them before Octokat and it will use their Promise API.
Otherwise, you can include a Promise polyfill like jakearchibald/es6-promise:
<script src="./node_modules/es6-promise/dist/promise-0.1.2.js"></script>
<script src="./octokat.js">
To use the APIs available for preview just add a acceptHeader
when instantiating Octokat.
For example:
var octo = new Octokat({
token: 'API_TOKEN'
acceptHeader: 'application/vnd.github.cannonball-preview+json'
});
To use the Enterprise APIs add the root URL when instantiating Octokat:
var octo = new Octokat({
token: 'API_TOKEN'
rootUrl: 'https://example.com/api/v3/'
});
npm test
will run the mocha tests for Node.js and the browser.
Additionally, they can be run in the browser by starting a web server
and going to ./test/index.html.
This library closely mirrors the https://developer.github.com/v3 documentation.
For example, GET /repos/:owner/:repo
becomes octo.repos(owner, repo).fetch()
and POST /repos/:owner/:repo/issues/:number/comments
becomes octo.repos(owner, repo).issues(number).comments.create(params)
.
This library supports Node.js-style callbacks as well as Promises.
To use a callback, just specify it as the last argument to a method. To use a Promise, do not specify a callback and the return value will be a Promise.
Example (get information on a repo):
# Using callbacks
octo.repos('philschatz', 'octokat.js').fetch (err, repo) ->
console.error(err) if err
# Do fancy stuff...
# Using Promises
octo.repos('philschatz', 'octokat.js').fetch()
.then (repo) ->
# Do fancy stuff
.then null, (err) -> console.error(err)
You construct the URL by chaining properties and methods together and an async call is made once a verb method is called (see below).
Example:
octo = new Octokat()
repo = octo.repos('philschatz', 'octokat.js')
# Check if the current user is a collaborator on a repo
repo.collaborators.contains(USER)
.then (isCollaborator) ->
# If not, then star the Repo
unless isCollaborator
repo.star.add()
.then () ->
# Done!
Or, update a specific comment:
octo = new Octokat(token: ...)
octo.repos('philschatz', 'octokat.js').issues(1).comments(123123).update(body: 'Hello')
.then () ->
# Done!
The basic structure of these methods is:
.foos.fetch({optionalStuff:...})
yields a list of items (possibly paginated).foos(id).fetch(...)
yields a single item (issue, repo, user).foos.contains(id)
tests membership in a list (yields true/false).foos.create(...)
creates a new foo
.foos(id).add()
adds an existing User/Repo to the list.foos(id).remove()
removes a member from a list or deletes the object and yields a boolean indicating successGitHub provides URL patterns in its JSON responses. These are automatically converted into methods. For example:
octo.repos('philschatz', 'octokat.js').fetch()
.then (repo) ->
# GitHub returns a JSON which contains something like compare_url: 'https://..../compare/{head}...{base}
# This is converted to a method that accepts 2 arguments
repo.compare(sha1, sha2).fetch()
.then (comparison) -> # Done!
If a .fetch()
returns paged results then nextPage()
, previousPage()
, firstPage()
and lastPage()
are added to the returned Object. For example:
octo.repos('philschatz', 'octokat.js').commits.fetch()
.then (someCommits) ->
someCommits.nextPage()
.then (moreCommits) ->
# Done!
npm install
grunt dist
to generate the files in the ./dist
directoryThe unit tests are named to illustrate examples of using the API.
See Travis tests or run npm test
to see them.
linkedin/sepia is used to generate recorded HTTP fixtures from GitHub and philschatz/sepia.js uses them in the browser. If you are adding tests be sure to include the updated fixtures in the Pull Request.
FAQs
Javascript GitHub client for NodeJS or a browser using promises or callbacks
The npm package octokat receives a total of 4,257 weekly downloads. As such, octokat popularity was classified as popular.
We found that octokat demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.