discord-api-types

What is discord-api-types?

The discord-api-types npm package provides TypeScript type definitions for the Discord API. It helps developers ensure type safety and autocompletion when interacting with the Discord API, making it easier to build bots and other applications that integrate with Discord.

What are discord-api-types's main functionalities?

Type Definitions for Discord API

Provides type definitions for various Discord API objects, such as users, channels, guilds, etc. This ensures that the data structures used in your application match the expected format of the Discord API.

import { APIUser } from 'discord-api-types/v10';

const user: APIUser = {
  id: '1234567890',
  username: 'exampleUser',
  discriminator: '0001',
  avatar: null,
  bot: false,
  system: false,
  mfa_enabled: false,
  banner: null,
  accent_color: null,
  locale: 'en-US',
  verified: true,
  email: '[e-mail]',
  flags: 0,
  premium_type: 1,
  public_flags: 0
};

Enum Definitions

Includes enums for various constants used in the Discord API, such as channel types, message types, and more. This helps in avoiding magic strings and makes the code more readable and maintainable.

import { ChannelType } from 'discord-api-types/v10';

const channelType: ChannelType = ChannelType.GuildText;

API Interaction Types

Defines types for various interactions that can occur in Discord, such as commands, button clicks, and more. This helps in handling different types of interactions in a type-safe manner.

import { APIInteraction, InteractionType } from 'discord-api-types/v10';

const interaction: APIInteraction = {
  id: '1234567890',
  application_id: '0987654321',
  type: InteractionType.Ping,
  data: null,
  guild_id: '1122334455',
  channel_id: '5566778899',
  member: null,
  user: null,
  token: 'aW50ZXJhY3Rpb25fdG9rZW4=',
  version: 1
};

Other packages similar to discord-api-types

discord.js

discord.js is a powerful JavaScript library for interacting with the Discord API. It provides a higher-level abstraction over the raw API, making it easier to build bots and other applications. Unlike discord-api-types, which focuses on type definitions, discord.js provides a full-featured library with methods and classes for interacting with Discord.

eris

Eris is another JavaScript library for interacting with the Discord API. It is known for being lightweight and efficient, making it suitable for large-scale bot applications. Like discord.js, Eris provides a higher-level abstraction over the raw API, whereas discord-api-types focuses solely on type definitions.

discord-api

discord-api is a lower-level library that provides direct access to the Discord API endpoints. It is more similar to discord-api-types in that it focuses on providing a direct interface to the API, but it does not provide type definitions. Instead, it focuses on making HTTP requests to the API.

README

Discord API Types

Simple type definitions for the Discord API.

Installation

Install with npm / yarn / pnpm:

npm install discord-api-types
yarn add discord-api-types
pnpm add discord-api-types

We also provide typings compatible with the deno runtime. You have 3 ways you can import them:

1. Directly from GitHub

// Importing the default API version
import { APIUser } from 'https://raw.githubusercontent.com/discordjs/discord-api-types/main/deno/mod.ts';

// Importing a specific API version
import { APIUser } from 'https://raw.githubusercontent.com/discordjs/discord-api-types/main/deno/v8/mod.ts';

1. From deno.land/x

// Importing the default API version
import { APIUser } from 'https://deno.land/x/discord_api_types@0.12.0/mod.ts';

// Importing a specific API version
import { APIUser } from 'https://deno.land/x/discord_api_types@0.12.0/v8/mod.ts';

1. From skypack.dev

// Importing the default API version
import { APIUser } from 'https://cdn.skypack.dev/discord-api-types?dts';

// Importing a specific API version
import { APIUser } from 'https://cdn.skypack.dev/discord-api-types/v8?dts';

Project Structure

The exports of each API version is split into three main parts:

• Everything exported with the API prefix represents a payload you may get from the REST API or the Gateway.

• Everything exported with the Gateway prefix represents data that ONLY comes from or is directly related to the Gateway.

• Everything exported with the REST prefix represents data that ONLY comes from or is directly related to the REST API.

  • For endpoint options, they will follow the following structure: REST<HTTP Method><Type><Query|(JSON|FormData)Body|Result> where the type represents what it will return.

    • For example, RESTPostAPIChannelMessageJSONBody or RESTGetAPIGatewayBotInfoResult.

    • Some exported types (specifically OAuth2 related ones) may not respect this entire structure due to the nature of the fields. They will start with either RESTOAuth2 or with something similar to REST<HTTP Method>OAuth2

  • If a type ends with Result, then it represents the expected result by calling its accompanying route.

    • Types that are exported as never usually mean the result will be a 204 No Content, so you can safely ignore it. This does not account for errors.

• Anything else that is miscellaneous will be exported based on what it represents (for example the REST route object).

• There may be types exported that are identical for all versions. These will be exported as is and can be found in the common directory. They will still be prefixed accordingly as described above.

Warning: This package documents just KNOWN (and documented) properties. Anything that isn't documented will NOT be added to this package (unless said properties are in an open Pull Request to Discord's API Documentation repository or known through other means and have received the green light to be used). For clarification's sake, this means that properties that are only known through the process of data mining and have not yet been confirmed in a way as described will NOT be included.

Usage

You can require / import the module directly, which will give you the latest types as of the current API version. This is considered the default version and will be updated according to Discord's default API version; this means it may break at any point in time.

We strongly recommend you use a version when importing this module! This will prevent breaking changes when updating the module.

const { APIUser } = require('discord-api-types');

// TypeScript/ES Module support
import { APIUser } from 'discord-api-types';

You should instead consider adding the API version you want to target by appending /v*, where the * represents the API version.

const { APIUser } = require('discord-api-types/v8');

// TypeScript/ES Module support
import { APIUser } from 'discord-api-types/v8';

Changelog

0.12.1 (2021-01-05)

Bug Fixes

• run deno workflow only on branch push (#66) (0ef4620)

Features

• add Snowflake and Permissions types (#69) (549a6f0)