mirror of
https://github.com/discordjs/discord-api-types.git
synced 2026-05-22 19:30:09 +00:00
Compare commits
6 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
7b1e5a70e5 | ||
|
|
8e5f07e2ee | ||
|
|
1c6ea86110 | ||
|
|
43c372d817 | ||
|
|
9f386cb874 | ||
|
|
019b9de1e8 |
3
.vscode/settings.json
vendored
3
.vscode/settings.json
vendored
@@ -5,5 +5,6 @@
|
||||
"source.organizeImports": false,
|
||||
"source.fixAll": true,
|
||||
"source.fixAll.eslint": true
|
||||
}
|
||||
},
|
||||
"cSpell.enableFiletypes": ["mdx"]
|
||||
}
|
||||
|
||||
12
CHANGELOG.md
12
CHANGELOG.md
@@ -1,3 +1,15 @@
|
||||
## [0.33.4](https://github.com/discordjs/discord-api-types/compare/0.33.3...0.33.4) (2022-06-06)
|
||||
|
||||
### Features
|
||||
|
||||
- **RESTPostAPIWebhookWithTokenJSONBody:** add `thread_name` ([#463](https://github.com/discordjs/discord-api-types/issues/463)) ([8e5f07e](https://github.com/discordjs/discord-api-types/commit/8e5f07e2eebc14e5777dbfb932ef54f252165524))
|
||||
|
||||
## [0.33.3](https://github.com/discordjs/discord-api-types/compare/0.33.2...0.33.3) (2022-06-04)
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
- **AddUndefinedToPossiblyUndefinedProperties:** recurse down objects ([#471](https://github.com/discordjs/discord-api-types/issues/471)) ([43c372d](https://github.com/discordjs/discord-api-types/commit/43c372d81722e48b105d5121a2cfdf614f1e7704))
|
||||
|
||||
## [0.33.2](https://github.com/discordjs/discord-api-types/compare/0.33.1...0.33.2) (2022-06-01)
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
@@ -1,3 +1,15 @@
|
||||
## [0.33.4](https://github.com/discordjs/discord-api-types/compare/0.33.3...0.33.4) (2022-06-06)
|
||||
|
||||
### Features
|
||||
|
||||
- **RESTPostAPIWebhookWithTokenJSONBody:** add `thread_name` ([#463](https://github.com/discordjs/discord-api-types/issues/463)) ([8e5f07e](https://github.com/discordjs/discord-api-types/commit/8e5f07e2eebc14e5777dbfb932ef54f252165524))
|
||||
|
||||
## [0.33.3](https://github.com/discordjs/discord-api-types/compare/0.33.2...0.33.3) (2022-06-04)
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
- **AddUndefinedToPossiblyUndefinedProperties:** recurse down objects ([#471](https://github.com/discordjs/discord-api-types/issues/471)) ([43c372d](https://github.com/discordjs/discord-api-types/commit/43c372d81722e48b105d5121a2cfdf614f1e7704))
|
||||
|
||||
## [0.33.2](https://github.com/discordjs/discord-api-types/compare/0.33.1...0.33.2) (2022-06-01)
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
@@ -144,6 +144,12 @@ export type RESTPostAPIWebhookWithTokenJSONBody = AddUndefinedToPossiblyUndefine
|
||||
* Message flags combined as a bitfield
|
||||
*/
|
||||
flags?: MessageFlags;
|
||||
/**
|
||||
* Name of thread to create
|
||||
*
|
||||
* Available only if the webhook is in a forum channel and a thread is not specified in {@link RESTPostAPIWebhookWithTokenQuery.thread_id} query parameter
|
||||
*/
|
||||
thread_name: string;
|
||||
}>;
|
||||
|
||||
/**
|
||||
@@ -171,6 +177,8 @@ export interface RESTPostAPIWebhookWithTokenQuery {
|
||||
wait?: boolean;
|
||||
/**
|
||||
* Send a message to the specified thread within a webhook's channel. The thread will automatically be unarchived.
|
||||
*
|
||||
* Available only if the {@link RESTPostAPIWebhookWithTokenJSONBody.thread_name} JSON body property is not specified
|
||||
*/
|
||||
thread_id?: Snowflake;
|
||||
}
|
||||
|
||||
@@ -144,6 +144,12 @@ export type RESTPostAPIWebhookWithTokenJSONBody = AddUndefinedToPossiblyUndefine
|
||||
* Message flags combined as a bitfield
|
||||
*/
|
||||
flags?: MessageFlags;
|
||||
/**
|
||||
* Name of thread to create
|
||||
*
|
||||
* Available only if the webhook is in a forum channel and a thread is not specified in {@link RESTPostAPIWebhookWithTokenQuery.thread_id} query parameter
|
||||
*/
|
||||
thread_name: string;
|
||||
}>;
|
||||
|
||||
/**
|
||||
@@ -171,6 +177,8 @@ export interface RESTPostAPIWebhookWithTokenQuery {
|
||||
wait?: boolean;
|
||||
/**
|
||||
* Send a message to the specified thread within a webhook's channel. The thread will automatically be unarchived.
|
||||
*
|
||||
* Available only if the {@link RESTPostAPIWebhookWithTokenJSONBody.thread_name} JSON body property is not specified
|
||||
*/
|
||||
thread_id?: Snowflake;
|
||||
}
|
||||
|
||||
@@ -7,7 +7,9 @@ export type Nullable<T> = {
|
||||
* (since JSON.stringify ignores undefined properties)
|
||||
*/
|
||||
export type AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Base> = {
|
||||
[K in keyof Base]: Base[K] extends Exclude<Base[K], undefined> ? Base[K] : Base[K] | undefined;
|
||||
[K in keyof Base]: Base[K] extends Exclude<Base[K], undefined>
|
||||
? AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Base[K]>
|
||||
: AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Base[K]> | undefined;
|
||||
};
|
||||
|
||||
export type StrictPartial<Base> = AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Partial<Base>>;
|
||||
|
||||
4
package-lock.json
generated
4
package-lock.json
generated
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "discord-api-types",
|
||||
"version": "0.33.2",
|
||||
"version": "0.33.4",
|
||||
"lockfileVersion": 2,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "discord-api-types",
|
||||
"version": "0.33.2",
|
||||
"version": "0.33.4",
|
||||
"license": "MIT",
|
||||
"devDependencies": {
|
||||
"@babel/runtime-corejs3": "^7.18.0",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "discord-api-types",
|
||||
"version": "0.33.2",
|
||||
"version": "0.33.4",
|
||||
"description": "Discord API typings that are kept up to date for use in bot library creation.",
|
||||
"exports": {
|
||||
"./globals": {
|
||||
|
||||
@@ -144,6 +144,12 @@ export type RESTPostAPIWebhookWithTokenJSONBody = AddUndefinedToPossiblyUndefine
|
||||
* Message flags combined as a bitfield
|
||||
*/
|
||||
flags?: MessageFlags;
|
||||
/**
|
||||
* Name of thread to create
|
||||
*
|
||||
* Available only if the webhook is in a forum channel and a thread is not specified in {@link RESTPostAPIWebhookWithTokenQuery.thread_id} query parameter
|
||||
*/
|
||||
thread_name: string;
|
||||
}>;
|
||||
|
||||
/**
|
||||
@@ -171,6 +177,8 @@ export interface RESTPostAPIWebhookWithTokenQuery {
|
||||
wait?: boolean;
|
||||
/**
|
||||
* Send a message to the specified thread within a webhook's channel. The thread will automatically be unarchived.
|
||||
*
|
||||
* Available only if the {@link RESTPostAPIWebhookWithTokenJSONBody.thread_name} JSON body property is not specified
|
||||
*/
|
||||
thread_id?: Snowflake;
|
||||
}
|
||||
|
||||
@@ -144,6 +144,12 @@ export type RESTPostAPIWebhookWithTokenJSONBody = AddUndefinedToPossiblyUndefine
|
||||
* Message flags combined as a bitfield
|
||||
*/
|
||||
flags?: MessageFlags;
|
||||
/**
|
||||
* Name of thread to create
|
||||
*
|
||||
* Available only if the webhook is in a forum channel and a thread is not specified in {@link RESTPostAPIWebhookWithTokenQuery.thread_id} query parameter
|
||||
*/
|
||||
thread_name: string;
|
||||
}>;
|
||||
|
||||
/**
|
||||
@@ -171,6 +177,8 @@ export interface RESTPostAPIWebhookWithTokenQuery {
|
||||
wait?: boolean;
|
||||
/**
|
||||
* Send a message to the specified thread within a webhook's channel. The thread will automatically be unarchived.
|
||||
*
|
||||
* Available only if the {@link RESTPostAPIWebhookWithTokenJSONBody.thread_name} JSON body property is not specified
|
||||
*/
|
||||
thread_id?: Snowflake;
|
||||
}
|
||||
|
||||
@@ -7,7 +7,9 @@ export type Nullable<T> = {
|
||||
* (since JSON.stringify ignores undefined properties)
|
||||
*/
|
||||
export type AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Base> = {
|
||||
[K in keyof Base]: Base[K] extends Exclude<Base[K], undefined> ? Base[K] : Base[K] | undefined;
|
||||
[K in keyof Base]: Base[K] extends Exclude<Base[K], undefined>
|
||||
? AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Base[K]>
|
||||
: AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Base[K]> | undefined;
|
||||
};
|
||||
|
||||
export type StrictPartial<Base> = AddUndefinedToPossiblyUndefinedPropertiesOfInterface<Partial<Base>>;
|
||||
|
||||
@@ -83,10 +83,10 @@ The file structure might seem confusing at first, especially if it's your first
|
||||
guide you through it.
|
||||
|
||||
When you clone the repository for the first time, you'll see a folder structure like this (we've not mentioned some
|
||||
tooling specific files like `.eslintrc.json` to keep the structure clean). We've highlighted the important folders you
|
||||
need to keep in mind when contributing.
|
||||
tooling specific files like `.eslintrc.json` to keep the structure clean). We've highlighted the important folders and
|
||||
files you need to keep in mind when contributing.
|
||||
|
||||
```bash {5,7-9,12-13,15-19}
|
||||
```bash {2,4-6,9-10,12-16}
|
||||
├── deno
|
||||
├── gateway
|
||||
├── node_modules (once you ran `npm ci`)
|
||||
@@ -205,7 +205,7 @@ miscellaneous scripts we might need. There's really not much to say about these
|
||||
|
||||
#### `tests`
|
||||
|
||||
This folder holds tests for certain complex types that the mdule might have, and is especially useful for validating
|
||||
This folder holds tests for certain complex types that the module might have, and is especially useful for validating
|
||||
unions.
|
||||
|
||||
:::info
|
||||
|
||||
@@ -83,10 +83,10 @@ The file structure might seem confusing at first, especially if it's your first
|
||||
guide you through it.
|
||||
|
||||
When you clone the repository for the first time, you'll see a folder structure like this (we've not mentioned some
|
||||
tooling specific files like `.eslintrc.json` to keep the structure clean). We've highlighted the important folders you
|
||||
need to keep in mind when contributing.
|
||||
tooling specific files like `.eslintrc.json` to keep the structure clean). We've highlighted the important folders and
|
||||
files you need to keep in mind when contributing.
|
||||
|
||||
```bash {5,7-9,12-13,15-19}
|
||||
```bash {2,4-6,9-10,12-16}
|
||||
├── deno
|
||||
├── gateway
|
||||
├── node_modules (once you ran `npm ci`)
|
||||
@@ -205,7 +205,7 @@ miscellaneous scripts we might need. There's really not much to say about these
|
||||
|
||||
#### `tests`
|
||||
|
||||
This folder holds tests for certain complex types that the mdule might have, and is especially useful for validating
|
||||
This folder holds tests for certain complex types that the module might have, and is especially useful for validating
|
||||
unions.
|
||||
|
||||
:::info
|
||||
|
||||
@@ -83,10 +83,10 @@ The file structure might seem confusing at first, especially if it's your first
|
||||
guide you through it.
|
||||
|
||||
When you clone the repository for the first time, you'll see a folder structure like this (we've not mentioned some
|
||||
tooling specific files like `.eslintrc.json` to keep the structure clean). We've highlighted the important folders you
|
||||
need to keep in mind when contributing.
|
||||
tooling specific files like `.eslintrc.json` to keep the structure clean). We've highlighted the important folders and
|
||||
files you need to keep in mind when contributing.
|
||||
|
||||
```bash {5,7-9,12-13,15-19}
|
||||
```bash {2,4-6,9-10,12-16}
|
||||
├── deno
|
||||
├── gateway
|
||||
├── node_modules (once you ran `npm ci`)
|
||||
@@ -205,7 +205,7 @@ miscellaneous scripts we might need. There's really not much to say about these
|
||||
|
||||
#### `tests`
|
||||
|
||||
This folder holds tests for certain complex types that the mdule might have, and is especially useful for validating
|
||||
This folder holds tests for certain complex types that the module might have, and is especially useful for validating
|
||||
unions.
|
||||
|
||||
:::info
|
||||
|
||||
@@ -83,10 +83,10 @@ The file structure might seem confusing at first, especially if it's your first
|
||||
guide you through it.
|
||||
|
||||
When you clone the repository for the first time, you'll see a folder structure like this (we've not mentioned some
|
||||
tooling specific files like `.eslintrc.json` to keep the structure clean). We've highlighted the important folders you
|
||||
need to keep in mind when contributing.
|
||||
tooling specific files like `.eslintrc.json` to keep the structure clean). We've highlighted the important folders and
|
||||
files you need to keep in mind when contributing.
|
||||
|
||||
```bash {5,7-9,12-13,15-19}
|
||||
```bash {2,4-6,9-10,12-16}
|
||||
├── deno
|
||||
├── gateway
|
||||
├── node_modules (once you ran `npm ci`)
|
||||
@@ -205,7 +205,7 @@ miscellaneous scripts we might need. There's really not much to say about these
|
||||
|
||||
#### `tests`
|
||||
|
||||
This folder holds tests for certain complex types that the mdule might have, and is especially useful for validating
|
||||
This folder holds tests for certain complex types that the module might have, and is especially useful for validating
|
||||
unions.
|
||||
|
||||
:::info
|
||||
|
||||
263
website/versioned_docs/version-0.33.3/Contributing.mdx
Normal file
263
website/versioned_docs/version-0.33.3/Contributing.mdx
Normal file
@@ -0,0 +1,263 @@
|
||||
---
|
||||
id: contributing_to_discord-api-types
|
||||
title: How to Contribute
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
So, you'd like to contribute to `discord-api-types` but don't know where to start or what to do? Here are some of the
|
||||
things you need to keep in mind before opening a pull request!
|
||||
|
||||
:::tip Before you begin
|
||||
|
||||
We recommend you contribute either through locally editing the files on your desktop (which means also installing
|
||||
[`npm`](https://www.npmjs.com/) dependencies as this will ensure not only a consistent code style, but also that the
|
||||
`deno` types stay in sync automatically) or through a service like
|
||||
[`GitHub Codespaces`](https://github.com/features/codespaces).
|
||||
|
||||
:::
|
||||
|
||||
:::info Still can't figure it out?
|
||||
|
||||
No problem! We await you with open hands in our [`Discord Server`](https://discord.gg/djs) in the `#discord-api-types`
|
||||
channel (under the `Miscellaneous` category)
|
||||
|
||||
:::
|
||||
|
||||
### Install npm dependencies first
|
||||
|
||||
One of the most crucial steps is installing [`npm`](https://www.npmjs.com/) dependencies via `npm ci`. This ensures that
|
||||
linting can be done, and it also sets up the `git` hooks for building the `deno` types and automatically
|
||||
formatting/linting the code when you commit it.
|
||||
|
||||
If you forget to install [`npm`](https://www.npmjs.com/) dependencies, or are doing the contributions through other
|
||||
means (like directly from GitHub web), you might see a comment like this one being sent as a review to your pull
|
||||
request:
|
||||
|
||||

|
||||
|
||||
The easiest way to solve this is to run the `build:deno` script (`npm run build:deno`) and pushing the results.
|
||||
|
||||
### Figure out if the update you want to contribute respects our rules about documentation
|
||||
|
||||
:::danger
|
||||
|
||||
We will not document client-only / client related types. If you plan on contributing, make sure the types you want to
|
||||
document can be used by bots and are _intended_ for usage by bots. This is a hard rule that will never change.
|
||||
|
||||
:::
|
||||
|
||||
Not every single update to the API is valid to be documented here. Our main stance for documentation is that properties
|
||||
must be known and documented on [`Discord's API Documentation repository`](https://github.com/discord/discord-api-docs),
|
||||
must be mentioned in an open pull request or must have received the green light to be used.
|
||||
|
||||
With that aside, there are times where documentation for certain types is not approved/merged by Discord on the grounds
|
||||
that `it isn't helpful for bots` (or similar), but it would actually benefit bot developers to have it documented (one
|
||||
good example is the UserFlags `SPAMMER` flag). As such, if you think your update should still be merged, please propose
|
||||
it and we will be handled on a case by case basis. If approved, your update will be documented with an `@unstable` tag.
|
||||
It will also not be subject to the same versioning rules as the rest of the types.
|
||||
|
||||
### Figure out what API versions need to receive the update
|
||||
|
||||
`discord-api-types` has multiple API versions in the repository, some of which may be considered `deprecated` or
|
||||
`discontinued` as we keep them till the version is completely dead before removing them. This is a good time to figure
|
||||
out which API versions need to be updated, and you can use the table below to guide you.
|
||||
|
||||
You can also check [`Discord's API versioning table`](https://discord.com/developers/docs/reference#api-versioning) if
|
||||
you want to be 1000% sure.
|
||||
|
||||
| **API Version** | **Should receive updates** |
|
||||
| :-------------: | :------------------------: |
|
||||
| 10 | Yes |
|
||||
| 9 | Yes |
|
||||
| 8 | No |
|
||||
| 7 | No |
|
||||
| 6 | No |
|
||||
|
||||
If the version you want to contribute to is not listed above (for instance if a new API version rolls out) or if the
|
||||
version you want to contribute to is for a different part of the API (for instance `voice`), feel free to submit it and
|
||||
we will review it accordingly.
|
||||
|
||||
### Figure out where exactly are the files you need to modify to make the update
|
||||
|
||||
The file structure might seem confusing at first, especially if it's your first time contributing, but we're here to
|
||||
guide you through it.
|
||||
|
||||
When you clone the repository for the first time, you'll see a folder structure like this (we've not mentioned some
|
||||
tooling specific files like `.eslintrc.json` to keep the structure clean). We've highlighted the important folders and
|
||||
files you need to keep in mind when contributing.
|
||||
|
||||
```bash {2,4-6,9-10,12-16}
|
||||
├── deno
|
||||
├── gateway
|
||||
├── node_modules (once you ran `npm ci`)
|
||||
├── payloads
|
||||
├── rest
|
||||
├── rpc
|
||||
├── scripts
|
||||
├── tests
|
||||
├── utils
|
||||
├── voice
|
||||
├── website
|
||||
├── globals.ts
|
||||
├── v6.ts
|
||||
├── v8.ts
|
||||
├── v9.ts
|
||||
├── v10.ts
|
||||
└── package.json
|
||||
```
|
||||
|
||||
#### `deno`
|
||||
|
||||
This folder stores the [`deno`](https://deno.land/) compatible typings for Discord's API.
|
||||
|
||||
:::danger
|
||||
|
||||
This folder should not be manually modified. Any manual changes will be overwritten by the `build:deno` script.
|
||||
|
||||
Any changes that need to be done to this folder need to be done through the `scripts/deno.mjs` file.
|
||||
|
||||
:::
|
||||
|
||||
#### `gateway`
|
||||
|
||||
This folder holds types that are strictly received from
|
||||
[`Discord's gateway`](https://discord.com/developers/docs/topics/gateway). It stores the gateway version the types are
|
||||
for, the intents and opcodes, and any data that can be received/sent through the gateway.
|
||||
|
||||
Each file in the folder represents a gateway version. It references types from the versioned [`payloads`](#payloads)
|
||||
folder unless the payloads come _only_ through the gateway. There is also a `common.ts` file which represents shared
|
||||
types across all versions, as well as an `index.ts` file that exports the recommended gateway version's types.
|
||||
|
||||
:::info
|
||||
|
||||
Types created here must start with the `Gateway` prefix (for instance `GatewayGuildCreateDispatchData` which is an
|
||||
extension of the `APIGuild` type with extra fields received only through the gateway).
|
||||
|
||||
:::
|
||||
|
||||
#### `payloads`
|
||||
|
||||
This folder holds the bulk of type definitions for Discord's APIs. Each API version receives its own folder. Inside of
|
||||
each folder there is always an `index.ts` file that exports every type available in that version, as well as the common
|
||||
types that can be found in `payloads/common.ts`. At the root of the `payloads` folder is also an `index.ts` file which
|
||||
exports the recommended API version's types.
|
||||
|
||||
Inside of each versioned folder, the files are defined from the structure in
|
||||
[`Discord's API Documentation`](https://discord.dev), under the `Resources` category. Depending on the complexity of the
|
||||
resource, you may opt for splitting it up into multiple files. If you want to do so, please create a folder named
|
||||
`_{resource_name}` where the `resource_name` is the same name as the resource you're splitting up (a good example is the
|
||||
`_interactions` folder which stores all the types for interactions in a neater structure), and create a
|
||||
`{resource_name}.ts` file which exports everything from that folder). If you feel like you need to split it up even
|
||||
more, just repeat the same structure of creating an `_{file_name}` folder and exporting everything from it in the
|
||||
`{file_name}.ts` file (you can see an example
|
||||
[here](https://github.com/discordjs/discord-api-types/tree/85802f1/payloads/v10/_interactions)).
|
||||
|
||||
:::info
|
||||
|
||||
Types created here must start with the `API` prefix (for instance `APIUser`), **except** for enums, which should have a
|
||||
normal name (for instance `UserFlags`).
|
||||
|
||||
:::
|
||||
|
||||
#### `rest`
|
||||
|
||||
This folder holds all the types that are related to Discord's REST API. Just like [`payloads`](#payloads), it is split
|
||||
into folders that have an `index.ts` file. from the structure in [`Discord's API Documentation`](https://discord.dev),
|
||||
under the `Resources` category.
|
||||
|
||||
:::info
|
||||
|
||||
Types created here must start with the `REST` prefix (for instance `RESTGetAPIUserResult`) unless they are objects or
|
||||
enums (for instance `Routes`).
|
||||
|
||||
They must also follow the following structure: `REST{http_method}{type_name}{Query|(JSON|FormData)|Result}`, where:
|
||||
|
||||
- `http_method` is the PascalCase HTTP method name (for instance `Get`, `Post`, and so on)
|
||||
- `type_name` is the actual name of the type it returns (for instance `APIUser`)
|
||||
- `Query|(JSON|FormData)Body|Result` should be used depending on what the route takes or returns
|
||||
- If a route doesn't take in any parameters, be it query, JSON or FormData, it shouldn't define any of those types
|
||||
- A route should always define a `Result` type, and should reference an `API*` type unless the data returned is only
|
||||
received through a REST call
|
||||
- If a route returns a `204 No Content` response, it should define a `Result` type with `never` as its value (this
|
||||
does not account for errors)
|
||||
|
||||
This structure should be followed whenever possible, however that might not always be doable. Specifically, types for
|
||||
OAuth2 may not follow the structure exactly, but should aim to follow it as much as possible.
|
||||
|
||||
:::
|
||||
|
||||
#### `rpc`
|
||||
|
||||
This folder holds types that are strictly related to
|
||||
[`Discord's RPC API`](https://discord.com/developers/docs/topics/rpc). Just like [`gateway`](#gateway), each RPC API
|
||||
version receives its own file.
|
||||
|
||||
:::info
|
||||
|
||||
Types created here must start with the `RPC` prefix (for instance `RPCErrorCodes`).
|
||||
|
||||
:::
|
||||
|
||||
#### `scripts`
|
||||
|
||||
This folder holds the module's scripts that empower our Continuous Integration / Deployment pipelines, as well as other
|
||||
miscellaneous scripts we might need. There's really not much to say about these really...
|
||||
|
||||
#### `tests`
|
||||
|
||||
This folder holds tests for certain complex types that the module might have, and is especially useful for validating
|
||||
unions.
|
||||
|
||||
:::info
|
||||
|
||||
Files created here **must** end in `.test-d.ts`, as otherwise they will not be picked up by
|
||||
[`tsd`](https://www.npmjs.com/package/tsd).
|
||||
|
||||
:::
|
||||
|
||||
#### `utils`
|
||||
|
||||
This folder holds certain utility functions which can be used while working with some complicated types (for instance
|
||||
for more complicated unions). Each API version gets its own file with utility functions, but a folder can be created if
|
||||
a lot of methods are created.
|
||||
|
||||
:::info
|
||||
|
||||
The `internals.ts` file stores types that are strictly used inside the module to help build out our strict types. These
|
||||
types should never be exported from the module.
|
||||
|
||||
:::
|
||||
|
||||
#### `voice`
|
||||
|
||||
This folder holds types that are strictly related to
|
||||
[`Discord's Voice API`](https://discord.com/developers/docs/topics/voice-connections). It follows the same folder
|
||||
structure as [`gateway`](#gateway).
|
||||
|
||||
:::info
|
||||
|
||||
Types in this folder must start with the `Voice` prefix (for instance `VoiceOpcodes`).
|
||||
|
||||
:::
|
||||
|
||||
#### `website`
|
||||
|
||||
This folder holds...well...this very site you are reading this page from! For the most part, you do not need to alter
|
||||
its contents, except if you're contributing a new API version to the module.
|
||||
|
||||
To add the new version to this very website, edit the `docusaurus.config.js` file, and in the `plugins` array, for the
|
||||
`docusaurus-plugin-typedoc-api` plugin, you need to add an entry similar to the ones already present.
|
||||
|
||||
#### `globals.ts`
|
||||
|
||||
This file stores types that are present regardless of the API version you use.
|
||||
|
||||
#### `v*.ts`
|
||||
|
||||
These files export everything from the previously mentioned folders that match the version the file is named after. It
|
||||
serves as the entry point for importing types from the module (for example by importing `discord-api-types/v10`).
|
||||
|
||||
#### `package.json`
|
||||
|
||||
This is the entry point of the package for [`npm`](https://www.npmjs.com/). You won't need to edit this file unless
|
||||
you're adding a new API version, in which case you should follow the same structure as seen in the `exports` field.
|
||||
167
website/versioned_docs/version-0.33.3/Introduction.mdx
Normal file
167
website/versioned_docs/version-0.33.3/Introduction.mdx
Normal file
@@ -0,0 +1,167 @@
|
||||
---
|
||||
id: introduction_to_discord-api-types
|
||||
title: Introduction
|
||||
sidebar_position: 0
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
<div align="center">
|
||||
|
||||
<img src="/svgs/logo_long_blurple.svg" className="markdown__logo" />
|
||||
|
||||
[](https://discord-api-types.dev/discord)
|
||||
[](https://www.patreon.com/vladfrangu)
|
||||
[](https://ko-fi.com/wolfgalvlad)
|
||||
[](https://github.com/sponsors/vladfrangu)
|
||||
|
||||
[](https://www.npmjs.com/package/discord-api-types)
|
||||
[](https://www.npmjs.com/package/discord-api-types)
|
||||
[](https://deno.land/x/discord_api_types)
|
||||
|
||||
</div>
|
||||
|
||||
## About
|
||||
|
||||
Discord API Types is a community-maintained project that brings API types for Discord's REST, Gateway and Voice APIs.
|
||||
|
||||
## Installation
|
||||
|
||||
Install with [`npm`](https://www.npmjs.com/) / [`yarn`](https://yarnpkg.com) / [`pnpm`](https://pnpm.js.org/):
|
||||
|
||||
```bash npm2yarn2pnpm
|
||||
npm install discord-api-types
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
You can only import this module by specifying the API version you want to target. Append `/v*` to the import path, where
|
||||
the `*` represents the API version. Below are some examples
|
||||
|
||||
<Tabs groupId="ts2esm2cjs">
|
||||
<TabItem value="javascript" label="JavaScript">
|
||||
|
||||
```typescript showLineNumbers
|
||||
/**
|
||||
* @type {import('discord-api-types/v10').APIUser}
|
||||
*/
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="esm" label="ESM">
|
||||
|
||||
```typescript showLineNumbers
|
||||
/**
|
||||
* @type {import('discord-api-types/v10').APIUser}
|
||||
*/
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="typescript" label="TypeScript">
|
||||
|
||||
```typescript showLineNumbers
|
||||
import { type APIUser } from 'discord-api-types/v10';
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
:::info
|
||||
|
||||
You may also import just certain parts of the module that you need. The possible values are: `globals`, `gateway`,
|
||||
`gateway/v*`, `payloads`, `payloads/v*`, `rest`, `rest/v*`, `rpc`, `rpc/v*`, `utils`, `utils/v*`, `voice`, and
|
||||
`voice/v*`. Below is an example of importing directly from the gateway submodule
|
||||
|
||||
```typescript ts2esm2cjs
|
||||
import { GatewayVersion } from 'discord-api-types/gateway/v10';
|
||||
|
||||
console.log(`Let's connect to wss://gateway.discord.gg/?v=${GatewayVersion}`);
|
||||
```
|
||||
|
||||
> _**Note:** The `v*` exports (`discord-api-types/v*`) include the appropriate version of `gateway`, `payloads`, `rest`,
|
||||
> `rpc`, and `utils` you specified, alongside the `globals` exports_
|
||||
|
||||
:::
|
||||
|
||||
### Deno
|
||||
|
||||
We also provide typings compatible with the [deno](https://deno.land/) runtime. Here are 3 examples of how you can
|
||||
import them:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="github" label="From GitHub">
|
||||
|
||||
```typescript showLineNumbers
|
||||
// Importing a specific API version
|
||||
import { APIUser } from 'https://raw.githubusercontent.com/discordjs/discord-api-types/main/deno/v10.ts';
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="deno" label="From deno.land/x" default>
|
||||
|
||||
```typescript showLineNumbers
|
||||
// Importing a specific API version
|
||||
import { APIUser } from 'https://deno.land/x/discord_api_types/v10.ts';
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="skypack" label="From skypack.dev">
|
||||
|
||||
```typescript showLineNumbers
|
||||
// Importing a specific API version
|
||||
import { APIUser } from 'https://cdn.skypack.dev/discord-api-types/v10?dts';
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
## 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
|
||||
`globals` file. They will still be prefixed accordingly as described above.
|
||||
|
||||
:::danger A note about how types are documented
|
||||
|
||||
This package will add types only for known and documented properties that are present in Discord's
|
||||
[API Documentation repository](https://github.com/discord/discord-api-docs), that are mentioned in an open pull request,
|
||||
or known through other means _and have received the green light to be used_. Anything else will not be documented (for
|
||||
example client only types).
|
||||
|
||||
With that aside, we may allow certain types that are not documented in the
|
||||
[API Documentation repository](https://github.com/discord/discord-api-docs) on a case by case basis. They will be
|
||||
documented with an `@unstable` tag and are not subject with the same versioning rules.
|
||||
|
||||
:::
|
||||
1
website/versioned_docs/version-0.33.3/api-packages.json
Normal file
1
website/versioned_docs/version-0.33.3/api-packages.json
Normal file
@@ -0,0 +1 @@
|
||||
[{"entryPoints":{"globals":{"path":"globals.ts","label":"Global Types"},"gateway/common":{"path":"gateway/common.ts","label":"Gateway - Common Types"},"payloads/common":{"path":"payloads/common.ts","label":"Payloads - Common Types"},"rest/common":{"path":"rest/common.ts","label":"REST - Common Types"},"rpc/common":{"path":"rpc/common.ts","label":"RPC - Common Types"},"v6":{"path":"v6.ts","label":"API v6 - Deprecated"},"v8":{"path":"v8.ts","label":"API v8 - Deprecated"},"v9":{"path":"v9.ts","label":"API v9"},"v10":{"path":"v10.ts","label":"API v10"},"rpc/v8":{"path":"rpc/v8.ts","label":"RPC v8"},"rpc/v9":{"path":"rpc/v9.ts","label":"RPC v9"},"rpc/v10":{"path":"rpc/v10.ts","label":"RPC v10"},"voice/v4":{"path":"voice/v4.ts","label":"Voice v4"},"utils/v8":{"path":"utils/v8.ts","label":"Utils v8"},"utils/v9":{"path":"utils/v9.ts","label":"Utils v9"},"utils/v10":{"path":"utils/v10.ts","label":"Utils v10"}},"packagePath":"./","packageSlug":"discord-api-types","packageName":"discord-api-types","packageVersion":"0.33.3"}]
|
||||
1
website/versioned_docs/version-0.33.3/api-typedoc.json
Normal file
1
website/versioned_docs/version-0.33.3/api-typedoc.json
Normal file
File diff suppressed because one or more lines are too long
Binary file not shown.
|
After Width: | Height: | Size: 126 KiB |
263
website/versioned_docs/version-0.33.4/Contributing.mdx
Normal file
263
website/versioned_docs/version-0.33.4/Contributing.mdx
Normal file
@@ -0,0 +1,263 @@
|
||||
---
|
||||
id: contributing_to_discord-api-types
|
||||
title: How to Contribute
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
So, you'd like to contribute to `discord-api-types` but don't know where to start or what to do? Here are some of the
|
||||
things you need to keep in mind before opening a pull request!
|
||||
|
||||
:::tip Before you begin
|
||||
|
||||
We recommend you contribute either through locally editing the files on your desktop (which means also installing
|
||||
[`npm`](https://www.npmjs.com/) dependencies as this will ensure not only a consistent code style, but also that the
|
||||
`deno` types stay in sync automatically) or through a service like
|
||||
[`GitHub Codespaces`](https://github.com/features/codespaces).
|
||||
|
||||
:::
|
||||
|
||||
:::info Still can't figure it out?
|
||||
|
||||
No problem! We await you with open hands in our [`Discord Server`](https://discord.gg/djs) in the `#discord-api-types`
|
||||
channel (under the `Miscellaneous` category)
|
||||
|
||||
:::
|
||||
|
||||
### Install npm dependencies first
|
||||
|
||||
One of the most crucial steps is installing [`npm`](https://www.npmjs.com/) dependencies via `npm ci`. This ensures that
|
||||
linting can be done, and it also sets up the `git` hooks for building the `deno` types and automatically
|
||||
formatting/linting the code when you commit it.
|
||||
|
||||
If you forget to install [`npm`](https://www.npmjs.com/) dependencies, or are doing the contributions through other
|
||||
means (like directly from GitHub web), you might see a comment like this one being sent as a review to your pull
|
||||
request:
|
||||
|
||||

|
||||
|
||||
The easiest way to solve this is to run the `build:deno` script (`npm run build:deno`) and pushing the results.
|
||||
|
||||
### Figure out if the update you want to contribute respects our rules about documentation
|
||||
|
||||
:::danger
|
||||
|
||||
We will not document client-only / client related types. If you plan on contributing, make sure the types you want to
|
||||
document can be used by bots and are _intended_ for usage by bots. This is a hard rule that will never change.
|
||||
|
||||
:::
|
||||
|
||||
Not every single update to the API is valid to be documented here. Our main stance for documentation is that properties
|
||||
must be known and documented on [`Discord's API Documentation repository`](https://github.com/discord/discord-api-docs),
|
||||
must be mentioned in an open pull request or must have received the green light to be used.
|
||||
|
||||
With that aside, there are times where documentation for certain types is not approved/merged by Discord on the grounds
|
||||
that `it isn't helpful for bots` (or similar), but it would actually benefit bot developers to have it documented (one
|
||||
good example is the UserFlags `SPAMMER` flag). As such, if you think your update should still be merged, please propose
|
||||
it and we will be handled on a case by case basis. If approved, your update will be documented with an `@unstable` tag.
|
||||
It will also not be subject to the same versioning rules as the rest of the types.
|
||||
|
||||
### Figure out what API versions need to receive the update
|
||||
|
||||
`discord-api-types` has multiple API versions in the repository, some of which may be considered `deprecated` or
|
||||
`discontinued` as we keep them till the version is completely dead before removing them. This is a good time to figure
|
||||
out which API versions need to be updated, and you can use the table below to guide you.
|
||||
|
||||
You can also check [`Discord's API versioning table`](https://discord.com/developers/docs/reference#api-versioning) if
|
||||
you want to be 1000% sure.
|
||||
|
||||
| **API Version** | **Should receive updates** |
|
||||
| :-------------: | :------------------------: |
|
||||
| 10 | Yes |
|
||||
| 9 | Yes |
|
||||
| 8 | No |
|
||||
| 7 | No |
|
||||
| 6 | No |
|
||||
|
||||
If the version you want to contribute to is not listed above (for instance if a new API version rolls out) or if the
|
||||
version you want to contribute to is for a different part of the API (for instance `voice`), feel free to submit it and
|
||||
we will review it accordingly.
|
||||
|
||||
### Figure out where exactly are the files you need to modify to make the update
|
||||
|
||||
The file structure might seem confusing at first, especially if it's your first time contributing, but we're here to
|
||||
guide you through it.
|
||||
|
||||
When you clone the repository for the first time, you'll see a folder structure like this (we've not mentioned some
|
||||
tooling specific files like `.eslintrc.json` to keep the structure clean). We've highlighted the important folders and
|
||||
files you need to keep in mind when contributing.
|
||||
|
||||
```bash {2,4-6,9-10,12-16}
|
||||
├── deno
|
||||
├── gateway
|
||||
├── node_modules (once you ran `npm ci`)
|
||||
├── payloads
|
||||
├── rest
|
||||
├── rpc
|
||||
├── scripts
|
||||
├── tests
|
||||
├── utils
|
||||
├── voice
|
||||
├── website
|
||||
├── globals.ts
|
||||
├── v6.ts
|
||||
├── v8.ts
|
||||
├── v9.ts
|
||||
├── v10.ts
|
||||
└── package.json
|
||||
```
|
||||
|
||||
#### `deno`
|
||||
|
||||
This folder stores the [`deno`](https://deno.land/) compatible typings for Discord's API.
|
||||
|
||||
:::danger
|
||||
|
||||
This folder should not be manually modified. Any manual changes will be overwritten by the `build:deno` script.
|
||||
|
||||
Any changes that need to be done to this folder need to be done through the `scripts/deno.mjs` file.
|
||||
|
||||
:::
|
||||
|
||||
#### `gateway`
|
||||
|
||||
This folder holds types that are strictly received from
|
||||
[`Discord's gateway`](https://discord.com/developers/docs/topics/gateway). It stores the gateway version the types are
|
||||
for, the intents and opcodes, and any data that can be received/sent through the gateway.
|
||||
|
||||
Each file in the folder represents a gateway version. It references types from the versioned [`payloads`](#payloads)
|
||||
folder unless the payloads come _only_ through the gateway. There is also a `common.ts` file which represents shared
|
||||
types across all versions, as well as an `index.ts` file that exports the recommended gateway version's types.
|
||||
|
||||
:::info
|
||||
|
||||
Types created here must start with the `Gateway` prefix (for instance `GatewayGuildCreateDispatchData` which is an
|
||||
extension of the `APIGuild` type with extra fields received only through the gateway).
|
||||
|
||||
:::
|
||||
|
||||
#### `payloads`
|
||||
|
||||
This folder holds the bulk of type definitions for Discord's APIs. Each API version receives its own folder. Inside of
|
||||
each folder there is always an `index.ts` file that exports every type available in that version, as well as the common
|
||||
types that can be found in `payloads/common.ts`. At the root of the `payloads` folder is also an `index.ts` file which
|
||||
exports the recommended API version's types.
|
||||
|
||||
Inside of each versioned folder, the files are defined from the structure in
|
||||
[`Discord's API Documentation`](https://discord.dev), under the `Resources` category. Depending on the complexity of the
|
||||
resource, you may opt for splitting it up into multiple files. If you want to do so, please create a folder named
|
||||
`_{resource_name}` where the `resource_name` is the same name as the resource you're splitting up (a good example is the
|
||||
`_interactions` folder which stores all the types for interactions in a neater structure), and create a
|
||||
`{resource_name}.ts` file which exports everything from that folder). If you feel like you need to split it up even
|
||||
more, just repeat the same structure of creating an `_{file_name}` folder and exporting everything from it in the
|
||||
`{file_name}.ts` file (you can see an example
|
||||
[here](https://github.com/discordjs/discord-api-types/tree/85802f1/payloads/v10/_interactions)).
|
||||
|
||||
:::info
|
||||
|
||||
Types created here must start with the `API` prefix (for instance `APIUser`), **except** for enums, which should have a
|
||||
normal name (for instance `UserFlags`).
|
||||
|
||||
:::
|
||||
|
||||
#### `rest`
|
||||
|
||||
This folder holds all the types that are related to Discord's REST API. Just like [`payloads`](#payloads), it is split
|
||||
into folders that have an `index.ts` file. from the structure in [`Discord's API Documentation`](https://discord.dev),
|
||||
under the `Resources` category.
|
||||
|
||||
:::info
|
||||
|
||||
Types created here must start with the `REST` prefix (for instance `RESTGetAPIUserResult`) unless they are objects or
|
||||
enums (for instance `Routes`).
|
||||
|
||||
They must also follow the following structure: `REST{http_method}{type_name}{Query|(JSON|FormData)|Result}`, where:
|
||||
|
||||
- `http_method` is the PascalCase HTTP method name (for instance `Get`, `Post`, and so on)
|
||||
- `type_name` is the actual name of the type it returns (for instance `APIUser`)
|
||||
- `Query|(JSON|FormData)Body|Result` should be used depending on what the route takes or returns
|
||||
- If a route doesn't take in any parameters, be it query, JSON or FormData, it shouldn't define any of those types
|
||||
- A route should always define a `Result` type, and should reference an `API*` type unless the data returned is only
|
||||
received through a REST call
|
||||
- If a route returns a `204 No Content` response, it should define a `Result` type with `never` as its value (this
|
||||
does not account for errors)
|
||||
|
||||
This structure should be followed whenever possible, however that might not always be doable. Specifically, types for
|
||||
OAuth2 may not follow the structure exactly, but should aim to follow it as much as possible.
|
||||
|
||||
:::
|
||||
|
||||
#### `rpc`
|
||||
|
||||
This folder holds types that are strictly related to
|
||||
[`Discord's RPC API`](https://discord.com/developers/docs/topics/rpc). Just like [`gateway`](#gateway), each RPC API
|
||||
version receives its own file.
|
||||
|
||||
:::info
|
||||
|
||||
Types created here must start with the `RPC` prefix (for instance `RPCErrorCodes`).
|
||||
|
||||
:::
|
||||
|
||||
#### `scripts`
|
||||
|
||||
This folder holds the module's scripts that empower our Continuous Integration / Deployment pipelines, as well as other
|
||||
miscellaneous scripts we might need. There's really not much to say about these really...
|
||||
|
||||
#### `tests`
|
||||
|
||||
This folder holds tests for certain complex types that the module might have, and is especially useful for validating
|
||||
unions.
|
||||
|
||||
:::info
|
||||
|
||||
Files created here **must** end in `.test-d.ts`, as otherwise they will not be picked up by
|
||||
[`tsd`](https://www.npmjs.com/package/tsd).
|
||||
|
||||
:::
|
||||
|
||||
#### `utils`
|
||||
|
||||
This folder holds certain utility functions which can be used while working with some complicated types (for instance
|
||||
for more complicated unions). Each API version gets its own file with utility functions, but a folder can be created if
|
||||
a lot of methods are created.
|
||||
|
||||
:::info
|
||||
|
||||
The `internals.ts` file stores types that are strictly used inside the module to help build out our strict types. These
|
||||
types should never be exported from the module.
|
||||
|
||||
:::
|
||||
|
||||
#### `voice`
|
||||
|
||||
This folder holds types that are strictly related to
|
||||
[`Discord's Voice API`](https://discord.com/developers/docs/topics/voice-connections). It follows the same folder
|
||||
structure as [`gateway`](#gateway).
|
||||
|
||||
:::info
|
||||
|
||||
Types in this folder must start with the `Voice` prefix (for instance `VoiceOpcodes`).
|
||||
|
||||
:::
|
||||
|
||||
#### `website`
|
||||
|
||||
This folder holds...well...this very site you are reading this page from! For the most part, you do not need to alter
|
||||
its contents, except if you're contributing a new API version to the module.
|
||||
|
||||
To add the new version to this very website, edit the `docusaurus.config.js` file, and in the `plugins` array, for the
|
||||
`docusaurus-plugin-typedoc-api` plugin, you need to add an entry similar to the ones already present.
|
||||
|
||||
#### `globals.ts`
|
||||
|
||||
This file stores types that are present regardless of the API version you use.
|
||||
|
||||
#### `v*.ts`
|
||||
|
||||
These files export everything from the previously mentioned folders that match the version the file is named after. It
|
||||
serves as the entry point for importing types from the module (for example by importing `discord-api-types/v10`).
|
||||
|
||||
#### `package.json`
|
||||
|
||||
This is the entry point of the package for [`npm`](https://www.npmjs.com/). You won't need to edit this file unless
|
||||
you're adding a new API version, in which case you should follow the same structure as seen in the `exports` field.
|
||||
167
website/versioned_docs/version-0.33.4/Introduction.mdx
Normal file
167
website/versioned_docs/version-0.33.4/Introduction.mdx
Normal file
@@ -0,0 +1,167 @@
|
||||
---
|
||||
id: introduction_to_discord-api-types
|
||||
title: Introduction
|
||||
sidebar_position: 0
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
<div align="center">
|
||||
|
||||
<img src="/svgs/logo_long_blurple.svg" className="markdown__logo" />
|
||||
|
||||
[](https://discord-api-types.dev/discord)
|
||||
[](https://www.patreon.com/vladfrangu)
|
||||
[](https://ko-fi.com/wolfgalvlad)
|
||||
[](https://github.com/sponsors/vladfrangu)
|
||||
|
||||
[](https://www.npmjs.com/package/discord-api-types)
|
||||
[](https://www.npmjs.com/package/discord-api-types)
|
||||
[](https://deno.land/x/discord_api_types)
|
||||
|
||||
</div>
|
||||
|
||||
## About
|
||||
|
||||
Discord API Types is a community-maintained project that brings API types for Discord's REST, Gateway and Voice APIs.
|
||||
|
||||
## Installation
|
||||
|
||||
Install with [`npm`](https://www.npmjs.com/) / [`yarn`](https://yarnpkg.com) / [`pnpm`](https://pnpm.js.org/):
|
||||
|
||||
```bash npm2yarn2pnpm
|
||||
npm install discord-api-types
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
You can only import this module by specifying the API version you want to target. Append `/v*` to the import path, where
|
||||
the `*` represents the API version. Below are some examples
|
||||
|
||||
<Tabs groupId="ts2esm2cjs">
|
||||
<TabItem value="javascript" label="JavaScript">
|
||||
|
||||
```typescript showLineNumbers
|
||||
/**
|
||||
* @type {import('discord-api-types/v10').APIUser}
|
||||
*/
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="esm" label="ESM">
|
||||
|
||||
```typescript showLineNumbers
|
||||
/**
|
||||
* @type {import('discord-api-types/v10').APIUser}
|
||||
*/
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="typescript" label="TypeScript">
|
||||
|
||||
```typescript showLineNumbers
|
||||
import { type APIUser } from 'discord-api-types/v10';
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
:::info
|
||||
|
||||
You may also import just certain parts of the module that you need. The possible values are: `globals`, `gateway`,
|
||||
`gateway/v*`, `payloads`, `payloads/v*`, `rest`, `rest/v*`, `rpc`, `rpc/v*`, `utils`, `utils/v*`, `voice`, and
|
||||
`voice/v*`. Below is an example of importing directly from the gateway submodule
|
||||
|
||||
```typescript ts2esm2cjs
|
||||
import { GatewayVersion } from 'discord-api-types/gateway/v10';
|
||||
|
||||
console.log(`Let's connect to wss://gateway.discord.gg/?v=${GatewayVersion}`);
|
||||
```
|
||||
|
||||
> _**Note:** The `v*` exports (`discord-api-types/v*`) include the appropriate version of `gateway`, `payloads`, `rest`,
|
||||
> `rpc`, and `utils` you specified, alongside the `globals` exports_
|
||||
|
||||
:::
|
||||
|
||||
### Deno
|
||||
|
||||
We also provide typings compatible with the [deno](https://deno.land/) runtime. Here are 3 examples of how you can
|
||||
import them:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="github" label="From GitHub">
|
||||
|
||||
```typescript showLineNumbers
|
||||
// Importing a specific API version
|
||||
import { APIUser } from 'https://raw.githubusercontent.com/discordjs/discord-api-types/main/deno/v10.ts';
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="deno" label="From deno.land/x" default>
|
||||
|
||||
```typescript showLineNumbers
|
||||
// Importing a specific API version
|
||||
import { APIUser } from 'https://deno.land/x/discord_api_types/v10.ts';
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="skypack" label="From skypack.dev">
|
||||
|
||||
```typescript showLineNumbers
|
||||
// Importing a specific API version
|
||||
import { APIUser } from 'https://cdn.skypack.dev/discord-api-types/v10?dts';
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
## 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
|
||||
`globals` file. They will still be prefixed accordingly as described above.
|
||||
|
||||
:::danger A note about how types are documented
|
||||
|
||||
This package will add types only for known and documented properties that are present in Discord's
|
||||
[API Documentation repository](https://github.com/discord/discord-api-docs), that are mentioned in an open pull request,
|
||||
or known through other means _and have received the green light to be used_. Anything else will not be documented (for
|
||||
example client only types).
|
||||
|
||||
With that aside, we may allow certain types that are not documented in the
|
||||
[API Documentation repository](https://github.com/discord/discord-api-docs) on a case by case basis. They will be
|
||||
documented with an `@unstable` tag and are not subject with the same versioning rules.
|
||||
|
||||
:::
|
||||
1
website/versioned_docs/version-0.33.4/api-packages.json
Normal file
1
website/versioned_docs/version-0.33.4/api-packages.json
Normal file
@@ -0,0 +1 @@
|
||||
[{"entryPoints":{"globals":{"path":"globals.ts","label":"Global Types"},"gateway/common":{"path":"gateway/common.ts","label":"Gateway - Common Types"},"payloads/common":{"path":"payloads/common.ts","label":"Payloads - Common Types"},"rest/common":{"path":"rest/common.ts","label":"REST - Common Types"},"rpc/common":{"path":"rpc/common.ts","label":"RPC - Common Types"},"v6":{"path":"v6.ts","label":"API v6 - Deprecated"},"v8":{"path":"v8.ts","label":"API v8 - Deprecated"},"v9":{"path":"v9.ts","label":"API v9"},"v10":{"path":"v10.ts","label":"API v10"},"rpc/v8":{"path":"rpc/v8.ts","label":"RPC v8"},"rpc/v9":{"path":"rpc/v9.ts","label":"RPC v9"},"rpc/v10":{"path":"rpc/v10.ts","label":"RPC v10"},"voice/v4":{"path":"voice/v4.ts","label":"Voice v4"},"utils/v8":{"path":"utils/v8.ts","label":"Utils v8"},"utils/v9":{"path":"utils/v9.ts","label":"Utils v9"},"utils/v10":{"path":"utils/v10.ts","label":"Utils v10"}},"packagePath":"./","packageSlug":"discord-api-types","packageName":"discord-api-types","packageVersion":"0.33.4"}]
|
||||
1
website/versioned_docs/version-0.33.4/api-typedoc.json
Normal file
1
website/versioned_docs/version-0.33.4/api-typedoc.json
Normal file
File diff suppressed because one or more lines are too long
Binary file not shown.
|
After Width: | Height: | Size: 126 KiB |
8
website/versioned_sidebars/version-0.33.3-sidebars.json
Normal file
8
website/versioned_sidebars/version-0.33.3-sidebars.json
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"sidebar": [
|
||||
{
|
||||
"type": "autogenerated",
|
||||
"dirName": "."
|
||||
}
|
||||
]
|
||||
}
|
||||
8
website/versioned_sidebars/version-0.33.4-sidebars.json
Normal file
8
website/versioned_sidebars/version-0.33.4-sidebars.json
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"sidebar": [
|
||||
{
|
||||
"type": "autogenerated",
|
||||
"dirName": "."
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,4 +1,6 @@
|
||||
[
|
||||
"0.33.4",
|
||||
"0.33.3",
|
||||
"0.33.2",
|
||||
"0.33.1",
|
||||
"0.33.0"
|
||||
|
||||
Reference in New Issue
Block a user