# gist-client > A client to consume Gist API with JS Latest version **1.1.1** (published 2019-10-15) · MIT license · 0 weekly downloads ## Install ```sh npm install gist-client pnpm add gist-client yarn add gist-client bun add gist-client ``` ## 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.1.1 | | Published | 2019-10-15 | | First published | 2017-11-02 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 5 | | Unpacked size | 80.1 KB | | Known vulnerabilities | 0 (+1 in 1 direct dependencies) | | Install scripts | no | | GitHub stars | 9 | | Author | José Vte. Calderón | | Maintainers | jvcalderon | | Keywords | gist, github | ## Links - npm: https://www.npmjs.com/package/gist-client - Repository: https://github.com/jvcalderon/gist-client - Homepage: https://github.com/jvcalderon/gist-client#readme - Issues: https://github.com/jvcalderon/gist-client/issues - npm.io page: https://npm.io/package/gist-client ## Dependencies (5) - [co](https://npm.io/package/co.md) ^4.6.0 - [snyk](https://npm.io/package/snyk.md) ^1.231.0 - [lodash](https://npm.io/package/lodash.md) ^4.17.4 - [request](https://npm.io/package/request.md) ^2.83.0 - [request-promise-native](https://npm.io/package/request-promise-native.md) ^1.0.5 ## Recent versions - 1.1.1 (latest) — 2019-10-15 - 1.1.0 — 2018-12-13 - 1.0.9 — 2018-12-04 - 1.0.8 — 2018-12-03 - 1.0.7 — 2017-11-08 - 1.0.6 — 2017-11-08 - 1.0.5 — 2017-11-08 - 1.0.4 — 2017-11-08 - 1.0.3 — 2017-11-08 - 1.0.2 — 2017-11-08 - 1.0.1 — 2017-11-03 - 1.0.0 — 2017-11-02 ## README [![NPM](https://nodei.co/npm/gist-client.png?downloads=true&stars=true)](https://nodei.co/npm/gist-client/) Gist Client ============== [![Build Status](https://travis-ci.org/jvcalderon/gist-client.svg?branch=master)](https://travis-ci.org/jvcalderon/gist-client) [![Coverage Status](https://coveralls.io/repos/github/jvcalderon/gist-client/badge.svg?branch=master)](https://coveralls.io/github/jvcalderon/gist-client?branch=master) [![Known Vulnerabilities](https://snyk.io/test/github/jvcalderon/gist-client/badge.svg)](https://snyk.io/test/github/jvcalderon/gist-client) A client to consume [Gist](https://gist.github.com/) API with JS. Provides some features like filtering or abstraction of resource pagination. You don't know Gist? See [official Github's help](https://help.github.com/articles/about-gists/). ## 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'](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/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: | Filter | Tier | Type | Notes | |-----------|----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | since | global | string | A timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Only gists updated at or after this time are returned. | | userName | resource | string | Name of the user whose documents you want to list. | | starred | resource | bool | Starred gists. | | public | resource | bool | Public gists. | | filename | file | string | Complete file name, f.ex: doc.json, index.sh... **It doesn`t filter files inside a gist. It just filter all gists that contains a file with given name**.| | size | file | int | File size in Kb. | | raw_url | file | string | Url to file's raw content. | | type | file | string | text/plain, application/json... | | language | file | string | PHP, Javascript, Erlang, Java... | | truncated | file | bool | The Gist API provides up to one megabyte of content for each file in the gist. Each file returned for a gist through the API has a key called truncated. If truncated is true, the file is too large and only a portion of the contents were returned in content. | | content | file | string | File content. **IMPORTANT: You must to activate option rawContent to use this filter**. | - **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](https://developer.github.com/v3/gists/). --- _Source: https://npm.io/package/gist-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._