@purplet/rest

This is a JavaScript implementation for the Discord REST API. It is very light, and doesn't do more than is needed. We do not depend on any runtime-specific apis, but rather the fetch and FormData standard APIs, meaning this client can run in Node.js and in Bun (with polyfills). Every route is fully typed via discord-api-types and documented using auto-generated JSDoc comments from the Discord API documentation.

Basic Example:

import { Rest } from '@purplet/rest';

const rest = new Rest({ token: process.env.token });

const me = await rest.user.getCurrentUser();

All routes are based off of the Discord API Docs, in the notation of .resource.actionName, where resource is the name of a page on the sidebar, and actionName is the name of the header above each endpoint. This means the endpoint used above is "Get Current User" on the "User" page.

note: "Receiving and Responding" is exposed as interactionResponse, as it is more concise

For requests with url params, JSON bodies, queries, file uploads, and the X-Audit-Log-Reason header; a consistent object is passed, though each route has a custom type generated to only allow the fields are allowed/required.

Sending a Message:

const result = await rest.channel.createMessage({
  // Url params are on the base object
  channelId: '995650617282412594',
  // JSON Body is `body`
  body: {
    content: 'Hello, world!',
    attachments: [
      {
        id: '0',
      },
    ],
  },
  // Attached files are `files`, you can pass a string, Uint8Array, or even `Bun.file(...)`
  files: [
    {
      name: 'cat.png',
      data: Bun.file('./cat.png'),
    },
  ],
});

Installing

@purplet/rest has a peer-dependency on discord-api-types so we do not have to bump this package when types change slightly.

pnpm install @purplet/rest discord-api-types
# or
bun add @purplet/rest discord-api-types

Polyfills

Until v18, node.js does not support fetch and FormData, and bun has yet to implement FormData. We provide another package, @purplet/polyfill which polyfills these APIs for you:

import '@purplet/polyfill';
import { Rest } from '@purplet/rest';
// ...

Missing/Incorrect Types

We generate most of our library's route metadata off of these GitHub repositories:

• discord-api-docs
• discord-api-types

We do apply some patches of our own, but missing types should be contributed to the above repositories instead of as extra overrides to us.