# discord-request

> A Discord HTTP client

Latest version **1.0.1** (published 2023-04-21) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install discord-request
pnpm add discord-request
yarn add discord-request
bun add discord-request
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2023-04-21 |
| First published | 2021-06-24 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 2 |
| Unpacked size | 115 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Ian Mitchell |
| Maintainers | ianmitchell |

## Links

- npm: https://www.npmjs.com/package/discord-request
- Homepage: https://github.com/ianmitchell/interaction-kit/tree/main/packages/discord-request
- npm.io page: https://npm.io/package/discord-request

## Dependencies (2)

- [discord-error](https://npm.io/package/discord-error.md) 3.0.1
- [discord-snowflake](https://npm.io/package/discord-snowflake.md) 2.0.0

## Recent versions

- 1.0.1 (latest) — 2023-04-21
- 1.0.0 — 2023-04-21
- 0.0.6 — 2023-04-07
- 0.0.4 — 2022-01-11
- 0.0.4-alpha.0 — 2022-01-04
- 0.0.3 — 2021-07-09
- 0.0.2 — 2021-07-09
- 0.0.1 — 2021-06-24

## README

# discord-request

> **Looking for an API Wrapper?**
> Check out [`discord-api-methods`](https://www.npmjs.com/package/discord-api-methods) instead. This package is low level, and works best in libraries as opposed to applications.

A Discord HTTP client that handles formatting and parsing requests.

## Usage

This package works best in conjuction with [`discord-api-types`](https://www.npmjs.com/package/discord-api-types). To begin, install both:

    npm install discord-request discord-api-types

Then you can combine the two (with or without typing the results):

```ts
import { Client } from "discord-request";
import {
	Routes,
	RESTGetAPIApplicationGuildCommandsResult,
} from "discord-api-types/v10";

const client = new Client();
client.setToken(process.env.DISCORD_TOKEN);

const guildCommands = client.get(
	Routes.applicationGuildCommands(applicationId, guildId)
) as Promise<RESTGetAPIApplicationGuildCommandsResult>;
```

## Options

When creating a new client, you can configure it by passing in optional arguments:

```ts
const instance = new Client({
	timeout: 1000,
	userAgent: "My Discord Bot",
}).setToken(process.env.DISCORD_TOKEN);
```

Every parameter listed below is optional.

- `api`: The API URL to use. Defaults to `https://discord.com/api`.
- `version`: The API version to use. Defaults to `10`.
- `cdn`: The CDN URL to use. Defaults to `https://cdn.discordapp.com`.
- `headers`: An object of additional headers to send with each request.
- `userAgent`: The user agent to use. Defaults to `Discord Request v0`.
- `timeout`: The number of milliseconds to wait before timing out a request. Defaults to `15000` (15 seconds).
- `abortSignal`: An AbortSignal to use when you need to cancel all unfinished requests to shut down the application.
- `onRequest`: See callbacks below.

#### Callbacks

###### `onRequest?: (path: string, init: RequestInit) => void;`

Runs when a request is sent to the Discord API. Passes information used to send the request.

## Client Configuration

There are various getters and setters you can use to configure the client once instantiated.

```ts
const instance = new Client();
instance.userAgent = "My Discord Bot";
console.log(instance.userAgent);
```

## Setting Token

To set an application token for the client to use, call `setToken` after you instantiate it.

```ts
const instance = new Client();
instance.setToken(process.env.DISCORD_TOKEN);
```

## Sending Requests

To send a request, use the `get`, `post`, `patch`, `put`, or `delete` methods.

```ts
import { Client } from "discord-request";

const instance = new Client().setToken(process.env.DISCORD_TOKEN);
const route = "...";
let result;

// GET
result = await instance.get(route);

// POST
result = await instance.post(route, {
	body: {
		key: "value",
	},
});

// PUT
result = await instance.put(route, {
	body: {
		key: "value",
	},
});

// PATCH
result = await instance.patch(route, {
	body: {
		key: "value",
	},
});

// DELETE
result = await instance.delete(route);
```

## Request Options

You can pass these options to each HTTP request method. Every parameter listed below is optional.

- `authorization` (boolean): Whether to use the authorization header.
- `authorizationPrefix` (string): The authorization prefix to use. Defaults to "Bot".
- `formData` (FormData): The body to send as form data.
- `body` (BodyInit | object): The body to send with the request. If you have defined `formData` or `files` this will be sent as `payload_json` in the form data.
- `files` (Attachment[] | undefined): A list of up to 10 files to upload and send as part of the request.
  - `Attachment` objects should consist of an optional `id` snowflake (for editing existing attachments), a `name` string, and a `data` Blob.
- `headers` (HeadersInit): Headers to add to the request.
- `rawBody` (boolean, defaults to false): If true, the body will not be processed before sending to Discord.
- `query` (URLSearchParams): Query parameters to add to the request.
- `reason` (string): If provided, an audit log entry will be made with this value.
- `versioned` (boolean): A boolean on whether to use the versioned API. By default, requests will set a specific API version.

## Request Errors

This library will throw several different errors based on the response.

- `RequestError` - If the request fails for any reason, this error will be thrown with the error message.
- `RateLimitError` - If your application is currently being Rate Limited by Discord, this error will be thrown with the parsed information.
- `DiscordRequestError` - If Discord's API returns an error with an error key, this error will be thrown with the parsed information.

## Credits

This code is derived from code originally written by the discord.js maintainers in the [@discordjs/rest](https://www.npmjs.com/package/@discordjs/rest) package and distributed under the Apache 2 license. It was changed to be built with Web APIs instead of Node.js APIs.

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