Gist Client

A client to consume Gist API with JS. Provides some features like filtering or abstraction of resource pagination. You don't know Gist? See official Github's help.

Installation

$ npm install --save gist-client

Get a Github token

Certain operations on Gist require authorization. Read more about how to get a granted token in 'About scopes for OAuth Apps'.

Basic use

To use Gist Client you need to require it and create an instance:

const GistClient = require("gist-client")
const gistClient = new GistClient()

If you want to get your private Gist or perform some securized operation, you need to use setToken method to bind your token:

gistClient.setToken('YOUR_TOKEN') //To bind token
gistClient.unsetToken() //To remove binded token

Getting a Gist

Gist Client works with promises. For example, if you want to get a single Gist you do the following:

gistClient.getOneById('GIST_ID')
    .then(response => {
        console.log(response)
    }).catch(err => {
        console.log(err)
    })

You don't need a token to get a public Gist, but if you are trying to get a private one, you need to set the token. You can do:

gistClient.setToken('YOUR_TOKEN').getOneById('GIST_ID')

Or:

gistClient.setToken('YOUR_TOKEN')
gistClient.getOneById('GIST_ID')

Get a Gist list

You can use getAll method to get a Gist list:

gistClient.setToken('YOUR_TOKEN').getAll() //List the authenticated user's gists
gistClient.getAll() //List all public gists (Max. 3000 -an API limitation-)

Iterating the list

Results can be iterated without worrying about pagination:

gistClient.setToken('YOUR_TOKEN').getAll().then((gistList) => {
    gistList.forEach((gist) => {
        console.log(gist)
    })
})

Filtering the list

Gist Client allows you to filter results. You can append filters, it will be applied with 'AND' criteria.

gistClient.setToken('YOUR_TOKEN').getAll({filterBy: [
    {public: true},
    {since: '2017-01-02T12:10:51Z'},
    {language: 'PHP'}
]})

This call will be return all user's public gists in PHP that have been updated since given date.

There is a limited list of filters that can be applied to a result:

• resource tier: filters at API resource level. You can't combine these filters types between them; for example if you are using 'userName' you can't use 'starred' too.
• file: filters at the level of documents linked to gists. It will search for any gist that contains a file with the given criteria.
• global tier: Can be used in combination with any other.

Bind raw content

Gist API hides the content of the files in lists to decrease payload. Gist Client provides an option to bind the content in list; rawContent (true|false). You can use it as follow:

gistClient.getAll({rawContent: true}) //false as default

IMPORTANT: Be careful with the preceding call. Using this option in combination with 'filterBy' is highly recommended to limit the total amount of requests to Gist API. Keep in mind that there were an aditional API call for each retrieved file. It can rebase your remaining rate limit on Github API.

Get a gist revision

gistClient.setToken('YOUR_TOKEN').getRevision('GIST_ID', 'VERSION_SHA') //Returns a promise

Get gist commits

gistClient.setToken('YOUR_TOKEN').getCommits('GIST_ID') //Returns a promise

Get gist forks

gistClient.setToken('YOUR_TOKEN').getForks('GIST_ID') //Returns a promise

Check if gist is starred

gistClient.setToken('YOUR_TOKEN').isStarred('GIST_ID') //Returns true if gist is starred

Star / unstar gists

//These methods return true if operation is done
gistClient.setToken('YOUR_TOKEN').star('GIST_ID') //Mark a gist as starred
gistClient.setToken('YOUR_TOKEN').unstar('GIST_ID') //Mark a gist as unstarred

Create / update gists

To create a new gist you can use 'create' method as follow:

gistClient.setToken('YOUR_TOKEN').create({
    "files": [{
        "x.txt": {
            "content": "xx"
        }
    }],
    "description": "desc",
    "public": true
}).then(newGist => {
    console.log(newGist)
})

To edit a gist you can use 'update' metod:

gistClient.setToken('YOUR_TOKEN').update('GIST_ID', {description: 'new description'})

Delete a gist

gistClient.setToken('YOUR_TOKEN').delete('GIST_ID') //Returns true if gist has been removed

If you need information about Gist API, you can see official documentation.