jonschlinkert / gists

Methods for working with the GitHub Gist API. Node.js/JavaScript

gists

Methods for working with the GitHub Gist API. Node.js/JavaScript

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.

Install

Install with npm:

$ npm install --save gists

Full support for:

• Gist API
• Gist Comments API

(If you find something missing or encounter a bug, please create an issue. Thanks!)

Heads up!

Breaking changes in v2.0!!!

Please read the CHANGELOG for more details.

Usage

Add gists to your node.js/JavaScript project with the following code:

const Gists = require('gists');
const gists = new Gists({
  username: 'your_username', 
  password: 'your_password'
});

// EXAMPLE: Download the Markdown Cheatsheet gist.
gists.get('5854601')
  .then(res => console.log(res))
  .catch(console.error)

API

See the GitHub Gist API documentation for additional details and input options for each method.

Gists

The main export is the Gists class. Start by creating an instance of Gists.

Params

• options {Object}

Example

// see github-base for all available options and other ways to authenticate
const Gists = require('gists');
const gists = new Gists({ username: 'your_username', password: '*******' });

// all methods, when invoked, return a promise with this sigature
gists.get(...args)
  .then(res => console.log(res.body))
  .catch(console.error);

.create

Create a new gist (docs).

Params

• options {Object}: Options to pass to github-base.

Example

// POST /gists
gists.create(options);

.get

Get a gist (docs).

Params

• gist_id {String}: (required) The id of the gist to get.
• options {Object}: Options to pass to github-base.

Example

// GET /gists/:gist_id
gists.get(gist_id[, options]);

.list

List all gists for the given username (docs).

Params

• username {String}
• options {Object}: Options to pass to github-base.

Example

// GET /users/:username/gists
gists.list(username[, options]);

.all

List the authenticated user's gists, or if called anonymously get all public gists. (docs).

Params

• options {Object}: Options to pass to github-base.

Example

// GET /gists/
gists.all(options);

.public

List all public gists sorted by most recently updated to least recently updated (docs).

Params

• options {Object}: Options to pass to github-base.

Example

// GET /gists/public
gists.public(options);

.starred

List the authenticated user's starred gists (docs).

Params

• options {Object}: Options to pass to github-base.

Example

// GET /gists/starred
gists.starred(options);

.revision

Get a specific revision of a gist (docs).

Params

• gist_id {String}: (required) The id of the gist to get.
• sha {String}: (required) The sha of the gist revision to get.
• options {Object}: Options to pass to github-base.

Example

// GET /gists/:gist_id/:sha
gists.revision(gist_id, sha[, options]);

.commits

List commits for a gist (docs).

Params

• gist_id {String}: (required) The id of the gist to get commits for.
• options {Object}: Options to pass to github-base.

Example

// GET /gists/:gist_id/commits
gists.commit(gist_id[, options]);

.forks

List all forks for a gist (docs).

Params

• gist_id {String}: (required) The id of the gist to list forks for.
• options {Object}: Options to pass to github-base.

Example

// GET /gists/:gist_id/forks
gists.forks(gist_id[, options]);

.fork

Fork a gist (docs).

Params

• gist_id {String}: The id of the gist to fork.
• options {Object}: Options to pass to github-base.

Example

// POST /gists/:gist_id/forks
gists.fork(gist_id[, options]);

.edit

Edit a gist (docs).

Params

• gist_id {String}: (required) The id of the gist to edit.
• options {Object}: Options to pass to github-base.

Example

// PATCH /gists/:gist_id
gists.edit(gist_id[, options]);

.delete

Delete a gist (docs).

Params

• gist_id {String}: (required) The id of the gist to delete.
• options {Object}: Options to pass to github-base.

Example

// DELETE /gists/:gist_id
gists.delete(gist_id[, options]);

.star

Star a gist (docs).

Params

• gist_id {String}: (required) The id of the gist to star.
• options {Object}: Options to pass to github-base.

Example

// PUT /gists/:gist_id/star
gists.star(gist_id[, options]);

.unstar

Unstar a gist (docs).

Params

• gist_id {String}: (required) The id of the gist to unstar.
• options {Object}: Options to pass to github-base.

Example

// DELETE /gists/:gist_id/star
gists.unstar(gist_id[, options]);

.isStarred

Check if a gist is starred (docs).

Params

• gist_id {String}: (required) The id of the gist to check.
• options {Object}: Options to pass to github-base.
• returns {Boolean}: Returns true if a gist is starred.

Example

// GET /gists/:gist_id/star
gists.isStarred(gist_id[, options])

.comment

Create a comment on a gist (docs).

Params

• gist_id {String}: (required)
• options {Object}: Options to pass to github-base.

Example

