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'),
},
],
});
@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
Until v18, node.js does not support fetch
, and no version of node or bun has FormData
built-in. We provide another package, @purplet/polyfill
which polyfills these APIs for you:
import '@purplet/polyfill';
import { Rest } from '@purplet/rest';
// ...
We generate most of our library's route metadata off of these GitHub repositories:
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. The following routes have buggy or incorrect types:
-
Some thread actions are missing. (types#526) / purplet#50)
channel.listPublicArchivedThreads
channel.listPrivateArchivedThreads