# gisty

> Wrapper for the GitHub Gists API

Latest version **1.0.0** (published 2026-06-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install gisty
pnpm add gisty
yarn add gisty
bun add gisty
```

## Health

**Score 50/100 (C)** — status: active.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2026-06-14 |
| First published | 2011-08-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=26.3 |
| Dependencies | 0 |
| Unpacked size | 15.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 17 |
| Author | Alexey Simonenko |
| Maintainers | meritt |
| Keywords | api, gist, gists, github, github-api, github-gist |

## Links

- npm: https://www.npmjs.com/package/gisty
- Repository: https://github.com/meritt/node-gisty
- npm.io page: https://npm.io/package/gisty

## Recent versions

- 1.0.0 (latest) — 2026-06-14
- 0.1.5 — 2014-04-05
- 0.1.4 — 2013-12-24
- 0.1.3 — 2013-11-03
- 0.1.2 — 2013-05-18
- 0.1.1 — 2013-03-16
- 0.1.0 — 2013-01-08
- 0.0.3 — 2012-04-22
- 0.0.2 — 2011-08-17
- 0.0.1 — 2011-08-16

## README

# gisty

[![NPM version][npm-image]][npm-url]
[![Build status][github-actions-image]][github-actions-url]
[![Coverage status][coveralls-image]][coveralls-url]
[![Dependency status][libraries-image]][libraries-url]

A small, zero-dependency client for the [GitHub Gists API](https://docs.github.com/en/rest/gists/gists). Reads return raw gist JSON; list methods are async iterables that paginate transparently.

## Requirements

- Node.js ≥ 26.3

## Installation

```bash
pnpm add gisty
# or: npm install gisty
```

## Usage

```js
import { Gisty } from 'gisty';

const gist = new Gisty({ token: process.env.GITHUB_TOKEN });

const one = await gist.fetch('aa5a315d61ae9438b18d');
for (const [name, file] of Object.entries(one.files)) {
  console.log(name, file.content);
}

for await (const g of gist.all()) {
  console.log(g.id, g.description);
}

const recent = await Array.fromAsync(gist.public({ limit: 50 }));
console.log(recent.length);

const created = await gist.create({ files: { 'hello.txt': 'Hello' } });
await gist.update(created.id, { description: 'updated' });
await gist.delete(created.id);
```

## Constructor

```js
new Gisty(options?)
```

| Option     | Default                  | Meaning                                    |
| ---------- | ------------------------ | ------------------------------------------ |
| `token`    | `env.GITHUB_TOKEN`       | Access token; omit for public reads only   |
| `username` | none                     | Default user for `all()`                   |
| `env`      | `process.env`            | Object to read `GITHUB_TOKEN` from         |
| `baseUrl`  | `https://api.github.com` | API host                                   |
| `timeout`  | `30000`                  | Per-request timeout in ms; `0` disables it |

## Reading

| Method                   | Returns                            | Endpoint                                  |
| ------------------------ | ---------------------------------- | ----------------------------------------- |
| `fetch(id, sha?)`        | one gist; `sha` selects a revision | `GET /gists/{id}[/{sha}]`                 |
| `all(options?)`          | the user's gists                   | `GET /gists` or `/users/{username}/gists` |
| `public(options?)`       | recent public gists                | `GET /gists/public`                       |
| `starred(options?)`      | starred gists (token required)     | `GET /gists/starred`                      |
| `history(id, options?)`  | a gist's revisions                 | `GET /gists/{id}/commits`                 |
| `forks(id, options?)`    | a gist's forks                     | `GET /gists/{id}/forks`                   |
| `comments(id, options?)` | a gist's comments                  | `GET /gists/{id}/comments`                |
| `comment(id, commentId)` | one comment                        | `GET /gists/{id}/comments/{commentId}`    |

`fetch` and `comment` resolve to a single object. The rest return async iterables; collect them with `Array.fromAsync`.

`options`:

| Key        | Default                | Meaning                                    |
| ---------- | ---------------------- | ------------------------------------------ |
| `perPage`  | `100`                  | Page size, max 100                         |
| `since`    | none                   | ISO 8601 timestamp; items updated after it |
| `limit`    | none                   | Stop after this many items                 |
| `username` | constructor `username` | `all()` only                               |

## Writing

Writes require a token and resolve to the raw gist (`delete` resolves to `undefined`).

| Method                | Returns          | Endpoint             |
| --------------------- | ---------------- | -------------------- |
| `create(gist)`        | the new gist     | `POST /gists`        |
| `update(id, changes)` | the updated gist | `PATCH /gists/{id}`  |
| `delete(id)`          | `undefined`      | `DELETE /gists/{id}` |

`create(gist)` takes `{ files, description?, public? }`; `public` defaults to `false`. `update(id, changes)` takes `{ files?, description? }` with at least one set.

In `files`, a string is the file body, `null` deletes a file, and `{ filename }` renames one:

```js
await gist.update(id, {
  files: {
    'hello.txt': 'Hello again', // update content
    'old.txt': { filename: 'new.txt' }, // rename
    'draft.txt': null // delete
  },
  description: 'updated'
});
```

## Rate limit

`gist.rateLimit` holds the latest GitHub rate-limit state after each request:

```js
gist.rateLimit; // { limit, remaining, reset: Temporal.Instant }
```

## Errors

A failed request throws `GistError`, carrying `message`, `status`, `documentationUrl`, `rateLimit`, and `cause`. It is raised on an HTTP error, a network failure, or a timeout:

```js
import { Gisty, GistError } from 'gisty';

try {
  await Array.fromAsync(new Gisty().starred());
} catch (err) {
  if (err instanceof GistError) {
    console.error(err.status, err.message);
  }
}
```

## Tokens

Public reads need no token. Private gists, `starred()`, and writes require one, passed as `{ token }` or read from `GITHUB_TOKEN`.

The least-privilege fine-grained PAT for reading carries no Gists permission. Writes need **Account → Gists → Read and write** (GitHub has no read-only gist level). The helper script creates and verifies a token:

```bash
node examples/get-access-token.js
```

## Author

- [Alexey Simonenko](https://github.com/meritt)

## License

MIT. See `LICENSE`.

[npm-image]: https://img.shields.io/npm/v/gisty.svg?style=flat
[npm-url]: https://www.npmjs.com/package/gisty
[github-actions-image]: https://github.com/meritt/node-gisty/actions/workflows/ci.yml/badge.svg
[github-actions-url]: https://github.com/meritt/node-gisty/actions/workflows/ci.yml
[coveralls-image]: https://coveralls.io/repos/github/meritt/node-gisty/badge.svg?branch=main
[coveralls-url]: https://coveralls.io/github/meritt/node-gisty?branch=main
[libraries-image]: https://img.shields.io/librariesio/release/npm/gisty.svg?style=flat
[libraries-url]: https://libraries.io/npm/gisty

---
_Source: https://npm.io/package/gisty · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._