// POST /gists/:gist_id/comments
gists.comment(gist_id, { body: 'Just commenting for the sake of commenting' });

.getComment

Get a single comment from a gist (docs).

Params

• gist_id {String}: (required)
• comment_id {String}: (required) The id of the comment to get.
• options {Object}: Options to pass to github-base.

Example

// GET /gists/:gist_id/comments/:comment_id
gists.getComment(gist_id, comment_id, options);

.listComments

List comments on a gist (docs).

Params

• gist_id {String}: (required)
• options {Object}: Options to pass to github-base.

Example

// GET /gists/:gist_id/comments
gists.listComments(options);

.edit

Edit a comment (docs).

Params

• gist_id {String}: (required)
• comment_id {String}: (required) The id of the comment to edit.
• options {Object}: Options to pass to github-base.

Example

// PATCH /gists/:gist_id/comments/:gist_id
gists.editComment(gist_id, comment_id[, options]);

.delete

Delete a comment (docs).

Params

• gist_id {String}: (required)
• comment_id {String}: (required) The id of the comment to edit.
• options {Object}: Options to pass to github-base.

Example

// DELETE /gists/:gist_id/comments/:comment_id
gists.deleteComment(gist_id, comment_id[, options]);

Release history

v2.0

• Decrecated .download in favor of .get. Start using .get now, as .download will be removed in the next major release.
• Decrecated .del in favor of .delete. Start using .delete now, as .del will be removed in the next major release.
• Upgraded github-base, which is now an ES6 class.

About

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Running Tests

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:

$ npm install && npm test

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

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

Related projects

You might also be interested in these projects:

• github-base: Low-level methods for working with the GitHub API in node.js/JavaScript. | homepage
• github-contributors: Generate a markdown or JSON list of contributors for a project using the GitHub API. | homepage

Contributors

Commits	Contributor
15	jonschlinkert
6	tennisonchan
4	doowb
1	sheeit

Author

Jon Schlinkert

• GitHub Profile
• Twitter Profile
• LinkedIn Profile

License

Copyright © 2018, Jon Schlinkert. Released under the MIT License.

---

This file was generated by verb-generate-readme, v0.6.0, on August 19, 2018.

gists's Issues

How i use Edit?

Hi (it's me again), i never used gists API and nothing related, and i don't know how to use edit function, maybe a bit of support could help me.

Ok, i have logged in into my accont, and i know how to get res from a gist, but i don't know how to edit it.

Im triying to do this,
gists.edit({opts: { "description": "Hi", "files": { "bot.txt": { "content": "Hello how are you?" }, }, } });
I tried to specify the id but i don't get how to do it, gists.edit({opts: All options etc}, opts.id:"id"})
This maybye? I try it but doesn't work.

Error: Unexpected end of JSON input

Better documentation or example on how to add params on an API request

If you want to call a gist with a param, say a /gist request with a param since (api), you need to do as the following:

// GET /gists?since=2017-10-15T18:20:28
gists.all({
    since: "2017-10-15T18:20:28",
    params: ['since']
}, cb);

Is it possible to auth with token ?

Where I can get the gist id ?

Where I can get the gist id ?

Auth using apps client ID and secret

Is it possible to authenticate by creating a github app and then using the client id and secret of the app?

Possible to write to gist from a pwa?

The example heavily relies on
https://github.com/jonschlinkert/gists/blob/master/test/support/auth.js#L20
in order to work. Taking it out leads to 401 auth error from gist.

The problem is that this does not work on progressive web apps. It requires access to the user's file system as it relies on the fs module :(

My question is - any ways around this? What if I have a pwa that runs from the web browser?

need to update how `options` / `data` objects are extended

currently these objects are merged, they shouldn't be though. that was done initially when I was going to allow a more flexible format.

Possible to upload image and other binary files?

If so, how do we get this from an input onChange event to gist?
The content option seems to only accept strings, however I know that it is possible to add images to a gist in other means
https://gist.github.com/mroderick/1afdd71aa69f6b29601d335751a1a9be

btw since I am trying this from a PWA, I cannot use fs = require('fs') as its only available when running from local server

How i get only the content of a gist.

I don't know how to get only the content. Is the json parsed? I tried to parse but i get error. If i try to acces an specific i get undefined.

res.files.text.txt.content if i use this i get error @jonschlinkert

The library has support for accounts with two-factor auth?

Recently I become to experiment with the library for some project that I'm currently working, somehow when I use my GitHub account to do some tests I saw that an error comes and was from the two-factor auth (my GitHub account has the two-factor auth).

`create` function doesn't work

According to Gist API, the call to create a new gist is POST /gists, not POST /gists/ as in here. I guess they changed it.

Thanks.